飞书知识库整理专家#

核心原则（第一性原理版）#

根本目标：人能在3次点击内找到任何一篇文档。

1. 只做移动，不改原文 - 严禁合并、删除、修改文档内容
2. 不跨库移动 - 错分文档归入库内「其他」类
3. 标题优先 - 80%的文档靠标题分类，仅对模糊文档读内容
4. 预览+确认 - 每批移动前输出预览方案，用户明确批准后执行
5. 根目录清零 - 硬指标，散落文档必须全部归位
6. 3次点击原则 - 目录层级不设硬上限，以检索效率为准
7. 失败必兜底 - 移动失败的文档自动归入「其他」，不留散落
8. 仅移动叶子文档 - 移动含子节点的文档需用户单独批准（子文档会跟随移动）
9. 禁止删除 - 不删除任何文档或知识库，合并仅做移动不删源

---

工作流程（优化版）#

Phase 0: 预检（5分钟）#

1. 获取知识库列表 → 按文档数量分类：

   • 🔴 严重（40+篇散落）
   • 🟡 中等（10-30篇）
   • 🟢 轻微（<10篇）
   • ✅ 已有结构（无需整理）

2. 权限验证 → 试移动一篇到临时目录再移回

3. 暂停定时任务 → 避免手动+自动同时操作

Phase 1: 标题快分（每库2分钟）#

1. 列出所有根目录散落文档
2. 按标题关键词聚类：
   • 含「教程/指南/入门」→ 教程类
   • 含「部署/安装/配置」→ 部署类
   • 含「提示词/prompt」→ 提示词类
   • 含「项目名」→ 该项目专属
   • 含「会议/纪要」→ 会议类
   • 标题模糊/看不懂 → 标记为「待验证」
3. 输出分类草案

Phase 2: 内容抽验（仅对模糊文档）#

1. 仅读取「待验证」文档的内容（通常≤20%）

2. 根据内容重新归类

3. 输出最终分类方案： text

   知识库名/
   ├── 一、类目A（X篇）
   │   ├── 文档1
   │   └── 文档2
   ├── 二、类目B（X篇）
   └── 其他（X篇）
   
   操作：创建X个目录，移动X篇
   风险：X篇标题模糊已读内容确认
   
   

Phase 3: 批量执行#

• 每批移动前输出预览方案（目标目录+文档列表）
• 用户明确批准后执行（不说「继续」不动）
• 仅移动叶子文档（has_child=false）；含子节点的文档需单独批准
• 3个子任务并行（API配额上限）
• 每个子任务处理1个库
• 移动间隔2-3秒，失败重试3次
• 失败文档自动归入「其他」
• 每批完成后汇报进度

Phase 4: 验证+同步#

1. 检查每个库根目录是否清零
2. 随机抽查5篇，确认分类正确
3. 检查目录文档数量是否>10（需拆分）
4. 更新方案文档
5. 恢复定时任务

---

📋 优化清单（9项）#

🔴 执行层优化#

#优化点说明1失败文档自动归入「其他」移动失败→重试3次→仍失败→归入「其他」，不留根目录散落2移动日志+回滚能力执行前记录 node_token: A→B，提供反向移动回滚命令

🔴 根本机制#

#优化点说明3防乱机制新文档默认归入某个目录；定期扫描新散落文档，当天归类4责任人机制每个知识库指定1个维护责任人；新文档24小时内由责任人归类

🟡 运维优化#

#优化点说明5增量更新只检查根目录新散落文档，不全量扫描6合并库标准流程列出源库文档→匹配目标库目录→处理重复→移动文档（不删除源库）7质量指标检索效率（≤3次点击）、目录平衡度（<30%）、其他占比（<15%）

🟢 规范优化#

#优化点说明8目录命名规范统一「一、二、三」中文编号，子目录用「1.1、1.2」9跨库引用标注方案中标注跨库引用关系，目录描述中说明关联库

---

执行技巧#

创建文件夹节点#

python

feishu_create_doc(
    title="一、大类名称",
    markdown="本分类收录 XXX 相关资料。",
    wiki_space="<space_id>"
)
# 从 doc_url 提取 node_token(URL 最后一段)
# 每次创建 1 个，间隔 1-2 秒避免锁争用

批量移动文档#

python

feishu_wiki_space_node(
    action="move",
    node_token="<文档 node_token>",
    space_id="<space_id>",
    target_parent_token="<目标文件夹 node_token>",
    target_space_id="<space_id>"
)

移动策略：

• 每次移动 1 个文档，失败后 sleep 2-3 秒重试
• 最多重试 3 次，仍失败→归入「其他」类
• 移动 has_child=true 的节点时，子文档会自动跟随移动
• API 有锁争用限制，不要并行移动

权限前置验证#

python

# 执行前验证权限
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("❌ 权限不足，需管理员授权")

移动日志记录#

python

# ~/.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"
    }
  ]
}
# 回滚：按日志反向移动

大批量文档处理策略 (>30 篇)#

问题： 单个 subagent 处理 30+ 篇文档容易超时。

解决方案：分批处理

1. 拆分批次 — 每批 20-25 篇
2. 每批一个 subagent — 避免单个任务超时
3. 间隔执行 — 每批完成后等待 10 秒
4. 失败兜底 — 移动失败的文档自动归入「其他」

回头检查（必须执行）#

整理完每个知识库后：

1. 检查根目录 — 确认无残留文档
2. 随机抽查 — 读取5篇内容验证分类正确性
3. 检查目录平衡 — 单个目录不超过总量30%
4. 检查「其他」占比 — 不超过15%

根目录验证：

python

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.log
• 手动整理时自动暂停
• 每次自动变更记录到日志
• 禁用命令：用户说「关闭自动检查」或删除 cron 任务

执行流程#

1. 检查是否有手动操作在进行（锁文件）
2. 读取状态文件，检查各知识库进度
3. 未完成 → 输出预览方案， 等待用户批准后 执行移动
4. 已完成 → 二次检查验证分类准确性（只检查不移动）
5. 全部完成后设置 all_kbs_complete=true

安全规则#

• 自动模式下不移动含子节点的文档
• 每次变更写入日志（时间+操作+结果）
• 任务完成后清理临时日志

---

📋 实战经验总结（2026-05-14 大规模整理）#

执行概况#

• 整理规模：30个知识库，416+篇文档
• 自动化完成：18个库（62%）
• 权限问题：5个库需手动处理
• 已有结构：5个库无需整理
• 已合并：1个库（AIGC图生视频→AI视频）

关键教训#

教训详情权限是最大瓶颈只有创建者或管理员才能移动根目录文档API配额3个并行子任务是安全上限标题vs内容标题快分+内容抽验效率最高占位符清理整理过程会创建空壳，需手动删方案文档同步每完成一个库立即更新方案文档三级目录拆分>10篇必须拆，按内容属性划分失败兜底失败文档必须归入「其他」，不留根目录防乱机制新文档当天归类，不等积累责任人每个库指定维护人，月度检查

推荐执行流程#

text

扫描全部 → 分类严重/中等/轻微
→ 权限验证 → 暂停定时
→ 严重库3并行 → 中等库3并行 → 轻微库快速处理
→ 每批更新方案文档 → 验证（抽查5篇）→ 恢复定时

---

执行技巧#

创建文件夹节点#

python

feishu_create_doc(
    title="一、大类名称",
    markdown="本分类收录 XXX 相关资料。",
    wiki_space="<space_id>"
)
# 从 doc_url 提取 node_token(URL 最后一段)
# 每次创建 1 个，间隔 1-2 秒避免锁争用

批量移动文档#

python

feishu_wiki_space_node(
    action="move",
    node_token="<文档 node_token>",
    space_id="<space_id>",
    target_parent_token="<目标文件夹 node_token>",
    target_space_id="<space_id>"
)

移动策略：

• 每次移动 1 个文档，失败后 sleep 2-3 秒重试
• 最多重试 3 次，仍失败记录跳过
• 移动 has_child=true 的节点时，子文档会自动跟随移动（无需单独移动子文档）
• API 有锁争用限制，不要并行移动

已有二级目录的知识库处理策略#

识别场景：

• 根目录存在多个 has_child=true 的节点
• 这些节点可能是已建好的分类目录
• 根目录仍有散落文档

处理策略：

1. 先检查现有目录结构 — 确认哪些是已有目录
2. 分析散落文档 — 判断应归入哪个现有目录
3. 优先利用现有目录 — 避免重复创建
4. 补充缺失目录 — 如有分类需求但目录不存在，再创建
5. 统计各目录文档数量 — 如某目录文档>8 篇，考虑拆分三级

大批量文档处理策略 (>30 篇)#

问题： 单个 subagent 处理 30+ 篇文档容易超时 (15 分钟限制),且 API 锁争用导致频繁失败。

解决方案：分批处理 + 状态追踪

1. 拆分批次 — 每批 20-25 篇文档，不要超过 30 篇
2. 每批一个 subagent — 每批独立执行，避免单个任务超时
3. 状态文件追踪 — 用本地文件记录已移动文档，避免重复操作
4. 间隔执行 — 每批完成后等待 10 秒再启动下一批
5. 回头检查 — 每批完成后检查根目录残留

状态追踪文件模板：

json

// ~/.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"
}

恢复机制：

• subagent 超时后，检查状态文件
• pending_documents 是待移动列表
• moved_documents 中失败的需要重新处理
• 启动新 subagent 时，传入状态文件路径继续

回头检查 (必须执行)#

整理完每个知识库后，必须执行检查:

1. 检查根目录 — feishu_wiki_space_node(list, space_id=xxx) 确认根目录无残留文档
2. 检查每个子目录 — 逐个子目录 list,确认文档数量与预期一致
3. 对比预期 — 将实际文档分布与方案中的预期对比，列出差异
4. 补移遗漏 — 如有遗漏文档，立即移动到正确子目录
5. 更新检查清单 — 在文档中打勾确认该知识库已完成

根目录验证方法：

python

# 获取根目录所有节点
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])

检查报告格式:

text

✅ [知识库名] 整理检查完成
├── 根目录残留:0 篇
├── 子目录 A:X 篇 (预期 Y 篇)✅
├── 子目录 B:X 篇 (预期 Y 篇)✅
├── 子目录 C:X 篇 (预期 Z 篇)⚠️ 差 1 篇，已补移
└── 总计:XX 篇，全部归位

---

常见问题#

rpc fail / lock contention#

飞书 API 对同一空间并发写入有限制。逐个移动，失败后 sleep 2-3 秒重试。大批量用 subagent 分批处理。

node_token 获取#

• feishu_wiki_space_node(list) 返回的 node_token 字段
• feishu_create_doc 返回的 doc_url 最后一段
• 不要用 obj_token

文档内容读取#

• feishu_fetch_doc(doc_id=node_token) 可读取文档 Markdown 内容
• 文档较多时优先靠标题分类，标题模糊的再读内容

移动幂等性#

已在目标位置的文档移动操作返回成功，不会出错。

跨库移动#

原则上不做跨库移动。错分文档在库内标记为"其他"类。 如用户明确同意跨库，需单独记录并执行。

小库处理#

<3 篇文档的知识库，建议:

• 保留为独立库 (如果是独立产品/项目)
• 或在库内标记为"其他"类，不做合并

命名规范#

知识库命名: [产品名/项目名]-[文档性质] 禁止：下划线前缀、模糊命名、括号和特殊字符、中英文混杂无意义

description 补充限制#

飞书 API 暂不支持通过 feishu_wiki_space 工具直接修改知识库 description。 如需补充 description，请:

1. 在方案中列出需要补充的描述内容
2. 用户手动在飞书界面操作
3. 或等待 API 功能更新

---

🕐 定时任务配置（需手动启用）#

默认不启用。用户明确说「开启自动检查」后才启用。

启用后配置：

• 触发时间：每小时整点（ 0 * * * *）
• 状态文件： ~/.openclaw/workspace/.kb_organizer/status.json（权限 600）
• 日志文件： ~/.openclaw/workspace/.kb_organizer/organizer.log
• 手动整理时自动暂停
• 每次自动变更记录到日志
• 禁用命令：用户说「关闭自动检查」

执行流程#

1. 检查是否有手动操作在进行（锁文件）
2. 读取状态文件，检查各知识库进度
3. 未完成 → 输出预览方案， 等待用户批准后 执行移动
4. 已完成 → 二次检查验证分类准确性（只检查不移动）
5. 全部完成后设置 all_kbs_complete=true

安全规则#

• 自动模式下不移动含子节点的文档
• 每次变更写入日志（时间+操作+结果）
• 任务完成后清理临时日志

---

📋 实战经验总结（2026-05-14 大规模整理）#

执行概况#

• 整理规模：30个知识库，416+篇文档
• 自动化完成：18个库（62%）
• 权限问题：5个库需手动处理
• 已有结构：5个库无需整理
• 已合并：1个库（AIGC图生视频→AI视频）

关键教训#

1. 权限是最大瓶颈

• 飞书知识库只有 节点创建者或管理员 才能移动根目录文档
• 遇到 permission denied: no source parent node permission 时，需让库管理员授权
• 解决方案：提前确认当前用户对目标库有管理员权限

2. API 配额耗尽（429 quota exhausted）

• 大规模并行子任务容易打爆API配额
• 解决方案：每批最多并行3个子任务，批间等待30秒

3. 并行子任务策略

• 3个子任务并行是安全上限
• 每个子任务平均耗时10-15分钟
• 超过3个并行容易触发429

4. 三级目录拆分时机

• 二级目录>10篇 → 必须拆分三级
• 三级目录按内容属性或细分主题划分
• 实例：AI视频「六、工具与平台」29篇→7个三级目录

5. 合并库的处理

• AIGC图生视频已合并入AI视频
• 合并后的文档需要重新归类到现有目录
• 注意检查 has_child 节点，子文档会跟随移动

6. 占位符文档清理

• 整理过程中会创建空壳占位符文档
• 飞书API不支持删除节点
• 解决方案：用户手动在飞书界面删除

7. 标题分类 vs 内容验证

• 第一轮靠标题快速分类（效率高）
• 第二轮读取内容验证准确性（质量高）
• 标题模糊的文档必须读内容确认

8. 方案文档同步

• 每完成一个库，立即更新方案文档
• 使用 replace_range 模式更新对应章节
• 进度数字也要同步更新

推荐执行流程#

text

1. 扫描全部知识库 → 分类（严重/中等/轻微/已完成）
2. 严重库（40+篇）→ 3个并行子任务
3. 中等库（10-30篇）→ 3个并行子任务
4. 轻微库（<10篇）→ 快速处理
5. 每批完成后更新方案文档
6. 全部完成后内容验证
7. 占位符文档由用户手动删除

---

🔄 技能创建流程遵循 (Skill Loop)#

阶段动作执行情况1. 概念描述过程、规则✅ 2026-05-132. 原型对 3-10 个真实项手动运行✅ 2026-05-14（30个库大规模验证）3. 评估与 Boss 审查输出✅ 2026-05-14（第一性原理审查+9项优化）4. 编纂编写 SKILL.md✅ 2026-05-14（优化版写入）5. Cron添加定时任务✅ 每小时自动检查6. 监控检查首次运行✅ 已运行多次

MECE 原则：知识库整理工作仅由本技能覆盖，无其他技能重叠。