飞书文档剥洋葱器

⚠️ 重要： 本 Skill 的输出（优化后的文档）是写回飞书的。优化前的文档路径由用户提供，优化后覆盖原文档或新建文档由用户决定。

🔴 第一层：超快速判断（3秒决定要不要用我）

📛 技能名称

飞书文档剥洋葱器（feishu-doc-onion-peeler）

🎯 一句话描述

将飞书长文档改造成「剥洋葱式」五层结构，让 AI 检索时先快速判断匹配度，节省 token

✅ 适用场景

• 飞书 wiki 文档超过 1000 字且被 AI Agent 频繁检索
• 飞书文档内容涵盖多个主题，AI 经常误匹配
• 需要在飞书上建立可被 AI 高效读取的知识库

❌ 绝对不要用我的场景

任意命中 1 条，直接关闭本文档！

• 文档少于 300 字（分层反而增加 overhead）
• 文档从来不会被 AI Agent 读取（仅供人类阅读）
• 文档是表格/数据库（bitable）而非文字型文档
• 文档需要保持原始排版精确不变
• 用户只是要快速摘录，不是要改造文档结构

📊 Token 消耗提示

🟠 第二层：核心能力清单（确认有用了再往下看）

👇 如果你的任务需要下面任何 3 项，继续往下读

🎯 我能帮你做的 5 件事

1. 文档结构改造 — 将长文档重组为五层剥洋葱结构
2. Token 成本标注 — 为每一层标注预估 token 消耗
3. 排除条件撰写 — 帮文档写清楚「什么时候绝对不要用」
4. 自测题生成 — 为深度内容设计 3 道验证问题
5. 替代方案提示 — 标注可替代的短文档路径

💡 替代方案提示（省 token！）

如果只是要下面其中一项，不要读我，去读更短的资料：

• 📝 只要「飞书 API 调用方式」→ 读《飞书 Open API 文档》（仅 ~200 字）
• 🎭 只要「Hermes Agent 技能格式」→ 读 hermes agent skill_view(name="hermes-agent-skill-authoring")
• 📊 只要「飞书文档 block 类型参考」→ 读 references/feishu-doc-block-reference.md

🟡 第三层：快速自测题

❓ 3 个问题自测

任意 1 个回答 NO → 直接关闭本文档
3 个都回答 YES → 恭喜你，这就是你要找的文档！

1. 我有一篇飞书长文档（>1000 字），AI Agent 经常读错或用不到？

   • 是 → 继续
   • 否 → 关闭（你的场景不需要结构优化）

2. 我能接受改造后的文档不再是「从头读到尾」的线性结构？

   • 是 → 继续
   • 否 → 关闭（五层结构是跳跃式的）

3. 我有权限修改这篇飞书文档的内容？

   • 是 → 继续
   • 否 → 关闭（你无法写回优化结果）

🟢 第四层：完整目录 + 章节摘要标签（确定要用了才看）

👇 每个章节标注【核心标签 + 字数预估】，按需跳读

🎭 第一章：核心设计原则

【标签：设计哲学、排除优先、token 透明】【约 300 字】

• 排除优先原则（告诉 AI「什么时候不要用」比「什么时候用」更重要）
• 逐层深入原则（每层都是可退出点）
• Token 透明原则（标注每层成本，让 AI 自己做判断）
• 替代方案原则（提供更短的替代文档路径）
• 飞书适配原则（使用飞书原生格式：callout、表格、折叠块）

📚 第二章：标准五层结构模板

【标签：模板、格式、结构】【约 400 字】

• 第一层：超快速判断（50 字）— 技能名称 + 一句话 + 适用场景 + 排除场景 + token 表
• 第二层：核心能力清单（150 字）— 5 项能力 + 替代方案提示
• 第三层：快速自测题 — 3 道是/否验证题
• 第四层：完整目录 + 章节摘要标签 — 按需跳读
• 第五层：深度内容 — 保留原始完整细节

📚 第三章：飞书格式实现指南

【标签：飞书 API、block 类型、格式限制】【约 500 字】

• 用 text block（type 2）搭配 bold 模拟标题
• 用折叠块（foldable block）封装深度内容
• 用 callout 高亮「退出信号」和「重要提示」
• 用表格呈现 token 消耗对比
• ⚠️ 飞书 API 限制：block type 3/4/12/13/22 可能返回 1770001 错误，建议只用 type 2

📚 第四章：执行流程

【标签：工作流、步骤、产出】【约 350 字】

• Step 1：读取原始文档全文
• Step 2：分析文档主题和适用场景
• Step 3：生成五层结构草稿
• Step 4：用户确认草稿
• Step 5：通过飞书 API 写回文档

📚 第五章：优化效果对比

【标签：量化、KPI、benchmark】【约 200 字】

⚠️ 注意： 以上数据仅计算「不匹配场景」。如果匹配成功，总消耗为（50+150+500+全文），约比直接读全文多 700 token，但换来的是结构化理解和精准跳读能力。

🔵 第五层：深度内容（真正要执行了才读）

⚠️ 这部分内容比较长，建议按需跳读，不需要一次性全部读完。

详细设计原则说明

1. 排除优先原则（Why it matters）

大多数技能文档只说「什么时候用」，但 AI 的 token 浪费主要来自「误匹配后全量加载」。明确告诉 AI「什么时候绝对不要用我」，能在第一层就拦截 90% 以上的误匹配。

• 排除条件必须用用户的真实场景语言写（不是技术术语）
• 每条排除条件必须「一票否决」— 命中任何一条就退出
• 排除条件放在第一层最显眼的位置（使用飞书 callout 或引用块）

2. 逐层深入原则（Onion Layer）

共五层，每层都是独立的可退出点：

第一层（~50 tokens）→ 不匹配？→ 退出（97.5% 已节省）
  ↓ 匹配
第二层（~100 tokens）→ 能力不匹配？→ 退出
  ↓ 匹配
第三层（~350 tokens）→ 自测不过？→ 退出
  ↓ 匹配
第四层（~500 tokens）→ 目录浏览，按需跳读
  ↓ 决定要读
第五层（全文）→ 真正执行

3. Token 透明原则

每一层开头标注预估 token 消耗，格式：

【本层消耗：~50 tokens | 累计消耗：~50 tokens | 退出可节省：~2950 tokens】

这让 AI（或人类）在做成本收益决策时有数据支撑。

4. 替代方案原则

如果用户只需要文档中的一小部分功能，不要强迫他读完整篇。替代方案提示需要：

• 具体指出「哪个功能」
• 具体指出「去读哪篇文档」
• 标注替代文档的长度

5. 飞书适配原则

飞书文档的 API 返回的是全文内容（raw_content），不会自动分层。因此：

• 冻结快照陷阱： 即使文档结构优化了，飞书 API 仍然会一次返回全部内容
• 解决方案： Agent 需要主动跳读。在技能执行时，Agent 应该先读第一层判断，如果匹配再继续往下读
• 替代方案： 如果飞书 API 支持分段读取（block-level read），优先使用分段读取

详细执行流程

Step 1：读取原始文档

# 通过飞书 API 读取文档全文
GET /open-apis/docx/v1/documents/{doc_token}/raw_content

Step 2：分析文档结构

• 确定文档主题、总字数、章节结构
• 判断哪些内容属于「快速判断」信息
• 判断哪些内容属于「深度内容」

Step 3：生成五层结构

• 撰写 50 字快速判断区
• 提炼 5 项核心能力
• 设计 3 道验证问题
• 生成目录 + 章节摘要
• 保留原始深度内容在第五层

Step 4：用户确认

• 展示优化前 vs 优化后对比
• 确认是否覆盖原文档或新建文档

Step 5：写回飞书

# 创建新文档或覆盖原文档
POST /open-apis/docx/v1/documents
# 逐 block 写入内容
POST /open-apis/docx/v1/documents/{doc_id}/blocks/{doc_id}/children

示例：技能文档优化前后对比

优化前（3000 字线性文档）

[从头到尾的完整叙述]
1. 什么是这个功能...
2. 功能列表...
3. 详细配置步骤...
4. API 参考...
5. 常见问题...

优化后（五层结构）

🔴 第一层：50字判断（你不是要找这个，现在就关掉）
🟠 第二层：核心能力清单（确认有用了再往下）
🟡 第三层：自测题（3个问题验证匹配度）
🟢 第四层：目录+摘要标签（按需跳读）
🔵 第五层：深度内容（真正要执行再读）

Token 消耗详细分析

场景 A：不匹配（省 token 场景）

场景 B：匹配成功（需要全文）

✅ 结论： 匹配成功时多花 ~30% token，但换来精准跳读 + 结构化理解能力。匹配失败时节省 98%。在 AI Agent 检索场景中，误匹配率通常 > 50%，所以整体 ROI 是正的。

附录：Hermes Agent 技能注册

# 在 config.yaml 中注册（可选）
skills:
  enabled:
    - feishu-doc-onion-peeler

触发后，Agent 通过 skill_view(name="feishu-doc-onion-peeler") 加载本技能，
然后按照执行流程处理用户提供的飞书文档 URL 或 doc_token。