利用 Claude Code 抓取飞书知识库转换为 Skill 指南
这是什么
把飞书 Wiki 里的技术文档（Bug 案例、SOP、流程指南等）拉下来，整理成 Claude Code 插件可以直接引用的内置知识库 Skill。
产出物：skills/<name>/SKILL.md + references/*.md，纯静态文件，运行时零 API 调用。
为什么用「双终端」模式
一句话：省钱。
制作一个知识库 Skill 的工作量大致分两类：
| 工作类型 | 举例 | 特点 |
|---|---|---|
| 动脑的 | 确定知识范围、设计 Skill 结构、写 SKILL.md 路由表、Review 产出质量 | 需要强推理，量少 |
| 动手的 | 遍历飞书文档树、逐篇 fetch、清理飞书特有标签、合并整理、控制体积 | 不需要强推理，量大 |
如果全程用 Opus（贵）干，大量 token 花在「读飞书文档 → 复制粘贴 → 清理格式」这种搬砖活上，很浪费。
所以我们拆成两个终端：
1 | ┌─────────────────────────┐ 提示词文件 ┌─────────────────────────┐ |
实测下来，WiFi 知识库（4 篇飞书文档 → 5 个参考文件，共 ~44KB）的搬砖工作用 Sonnet 跑，成本大约是纯 Opus 的 1/5。Plan Model 只在开头（写提示词）和结尾（Review + 写 SKILL.md）消耗 token。
前置条件
飞书 MCP
1 | # 添加飞书 MCP（用户级，所有项目可用） |
两个终端
- 终端 A：你日常用的 Claude Code 窗口，跑贵模型（Opus）
- 终端 B：另开一个 Claude Code 窗口，指定便宜模型（
claude --model sonnet或通过 API 中转的更便宜模型）
完整流程
Step 1：确定知识范围（终端 A）
在终端 A 里，先跟 Plan Model 对齐要做什么。你需要明确：
- 领域：WiFi / Camera / Audio / 蓝牙 …
- 飞书入口：Wiki 空间 URL 或几篇核心文档的链接
- 预期产出：几个参考文件、分别覆盖什么内容
- 体积预算：单文件建议不超过 20KB（Context Window 有限）
示例对话：
1 | 你: 我想把 WiFi 团队的飞书知识库做成一个 skill， |
Step 2：写抓取提示词（终端 A）
Plan Model 生成一个提示词文件（比如 feishu-kb-fetch-prompt.md），指导 Worker Model 做什么。
提示词文件是两个终端之间的「接口契约」。 写得越清晰，Worker 越不容易跑偏，你 Review 的工作量就越少。
提示词文件应该包含：
2.1 任务说明
告诉 Worker 它要做什么、产出物是什么。
2.2 飞书文档清单
列出每篇要抓取的文档 URL，说明各自对应哪个参考文件。
1 | | 飞书文档 URL | 输出文件 | 整理要求 | |
2.3 格式规范
1 | ## 参考文件格式要求 |
2.4 输出位置
1 | 所有文件写入: |
Step 3：Worker 抓取和整理（终端 B）
在终端 B 启动便宜模型，把提示词文件喂给它：
1 | # 终端 B |
Worker Model 会：
- 读取提示词文件
- 调用飞书 MCP 的
list-docs遍历文档树 - 逐篇调用
fetch-doc拉取内容 - 按规范清理格式、去冗余
- 合并写入
references/*.md - 输出完成报告
Worker 遇到的典型问题： 飞书大文档可能需要分页 fetch（用 offset + limit 参数）；Wiki 子文档需要先 list-docs 拿到子节点再逐个 fetch；飞书 Markdown 中的 whiteboard 标签需要用 fetch-file 单独获取内容或直接删除。这些都应该在提示词里预先说明。
Worker 完成后的典型输出
1 | 完成！已生成以下参考文件： |
Step 4：Review 参考文件（终端 A）
回到终端 A，让 Plan Model 检查 Worker 的产出：
1 | 你: 帮我 review 一下 skills/wifi-knowledge/references/ 下面的 4 个文件， |
Plan Model 会逐个读取文件并给出反馈。如果有问题，修改提示词让 Worker 重跑，或者 Plan Model 直接小幅修正。
Step 5：写 SKILL.md（终端 A）
参考文件确认无误后，让 Plan Model 基于这些内容创建 SKILL.md：
1 | 你: 参考文件都没问题了。现在帮我写 SKILL.md，要求： |
SKILL.md 的关键部分
YAML Frontmatter（决定 Progressive Disclosure 是否正确触发）：
1 |
|
注意： description 必须包含具体的触发关键词（WiFi、connection failures、roaming 等），不要写泛泛的「搜索知识库」。这个字段直接决定 Claude Code 在什么时候自动加载你的 Skill。
问题分类路由表（告诉 Agent 遇到什么关键词去读哪个文件）：
1 | | 分类 | 触发关键词 | 主参考文件 | 章节 | |
实际案例：wifi-knowledge
用这个模式做的一个知识库 Skill，完整产出：
| 文件 | 说明 | 大小 |
|---|---|---|
skills/wifi-knowledge/SKILL.md |
Skill 定义：路由表 + 索引 + 流程 + 输出格式 | ~4K |
references/log-analysis-guide.md |
7 类问题的日志关键字 + regex + 示例 | 8.7K |
references/connection-flow.md |
连接链路全解 + 高通/MTK 日志 + Status Code 表 | 12K |
references/rootcause-cases.md |
25 个历史案例（含快速索引） | 20K |
references/sop-reference.md |
热点 SOP 汇总 + 分析路径 | 2.9K |
成本对比
以 wifi-knowledge 为例（4 篇飞书文档，25 个子文档，总输出 ~44KB）：
| 方案 | 模型 | 预估 token 消耗 | 相对成本 |
|---|---|---|---|
| 全程 Opus | Opus 干所有活 | ~200K（大量花在 fetch + 清理） | 1x |
| 双终端 | Opus 写提示词 + Review + SKILL.md ≈ 40K | — | — |
| — | Sonnet 抓取 + 整理 ≈ 160K | — | ~0.3x |
Sonnet 的 token 单价大约是 Opus 的 1/5 ~ 1/8。160K token 的搬砖活从 Opus 换到 Sonnet，省的钱够跑好几轮分析了。
设计要点
做：
- description 写具体触发关键词
- 参考文件控制在 20KB 以内
- 提示词文件写清楚格式要求
- 注明数据来源和更新时间
- Worker 完成后一定要 Review
不做：
- 不让 Opus 干搬砖活
- 不把飞书文档原样复制（清理 + 精简）
- 不让 description 和其他 Skill 冲突
- 不超过单文件 20KB 限制
- 不信任 Worker 的输出不检查
常见问题
Q: Worker 抓飞书文档报错怎么办？
飞书 MCP 的 fetch-doc 对超大文档可能需要分页。在提示词里加一句：「如果文档内容被截断（返回的 total_length > length），用 offset 参数分页获取」。
Q: 飞书文档里有图表/画板怎么处理？
<whiteboard> 标签无法转为文本。两种处理：用 fetch-file 工具获取画板图片看一眼内容，然后用文字描述替代；或者直接删除，在参考文件里标注「原文此处有流程图，请查阅飞书原文」。
Q: 如何更新知识库？
飞书文档更新后，重新让 Worker 跑一遍抓取提示词，覆盖 references 目录即可。SKILL.md 一般不需要改（除非新增了问题分类）。
