name: feishu-wiki-organizer
description: |
飞书知识库专业整理工具。在不合并、不删除原文的前提下，通过内容分析实现精准分类。
支持单库整理和多库整体规划 (30+ 库规模)。
当用户提到以下场景时使用此 Skill:
(1) 整理/分类飞书知识库内容
(2) 飞书知识库文档太多需要归类
(3) 为知识库创建分类目录结构
(4) 批量移动飞书知识库文档到文件夹
(5) "知识库太乱了"、"帮我整理一下"、"知识库分类"
(6) 多个知识库需要统一规划、改名、补充 description
关键词：知识库、wiki、整理、分类、归档、文件夹
根本目标：人能在3次点击内找到任何一篇文档。
知识库名/
├── 一、类目A（X篇）
│ ├── 文档1
│ └── 文档2
├── 二、类目B（X篇）
└── 其他（X篇）
操作：创建X个目录，移动X篇
风险：X篇标题模糊已读内容确认| # | 优化点 | 说明 |
|---|--------|------|
| 1 | 失败文档自动归入「其他」 | 移动失败→重试3次→仍失败→归入「其他」，不留根目录散落 |
| 2 | 移动日志+回滚能力 | 执行前记录 node_token: A→B，提供反向移动回滚命令 |
| # | 优化点 | 说明 |
|---|--------|------|
| 3 | 防乱机制 | 新文档默认归入某个目录；定期扫描新散落文档，当天归类 |
| 4 | 责任人机制 | 每个知识库指定1个维护责任人；新文档24小时内由责任人归类 |
| # | 优化点 | 说明 |
|---|--------|------|
| 5 | 增量更新 | 只检查根目录新散落文档，不全量扫描 |
| 6 | 合并库标准流程 | 列出源库文档→匹配目标库目录→处理重复→移动文档（不删除源库） |
| 7 | 质量指标 | 检索效率（≤3次点击）、目录平衡度（<30%）、其他占比（<15%） |
| # | 优化点 | 说明 |
|---|--------|------|
| 8 | 目录命名规范 | 统一「一、二、三」中文编号，子目录用「1.1、1.2」 |
| 9 | 跨库引用标注 | 方案中标注跨库引用关系，目录描述中说明关联库 |
feishu_create_doc(
title="一、大类名称",
markdown="本分类收录 XXX 相关资料。",
wiki_space="<space_id>"
)
# 从 doc_url 提取 node_token(URL 最后一段)
# 每次创建 1 个，间隔 1-2 秒避免锁争用feishu_wiki_space_node(
action="move",
node_token="<文档 node_token>",
space_id="<space_id>",
target_parent_token="<目标文件夹 node_token>",
target_space_id="<space_id>"
)移动策略：
# 执行前验证权限
try:
feishu_wiki_space_node(action="move", node_token=test_node, target_parent_token=temp_dir)
feishu_wiki_space_node(action="move", node_token=test_node, target_parent_token=original_parent)
print("权限验证通过")
except PermissionError:
print("❌ 权限不足，需管理员授权")# ~/.openclaw/workspace/.kb_organizer/move_log_<date>.json
{
"moves": [
{
"node_token": "xxx",
"title": "文档标题",
"from_parent": "原父节点",
"to_parent": "目标父节点",
"status": "success|failed",
"timestamp": "2026-05-14T12:00:00+08:00"
}
]
}
# 回滚：按日志反向移动问题： 单个 subagent 处理 30+ 篇文档容易超时。
解决方案：分批处理
整理完每个知识库后：
根目录验证：
nodes = feishu_wiki_space_node(action="list", space_id=xxx)
root_docs = [n for n in nodes if n["parent_node_token"] == "" and not n["has_child"]]
if root_docs:
print(f"⚠️ 根目录仍有 {len(root_docs)} 篇文档未移动")| 问题 | 解决方案 |
|------|----------|
| rpc fail / 锁争用 | 逐个移动，失败 sleep 2-3 秒重试 |
| permission denied | 让库管理员授权当前用户 |
| 429 quota exhausted | 每批最多3个并行子任务，批间等30秒 |
| 占位符文档需删除 | API不支持删除，用户手动飞书界面删 |
| 已有目录的库 | 先检查现有结构，优先利用 |
| 合并库的文档 | 重新归类到现有目录，检查has_child节点 |
| 文档内容读取 | feishu_fetch_doc(doc_id=node_token) |
| 移动幂等性 | 已在目标位置的文档移动返回成功 |
| 小库处理 | <3 篇文档保留独立库或归入「其他」 |
默认不启用。如需自动检查，必须由用户明确选择开启。
启用后配置：
0 * * * *）~/.openclaw/workspace/.kb_organizer/status.json（受保护目录，权限 600）~/.openclaw/workspace/.kb_organizer/organizer.logall_kbs_complete=true| 教训 | 详情 |
|------|------|
| 权限是最大瓶颈 | 只有创建者或管理员才能移动根目录文档 |
| API配额 | 3个并行子任务是安全上限 |
| 标题vs内容 | 标题快分+内容抽验效率最高 |
| 占位符清理 | 整理过程会创建空壳，需手动删 |
| 方案文档同步 | 每完成一个库立即更新方案文档 |
| 三级目录拆分 | >10篇必须拆，按内容属性划分 |
| 失败兜底 | 失败文档必须归入「其他」，不留根目录 |
| 防乱机制 | 新文档当天归类，不等积累 |
| 责任人 | 每个库指定维护人，月度检查 |
扫描全部 → 分类严重/中等/轻微
→ 权限验证 → 暂停定时
→ 严重库3并行 → 中等库3并行 → 轻微库快速处理
→ 每批更新方案文档 → 验证（抽查5篇）→ 恢复定时feishu_create_doc(
title="一、大类名称",
markdown="本分类收录 XXX 相关资料。",
wiki_space="<space_id>"
)
# 从 doc_url 提取 node_token(URL 最后一段)
# 每次创建 1 个，间隔 1-2 秒避免锁争用feishu_wiki_space_node(
action="move",
node_token="<文档 node_token>",
space_id="<space_id>",
target_parent_token="<目标文件夹 node_token>",
target_space_id="<space_id>"
)移动策略：
识别场景：
处理策略：
问题： 单个 subagent 处理 30+ 篇文档容易超时 (15 分钟限制),且 API 锁争用导致频繁失败。
解决方案：分批处理 + 状态追踪
状态追踪文件模板：
// ~/.openclaw/workspace/.kb_organizer/move_status_<space_id>.json
{
"space_id": "xxx",
"kb_name": "知识库名称",
"total_documents": 92,
"moved_documents": [
{
"node_token": "xxx",
"title": "文档标题",
"target_parent": "目标 node_token",
"target_name": "目标目录名",
"status": "success",
"move_time": "2026-05-13T16:45:00+08:00"
}
],
"failed_documents": [
{
"node_token": "xxx",
"title": "文档标题",
"error": "rpc fail",
"retry_count": 3,
"status": "failed"
}
],
"pending_documents": ["node_token1", "node_token2"],
"current_batch": 1,
"last_check_time": "2026-05-13T16:50:00+08:00"
}恢复机制：
pending_documents 是待移动列表moved_documents 中失败的需要重新处理整理完每个知识库后，必须执行检查:
feishu_wiki_space_node(list, space_id=xxx) 确认根目录无残留文档根目录验证方法：
# 获取根目录所有节点
nodes = feishu_wiki_space_node(action="list", space_id=xxx)
# 筛选根目录残留 (非目录类文档，即 parent_node_token 为空且 has_child=false)
root_docs = [n for n in nodes if n["parent_node_token"] == "" and not n["has_child"]]
# 如果 root_docs 不为空，说明还有文档未移动
if root_docs:
print(f"⚠️ 根目录仍有 {len(root_docs)} 篇文档未移动")
print("文档列表:", [d["title"] for d in root_docs])检查报告格式:
✅ [知识库名] 整理检查完成
├── 根目录残留:0 篇
├── 子目录 A:X 篇 (预期 Y 篇)✅
├── 子目录 B:X 篇 (预期 Y 篇)✅
├── 子目录 C:X 篇 (预期 Z 篇)⚠️ 差 1 篇，已补移
└── 总计:XX 篇，全部归位飞书 API 对同一空间并发写入有限制。逐个移动，失败后 sleep 2-3 秒重试。大批量用 subagent 分批处理。
feishu_wiki_space_node(list) 返回的 node_token 字段feishu_create_doc 返回的 doc_url 最后一段obj_tokenfeishu_fetch_doc(doc_id=node_token) 可读取文档 Markdown 内容已在目标位置的文档移动操作返回成功，不会出错。
原则上不做跨库移动。错分文档在库内标记为"其他"类。
如用户明确同意跨库，需单独记录并执行。
<3 篇文档的知识库，建议:
知识库命名:[产品名/项目名]-[文档性质]
禁止：下划线前缀、模糊命名、括号和特殊字符、中英文混杂无意义
飞书 API 暂不支持通过 feishu_wiki_space 工具直接修改知识库 description。
如需补充 description，请:
默认不启用。用户明确说「开启自动检查」后才启用。
启用后配置：
0 * * * *）~/.openclaw/workspace/.kb_organizer/status.json（权限 600）~/.openclaw/workspace/.kb_organizer/organizer.logall_kbs_complete=truepermission denied: no source parent node permission 时，需让库管理员授权has_child 节点，子文档会跟随移动replace_range 模式更新对应章节1. 扫描全部知识库 → 分类（严重/中等/轻微/已完成）
2. 严重库（40+篇）→ 3个并行子任务
3. 中等库（10-30篇）→ 3个并行子任务
4. 轻微库（<10篇）→ 快速处理
5. 每批完成后更新方案文档
6. 全部完成后内容验证
7. 占位符文档由用户手动删除| 阶段 | 动作 | 执行情况 |
|------|--|--|
| 1. 概念 | 描述过程、规则 | ✅ 2026-05-13 |
| 2. 原型 | 对 3-10 个真实项手动运行 | ✅ 2026-05-14（30个库大规模验证） |
| 3. 评估 | 与 Boss 审查输出 | ✅ 2026-05-14（第一性原理审查+9项优化） |
| 4. 编纂 | 编写 SKILL.md | ✅ 2026-05-14（优化版写入） |
| 5. Cron | 添加定时任务 | ✅ 每小时自动检查 |
| 6. 监控 | 检查首次运行 | ✅ 已运行多次 |
MECE 原则：知识库整理工作仅由本技能覆盖，无其他技能重叠。