system-dev-template/template/.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 永遠唯讀**：所有產出只往 `.claude/wiki/` 寫，絕不改動、搬移、重新命名原文。

---

## 執行流程

### 第一步：偵測專案狀態

檢查以下項目，判斷是新專案還是已有專案：
- 根目錄有沒有 `.claude/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. **先套用 `.claude/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）：

```
.claude/wiki/
├── INDEX.md              ← 頂層：標籤視圖（不是資料夾列表）
├── TAXONOMY.md           ← 標籤字典（分類骨架，受控擴充：先查重再登記）
├── status.md / mistakes.md / decisions-summary.md
└── cards/
    └── <bucket>/         ← 儲存桶（一般專案沿用 docs 分類；vault 由 AI 重新組織）
        ├── 00-INDEX.md   ← 桶子索引（固定名，容器：只連不重寫，H2/H3 分節）
        └── <概念全名>.md  ← 概念原子卡（一概念一檔，自包含）
```

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

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

一般專案仍可同時建 `docs/` 分類樹（SDD 等）：
```
docs/{1-vision,2-architecture/decisions,3-specs,4-guides,5-records/{incidents,test-reports},6-user}
```
（純 PKM vault 不需要 `docs/` 分類樹時，只建 `.claude/wiki/`。）

檔案（不存在才建）：
- `.claude/wiki/INDEX.md`、`TAXONOMY.md`
- `.claude/wiki/status.md`、`mistakes.md`、`decisions-summary.md`
- `docs/README.md`（一般專案才需要）

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

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

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

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

（第二步確認後執行）

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

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

卡片格式（每張卡）：
```markdown
---
tags: [知識管理, AI協作, 方法論]
---
# 概念全名

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

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

## 摘要
[一句話核心]

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

## 關聯
- [[本卡]] >> 謂詞（動詞短語） >> [[他卡]]
- [[原子筆記]] >> 是其最小單元 >> [[卡片盒筆記法]]
```

**麵包屑用帶路徑 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，把「關係」也預編譯，下游 ingest 直接 parse 出帶類型的有向邊）：
1. **方向性**：`A >> 謂詞 >> B` 必須讀成「A（謂詞）B」一句通順的話；A、B 順序就是主→賓真實方向。
2. **謂詞用動詞 / 動詞短語**（反駁、奠基於、是…的實作），動詞天然帶方向。
3. **謂詞自由書寫，不受控詞彙**：下游對謂詞 embedding 時同義謂詞會自動聚類；但方向仍靠書寫順序保證。
4. **向後相容**：純 `[[A]]` 仍合法（視為無類型邊），盡量補謂詞。

> `>>` 是分隔語法，repo 可自選符號，但全程一致。

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

> 與 claude.ai Cowork 的 `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]
原文驗證：pages/ journals/ git status 0 異動 ✅
下一步：用 /wiki-capture 把重要決策存進 wiki
```