Leo
331e4d56a7
裸 [[wikilink]] 是弱連結——只說「有關」，沒說關係是什麼，下游要建 knowledge graph 還得回讀兩張卡。改寫成帶語義的三元組，下游 ingest 直接 parse 出帶類型的有向邊，把關係也預編譯。 - wiki-init.md + docs/SKILL.md 的 ## 關聯 改用 [[A]] >> 謂詞 >> [[B]]。 - 規則：方向性、謂詞用動詞、自由詞彙、向後相容（裸 [[A]] 仍合法）。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
148 lines
7.2 KiB
Markdown
148 lines
7.2 KiB
Markdown
# /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 擋下
|
||
> 編入任何檔案前，先檢查是否含密碼/金鑰/個資——有就改記「位置」而非「值」。
|
||
|
||
### 第三步：建立缺少的結構
|
||
|
||
只建立不存在的目錄和檔案，**已有的一律不動**：
|
||
|
||
目錄：
|
||
```
|
||
docs/{1-vision,2-architecture/decisions,3-specs,4-guides,5-records/{incidents,test-reports},6-user}
|
||
.claude/wiki/
|
||
```
|
||
（純 PKM vault 不需要 `docs/` 分類樹時，可只建 `.claude/wiki/`。）
|
||
|
||
檔案（不存在才建）：
|
||
- `.claude/wiki/INDEX.md`
|
||
- `.claude/wiki/status.md`
|
||
- `.claude/wiki/mistakes.md`
|
||
- `.claude/wiki/decisions-summary.md`
|
||
- `docs/README.md`（一般專案才需要）
|
||
|
||
### 第四步：訪談（每次一個問題）
|
||
|
||
依序問：
|
||
1. 這個專案做什麼？（一句話）
|
||
2. 有哪些絕對不能違反的限制？（技術棧、架構原則等）
|
||
3. 現在進行到哪個階段？
|
||
4. 有沒有 CC 曾經犯過的錯要先記下來？
|
||
|
||
把答案填進 `CLAUDE.md`（如果存在）或建立新的。
|
||
|
||
### 第五步：改寫成 wiki（AI 當總編輯）
|
||
|
||
（第二步確認後執行）
|
||
|
||
**不搬動原文**。逐份讀 raw source，改寫萃取成 `.claude/wiki/` 裡的自包含條目：
|
||
|
||
- **概念原子化**：一個 wiki 頁面講一個主題，不是一篇原文對一頁。原文太雜就拆，多份相關原文就合。
|
||
- **自包含**：讀 wiki 條目就懂，不必回去翻原文。把口語、重複、時間順序的流水帳，改寫成結構化的知識。
|
||
- **保留來源指針**：每條標 `**來源**：原文相對路徑`，是為了可追溯，不是要使用者回去讀。
|
||
- **互相連結（typed-edge 三元組）**：`## 關聯` 不要只列裸 `[[頁面]]`——那只說「有關」，沒說關係是什麼，下游要建 knowledge graph 還得回讀兩張卡。改寫成帶語義的三元組（見下方規則）。
|
||
|
||
wiki 條目格式：
|
||
```markdown
|
||
# [主題名稱]
|
||
|
||
**來源**：`[raw source 相對路徑]`
|
||
**最後更新**：YYYY-MM-DD
|
||
|
||
## 摘要
|
||
[2-3 句說明這個主題的核心]
|
||
|
||
## 重點
|
||
- [改寫後的要點，自包含、不依賴原文]
|
||
|
||
## 關聯
|
||
- [[本主題]] >> 謂詞（動詞短語） >> [[相關主題]]
|
||
- [[原子筆記]] >> 是其最小單元 >> [[卡片盒筆記法]]
|
||
- [[筆記墳場]] >> 是的反面教訓 >> [[筆記要重複使用而非複製貼上]]
|
||
```
|
||
|
||
**typed-edge 規則**（把「關係」也預編譯，下游 ingest 直接 parse 出帶類型的有向邊）：
|
||
1. **方向性**：`A >> 謂詞 >> B` 必須能讀成「A（謂詞）B」一句通順的話；A、B 順序就是主→賓的真實方向。
|
||
2. **謂詞用動詞 / 動詞短語**（反駁、奠基於、是…的實作），動詞天然帶方向。
|
||
3. **謂詞自由書寫，不受控詞彙**：下游若對謂詞做 embedding，同義謂詞會自動聚類；但 embedding 分不清方向，方向仍靠書寫順序保證。
|
||
4. **向後相容**：純 `[[A]]` 仍合法（視為無類型邊），但盡量補謂詞。
|
||
|
||
> `>>` 是分隔語法，repo 可自選慣例符號——但同一個 repo 全程一致。
|
||
|
||
INDEX.md 是**概念索引**，指向 wiki 內部條目（非原文）：
|
||
```markdown
|
||
## 概念索引
|
||
| 條目 | 來源 | 一句話 | 最後更新 |
|
||
|------|------|--------|----------|
|
||
| [[主題名稱]] | `raw/path.md` | 一句話摘要 | YYYY-MM-DD |
|
||
```
|
||
|
||
> 與 claude.ai Cowork 的 `docs/SKILL.md` 改寫邏輯一致，兩條路徑（CC / Cowork）產出同一種 wiki。
|
||
|
||
### 第六步：完成報告
|
||
|
||
告知：
|
||
```
|
||
✅ wiki-init 完成
|
||
建立了：[列出新建的目錄和檔案]
|
||
跳過了：[列出已有因此不動的]
|
||
改寫了：[N 份原文 → M 條 wiki 條目]
|
||
下一步：用 /wiki-capture 把重要決策存進 wiki
|
||
```
|