來源 / 上游
- 上游: https://github.com/kangarooking/cangjie-skill
- 授權: MIT
- 內置於:
.agents/skills/book-to-skill-distill/SKILL.md供 Moi/Codex 共享安裝 - 注意: 完整流程也需要上游儲存庫中的 methodology/ 和 extractors/。
此檔案可能是內置副本或簡短指標。當上游儲存庫包含資產、腳本或 AGPL 義務時，建議安裝/複製上游儲存庫。
cangjie-skill — 把一本書蒸餾成一組可執行 skills 的元 skill
使命
把一本書裡沉澱的方法論，拆解成原子化、可被 agent 在真實場景下調用的能力，並按使用者目的編譯成合適數量的 skill，讓讀者真正用起來。
術語約定: 本文檔及
methodology/、extractors/中所有的「書」，泛指一切被蒸餾的長內容 — 書籍、長影片轉寫、播客文字稿、課程、訪談、長文、資料集。
邊界:
- ✅ 做: 方法論 / 決策框架 / 操作流程 / 計算規則 / 排障 / 清單 / 原則的蒸餾，概念體系作為參考支撐
- ❌ 不做: 書摘 / 讀後感 / 作者人設角色扮演 (後者請用 nuwa-skill)
核心方法論: RIA-TV++（v2.5 Bundle 版）
一個五階段 + 並行提取 + 三重驗證 + 晉級門 + darwin 相容測試的流水線。詳見 methodology/00-overview.md。
階段 0: Adler 整書理解 → BOOK_OVERVIEW.md
階段 1: 5 個 agent 並行提取 → 候選方法論單元池
階段 1.5: 三重驗證篩選（知識驗證） → 通過的單元 (使用者輕確認)
階段 1.6: 獨立 Skill 晉級門（產品化驗證）→ promoted / router 去向
階段 2: RIA++ 建構能力卡 → .cangjie/capabilities/cards/<slug>.md
階段 3: Zettelkasten 連結 → verified.yaml 的 also_read + GLOSSARY
階段 4: 壓力測試 (darwin 相容) → 評測用例 + 回爐淘汰
階段 5: 編譯與交付 → cangjie.py compile（single/pack）+ DIGEST.md + 安裝
v2.5 關鍵變化（ADR-002）: 階段 2–4 不再直接把每個單元寫成獨立的 Skill 目錄，而是產出一份 Capability Bundle（books/<slug>/.cangjie/capabilities/verified.yaml + cards/*.md）。single 與 pack 都從這同一份 Bundle 由 scripts/cangjie.py compile 確定性編譯，兩者引用同一組穩定 capability_id。舊的 one-to-one 輸出仍受支援（legacy-pack，見 docs/migrations/2026-08-25-v2.0-to-v2.1.md）。
何時呼叫此 skill
使用者說類似:
- 「幫我拆《窮查理寶典》」
- 「把毛選蒸餾成 skill」
- 「把這個 B 站影片/播客/課程蒸餾成 skill」
- 「distill this book into skills: 」
- 「我想把這本書的方法論做成可用的 skill」
輸入要求
在開始前必須從使用者處確認:
腳本依賴: 確定性腳本(
scripts/)需要 Python 3.10+ 與 PyYAML(python3 -m pip install pyyaml)。缺 PyYAML 時先執行python3 scripts/cangjie.py doctor自檢，它會給出安裝指引。
- 內容文字來源: PDF / EPUB / TXT / 字幕檔案 / 轉寫稿路徑，或可存取的純文字。不要在沒有文字的情況下「憑記憶」蒸餾 — 寧可停下來問使用者要。(影片/播客建議先用 video-downloader 類工具拿到轉寫文字)
- 內容元資訊: 書籍是「書名 + 作者 + 出版年」; 影片/播客/課程是「標題 + 作者(UP 主/主播/講者) + 發布時間」。用於目錄命名和稽核。
- 使用目的（決定輸出模式推薦）: 學習/查閱這本書 → 傾向 single；接入日常工作流、跨書組合 → 傾向 pack。不確定時按 single-first 原則先推薦 single。
- 是否首次試點: 如果使用者是第一次用 cangjie-skill，建議先蒸餾 1 份內容驗證流程再批量。
非書籍內容的欄位映射: 章節類欄位對影片填時間戳或分 P，對播客填集數，對課程填講次 — 保證可追溯即可。
輸出結構
books/<book-slug>/
├── PIPELINE_STATE.md # 流水線狀態: 目前階段 + 進度 (斷點續跑用)
├── BOOK_OVERVIEW.md # 階段 0 產出: 主旨/骨架/術語/批判
├── verified.md # 階段 1.5 產出: 通過三重驗證的單元 + 判定理由
├── coverage-audit.md # 原書關鍵任務 → 候選 → 判定 → 實際交付去向
├── references.md # 有依據但不執行的參考內容及交付映射
├── needs-review.md # 來源/條件/測試缺口；不編譯為 active 能力
├── GLOSSARY.md # 階段 3 產出: 全書共享術語詞典
├── DIGEST.md # 階段 5 產出: 面向讀者的精華長文
├── candidates/ # 階段 1 產出: 原始候選池 (稽核用)
├── rejected/ # 階段 1.5 淘汰的單元 + 原因 (稽核用)
└── .cangjie/ # v2.5 側車層（編譯事實來源 + 執行記錄）
├── capabilities/
│ ├── verified.yaml # Capability Bundle（唯一編譯事實來源, capability-bundle.schema.json）
│ ├── cards/<slug>.md # RIA 能力卡（R/I/A1/A2/E/B, 階段 2 產出）
│ ├── resources/ # 能力明確宣告的 UTF-8 腳本、CSV/JSON/Markdown 模板（可選）
│ ├── destinations.json # 晉級/路由去向映射（階段 1.6 產出）
│ └── book/{overview.md,glossary.md}
├── runs/<run-id>/ # 每次編譯/更新的決策報告與校驗日誌
└── snapshots/ # 發布前快照（rollback 用）
最終交付物由 scripts/cangjie.py compile 從 Bundle 編譯（--output single 得到 1 個入口 + 能力卡；--output pack 得到 1 個來源路由入口 + 少量晉級 Skill）。
執行流程 (嚴格按順序)
斷點續跑: 開始前先檢查 books/<slug>/PIPELINE_STATE.md 是否存在。存在則讀取並從記錄的階段續跑，不要從頭重來。每完成一個階段，更新該檔案。
階段 0 — 整書理解
- 讀取使用者提供的書本文字。大檔案分塊閱讀。
- 執行
methodology/01-stage0-adler.md中的 Adler 四步 (結構 / 解釋 / 批判 / 應用)。 - 按
templates/BOOK_OVERVIEW.md.template填充，寫入books/<slug>/BOOK_OVERVIEW.md。 - 把產出展示給使用者確認:「骨架我理解對了嗎?有沒有你希望重點突出的方向?」 得到確認再進入階段 1。
階段 1 — 5 個 sub-agent 並行提取
並行 spawn 5 個 Task sub-agents(使用 Agent 工具，一次呼叫中發起 5 個):
| sub-agent | 讀取的 prompt | 上下文策略 | 產出 |
|---|---|---|---|
| 框架提取器 | extractors/framework-extractor.md | 全量掃描（兼顧跨章節與單處完整機制） | 決策框架 / 思維模型 / 流程 / 排障 |
| 原則提取器 | extractors/principle-extractor.md | 全量掃描（含公式、表格、腳註） | 原則 / 清單 / 規則 / 計算口徑 |
| 案例提取器 | extractors/case-extractor.md | 檢索式取塊（局部命中型） | 書中實例、轉述案例、例題，標明類型 |
| 反例提取器 | extractors/counter-example-extractor.md | 檢索式取塊（局部命中型） | 書中警告的失敗模式 |
| 術語提取器 | extractors/glossary-extractor.md | 檢索式取塊 + 腳本預篩 | 關鍵概念詞典 |
每個 sub-agent 獨立判斷、獨立輸出到 books/<slug>/candidates/<type>.md。
- 長文字: 超出單個 sub-agent 上下文的內容，按
methodology/02-stage1-parallel-extract.md的分塊策略處理；已建立內容索引（.cangjie/index/）時，檢索式 extractor 按索引取相關塊。 - 覆蓋率硬門: 同時對照全量掃描候選和階段 0 的原書關鍵任務清單，不只檢查舊版通過項。重要任務須有候選及明確去向；有未解釋遺漏時補讀/退回全量掃描，不虛報零遺漏。
- 降級方案: 目前環境不支援並行 sub-agent 時，用同樣 5 個 extractor prompt 串行執行，產出格式不變。
階段 1.5 — 三重驗證篩選（知識驗證）
讀取 methodology/03-stage1.5-triple-verify.md，對每個候選單元執行:
- V1 來源充分性: 可定位原文足以支援限定範圍內的做法嗎？完整機制在一處講透也可通過。
- V2 可執行性: 用合法的新輸入能完成任務並核驗結果嗎？不強求跨領域外推。
- V3 任務增益: 能減少遺漏、統一口徑或穩定交付嗎？不要求作者獨創。
按 verified / reference / needs_review / rejected 分流，記錄依據及缺口；參考內容須映射到實際交付的 overview/glossary，不是所有未通過項都淘汰。更新 coverage-audit.md。
使用者輕確認 ★: 展示可執行候選、參考、待核查、淘汰四類及重要缺口，再進入階段 1.6；確認不能替代來源驗證。
階段 1.6 — 獨立 Skill 晉級門（產品化驗證）
讀取 methodology/03b-stage1.6-promotion-gate.md。知識驗證通過 ≠ 值得成為獨立 Skill。對每個單元評審五條判據（獨立意圖/獨立契約/獨立執行/獨立複用/獨立評測，前 3 條必須通過，後 2 條至少 1 條），把去向寫入 Bundle 的 promotion.destination（promoted / router）。未晉級單元不淘汰，保留為來源路由入口內的能力卡。可發現入口軟預算預設 8（含 1 個來源路由入口）。
階段 2 — RIA++ 建構能力卡
對每個通過的單元，按 methodology/04-stage2-ria-plus.md 建構 R / I / A1 / A2 / E / B 六段能力卡:
- 卡片正文寫入
books/<slug>/.cangjie/capabilities/cards/<slug>.md（不帶 frontmatter，frontmatter 數據記入 Bundle）; - 同時在
verified.yaml登記該能力: 穩定capability_id、intents、keywords、one_liner、importance（附依據）、frontmatter.description（A2 濃縮版）。 - A1 區分原書案例與明確標記的合成演練；E 明確輸入、輸出、分支和完成標準。必要時透過
resources明確宣告配套文字資源，見階段 2 說明。
階段 3 — Zettelkasten 連結
按 methodology/05-stage3-zettelkasten.md:
- 找出能力之間的引用關係，寫入 Bundle 中各能力的
also_read，並回填 A2 的「與相鄰能力的區分」 - 把
candidates/glossary.md整理成books/<slug>/GLOSSARY.md，並複製到.cangjie/capabilities/book/glossary.md - INDEX/路由表由編譯器從 Bundle 生成，不再手寫
- 把
references.md中需保留的內容併入 Bundle 的book/overview.md或book/glossary.md，在覆蓋稽核登記實際路徑；不把待核查內容偽裝為可執行方法
階段 4 — 壓力測試 (darwin 相容)
按 methodology/06-stage4-pressure-test.md，晉級能力測觸發，router 能力測可達；兩類都要實際完成代表任務並核對輸出，不能用「會呼叫」替代「做得對」。缺失輸出計入評測分母，未完成不得宣告通過。未過的回爐重做階段 2。
階段 5 — 編譯與交付
按 methodology/07-stage5-deliver.md:
- 生成
books/<slug>/DIGEST.md— 面向讀者的精華長文 - 執行
python3 scripts/cangjie.py compile --bundle books/<slug>/.cangjie/capabilities --out <目標目錄> --output auto，把決策報告展示給使用者輕確認（按推薦 / 改 single / 改 pack） - 詢問使用者安裝位置，把編譯產物複製或 symlink 過去
- 告知使用者: 「已完成，可一鍵餵給 darwin-skill 自動進化」
品質紅線 (違反則阻止輸出)
- 每個能力必須通過全部三重驗證
- 每張能力卡必須有完整的 R / I / A1 / A2 / E / B 六段；A1 無原書案例時如實標註，合成演練不冒充書中事實
- 原文引用 ≤150 字/段 (英文 ≤100 詞/段)
- 每個 active 能力在
destinations.json中恰好一個去向（promoted_to 或 served_by）;未晉級能力必須可經來源路由入口到達 - 晉級 Skill 的
description必須明確 trigger 條件，並與來源路由入口互有近鄰負例 - 編譯產物必須通過
scripts/validate_skill_pack.py（格式/相對引用/frontmatter 100%） - 生成目錄唯讀:偵測到本地手改時不得靜默覆蓋（編譯器強制三選一）
- 關鍵任務覆蓋有可追溯去向；實際輸出評測與來源核查分別記錄。存在重要缺口只能交付明確標註範圍的草稿，不能宣稱完整通過
與 nuwa-skill / darwin-skill 的生態定位
- nuwa-skill: 蒸餾人 (思維方式 / 表達 DNA)
- cangjie-skill (本 skill): 蒸餾書 (方法論 / 框架 / 原則)
- darwin-skill: 進化任意 skill
三者咬合: 本 skill 輸出的評測用例遵循 darwin-skill 格式，以便產出的 skill 可直接接入 darwin 做自動進化。
呼叫慣例
- 永遠先試點 1 本 — 除非使用者明確說「批量」
- 階段之間主動彙報進度 — 不要靜默跑完再 dump 結果
- 不憑記憶拆書 — 沒文字就停下來問
- 保留稽核軌跡 — candidates/ 和 rejected/ 都要留
- 隨時可續跑 — 每完成一個階段就更新 PIPELINE_STATE.md，中斷後從狀態檔案恢復
- 輸出策略持久化 — update/repair 預設沿用原輸出模式，不因新增材料靜默改變產物型態