飞书知识库整理专家

SKILL.md

---
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 原则**：知识库整理工作仅由本技能覆盖，无其他技能重叠。