飞书知识库整理专家

飞书知识库专业整理工具。在不合并、不删除原文的前提下，通过内容分析实现精准分类。 支持单库整理和多库整体规划 (30+ 库规模)。 当用户提到以下场景时使用此 Skill: (1) 整理/分类飞书知识库内容 (2) 飞书知识库文档太多需要归类 (3) 为知识库创建分类目录结构 (4) 批量移动飞书知识库文档到文件夹 (5) "知识库太乱了"、"帮我整理一下"、"知识库分类" (6) 多个知识库需要统一规划、改名、补充 description 关键词：知识库、wiki、整理、分类、归档、文件夹

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

根本目标：人能在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-13
2. 原型	对 3-10 个真实项手动运行	✅ 2026-05-14（30个库大规模验证）
3. 评估	与 Boss 审查输出	✅ 2026-05-14（第一性原理审查+9项优化）
4. 编纂	编写 SKILL.md	✅ 2026-05-14（优化版写入）
5. Cron	添加定时任务	✅ 每小时自动检查
6. 监控	检查首次运行	✅ 已运行多次

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