飞书知识库整理专家

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

Audits

Pass

ClawScanReview

Agentic behavior and permission review.

Static analysisPass

Pattern checks against bundled files.

VirusTotalPass

Multi-engine malware detections and file reputation.

Install

openclaw skills install feishu-wiki-organizer

飞书知识库整理专家

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

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

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

工作流程（优化版）

Phase 0: 预检（5分钟）

获取知识库列表 → 按文档数量分类：
- 🔴 严重（40+篇散落）
- 🟡 中等（10-30篇）
- 🟢 轻微（<10篇）
- ✅ 已有结构（无需整理）
权限验证 → 试移动一篇到临时目录再移回
暂停定时任务 → 避免手动+自动同时操作

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

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

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

仅读取「待验证」文档的内容（通常≤20%）
根据内容重新归类

输出最终分类方案：

知识库名/
├── 一、类目A（X篇）
│   ├── 文档1
│   └── 文档2
├── 二、类目B（X篇）
└── 其他（X篇）

操作：创建X个目录，移动X篇
风险：X篇标题模糊已读内容确认

Phase 3: 批量执行

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

Phase 4: 验证+同步

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

📋 优化清单（9项）

🔴 执行层优化

#	优化点	说明
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>"
)

移动策略：

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

权限前置验证

# 执行前验证权限
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"
    }
  ]
}
# 回滚：按日志反向移动

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

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

解决方案：分批处理

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

回头检查（必须执行）

整理完每个知识库后：

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

根目录验证：

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 任务

执行流程

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

安全规则

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

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

执行概况

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

关键教训

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

执行技巧

创建文件夹节点

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>"
)

移动策略：

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

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

识别场景：

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

处理策略：

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

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

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

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

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

状态追踪文件模板：

// ~/.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 时，传入状态文件路径继续

回头检查 (必须执行)

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

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

根目录验证方法：

# 获取根目录所有节点
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 篇，全部归位

常见问题

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，请:

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

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

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

启用后配置：

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

执行流程

检查是否有手动操作在进行（锁文件）
读取状态文件，检查各知识库进度
未完成 → 输出预览方案，等待用户批准后执行移动
已完成 → 二次检查验证分类准确性（只检查不移动）
全部完成后设置 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 模式更新对应章节
进度数字也要同步更新

🔄 技能创建流程遵循 (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 原则：知识库整理工作仅由本技能覆盖，无其他技能重叠。

飞书知识库整理专家

Audits

Install

飞书知识库整理专家

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

工作流程（优化版）

Phase 0: 预检（5分钟）

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

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

Phase 3: 批量执行

Phase 4: 验证+同步

📋 优化清单（9项）

🔴 执行层优化

🔴 根本机制

🟡 运维优化

🟢 规范优化

执行技巧

创建文件夹节点

批量移动文档

权限前置验证

移动日志记录

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

回头检查（必须执行）

常见问题

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

执行流程

安全规则

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

执行概况

关键教训

推荐执行流程

执行技巧

创建文件夹节点

批量移动文档

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

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

回头检查 (必须执行)

常见问题

rpc fail / lock contention

node_token 获取

文档内容读取

移动幂等性

跨库移动

小库处理

命名规范

description 补充限制

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

执行流程

安全规则

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

执行概况

关键教训

1. 权限是最大瓶颈

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

3. 并行子任务策略

4. 三级目录拆分时机

5. 合并库的处理

6. 占位符文档清理

7. 标题分类 vs 内容验证

8. 方案文档同步

推荐执行流程

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