kbdb-ingest-plugin/.claude/commands/wiki-init.md

/wiki-init — 初始化或接入 LLM Wiki 系統

初始化這個專案的 LLM Wiki 記憶系統。 新專案建立空白結構，已有專案掃描現有文件並改寫成 wiki。

---

核心概念：wiki 是 AI 改寫過的記憶，不是原文索引

記憶系統的目的，是讓 AI 之後讀得快。但人類寫的原始文件——不管是 vault 的隨手記、開發專案的會議記錄、規格草稿、散落的 .md——天生是亂的：重複、流水帳、半成品、口語。

如果 wiki 只是一份 [[原文檔名]] 指回原文的索引，那每次未來要用都得重新解析那團亂，等於沒省到。wiki 的價值在於「改寫一次，之後每次讀都便宜」。

所以原則對所有專案一致（不分 vault 或一般開發）：

人類寫的原文是 SSoT（真理來源，永遠唯讀）。 但實際要長期保存、被 AI 反覆讀的是 AI 改寫整理過的 wiki。 AI 是總編輯——把原文改寫成自包含、概念原子化、互相連結、適於 AI 讀的知識條目。

唯一例外：原文是不可改動的正式文件（簽署過的規格、法規、合約），必須逐字讀原文——這種才在 wiki 裡用指針指回去，並註明「逐字依原文」。除此之外，一律改寫。

raw source 永遠唯讀：所有產出只往 system-dev/wiki/ 寫，絕不改動、搬移、重新命名原文。

---

執行流程

第一步：偵測專案狀態

檢查以下項目，判斷是新專案還是已有專案：

• 根目錄有沒有 system-dev/wiki/
• 根目錄有沒有 docs/（或 vault 的 pages/、journals/、根目錄 .md）
• 有沒有散落的 .md 檔案

同時偵測 raw source 路徑（同 install.sh 邏輯）：

• 根目錄有 logseq/ → Logseq vault，raw source = pages/ + journals/
• 根目錄有 .obsidian/ → Obsidian vault，raw source = 根目錄所有 .md
• 都沒有 → 一般專案，raw source = docs/ 下所有 .md（及散落的 .md）

新專案（幾乎空的）→ 直接建立結構，跳到第三步 已有專案（有文件）→ 執行第二步

第二步：已有專案的掃描（已有專案才執行）

1. 遞迴找出 raw source 裡所有 .md 檔案
2. 先套用 system-dev/wiki/.wikiignore：命中 pattern 的檔案整個排除，不讀不編入。
   • 若 .wikiignore 不存在，從範本建立一份（預設排除 .env/*.pem/*secret* 等）
   • 被排除的檔案在清單裡標「🚫 .wikiignore 排除」，不可被覆蓋
3. 對其餘檔案標注改寫計畫：會萃取成哪些 wiki 條目。一份原文可能拆成多個概念原子條目，多份相關原文也可能合併成一條。
4. 列出清單給使用者確認，停下來等確認

量大時建議用 Haiku 改寫：逐份原文「改寫成 wiki 格式」是重複、機械、判斷成本低的工作——正適合 Haiku。原文數量多（如數十、上百份）時，主動建議： 「共 N 份原文要改寫，這類逐份萃取很適合用 Haiku 並行處理（便宜、夠快）。要我派 Haiku subagent 改寫嗎？」 得同意後，用 Task / subagent 把每份原文（或每批）丟給 Haiku 改寫，主模型只負責切分概念、定條目邊界、最後審稿與互連。

機敏防護（三層）：

• L1 .wikiignore：整檔排除（這一步）
• L2 行內標記：檔案要編入但某段不要 → 遇到 <!-- wiki:ignore --> … <!-- wiki:end --> 之間的內容略過，只留「（此處機敏，已略過）」
• L3 hook：萬一機敏值仍被寫進 wiki，wiki-secret-scan.sh 會 exit 2 擋下 編入任何檔案前，先檢查是否含密碼/金鑰/個資——有就改記「位置」而非「值」。

第三步：建立缺少的結構

只建立不存在的目錄和檔案，已有的一律不動。

wiki 採三層 + 標籤橫切架構（183 卡實證，issue #8）：

system-dev/wiki/
├── INDEX.md              ← 索引：多角度視圖的家（標籤角度、決策角度、…）
├── TAXONOMY.md           ← 標籤字典（cards 的分類元資料，受控擴充）
├── status.md             ← [push] 時態狀態：當前進度、下一步
├── mistakes.md           ← [push] 踩過的坑、被糾正的誤解（防不自覺盲區）
├── principles.md         ← [push] 跨全局的設計原則（行動前必服從）
└── cards/                ← [pull] 一切知識內容：原文摘要、AI 筆記、決策、概念…
    └── <bucket>/         ← 儲存桶（分類由 frontmatter 標籤承載）
        ├── 00-INDEX.md   ← 桶子索引（固定名，容器：只連不重寫，H2/H3 分節）
        └── <概念全名>.md  ← 概念原子卡（一概念一檔，自包含）

[push] / [pull] 是這套 wiki 的核心判準——因為 wiki 主要是給 AI（CC）看的。 見下方「核心判準：push vs pull」。decisions-summary.md 已降級為 cards + INDEX 決策視圖（決策是知識內容＝card）；既有的 decisions-summary 若存在，保留為相容，不刪。

關鍵原則：資料夾只是儲存桶，分類由 frontmatter 標籤承載。資料夾名不該硬繼承原稿目錄——原稿目錄是「人為了整理草稿」分的，wiki 連分類都該由 AI 重新組織。

桶子索引固定叫 00-INDEX.md（issue #6）：00- 前綴讓它排序最前、一眼可辨（像 README 之於資料夾），AI 載入任何 cards/<bucket>/ 一律先讀它，不必猜。檔內 H1 仍寫主題名（如 # PKM 知識管理），語意不丟。

一般專案仍可同時建 system-dev/docs/ 分類樹（SDD 等）：

system-dev/docs/{1-vision,2-architecture/decisions,3-specs,4-guides,5-records/{incidents,test-reports},6-user}

（純 PKM vault 不需要 system-dev/docs/ 分類樹時，只建 system-dev/wiki/。）

檔案（不存在才建）：

• system-dev/wiki/INDEX.md、TAXONOMY.md
• system-dev/wiki/status.md、mistakes.md、principles.md（三個 push 檔）
• system-dev/docs/README.md（一般專案才需要）

---

核心判準：push vs pull（wiki 是給 AI 看的）

整理任何內容前，先判斷它該 push 還 pull——判準是「CC 做事時會不會被動看見」：

• push：CC 行動前必須主動出現在 context（session 開始就由 hook 注入）。給「CC 不會主動去查、但不看就出事」的東西。
• pull：CC 想到要查、或載入相關卡時才看見。給「CC 面對它時自然會查」的知識。

為什麼這是核心：mistakes 防的是 CC「不自覺的盲區」——一個你不知道存在的錯，你不會主動去檢索它。靠 CC 自覺去查自己沒自覺的盲區是自相矛盾的，所以 pull 對盲區失效，必須 push。原則同理：沒被推到眼前的準繩，CC 設計時很可能沒想到要服從就做了。

內容	push/pull	注入形態（hook）
status	push	全文——CC 必須知道精確的下一步，摘要會漏 task 編號
principles	push	全文（一行一條）——短而硬的約束，漏一條就違反；≤15 條，超過代表該下放成 card
mistakes	push	標題清單 + 一行症狀，全文按需 pull——量可能大，摘要足以觸發「我正撞到某條」的認出
decisions、原文摘要、概念知識、一切其餘	pull	寫成 cards；CC 面對時自然會查，INDEX 提供角度入口

principles 維護規則：一行一條精煉準繩（如「不污染用戶根目錄」「目標用戶 low-code」「wiki 主要給 AI 看」）。發現新的跨全局原則 → append 一行；超過 ~15 條代表某些該合併或下放成 card。累積原則只改 principles.md，不必問用戶開新檔。

第四步：訪談（每次一個問題）

依序問：

1. 這個專案做什麼？（一句話）
2. 有哪些絕對不能違反的限制？（技術棧、架構原則等）
3. 現在進行到哪個階段？
4. 有沒有 CC 曾經犯過的錯要先記下來？

把答案填進 CLAUDE.md（如果存在）或建立新的。

第五步：改寫成 wiki（AI 當總編輯）

（第二步確認後執行）

不搬動原文。逐份讀 raw source，改寫萃取成 cards/<bucket>/ 裡的自包含原子卡：

• 概念原子化：一張卡講一個概念，不是一篇原文對一張卡。原文太雜就拆，多份相關原文就合。
• 自包含：讀卡就懂，不必回去翻原文。把口語、重複、流水帳改寫成結構化知識，不寫「詳見原文」。
• 保留來源指針：每卡標 **來源**：原文相對路徑，為可追溯，不是要使用者回去讀。
• frontmatter 標籤分類（見下方）：分類走 frontmatter tags:，不靠資料夾、不靠行內 #tag。
• 互相連結（typed-edge 三元組）：## 關聯 不只列裸 [[頁面]]，改寫成帶語義的三元組（見下方）。
• 萃 gloss（node 一句說明）：frontmatter 放 gloss: —— 這張卡（= 一個 entity / graph node）的一句話定義，供下游語義 normalize（見下方）。

卡片格式（每張卡）：

---
tags: [知識管理, AI協作, 方法論]
gloss: 一句話定義這個概念是什麼（給下游語義 normalize 用，選填、deep tier 才產）
---
# 概念全名

← [[<bucket>/00-INDEX]]

**來源**：`[raw source 相對路徑]`
**最後更新**：YYYY-MM-DD

## 摘要
[一句話核心]

## 重點
- [自包含改寫的要點，不依賴原文]

## 實體
> 本卡內文的關鍵實體（也是 graph node）。名＋描述供下游 embedding normalize。集中放、一行一個、不縮排、不重複。
- **原子筆記**（atomic note／卡片原子化）— 每張卡只承載一個不可再分論點的知識記錄單元。
- **傳統筆記**（大鍋炒筆記）— 把多主題混雜在同一篇、難精確引用的記錄方式。

## 關聯
### 內文知識關係（內文實體間；端點＝上方 `## 實體` 正規名，一字不差）
- 原子筆記 >> 對立於 >> 傳統筆記
### 卡片關係（卡對卡）
- [[本卡]] >> 謂詞（動詞短語） >> [[他卡]]

麵包屑用帶路徑 wikilink（issue #7）：H1 次行放 ← [[<bucket>/00-INDEX]] 指回桶子索引。 桶子索引固定名 00-INDEX 跨桶會撞名，故指 00-INDEX 一律帶路徑（[[pkm/00-INDEX]]，Logseq 原生支援、下游 ingest 也能對應到具體檔）。普通卡片間連結仍用裸 [[卡名]]（卡名唯一，不需路徑）。

frontmatter 標籤分類（issue #8）：

• 用 frontmatter tags: 而非行內 #tag：卡片內文常大量用 #（講筆記法時的 #猜想、#book100），分類標籤若也行內 #，下游 ingest 無法區分「分類」與「內文範例」會污染 graph。frontmatter 與內文完全分開，零歧義。
• 用標籤而非資料夾分類：資料夾＝強制單一歸屬；標籤＝多重歸屬。一張卡可同時屬知識管理＋AI協作＋架構設計，硬塞一個資料夾會在其他檢索角度漏掉。
• 雙軸 taxonomy（寫進 TAXONOMY.md 當字典；受控擴充，非凍結）：
  • 領域（主軸，1-3 個）：如 知識管理／學習認知／AI協作／生產力／系統設計／工具教學
  • 形態（副軸，0-2 個）：方法論／工具實作／觀點主張／架構設計／案例經驗
  • 一般開發專案的軸可不同（如 子系統／層級／決策類型），由 AI 依專案性質提出、寫進 TAXONOMY.md。
  • 遇到現有軸裝不下的內容：先查是否只是現有標籤的同義詞；確實是新軸才加進 TAXONOMY.md（附定義）再用——禁止繞過字典在卡片直接冒新標籤。字典是 per-repo，跨 repo 不必共用。

typed-edge 規則（issue #5/#11，把「關係」也預編譯，下游 ingest 直接 parse 出帶類型的有向邊）：

• 重點抓內文實體關係，不只卡對卡：卡對卡（[[卡A]] >> 謂詞 >> [[卡B]]）只是既有雙鏈加動詞、資訊量幾乎沒增加；價值在內文概念關係（原子筆記 >> 對立於 >> 傳統筆記，A/B 是內文概念非卡標題）。

1. 方向性：A >> 謂詞 >> B 必須讀成「A（謂詞）B」一句通順的話；A、B 順序就是主→賓真實方向。
2. 謂詞用動詞 / 動詞短語（反駁、奠基於、犧牲）。禁名詞當謂詞——>> 存儲格式 >>、>> 操作體驗 >> 讀不通，是錯的。
3. 謂詞自由但別太天馬行空：「參考／參照」皆可（下游 embed 自動聚類），別寫「瞄了一眼」這種抓不到同義的。
4. 內文三元組端點用裸文字（非 [[wikilink]]），避免 Logseq 紅色斷鏈；卡對卡那層才用 [[]]。
5. 向後相容：純 [[A]] 仍合法（視為無類型邊），盡量補謂詞。

★ 硬自檢（Haiku 量產必備）★ 內文三元組端點必須與 ## 實體 某粗體正規名【一字不差】。寫完逐條把 A、B 拿去 ## 實體 比對，沒有完全相同的 → 這條錯了，改用實體表已有的詞、或把端點補進 ## 實體 再指它。禁止端點帶括號註解／整句補語／形容詞短語。（實證：光寫規則 Haiku 會略過，端點對不齊 14 條；寫成自檢動作後 14→0。跑 12 張才暴露。） >> 是分隔語法，repo 可自選符號，但全程一致。

萃 gloss 規則（issue #9/#11，把「node 的一句說明」也預編譯，供下游 KBDB 語義 normalize）：

• gloss = 這個 entity / graph node 是什麼的一句話。下游對「entity 名 + gloss」一起做 embedding 求相似度，自動歸一同義詞（比只對名字準、比手維護 alias 表自動）。
• 兩層 gloss：① frontmatter gloss: 描述卡標題這個 node；② ## 實體 每行描述句描述內文實體 node。內文實體也是 graph node、也需描述句才能 normalize（黃仁勳 vs Jensen Huang 靠描述拉近向量）。
• 實體要描述、謂詞不用：實體同義詞字面差遠需描述拉近；謂詞同義詞字面本就近，裸詞 embed 自動聚類。
• 在知識生產的當下、由 local CC 建：gloss 跟三元組同階段萃，不留給下游 ingest 臨時補——下游只有單檔 / 跨庫視角，編不出貼合的 gloss（＝胡扯）。
• 選填、deep tier 才產：淺萃（只要結構）時不浪費；deep 改寫時每張卡補。
• gloss ≠ 摘要：gloss 是給機器 normalize 的定義句（「X 是…」）；## 摘要 是給人讀的核心一句。
• 格式對齊下游 envelope：frontmatter gloss: 與 ## 實體 詞條對應下游 ingest envelope 的 nodes[].gloss，ingest 直接取用。

INDEX.md 是標籤視圖（非資料夾列表），00-INDEX.md 是桶內容器（只連不重寫，H2/H3 分節）。 頂層索引指桶子索引帶路徑：[[pkm/00-INDEX]]。

與 claude.ai Cowork 的 system-dev/docs/SKILL.md 改寫邏輯一致，兩條路徑（CC / Cowork）產出同一種 wiki。

第六步：完成報告 + 驗證

完成後驗證原文 0 動（踩過的坑，issue #8）：

git status --short pages/ journals/    # 或一般專案的 docs/ ——須 0 新增 0 修改

改寫時必守（subagent 尤其）：

1. 絕不寫入 raw source：subagent 目標一律給絕對路徑到 cards/<bucket>/，明寫「絕不寫入 pages/journals/docs 原稿」；事後用上面的 git status 驗。
2. 檔名 = 卡片全名，否則 [[全名]] 對不到檔。冒號用全形「：」、斜線用全形「／」，全程一種字元，避免 /、∕、： 混用斷鏈。
3. 量大用 Haiku 並行改寫，主模型只切概念邊界＋審稿＋修跨資料夾斷鏈。

告知：

✅ wiki-init 完成
建立了：[列出新建的目錄和檔案]
跳過了：[列出已有因此不動的]
改寫了：[N 份原文 → M 張原子卡、K 條 typed-edge、M 條 gloss（deep tier）]
原文驗證：pages/ journals/ git status 0 異動 ✅
下一步：用 /wiki-capture 把重要決策存進 wiki