AI飞书文档索引生成器

> ⚠️ 重要提示： 本 Skill 會在飛書文檔頭部插入 AI 檢索索引區，原文完整保留在分隔線之後。文檔路徑由用戶提供，操作前會自動備份原文。

🔴 第一層：超快速判斷（3秒決定要不要用我）

📛 技能名稱

AI飞书文档索引生成器（feishu-doc-index-generator）

🎯 一句話描述

在飛書文檔頭部插入 7 字段 AI 檢索索引，讓 Agent 快速判斷是否要讀、該讀哪部分

✅ 適用場景

• 飛書知識庫文檔被 AI Agent 頻繁檢索但命中率低
• 需要讓多個 Agent 共享同一份文檔但各自判斷匹配度
• 文檔主題模糊，AI 經常誤匹配後才發現不對

❌ 絕對不要用我的場景

> 任意命中 1 條，直接關閉本文檔！

• 文檔少於 300 字（加索引的 overhead 大於收益）
• 文檔是 bitable / 表格 / 數據庫（非文字型文檔）
• 文檔從不會被 AI Agent 讀取（僅供人類閱讀）
• 文檔不允許任何內容修改（純唯讀權限）

📊 Token 消耗提示

🟠 第二層：核心能力清單（確認有用了再往下看）

🎯 我能幫你做的 5 件事

1. 生成 7 字段 AI 索引 — 在文檔頭部插入結構化索引區
2. 排除優先排序 — ❌ 排除場景排在 ✅ 適用場景前面，優先幫 AI 排除
3. 樹狀章節速覽 — 巢狀結構呈現章節層級關係
4. 12 項自動校驗 — 索引寫入後自動驗證完整性和正確性
5. 原文雙備份 + 自動回滾 — 校驗失敗自動恢復原文，零風險

💡 Agent 使用指引

> AI Agent 請注意： 讀取文檔時，先讀文檔前 500 字符（即索引區），判斷是否匹配你的任務。如果 ❌ 排除場景中有任何一條命中，直接關閉文檔，不要往下讀。如果 ✅ 適用場景中有匹配項，再根據 📑 章節速覽跳讀指定章節，不需要一次性讀完全文。

🟡 第三層：快速自測題

❓ 3 個問題自測

> 任意 1 個回答 NO → 直接關閉本文檔

1. 我有權限修改這篇飛書文檔的內容？
• 是 → 繼續
• 否 → 關閉（無法寫入索引）

1. 這篇文檔超過 300 字且主要是文字內容？
• 是 → 繼續
• 否 → 關閉（太短或非文字文檔不適用）

1. 這篇文檔會被 AI Agent 用來檢索？
• 是 → 繼續
• 否 → 關閉（純人類閱讀不需要索引）

🟢 第四層：完整目錄 + 章節摘要標籤（確定要用了才看）

> 👇 每個章節標註【核心標籤 + 字數預估】，按需跳讀

🎭 第一章：7 字段詳細規範

【標籤：字段說明、格式規範、示例】【約 600 字】

• 1️⃣ 📛 文檔名稱 — 取正式標題，太長則精簡
• 2️⃣ 🎯 一句話描述 — [動作] + [對象] + [核心價值]，不超過 50 字
• 3️⃣ ❌ 什麼時候絕對不要讀我 — 3~5 條排除場景（優先展示）
• 4️⃣ ✅ 什麼時候應該讀我 — 3~5 條適用場景
• 5️⃣ 🏷️ 核心內容標籤 — 10~15 個標籤，逗號分隔
• 6️⃣ 📊 token 預估 — 格式「約 XXX tokens（XX 分鐘閱讀）」，中文 1 字 ≈ 1.8 tokens
• 7️⃣ 📑 章節速覽 — 樹狀巢狀結構，每章節 1~2 句摘要

📚 第二章：標準輸出格式（v2.1）

【標籤：模板、Callout、標題層級】【約 400 字】

<blue callout> 👋 你好AI！這是給你看的檢索說明～ </blue callout>
## 🤖 AI檢索索引
### 📛 文檔名稱
### 🎯 一句話描述
### ❌ 什麼時候絕對不要讀我
### ✅ 什麼時候應該讀我
### 🏷️ 核心內容標籤
### 📊 token預估
### 📑 章節速覽
<gray callout> 👆 以上是Agent檢索說明，以下是原文內容 </gray callout>
[原文完整內容]

• 7 個字段全部使用三級標題（###）
• 藍色 Callout 開頭，灰色 Callout 分隔
• 原文完整保留在分隔線之後

📚 第三章：執行流程（7 步標準流程）

【標籤：工作流、步驟、安全機制】【約 500 字】

• Step 1：原文雙備份
• 備份方式 1：寫入本地 .md 文件
• 備份方式 2：內存變量完整保存
• 目的：任何校驗失敗立即回滾

• Step 2：文檔類型判斷
• 文檔少於 300 字 → 跳過（不需要索引）
• 文檔類型非 docx → 跳過（不適用）

• Step 3：文檔內容分析
• 讀取全文，理解主題和結構
• 識別核心章節、關鍵概念、技術棧

• Step 4：生成 7 個字段內容
• 按照字段規範逐個生成
• ❌ 排除場景排在最前面

• Step 5：組裝完整索引 + 覆蓋寫入飛書
• 新內容 = 索引區 + 分隔線 + 原文
• 覆蓋寫入（不是追加）

• Step 6：8 項關鍵內容校驗
• ① 藍色 Callout 存在
• ② 二級標題「AI檢索索引」存在
• ③~⑨ 7 個字段全部存在
• ⑩ 底部分隔 Callout 存在

• Step 7：校驗結果處理
• ✅ 全部通過 → 任務完成
• ❌ 任何一項失敗 → 使用備份原文回滾

📚 第四章：索引維護說明

【標籤：更新、過期、版本】【約 250 字】

• 索引區應包含生成日期：「📌 索引生成日期：YYYY-MM-DD」
• 原文更新後，索引需要重新生成（特別是章節速覽和 token 預估）
• Agent 發現索引日期過舊（>30 天），應提示用戶重新生成

📚 第五章：優化效果對比

【標籤：量化、benchmark】【約 200 字】

🔵 第五層：深度內容（真正要執行了才讀）

> ⚠️ 這部分內容比較長，建議按需跳讀，不需要一次性全部讀完。

7 字段詳細規範

1. 📛 文檔名稱

• 取文檔的正式標題
• 如果標題太長，適當精簡但保留核心信息

2. 🎯 一句話描述

• 用 1 句話（不超過 50 字）概括文檔的核心內容
• 格式：[動作] + [對象] + [核心價值]
• 示例：「詳細拆解 Claude Agent 的 7 層模塊化文件架構體系」

3. ❌ 什麼時候絕對不要讀我（排除優先！）

• 列出 3~5 個具體的不適用場景
• 站在 Agent 角度思考：什麼情況下我絕對不應該讀這個文檔？
• 排在 ✅ 適用場景前面
• 示例：
• 當你只是需要簡單問答，無需自定義配置時
• 當你使用的是 ChatGPT 而非 Claude 時
• 當你只需要使用默認配置即可時

4. ✅ 什麼時候應該讀我

• 列出 3~5 個具體的適用場景
• 站在 Agent 角度思考：什麼情況下我需要讀這個文檔？
• 示例：
• 當你需要搭建自定義 Claude Agent 時
• 當你想了解模塊化設計的最佳實踐時
• 當你需要配置 Prompt 文件架構時

5. 🏷️ 核心內容標籤

• 列出 10~15 個核心標籤，逗號分隔
• 包含：技術棧、核心概念、應用場景、文檔類型等維度
• 示例：Claude Agent, 文件架構, Prompt工程, 模塊化設計, 最佳實踐

6. 📊 Token 預估

• 格式：約 XXX tokens（XX 分鐘閱讀）
• 中文文檔約 1 字 ≈ 1.8 tokens
• 英文文檔約 1 字 ≈ 0.7 tokens
• 閱讀時間：約 400 tokens/分鐘
• 示例：約 5400 tokens（13 分鐘閱讀）

7. 📑 章節速覽（樹狀結構）

• 遍歷文檔的所有主要章節
• 使用樹狀巢狀結構呈現層級關係
• 每個章節用 1~2 句話摘要核心內容
• 格式示例：

### 📑 章節速覽
├─ 第一章：系統架構（~500 tokens）
│   ├─ 1.1 整體設計 — 描述整體架構設計理念
│   └─ 1.2 模塊劃分 — 各模塊的功能邊界
├─ 第二章：配置說明（~800 tokens）
│   └─ 2.1 環境配置 — 開發環境搭建步驟
└─ 第三章：API 參考（~2000 tokens）

8 項關鍵內容校驗

> 注意： 不使用逐字符對比（容易因飛書自動格式調整誤判），使用「關鍵內容存在性」校驗。

安全機制

雙備份機制

• 文件備份：本地 .md 文件，永久保存
• 內存備份：執行過程中內存變量完整保存
• 任意備份渠道都可以恢復原文

自動回滾機制

• 觸發條件：8 項校驗中任何一項失敗
• 執行動作：使用備份的原文覆蓋寫入
• 結果：文檔恢復到執行前的狀態

Token 消耗詳細分析

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

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

附錄：Hermes Agent 技能註冊

# 在 config.yaml 中註冊（可選）
skills:
  enabled:
    - feishu-doc-index-generator

觸發後，Agent 通過 skill_view(name="feishu-doc-index-generator") 載入本技能，然後按照 7 步執行流程處理用戶提供的飛書文檔 URL 或 doc_token。