Skill: lgugeng/feishu-wiki-organizer (version 1.0.1)

--- name: feishu-wiki-organizer description: | 飞书知识库专业整理工具。在不合并、不删除原文的前提下，通过内容分析实现精准分类。 支持单库整理和多库整体规划 (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. 输出最终分类方案： ``` 知识库名/ ├── 一、类目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篇必须拆，按内容属性划分 | | 失败兜底 | 失败文档必须归入「其他」，不留根目录 | | 防乱机制 | 新文档当天归类，不等积累 | | 责任人 | 每个库指定维护人，月度检查 | ### 推荐执行流程 ``` 扫描全部 → 分类严重/中等/轻微 → 权限验证 → 暂停定时 → 严重库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]) ``` **检查报告格式**: ``` ✅ [知识库名] 整理检查完成 ├── 根目录残留: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` 模式更新对应章节 - 进度数字也要同步更新 ### 推荐执行流程 ``` 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 原则**：知识库整理工作仅由本技能覆盖，无其他技能重叠。


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)