飞书文档剥洋葱器
> ⚠️ 重要： 本 Skill 的輸出（優化後的文檔）是寫回飛書的。優化前的文檔路徑由用戶提供，優化後覆蓋原文檔或新建文檔由用戶決定。
🔴 第一層：超快速判斷（3秒決定要不要用我）
📛 技能名稱
飞书文档剥洋葱器（feishu-doc-onion-peeler）
🎯 一句話描述
將飛書長文檔改造成「剝洋蔥式」五層結構，讓 AI 檢索時先快速判斷匹配度，節省 token
✅ 適用場景
- 飛書 wiki 文檔超過 1000 字且被 AI Agent 頻繁檢索
- 飛書文檔內容涵蓋多個主題，AI 經常誤匹配
- 需要在飛書上建立可被 AI 高效讀取的知識庫
❌ 絕對不要用我的場景
> 任意命中 1 條，直接關閉本文檔！
- 文檔少於 300 字（分層反而增加 overhead）
- 文檔從來不會被 AI Agent 讀取（僅供人類閱讀）
- 文檔是表格/數據庫（bitable）而非文字型文檔
- 文檔需要保持原始排版精確不變
- 用戶只是要快速摘錄，不是要改造文檔結構
📊 Token 消耗提示
| 讀取深度 | 消耗 Token | 建議場景 |
|---|---|---|
| 只看第一層 | ~50 | 快速排除不匹配 |
| 看到第二層 | ~150 | 判斷核心能力匹配 |
| 看到第三層 | ~500 | 了解完整目錄結構 |
| 讀取全部詳情 | ~XXX | 真正要落地執行 |
🟠 第二層：核心能力清單（確認有用了再往下看）
> 👇 如果你的任務需要下面任何 3 項，繼續往下讀
🎯 我能幫你做的 5 件事
- 文檔結構改造 — 將長文檔重組為五層剝洋蔥結構
- Token 成本標註 — 為每一層標註預估 token 消耗
- 排除條件撰寫 — 幫文檔寫清楚「什麼時候絕對不要用」
- 自測題生成 — 為深度內容設計 3 道驗證問題
- 替代方案提示 — 標註可替代的短文檔路徑
💡 替代方案提示（省 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 → 恭喜你，這就是你要找的文檔！
-
我有一篇飛書長文檔（>1000 字），AI Agent 經常讀錯或用不到？
- 是 → 繼續
- 否 → 關閉（你的場景不需要結構優化） -
我能接受改造後的文檔不再是「從頭讀到尾」的線性結構？
- 是 → 繼續
- 否 → 關閉（五層結構是跳躍式的） -
我有權限修改這篇飛書文檔的內容？
- 是 → 繼續
- 否 → 關閉（你無法寫回優化結果）
🟢 第四層：完整目錄 + 章節摘要標籤（確定要用了才看）
> 👇 每個章節標註【核心標籤 + 字數預估】，按需跳讀
🎭 第一章：核心設計原則
【標籤：設計哲學、排除優先、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 字】
| 階段 | 不匹配時浪費的 token | 節省比例 |
|---|---|---|
| 原始全文 | 3000 | 0% |
| 普通分層 | 800 | 73% |
| 本 Skill 優化 | 50 | 98.3% |
> ⚠️ 注意： 以上數據僅計算「不匹配場景」。如果匹配成功，總消耗為（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 場景）
| 步驟 | Token | 累計 |
|---|---|---|
| 讀第一層判斷 | 50 | 50 |
| 發現不匹配 → 退出 | 0 | 50 |
| 總消耗 | 50 | |
| 原始消耗 | 3000 | |
| 節省 | 98.3% |
場景 B：匹配成功（需要全文）
| 步驟 | Token | 累計 |
|---|---|---|
| 讀第一層 | 50 | 50 |
| 讀第二層 | 100 | 150 |
| 讀第三層 | 350 | 500 |
| 讀第四層 | 500 | 1000 |
| 讀第五層（全文） | 3000 | 4000 |
| 總消耗 | ~3700-4000 | |
| 原始消耗 | 3000 | |
| 額外開銷 | ~700-1000（換取結構化理解） |
> ✅ 結論： 匹配成功時多花 ~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。
