Day17 [llm-wiki] 引擎與燃料：skill 範本、使用時機、客製化要注意的地方

---
name: inbox-triage
description: Use when triaging Inbox/ files and folders with timestamp names, routing to domain raw/ folders
---

# Inbox Triage

分類 Inbox/ 裡的時間戳檔案和資料夾，重新命名後路由到對應域的 raw/。

## 觸發方式

`/inbox-triage` — 處理 Inbox/ 裡所有未分類檔案和資料夾
`/inbox-triage {filename}` — 處理指定單一檔案或資料夾
`/inbox-triage {自由指示}` — 例如「裡面有 url 的先不管」會作為過濾條件套用

## 核心原則：**強制匯出決策檔，不在對話中逐項詢問**

每次執行都**必須**產出一份 `Inbox/_reviews/triage-review-YYYY-MM-DD.md`（檔名含執行當日日期 stamp），把所有候選項目整理成表格交給使用者填寫。**不要**在對話內逐一詢問路由建議；對話只負責掃描、匯出、等待、執行。

若 `triage-review-YYYY-MM-DD.md` 已存在，append 新的一節 `## Run 2 / Run 3...`，不要覆蓋舊紀錄。

## 流程

### Phase 1 — 掃描與匯出

> **並行策略**：Inbox 項目 ≥ 5 個時，**並行派發** subagent 做初判（每個 subagent 讀 1–N 個項目，回傳「域 / 內容型態 / 一句摘要 / 建議路徑」結構化結果；機械分類可指定較輕模型）。主 agent 只負責**彙整成 triage-review 表**與最後路由決策。項目 < 5 個則直接 inline 處理，不必 fan-out。subagent **只讀不寫**；所有 move/delete 在 Phase 2 由主 agent 執行（單寫入點）。

1. 掃描 `Inbox/`，讀取每個檔案/資料夾內容
   - **排除**：`_` 前綴的 meta 項目（尤其 `Inbox/_reviews/` 決策檔存放夾）與任何 `triage-review-*.md`——這些是 triage 自己的產物，**永不**列為待分類項
2. 套用使用者的自由指示（例如「有 url 的先不管」→ 內含 `http://` 或 `https://` 的列入「跳過」區）
3. 對每個未跳過項目，內部判斷：
   - 域（見下方「域路由速查」）
   - **內容型態**：是「概念素材」還是「練習日記」？
     - 練習日記訊號：含時間戳 + 當日體感 / 單次練習觀察 / 短篇日誌格式（去處：`{domain}/logs/`）
     - 概念素材訊號：知識整理、文章摘錄、想法 essay
   - 一句摘要
   - 建議路徑：
     - 練習日記 → `{domain}/logs/YYYY-MM-DD.md`（YYYY-MM-DD 從內容時間戳取，無時間戳則用檔名 timestamp 當日）
     - 概念素材 → `{domain}/raw/{檔名}`（中文內容用中文檔名 ≤ 8 字；英文用 kebab-case ≤ 5 詞）
     - 書籍 → `books/raw/{書名}.md`（扁平單檔，書名作檔名）；若該書已有檔，新素材 append 成 `## {原檔名}` 區段，不另建檔；書籍圖片入 `books/raw/_attachments/`
4. 輸出 `Inbox/_reviews/triage-review-YYYY-MM-DD.md`，格式如下：

```markdown
# Inbox Triage Review — YYYY-MM-DD

每行後面填 `ok` / `skip` / 改路徑 / `刪除` / `需要 enrich` / `需要 note_explore` / `需要 wiki_build` / `建造` / 其他指令。完成後告訴我「處理」。

## 跳過（依 {使用者過濾條件} 不動）

- `{原檔名}` — {跳過原因，例如 "Threads link"}
- ...

## 待決定

| # | 原檔名 | 摘要 | 建議路由 | 決定 |
|---|--------|------|----------|------|
| 1 | `{原檔名}` | {一句摘要} | `{domain}/raw/{建議檔名}` | |
| 2 | ... | ... | ... | |
```

5. 告訴使用者：「已輸出 `Inbox/_reviews/triage-review-YYYY-MM-DD.md`，請填好決定後說『處理』。」**對話到此結束**，等使用者回覆。

### Phase 2 — 執行決策

使用者說「處理」後：

1. 重新讀取 `Inbox/_reviews/triage-review-YYYY-MM-DD.md`，解析每行的「決定」欄
2. 解析規則：
   - `ok` / `OK` / 空白 → 套用建議路由（移動 + 重命名）
   - `skip` / 留空指示性文字（例如「想要找個地方放這些」）→ **不處理**，留在 Inbox
   - `刪除` / `delete` → `rm` 該檔
   - `需要 enrich` / `需要 note_explore` / `需要 wiki_build` / `建造` / `需要擴充` 等**指向後續 skill** 的決定 → 見下方「核心規則」，**一律寫進根目錄 `TODO.md`**
   - 自定路徑（例如 `engineer/raw/foo.md`）→ 用該路徑取代建議路由
   - 其他自由指示 → 比照上一條寫進 `TODO.md`，不自動臆測執行

   **核心規則：需要 skill 協助的 note 一律入 `TODO.md`。** 任何決定欄指向需要後續 skill（`enrich` / `note-explore` / `wiki-build` / `建造` / `擴充` …）的項目，**不可只在對話提一句**——必須在根目錄 `TODO.md` 追加一條 TODO，格式：

   `- [ ] {動作}：{一句摘要} → \`{新檔路徑}\``（若原檔仍留 Inbox 待後續，括號附原素材路徑）

   - 動作命名對齊既有 skill：`note-explore（新 session 深化）` / `enrich` / `wiki-build` / `建造`。
   - 寫入區段：**一律**追加到 `TODO.md` 的 `## FROM INBOX-TRIAGE` 區段（統一收納，**不分散**到 Articles / Coding / Thinking）。若該區段不存在，在 `TODO.md` 頂端新建 `## FROM INBOX-TRIAGE`。
   - 若該項在 Phase 2 內已**當場派 subagent 跑掉**（如直接 enrich/note-explore），TODO 改記「後續可深化」或省略——已落地的不重複掛。
3. 執行所有可立即動作的項目（move / delete）。**每個 move 前先改 backlink**：
   - 對每個即將被移動/改名的 Inbox 檔案，先用 `grep -rl` 掃全 vault（排除 `Inbox/_reviews/`）找出引用舊檔名的地方——含 `[[Inbox/{原檔名}]]` 全路徑寫法，以及 `[[{原檔名}]]`（不含副檔名）裸名寫法。
   - 掃到的每個引用，改寫成目標新檔案的最短路徑 wikilink（例如 `[[Inbox/20260701-1200]]` 或 `[[20260701-1200]]` → `[[{新檔名}]]`，新檔名為移動後的 basename，不含 domain 路徑前綴）。
   - **先改 backlink、後搬檔**：確保搬完當下該連結已指向新名字，不留一拍斷鏈的窗口。
   - 若掃到多個引用來源檔，逐一改寫並在下方 log 摘要註記受影響的檔案數。
   - 找不到任何引用 → 略過，不用特別記錄。
4. **寫 `TODO.md`**：把步驟 2 蒐集到的「需要 skill」項目逐條 append 到根目錄 `TODO.md` 的 `## FROM INBOX-TRIAGE` 區段（含動作 + 新檔路徑）。`TODO.md` 是核心行動中樞，這是 triage 的固定輸出，不可遺漏。
5. **記錄**：append 本次 triage 摘要到當月 `log/YYYY-MM.md`（檔不存在就建，檔頭沿用既有月檔格式）。triage-review 檔本身即稽核軌跡。

```
## [YYYY-MM-DD] triage | N 項處理（M 移動 / K 刪除 / S skip / T 寫入 TODO.md / B backlink 已改）
- {原檔名} → {目標路徑 or "刪除" or "skip" or "TODO.md：{動作}"}（backlink 改寫：{受影響檔案清單 or "無"}）
- ...
```

6. 告訴使用者執行結果摘要，並列出**已寫入 `TODO.md` 的待辦清單**與**已改寫 backlink 的檔案清單**（若有）。
7. **管線推進（收尾必做）**：
   - 若 TODO.md 本輪有新增項目 → 主動問：「要現在接著跑其中哪個？」（enrich / note-explore / wiki-build）
   - 路由後檢查目標域：若該域 `raw/` 已聚集 **≥ 5 個同主題檔**且無對應 wiki 頁 → 主動提議「`{domain}` 的 {主題} 已累積 N 份素材，要排 `/wiki-build` 消化嗎？」不強制執行，提議即可。

### Phase 3 — 清理（選用）

決策檔自始即寫在 `Inbox/_reviews/`（不污染 Inbox 主視圖、留作稽核軌跡）。所有項目處理完畢後，**預設不刪、不再搬動**——`Inbox/_reviews/` 就是它的最終歸宿。除非使用者明確要求，否則不刪。

## 命名範例

- 內容是 V60 沖煮文章（英文）→ `coffee/raw/v60-brewing-guide.md`
- 內容是《原子習慣》書摘 → `books/raw/原子習慣.md`
- 內容是 Karpathy 的文章（英文）→ `engineer/raw/karpathy-llm-wiki.md`
- 資料夾包含多個相關檔案 → `engineer/raw/ai-system-design/`（保持資料夾結構）
- 內容是某天的練習心得 → `{domain}/logs/YYYY-MM-DD.md`（logs 型）

## 域路由速查（換成你自己的域）

- `books` — 書籍筆記專用（讀後感、書摘）
- `engineer` — 工具／流程／系統設計／技術文章
- `ideas` — 個人觀察、碎片想法、跨域探索
- `others` — 無明確域歸屬的素材先停這裡，合法，不硬塞域
- `{你的域}` — 一句話說明收什麼

**Logs 型識別**：內容是時序型的單日體感／練習觀察 → 路由到 `{domain}/logs/YYYY-MM-DD.md` 而非 raw/。同日已有 logs 檔：同主題 append 到既有檔；不同 session 改用 `YYYY-MM-DD-{slug}.md` 並提示使用者。

## 成功標準

執行完 Phase 2 後逐一確認：
- [ ] 所有 `ok` 項目已移到對應 `{domain}/raw/`
- [ ] 所有 `刪除` 項目已從 Inbox 移除
- [ ] `skip` 與 `需要 note_explore` 項目仍在 Inbox
- [ ] 每個被移動/改名的檔案，移動前已 grep 全 vault 找出引用舊 Inbox 檔名的 wikilink（含 `[[Inbox/...]]` 與裸名形式）並改寫為指向新檔名
- [ ] **所有「需要 skill」項目（enrich / note-explore / wiki-build / 建造 / 擴充）已逐條寫入根目錄 `TODO.md`，含動作 + 新檔路徑**
- [ ] 已 append 本次紀錄到當月 `log/YYYY-MM.md`
- [ ] 使用者收到執行摘要與 `TODO.md` 待辦清單

---
name: wiki-query
description: Use when querying the knowledge base for a specific question using index-accelerated lookup without scanning the full vault
---

# Wiki Query

索引加速查詢，不掃全 vault。三步定位目標頁後合成答案。

## 觸發方式

`/wiki-query {問題}`

## 行動前陳述

執行前先說：「問題涉及 {推斷的域}，我會依 CLAUDE 路由規則讀取 `{domain}/index.md` 與相關頁面（預計 2–4 頁）。」
若問題橫跨多域，明確說明將讀取哪幾個域的 `{domain}/index.md`。

## 流程

1. 依 topic 與 CLAUDE 路由規則判斷問題涉及哪些域
2. 讀取 `{domain}/index.md` → 找到相關頁面名稱
3. 只讀那幾個頁面（通常 2–4 頁）→ 合成答案
4. 回答格式：
   - 主要答案（清晰、有結構）
   - 引用來源：[[page/path]]
   - 延伸閱讀：[[related/page]]（若有）
5. 若答案有長期保留價值，**escalate to `/wiki-build {topic}`**——本 skill 不直接寫 wiki 頁。理由：單問題 → 單頁的轉換容易壓縮過頭、reference 不足，wiki-build 有反壓縮紀律。

## 被其他 skill 調用時（整合模式）

當其他 skill（例如 wiki-build）呼叫本技能做去重時，使用精簡輸出：

1. 先按同樣規則讀 `{domain}/index.md`，再讀 1–3 個最相關頁
2. 回傳三段結果：
   - `判斷`：`新建` / `整合到既有頁`
   - `目標頁`：`[[page/path]]`（若有）
   - `差異摘要`：一句話說明新內容與既有頁差異
3. 若 `index.md` 找不到相關條目但疑似漏索引，明確附註「建議先執行 `/vault-maintain {domain}`（單域快掃）」

## 重要原則

- 不跳過 index 直接掃 wiki/ 資料夾
- 若 index 中找不到相關條目，告知使用者並建議執行 /vault-maintain {domain} 檢查是否有頁面未被索引

## 成功標準

- [ ] 答案有明確引用來源（[[page/path]]）
- [ ] 若答案值得保留，已詢問使用者是否建立 wiki 頁
- [ ] 若 index 中找不到，已告知使用者並建議執行 /vault-maintain {domain}
- [ ] 若為整合模式，已回傳 `判斷/目標頁/差異摘要` 三段結果

---
name: wiki-build
description: Use when consolidating multiple raw/ files (and optional Inbox notes) into a new or existing wiki page, especially when expanding a thin wiki page that needs more detail and references
---

# Wiki Build

把多份 raw/ + Inbox 內容整合 / 擴充成 wiki 頁。**整合是擴張 + 去重，不是壓縮。**

## 觸發方式

`/wiki-build {topic}` 或對話中收到「把 X 整合進 wiki」「擴充 wiki/Y」這類請求。

## 行動前陳述

執行前先列出：

1. **來源清單**：所有相關 raw/、Inbox/、既有 wiki/ 頁，含各檔行數
2. **目標頁路徑**：新建 vs 擴充既有
3. **預估產出規模**：建議 ≥ 來源加總 × 0.7（去重後底線；< 0.5 視為過度壓縮）
4. **既有 wiki 處理策略**：哪些保留為 wikilink + 摘錄、哪些要併入

例：「整合 hermes-agent — 來源 4 份（raw 164+89 行 / Inbox 24 行 / 既有 wiki 85 行），目標 `engineer/wiki/hermes-agent.md`（擴充），預估 ≥ 250 行。provider-strategy / claude-code-vs 保留為 wikilink + 1-2 句摘錄。」

## 流程

1. **列來源**：`ls`/`grep` 找出 `{domain}/raw/`、`Inbox/`、`{domain}/wiki/` 中相關檔
2. **去重檢查**（呼叫 `wiki-query` 的整合模式）：避免重建已存在概念
   - 若有 ≥ 3 個候選既有頁需比對，**並行派發** subagent 各比一頁（回傳「重疊度 / 差異摘要 / 建議：併入或新建」），主 agent 彙整後決策；候選 < 3 則 inline 比對
3. **逐源完整讀取**：標記每個重要概念的來源出處（檔名 + 行段）
4. **大綱合成**：每章節旁註 source（例 `## Memory 架構 ← [[architecture]] L43-62 + [[20260505_inbox-note]] L5`）
5. **撰寫**，遵守內容守則（見下）
5.5. （選用）撰寫完成後，直接套用你自己的文字收斂規則（例如段落長度上限、禁用詞），不要先問使用者。
6. **Reference 區強制 ≥ 5 條**：≥ 2 wikilinks + ≥ 2 外部 source + ≥ 1 探索筆記（raw/）回鏈
6.5. **跨域連結 pass**（收尾必經）：拿本頁 summary + tags 掃**其他域**的 `index.md`（只讀索引行，不讀全文），挑最多 3 個候選頁、各附一句關聯理由（互相支持或互相打架都算）。列給使用者確認，**確認後才寫入**：本頁 Reference 追加 `[[候選頁]]`，候選頁 Reference 補反向連結。無合適候選就明說「本次無跨域候選」，不硬湊。
7. **更新 `{domain}/index.md`**：若新建頁或 summary 有變
8. **Append `log/YYYY-MM.md`**（當月檔，不存在就建）：operation 用 `build`

## 內容守則（防壓縮）

| 守則 | 為什麼 |
|------|--------|
| 所有 source 引用與 Reference 條目一律用 `[[note-name]]`（Obsidian shortest-path），不寫 `raw/filename` 純文字或 `[[domain/raw/filename]]` 全路徑 | 全路徑在 Obsidian 中無法解析為雙向連結 |
| 正文不寫行內 citation（`← [[note]] L##`）；來源追蹤統一放頁尾「Sources by section」表 | 行內 citation 干擾閱讀，讀者習慣到底部查來源 |
| Raw 裡的 H3 小節，wiki 對應位置也應為 H3，不要合併入單一表格 | 表格適合掃描，但會丟失推理鍊與例子 |
| 可運行範例（程式碼、命令、URL）全部保留 | 這是 wiki 對 LLM 的高密度價值 |
| Wikilink 出去 ≠ 不寫：被引用的頁要有 1–2 句摘錄 + 連結 | 純連結讓讀者跳走後失去 context |
| 每個外部資源（GitHub repo / 標準 / 工具）獨立列出 | Reference 不是裝飾 |
| 「我的觀察」「沒涵蓋」段落保留 | vault 主人的判斷信號，未來自己會回頭參考 |
| 子模組路徑（`run_agent.py`、`gateway/run.py` 等）保留 | 之後查 codebase 直接定位 |

## 紅旗（出現要停下）

- 「讓我整理一下這個列表 / 表格」→ 你是不是把推理鍊壓掉了？
- 「這部分 X 頁已有，連過去就好」→ 在這頁的讀者跳得回來嗎？
- 「精簡為一句話」→ 你在丟資訊還是真有共識可拍板？
- 產出 < 來源加總 × 0.5 → 過度壓縮，回去補

## 成功標準

- [ ] 行動前已列來源清單 + 預估規模
- [ ] 每章節有 source 標註（在 outline 或頁尾「Sources by section」表）
- [ ] 所有 source 引用與 Reference 條目使用 `[[note-name]]` 格式（Obsidian shortest-path wikilink），**不**寫 `raw/filename` 純文字或 `[[domain/raw/filename]]` 全路徑
- [ ] 正文無行內 citation（`← [[note]] L##`）；來源追蹤統一在頁尾「Sources by section」表
- [ ] Reference 區 ≥ 5 條（含 ≥ 2 wikilinks + ≥ 2 外部）
- [ ] 沒有「純連結出去無摘錄」的既有 wiki 引用
- [ ] Raw 中的可運行範例（cmd / code / URL）全保留
- [ ] （若有設定）已套用文字收斂規則
- [ ] 已跑跨域連結 pass（候選 ≤ 3、附理由、經使用者確認才寫入；無候選需明說）
- [ ] `{domain}/index.md` summary 對齊
- [ ] 當月 `log/YYYY-MM.md` 已 append（operation: `build`）

---
name: note-enrich
description: Use when a note (an Inbox file, an existing raw/logs markdown file, or a plain-text topic) needs web research folded in to fill gaps; researched facts are woven into the note in place with clickable markdown-link sources for web pages (wikilinks reserved for internal vault notes), never as a separate appended section
---

# Note Enrich

對任何 note 做網頁搜尋擴充：查到的事實**就近融入**筆記相關段落（外部來源帶可點 `[標題](url)`），不另立 section、不改寫原句。輸入三態——Inbox 檔、既有 `raw/`/`logs/` markdown 檔、純文字 topic。

## 觸發方式

- `/note-enrich {路徑}` — 對指定檔案 enrich（Inbox 檔 / `{domain}/raw/` 檔 / `{domain}/logs/` 檔）
- `/note-enrich {純文字 topic}` — 對一個主題直接查網路並沉澱成新 raw 檔（無對應檔時）
- `/note-enrich {路徑或 topic} {自由指示}` — 例如「重點查 v60 水溫範圍」「不要查歷史背景」作為查詢方向／過濾條件
- `/note-enrich` — 掃 Inbox/，列出「內容明顯不足」候選（< ~150 字、只有片段、含 URL 無摘要等）讓使用者選一個處理

### 輸入判別（arg 是檔案還是純文字 topic）

依序把第一段 arg 嘗試解析成路徑：`Inbox/{arg}` → 各 `{domain}/raw/{arg}` → 各 `{domain}/logs/{arg}`（也接受使用者直接給的完整相對路徑）。

- 解析到實體檔案 → **檔案模式**（再依所在目錄細分 Inbox / raw / logs / wiki）
- 解析不到任何檔 → **純文字 topic 模式**

無旗標、零額外語法。

## 核心原則

1. **原句與段序不動**（檔案模式）— 查到的資訊以句子／子項**就近插入**相關段落，**不改寫原句、不重排原段落、不另立分隔標題**（不使用 `## Web Research` 之類的附錄 section）。純文字模式無原始檔，直接寫成連貫一篇
2. **每筆網路資訊都要 source 標註（區分內外部）** — **外部網頁一律用標準 markdown 連結 `[標題](https://...)`**（可點、直接開瀏覽器）；`[[wikilink]]` **只保留給 vault 內部節點**（別的筆記／書頁／wiki）。不匿名、不寫裸 URL，**不可**把網址塞進 `<!-- -->` 註解（在閱讀模式看不到也不能點，且 `[[外部標題]]` 會被 Obsidian 當成未建立的內部筆記，點下去誤建空白頁）
3. **查詢前必須先給使用者看問題清單** — 避免 WebSearch / WebFetch 跑無關查詢浪費成本與時間
4. **重跑防重複** — 對已 enrich 過的檔重跑時，先讀全文比對，避免重插已存在的事實（無日期段可依循，靠內容判斷）
5. **wiki/ 目標一律擋** — wiki 是策展、自包含節點，不接受網路素材就地插入污染；偵測到 `{domain}/wiki/` 目標即拒絕（見 Phase 1）

## 流程

### Phase 1 — 讀取、判別、gap 分析

1. **輸入判別**（見上）決定模式
2. **wiki/ 守門**：若解析到的檔在 `{domain}/wiki/` 下 → **不執行**，回覆：
   > 目標是 wiki 頁（策展、自包含），不就地插入網路素材以免污染。建議：把素材丟對應 `{domain}/raw/`，或用 `/wiki-build` 策展擴充。
   結束，不進 Phase 2。
3. 檔案模式：讀取目標檔**全文**。純文字模式：以 topic 為分析對象，跳過讀檔
4. **若內文含 URL（非 YouTube）→ 先用 `WebFetch` 抓內容**，避免只憑檔名/片段亂猜主題
   - YouTube URL（含 `youtube.com` / `youtu.be`）→ 暫不處理該 URL，Phase 3 保留原樣並在對話提醒「YouTube URL 待人工轉錄回填」，跳過
5. LLM 內部分析（含 URL 內容）：
   - 主題與可能的域歸屬（依你的域清單）
   - **3–5 條具體查詢問題**（可直接交給搜尋引擎，如「v60 的標準水粉比是多少？」「TSMC 2025Q1 毛利率與前一季比較？」）
6. 對話內輸出簡短報告（**不寫 review 檔**）：

   檔案模式：
   ```
   檔案：{路徑}
   模式：{Inbox → 搬 raw / 既有 raw、logs → 原地融入}
   主題：{推測主題，一句}
   建議域：{domain}（信心：高/中/低）   ← 僅 Inbox 模式需判域

   建議查詢（{N} 條）：
   1. {問題1}
   ...
   要 go / 改清單 / 取消？
   ```

   純文字模式：
   ```
   Topic：{原文}
   主題：{推測主題，一句}
   建議域：{domain}（信心：高/中/低）
   建議新檔：{domain}/raw/{slug}.md

   建議查詢（{N} 條）：
   1. {問題1}
   ...
   要 go / 改清單 / 取消？
   ```

7. 等使用者回應。`go` / `ok` / `查` → 進 Phase 2；其他 → 依指示調整問題後再問。域信心「低」時，Phase 1 就先問使用者，不亂寫

### Phase 2 — 網路查詢

對每條問題：
1. `WebSearch` 查問題 → 拿到候選 URL + snippet 列表
2. 從候選中挑 1–3 個最相關的（官方文件、技術部落格、StackOverflow 等優先；論壇雜訊降權）
3. `WebFetch` 抓挑出的 URL 的詳細內容，prompt 直接寫該問題以聚焦摘要
4. 收集每個 URL 的 page title 與 URL 本身，作為 source citation 來源

失敗處理：
- WebSearch 無結果 → 該問題標記「查詢失敗：無相關結果」，Phase 3 不插入該點
- WebFetch 失敗（403 / robots.txt / 重新導向）→ 換下一個候選
- 全部失敗 → 該問題標記失敗，**不中斷其他問題**

### Phase 3 — 融入與落地

**融入方式（所有檔案模式共用）**：把每條查到的事實，就近插入原內容相關段落之後（新句或子項），句尾附來源連結——**外部網頁用 `[標題](https://...)`**（完整可點 URL，不用 `<!-- -->` 註解），vault 內部節點才用 `[[note-name]]`。**不改寫原句、不重排原段落、不加分隔標題**。找不到明確落點的事實，插在最相關段落結尾；真的無處可插的補充，收在原內容最末（仍不加標題）。

依模式分流：

- **Inbox 模式**：就近融入原內容 → 補齊 frontmatter（見下）→ 寫入 `{domain}/raw/{slug}.md` → 確認寫入成功後**刪除原 Inbox 檔** → log
- **既有 raw / logs 模式**：就近融入原檔 → **原檔不搬、不刪、不改名**（原地覆寫內容）→ log。原檔缺 frontmatter **不強制補**（尊重 logs 慣例）
- **純文字模式**：無原始檔，直接把查到的資訊寫成**連貫一篇**（frontmatter + 內文，句子帶外部來源 `[標題](url)`，無 Web Research 標題）→ 寫入 `{domain}/raw/{slug}.md` → log

**frontmatter**（Inbox 模式補齊、純文字模式新建；raw/logs 已有則不動）：
```yaml
---
summary: {LLM 綜合內容 + 網路結果寫的一句摘要}
tags: [{推測 tags, kebab-case, 3–6 個}]
date: YYYY-MM-DD
source: enriched   # 純文字模式可用 enriched-from-topic
---
```

**命名規則**（與 inbox-triage 一致，不另創）：
- 中文內容 → 中文檔名 ≤ 8 字
- 英文內容 → kebab-case ≤ 5 詞
- 書籍 → 扁平單檔 `{書名}.md`（已有檔則就近融入既有內容）

**log/YYYY-MM.md append**（當月檔，不存在就建）：
```
## [YYYY-MM-DD] enrich | {來源描述} → {結果路徑}
- 融入 {N} 條 web research（{M} 成功 / {K} 失敗）
- 來源：{總 source 數} 個來源連結 citations
```
來源描述：Inbox 模式 `{原檔名}`；raw/logs 模式 `{原路徑}（原地）`；純文字模式 `topic:{原文}`。

## 命名範例

- Inbox `2026-05-09-某咖啡筆記.md` 主題 V60 → `coffee/raw/v60沖煮筆記.md`
- 既有 `coffee/raw/烘焙度.md` → 原地融入，路徑不變
- 純文字 `咖啡烘焙度的名稱與顏色表` → `coffee/raw/烘焙度色階.md`

## 與其他 skill 的分工

| Skill | 處理場景 |
|-------|---------|
| `inbox-triage` | 直接知道要放哪、**不需查資料** |
| `note-enrich` | 需要**網路補充**才能歸位／補完，或想對一個主題直接查網路沉澱 |
| `note-explore` | 內容夠但要**靈魂拷問**、發散探索 |
| `wiki-build` | 要把 raw 素材**策展合成**為 wiki 頁（wiki 擴充走這條，不走 note-enrich）|

## 失敗處理

- WebSearch / WebFetch 全部失敗：檔案模式**維持原檔不動**、純文字模式仍建檔但內文標 `> [!warning] 全部查詢失敗，待手動補`，**不卡流程**；對話回報
- 域判斷不確定（信心「低」）：Phase 1 對話內就問使用者，**不亂寫**
- 寫入 / 融入過程任何錯誤 → **保留原檔**（Inbox 檔不刪、raw/logs 原檔不覆寫），回報錯誤
- wiki/ 目標：Phase 1 直接擋下並提示，不查詢、不寫入
- YouTube URL：暫不處理，保留原樣，提醒人工轉錄回填後再跑一次

## 成功標準

- [ ] 三模式落地位置正確：Inbox → 搬 `{domain}/raw/`；raw/logs → 原地；純文字 → 新 `{domain}/raw/`
- [ ] wiki/ 目標被擋下，未查詢未寫入
- [ ] 查到的事實**就近融入**相關段落、外部來源帶可點 `[標題](url)`（**非** `[[wikilink]]`、**非** `<!-- -->` 註解），**無** `## Web Research` 分隔標題
- [ ] 檔案模式原句與段序未被改寫／重排
- [ ] Inbox 模式原檔已刪除（除非出錯）；raw/logs 原檔未搬未刪
- [ ] 當月 `log/YYYY-MM.md` 有本次 `enrich` 紀錄

---
name: note-explore
description: Use when the user wants to deeply question or divergently explore a note file — soul-questioning its assumptions and branching into connections
---

# Note Explore

針對一篇筆記進行對話式深度探索：靈魂拷問（挑戰假設）＋發散（延伸連結）。
**核心精神：這是對話，不是獨白。** Claude 提問，等使用者回應，再推進。

## 用法

```
/note-explore {file-path}
```

## 流程

### 準備
讀取目標檔案，用 1 句話說明你對筆記核心主張的理解，然後進入 Phase 1。

---

### Phase 1：靈魂拷問（對話式）

挑出 **最犀利的 2–3 個問題**，直接問使用者——不要自己回答。

問題類型選擇最有殺傷力的：
- **假設挑戰**：這個主張成立的前提是什麼？那個前提可靠嗎？
- **矛盾偵測**：筆記內有沒有互相矛盾的地方？
- **所以呢？**：如果這是真的，最重要的含義是什麼？
- **反例**：什麼情況下這個觀點會失效？
- **邊界測試**：這個概念的適用範圍在哪裡？

格式：
```
**Q1：[問題]**

**Q2：[問題]**

**Q3：[問題]**（可選）

你想從哪個問題開始？或是直接回答你想談的。
```

**等使用者回應後：**
- 針對他的回答深入追問或點出盲點（不超過 2 句 + 1 個追問）
- 若使用者回答完所有問題，或說「繼續」，進入 Phase 2

---

### Phase 2：發散（對話式）

提出 **4–6 個延伸方向**，必須同時涵蓋正向、反向、以及其他角度，請使用者選一個或多個深入。

方向分類（每次至少包含以下三類）：

**正向**（支持、延伸、應用）
- **強化論據**：哪些證據或案例能讓這個主張更站得住腳？
- **行動轉化**：這個洞見可以變成什麼具體行動或實驗？
- **Vault 內連結**：與哪些已有頁面或概念相關？（用 `[[wikilink]]`）

**反向**（挑戰、否定、邊界）
- **對立視角**：誰會強烈反對？他們最強的理由是什麼？
- **失效條件**：什麼情況下這個觀點會完全失效？
- **代價**：接受這個觀點需要放棄或忽略什麼？

**其他方向**（跳脫、重組、深挖）
- **跨域應用**：這個概念能移植到哪個不同領域？
- **換個層次看**：從更宏觀或更微觀的角度，這件事變成什麼？
- **深挖方向**：哪一個子問題值得單獨開一篇 wiki 探討？

格式：
```
**發散方向：**

🟢 正向
1. [標題] — [一句說明]
2. [標題] — [一句說明]

🔴 反向
3. [標題] — [一句說明]
4. [標題] — [一句說明]

🔵 其他
5. [標題] — [一句說明]
6. [標題] — [一句說明]

你想往哪個方向走？
```

**使用者選擇後：**
- 針對選定方向深入展開（100–150 字），然後再問一個推進問題
- 使用者說「繼續」或「總結」時，進入 Phase 3

---

### Phase 3：完整綜合回應

對話結束後，主動產出一份完整的探索總結，整合整段對話的洞見。

格式：
```
## 探索總結：[筆記標題]

### 核心主張（重新詮釋）
[用對話後更深的理解，重新表述這篇筆記的核心，1–2 句]

### 關鍵洞見
- [洞見 1]：[說明]
- [洞見 2]：[說明]
- [洞見 3]：[說明]

### 正反張力
| 正向 | 反向 |
|------|------|
| [支持論點] | [挑戰論點] |
| [支持論點] | [挑戰論點] |

### 未解問題
- [對話中浮現但沒有解答的問題]

### 建議後續行動
- [具體行動或下一步探索]
```

產出後詢問：「要把這份探索存入 wiki 嗎？」

**若來源檔案在 `Inbox/`**，在 wiki 存入問題之後，額外提示：
「`{原檔名}` 仍在 Inbox，建議移至 `{domain}/raw/{新檔名}`，確認嗎？」
- 新檔名規則同 inbox-triage：中文內容用中文名、英文用 kebab-case，raw 名與對應 wiki／概念名對齊
- 使用者確認後執行 `mv`，並在 `log/YYYY-MM.md` append（當月檔，不存在就建）：
  ```
  ## [YYYY-MM-DD] triage | {原檔名} → {domain}/raw/{新檔名}
  ```

---

### 儲存（僅當使用者確認時）

固定寫入 wiki，不寫回原筆記。

1. 判斷筆記所屬域（從檔案路徑推斷）
2. 在 `{domain}/wiki/` 建立新頁，檔名為 `explore-{slug}-{YYYY-MM-DD}.md`
3. 內容為 Phase 3 的完整總結，加上 frontmatter：
   ```yaml
   ---
   summary: [一行摘要]
   tags: [explore, {domain}]
   date: YYYY-MM-DD
   source: "[[{原筆記相對路徑}]]"
   ---
   ```
3.5. （選用）寫入前直接套用你自己的文字收斂規則，不要先問使用者。
3.6. **跨域連結 pass**：拿探索總結的核心主張掃**其他域**的 `index.md`（只讀索引行），挑最多 3 個候選頁、各附一句關聯理由，列給使用者確認後才寫入（本頁 Reference + 候選頁反向連結）。無合適候選就明說，不硬湊。
4. 更新 `{domain}/index.md`，新增條目
5. **若來源檔案在 `Inbox/`**（由 Phase 3 後的確認步驟處理，此處跳過，避免重複詢問）

---

## 行為準則

- **問完就停**：丟出問題後，不要自己接著回答，等使用者說話
- 拷問要真的尖銳，不要為了「平衡」而softening
- 使用者回應後，你的每次回覆：點評 + 追問，控制在 3–5 句
- 發散方向要具體，避免「可以進一步研究」這種空話
- 儲存前**不主動寫檔**，等使用者確認

---
name: vault-maintain
description: Use for vault health - from single-domain read-only quick checks (frontmatter completeness, wikilink format, index sync, broken links, raw orphans) to whole-vault sweeps with safe auto-fixes and adversarial verification. Trigger on "vault 巡檢 / 健檢 / lint / 檢查 {domain} / vault-maintain / 整理 vault 健康", after wiki-build, or before publishing the vault.
---

# Vault Maintain

vault 健康的唯一入口。**混合架構：機械項腳本掃、語意項 LLM 判、修復對抗式驗證**。範圍與重量由參數決定。

## 觸發方式

| 指令 | 行為 |
|------|------|
| `/vault-maintain {domain}` | **單域快掃**：只跑 Phase 1a 腳本掃該域，唯讀、輕量、report 直接輸出。`hubs` 亦可作為範圍 |
| `/vault-maintain` | **全 vault dry-run**：Phase 1a + 1b 語意掃描 + 1.5 config drift，只報告不寫檔 |
| `… --apply` | 巡檢後自動修復「安全項」，每筆對抗式驗證。可與單域組合（`/vault-maintain ideas --apply` = 只修該域） |
| `… --strict` | 放寬 W4 對 `books/wiki/` 概念頁的排除，改用 < 10 行門檻一併檢查 |

## 檢查規則（單一住所——全 vault 唯一規則表）

### Error（必須修）

| 規則 | 違反條件 |
|------|---------|
| **E1 frontmatter 缺欄位** | `{domain}/wiki/*.md` 與 `hubs/*.md` 缺 `title` / `summary` / `tags` / `date` 任一；tags 為空；tags 含 `books` / `concept` 等來源標記（型別 tag 僅限 review / explore / hub） |
| **E2 wikilink 全路徑** | 內容頁出現 `[[domain/raw/foo]]` / `[[domain/wiki/foo]]` 全路徑寫法。**例外**：(a) `index.md` 條目格式本就用路徑；(b) **任何指向書頁的連結**（sources、References、聯想、hub 條目…）的路徑限定 `[[books/wiki/{書名}]]`——books/raw 扁平化後與書頁同 basename，裸名歧義，路徑限定是明文規則（見 CLAUDE.md 寫作格式） |
| **E3 純文字引用** | Reference 區或 Sources by section 用純文字 / `raw/filename.md`，不是 `[[name]]` |
| **E4 broken / ambiguous wikilink** | `[[name]]` 指向 vault 中不存在的 note；或**裸名命中多個同名檔**（典型：書頁 raw/wiki 並存）——歧義即違規，改用路徑限定消歧。**排除 code-span**：inline code 與 fenced code block 內的 `[[...]]` 是語法示例，一律跳過 |
| **E5 records vs logs 互斥** | 同一個域同時有 `records.md` 和 `logs/` |
| **E6 路由違規** | `books/wiki/` 出現書頁以外的概念頁（概念應路由主題域，跨域/通用 → ideas）；`{domain}/wiki/` 直接寫入未經 raw/ 沉澱。**例外**：外提概念頁（frontmatter `sources` 指向 vault 內來源節點——書頁／藝評頁／wiki 頁）視為已沉澱，沉澱在來源側（書的沉澱在 `books/raw/{書名}.md`） |
| **E7 hub 一致性** | `hub-*.md` 出現在 `hubs/` 以外；或 `hubs/` 內檔案缺 `hub-` 前綴／tags 缺 `hub` |

### Warning（建議修）

| 規則 | 違反條件 |
|------|---------|
| **W1 index 缺條目** | wiki 頁存在但 `{domain}/index.md` 無對應行 |
| **W2 index 殭屍條目** | index 引用的 `[[…]]` 對應檔案已不存在；含黏行（兩條目擠一行） |
| **W3 summary 不一致** | frontmatter `summary` 與 index 該行摘要顯著不同 |
| **W4 thin wiki** | wiki 頁 < 50 行且 Reference < 3 條（建議 wiki-build 擴充）；**外提概念卡預設排除**（判定鍵：frontmatter `sources` 指向書頁／藝評頁——Mode C 產出本就精簡，且已散居各主題域，不能用「位置在 books/wiki」判定），`--strict` 時改 < 10 行門檻 |
| **W5 raw 孤兒** | raw 檔未被任何 wiki 頁引用（wikilink **或** Sources by section 表）且 mtime > 30 天。**可驗性前提**：Sources 表須列完整檔名或 wikilink——縮寫檔名機械不可驗，掃描時遇縮寫應標註「W5 數字不可信」而非照報 |

### Info（提示）

| 規則 | 違反條件 |
|------|---------|
| **I1 根目錄雜物** | 根目錄出現非 vault 結構檔（`*.js` / `*.py` / `*_REPORT.txt` / `package.json` / `node_modules/`…） |
| **I2 Inbox 老檔** | `Inbox/` 有 mtime > 14 天的檔（建議 triage 或 enrich） |
| **I3 缺 logs 提示** | logs 型域今天沒有當日檔（僅提示） |
| **I4 暫存區升級提示** | `others/wiki/` 同主題聚 ≥ 5 頁（應升為頂層域） |

## 核心原則

1. **機械歸腳本、語意歸 LLM**：E1–E7／W1–W5／I1–I4 全部規則可判，一律唯讀腳本——快、準、零 token。實證教訓：LLM 連數檔案都會數錯（books 43 數成 41），計數與存在性檢查絕不交給模型。
2. **模型分層**：腳本（機械）→ sonnet（語意：重複概念、路由合理性、叢集判讀）→ 主 agent（綜合裁決）。haiku 只做「讀檔回傳摘要」搬運，**不做內容判斷**（實證：曾把繪畫心理誤判成 skateboard）。
3. **fan-out 只讀、單寫入點**：掃描層絕不寫檔；修復由主 agent 執行。
4. **先驗證後宣稱**：每筆 auto-fix 派 subagent 對抗式驗證（預設懷疑、傾向 fail），不過關回滾轉人工。
5. **安全項才自動修**；語意風險一律轉人工。

## 流程

### Phase 1a — 機械掃描（唯讀腳本，主 agent 執行；單域模式只跑這步）

寫一支唯讀 Python 腳本放 **scratchpad**（絕不放 vault 內），按上方規則表逐條掃描（單域模式限定該域範圍）。實作注意：E4/E2 排除 code-span。腳本輸出結構化 JSON，主 agent 直接採信——**不需要 LLM 覆核機械項**。

**行動前陳述**：「即將檢查 {N} 個 wiki 頁、{M} 個 raw 檔（範圍：{全 vault | 域}），{是否 dry-run}。」

### Phase 1b — 語意掃描（並行 subagent，sonnet；僅全 vault 模式）

1. **重複概念偵測**（per 大域）：標題與 summary 近義比對 → `dup_concepts[{a,b,理由}]`
2. **路由合理性抽查**：抽 10–15 張近期新增頁，驗 books 只放書頁、概念頁未誤落 raw/。**不查 engineer vs ideas**——ideas 是概念頁預設值，放在 ideas 永不算誤路由；只有「明確是工具／config／實作 artifact 卻在 ideas」才提，且僅列為建議
3. **Raw 叢集判讀**（高庫存域）：≥ 5 檔且無對應 wiki 的主題叢（wiki-build 候選）
4. **Hub 探勘判讀**：腳本產出 tag 統計（跨 ≥ 2 域、≥ 5 頁、無對應 hub），agent 判讀真主題叢（排除型別／域名／書籍類型 tag）→ `hub_candidates` 附理由

回傳純結構化結果附一句理由；不接受散文報告。

### Phase 1.5 — Config drift 檢查（主 agent 腳本；僅全 vault 模式）

`.claude/skills/` 是 single source of truth，腳本比對 **Skills ↔ CLAUDE.md 表格**：每個 skill 目錄在表中有列、指令名稱與參數簽名一致；表格無已刪 skill 殘留列。

### Phase 2 — 彙整與分類（主 agent）

- **AUTO（安全可自動修）**：`index_missing` 補條目（summary 取自 frontmatter）｜`frontmatter_missing` 且內容完整 → 補 scaffold（date 用檔案 birthtime／mtime、summary 用首段、tags 留 `TODO` 待人工）｜`full_path_links`（目標 basename 全庫唯一且非 E2 例外）→ 改寫最短路徑
- **HUMAN**：`orphan_pages`、`dup_concepts`（合併哪邊？）、根目錄污染（移出或刪？）、CLAUDE.md 表格編輯（一律報告不自動改）、`hub_candidates`（策展決定）、`raw_clusters`（wiki-build 排程建議）、W3／W4／W5（語意層，人決定）

### Phase 3 — 套用 + 對抗式驗證（**僅 `--apply`**）

1. 主 agent 逐筆套用 AUTO（單寫入點）。
2. 派 1 個 sonnet subagent **對抗式驗證整批**：「每筆是否正確、是否丟失資料？預設懷疑、傾向 fail。實際讀檔，不信宣稱。」逐筆 `{ok, reason}`。
3. 任一筆 fail → 回滾該筆、轉 HUMAN 附原因。

### Phase 4 — 報告 + log

```
### ✅ 已自動修復（已對抗式驗證）        ← 僅 --apply
### 🔴 待人工決定（附理由與建議動作）
### ⚪ dry-run 未套用（加 --apply 執行）
## 建議行動                              ← W4 → /wiki-build 擴充；W5 → /wiki-build 或 /note-explore；I4 → 升頂層域
```

每條 finding 帶可定位資訊（檔名＋行號 if applicable）。`--apply` 結束後 append 當月 `log/YYYY-MM.md`（operation: `lint`，標題 `vault-maintain | N 修復 / M 待人工`）。單域 dry-run 快掃不寫 log（report 即產出）。

## Workflow 版（harness 支援 Workflow 工具時優先採用）

若當前 harness 有 `Workflow` 工具（無則 fallback 用 Agent fan-out），把流程寫成 workflow script：

```
phase Scan:    scan = run_script(mechanical_lint)          # 腳本，不進 agent
phase Semantic: sem = parallel(dup/routing/cluster/hub agents, schema 強制, model: sonnet)
phase Classify: findings = classify(scan + sem)            # 主 script 邏輯
phase Apply(--apply): pipeline(auto_items, apply_fix, adversarial_verify(sonnet))
                      # pipeline 無 barrier：單筆修完立即驗證，fail 即回滾該筆
phase Report:  return 三區報告
```

Workflow 的價值：schema 強制結構化回傳、per-item 修復-驗證流水線、中斷可 resume。腳本與 agent 的分工原則不變。

## 不做的事

- 不重寫頁面內容、不重排段落、不潤飾文字
- dry-run 不刪任何檔案（raw 孤兒只是 warning，由人決定）
- 不調整 frontmatter `tags` / `summary` 的語意內容（需人判斷）

## 成功標準

- [ ] 機械項全由唯讀腳本完成（LLM 不做計數與存在性檢查）；腳本放 scratchpad 不進 vault
- [ ] 單域模式輕量：只跑 Phase 1a + report，不派語意 agent、不寫 log
- [ ] 語意項由 sonnet 並行完成、回傳結構化結果；haiku 不做內容判斷
- [ ] 所有寫入由主 agent 單點執行；dry-run 不寫任何檔
- [ ] 每筆 auto-fix 通過對抗式驗證（實際讀檔覆核；失敗回滾轉人工）
- [ ] CLAUDE.md 表格編輯一律報告不自動改
- [ ] 報告三區分明、每條 finding 可定位、末尾有建議行動；`--apply` 後 log 已記錄