飞书知识库整理专家

飞书知识库整理专家 核心原则（第一性原理版）

根本目标：人能在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: 批量执行 3个子任务并行（API配额上限） 每个子任务处理1个库 移动间隔2-3秒，失败重试3次 失败文档自动归入「其他」 每批完成后汇报进度 Phase 4: 验证+同步 检查每个库根目录是否清零 随机抽查5篇，确认分类正确 检查目录文档数量是否>10（需拆分） 更新方案文档 恢复定时任务 📋 优化清单（9项） 🔴 执行层优化 # 优化点 说明 1 失败文档自动归入「其他」 移动失败→重试3次→仍失败→归入「其他」，不留根目录散落 2 移动日志+回滚能力 执行前记录 node_令牌: A→B，提供反向移动回滚命令 🔴 根本机制 # 优化点 说明 3 防乱机制 新文档默认归入某个目录；定期扫描新散落文档，当天归类 4 责任人机制 每个知识库指定1个维护责任人；新文档24小时内由责任人归类 🟡 运维优化 # 优化点 说明 5 增量更新 只检查根目录新散落文档，不全量扫描 6 合并库标准流程 列出源库文档→匹配目标库目录→处理重复→删除源库 7 质量指标 检索效率（≤3次点击）、目录平衡度（<30%）、其他占比（<15%） 🟢 规范优化 # 优化点 说明 8 目录命名规范 统一「一、二、三」中文编号，子目录用「1.1、1.2」 9 跨库引用标注 方案中标注跨库引用关系，目录描述中说明关联库 执行技巧 创建文件夹节点 feishu_创建_doc( title="一、大类名称", markdown="本分类收录 XXX 相关资料。", wiki_space="" ) # 从 doc_url 提取 node_令牌(URL 最后一段) # 每次创建 1 个，间隔 1-2 秒避免锁争用

批量移动文档 feishu_wiki_space_node( action="move", node_令牌="<文档 node_令牌>", space_id="", tar获取_parent_令牌="<目标文件夹 node_令牌>", tar获取_space_id="" )

移动策略：

每次移动 1 个文档，失败后 sleep 2-3 秒重试 最多重试 3 次，仍失败→归入「其他」类 移动 has_child=true 的节点时，子文档会自动跟随移动 API 有锁争用限制，不要并行移动 权限前置验证 # 执行前验证权限 try: feishu_wiki_space_node(action="move", node_令牌=test_node, tar获取_parent_令牌=temp_dir) feishu_wiki_space_node(action="move", node_令牌=test_node, tar获取_parent_令牌=original_parent) print("权限验证通过") except 权限Error: print("❌ 权限不足，需管理员授权")

移动日志记录 # /tmp/kb_move_记录_.json { "moves": [ { "node_令牌": "xxx", "title": "文档标题", "from_parent": "原父节点", "to_parent": "目标父节点", "状态": "成功|fAIled", "timestamp": "2026-01-01T12:00:00+08:00" } ] } # 回滚：按日志反向移动

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

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

解决方案：分批处理

拆分批次 — 每批 20-25 篇 每批一个 sub代理 — 避免单个任务超时 间隔执行 — 每批完成后等待 10 秒 失败兜底 — 移动失败的文档自动归入「其他」 回头检查（必须执行）

整理完每个知识库后：

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

根目录验证：

nodes = feishu_wiki_space_node(action="列出", space_id=xxx) root_docs = [n for n in nodes if n["parent_node_令牌"] == "" and not n["has_child"]] if root_docs: print(f"⚠️ 根目录仍有 {len(root_docs)} 篇文档未移动")

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

识别场景：

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

处理策略：

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

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

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

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

状态追踪文件模板：

// /tmp/kb_move_状态_.json { "space_id": "", "kb_name": "知识库名称", "total_documents": 92, "moved_documents": [ { "node_令牌": "xxx", "title": "文档标题", "tar获取_parent": "目标 node_令牌", "tar获取_name": "目标目录名", "状态": "成功", "move_time": "2026-01-01T16:45:00+08:00" } ], "fAIled_documents": [ { "node_令牌": "xxx", "title": "文档标题", "error": "rpc fAIl", "retry_count": 3, "状态": "fAIled" } ], "pending_documents": ["node_令牌1", "node_令牌2"], "current_batch": 1, "last_检查_time": "2026-01-01T16:50:00+08:00" }

恢复机制：

sub代理 超时后，检查状态文件 pending_documents 是待移动列表 moved_documents 中失败的需要重新处理 启动新 sub代理 时，传入状态文件路径继续 常见问题 问题 解决方案 rpc fAIl / 锁争用 逐个移动，失败 sleep 2-3 秒重试 权限 denied 让库管理员授权当前用户 429 quota exhausted 每批最多3个并行子任务，批间等30秒 占位符文档需删除 API不支持删除，用户手动飞书界面删 已有目录的库 先检查现有结构，优先利用 合并库的文档 重新归类到现有目录，检查has_child节点 文档内容读取 feishu_fetch_doc(doc_id=node_令牌) 移动幂等性 已在目标位置的文档移动返回成功 小库处理 <3 篇文档保留独立库或归入「其他」 跨库移动 原则上不做，错分文档归入「其他」；用户明确同意时单独记录执行 命名规范 禁止下划线前缀、模糊命名、括号和特殊字符 🕐 定时任务配置（可选）

可为本技能配置每小时自动检查，实现智能整理 + 二次检查：

任务配置 触发时间：每小时整点（0 ） 状态文件：/tmp/kb_organizer_状态.json 日志文件：/tmp/kb_organizer.记录 手动整理时自动暂停 执行流程 检查是否有手动操作在进行（锁文件） 读取状态文件，检查各知识库进度 未完成 → 读取文档内容 + 智能分类 + 移动 已完成 → 二次检查验证分类准确性 全部完成后设置 all_kbs_complete=true 关键规则 仅移动文档，不修改/删除内容 API 超时重试最多 3 次 (sleep 2-3 秒) 二级目录>10篇必须拆分三级 内容分析：移动前读取文档内容确认分类 二次检查：所有库完成后逐一验证 📋 实战经验总结 执行概况 整理规模：30个知识库，400+篇文档 自动化完成：18个库（62%） 权限问题：5个库需手动处理 已有结构：5个库无需整理 已合并：1个库 关键教训 教训 详情 权限是最大瓶颈 只有创建者或管理员才能移动根目录文档 API配额 3个并行子任务是安全上限 标题vs内容 标题快分+内容抽验效率最高 占位符清理 整理过程会创建空壳，需手动删 三级目录拆分 >10篇必须拆，按内容属性划分 失败兜底 失败文档必须归入「其他」，不留根目录 防乱机制 新文档当天归类，不等积累 责任人 每个库指定维护人，月度检查 推荐执行流程 扫描全部 → 分类严重/中等/轻微 → 权限验证 → 暂停定时 → 严重库3并行 → 中等库3并行 → 轻微