diff --git a/CHANGELOG.md b/CHANGELOG.md index f9452a7..73fb073 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,24 @@ --- +## 1.6.0 — wiki 完整規劃方式（183 卡實證）：三層架構 + frontmatter 標籤 + 多層索引（issue #8/#6/#7） + +在一個中文 Logseq vault（234 篇 pages + journals → 183 張原子卡、571 條 typed-edge）完整跑了一輪 LLM Wiki，把「對 AI 最優」的規劃方式定案。一次納入 `wiki-init.md` 與 `docs/SKILL.md`（CC / Cowork 兩路徑一致）： + +**新增** +- **三層 + 標籤橫切架構**：頂層 `INDEX.md`（標籤視圖）→ `cards//00-INDEX.md`（桶子索引）→ 概念原子卡。資料夾只是儲存桶，**分類由標籤承載**，不繼承原稿目錄。 +- **frontmatter 標籤分類**（issue #8）：分類走 frontmatter `tags:`，不靠資料夾、不靠行內 `#tag`——內文常用 `#`（如 `#猜想`），行內標籤會讓下游 ingest 分不清「分類」與「內文範例」污染 graph。雙軸 taxonomy（領域 + 形態）寫進新檔 **`TAXONOMY.md`** 當字典，**禁止自創標籤**。 +- **桶子索引固定名 `00-INDEX.md`**（issue #6）：`00-` 排序最前、一眼可辨，AI 載入任何桶一律先讀它。 +- **麵包屑帶路徑 wikilink**（issue #7）：卡片 H1 次行 `← [[/00-INDEX]]`。固定名 `00-INDEX` 跨桶撞名，故指它一律帶路徑；卡片間連結仍用裸 `[[卡名]]`。 +- **新檔 `template/.claude/wiki/TAXONOMY.md`**：標籤字典範本。install.sh `download_if_missing`、update.sh `keep_file`（使用者客製，永不覆蓋）。 + +**踩坑警語寫進 wiki-init** +- subagent 改寫時會誤把卡寫進 raw source → 目標一律給絕對路徑到 `cards//`，事後 `git status --short pages/ journals/` 驗證原文 0 異動。 +- 檔名＝卡片全名，冒號用全形「：」、斜線用全形「／」，全程一種字元避免斷鏈。 +- 量大用 Haiku 並行改寫，主模型只切概念邊界 + 審稿 + 修斷鏈。 + +--- + ## 1.5.0 — wiki 連結升級成 typed-edge 三元組（issue #5） **背景**：`## 關聯` 原本只列裸 `[[頁面]]`（沿用 Karpathy LLM Wiki）。但裸 `[[A]]` 是**弱連結**——只說「A 和本卡有關」，沒說關係是什麼。下游要從 wiki 抽 knowledge graph 時，拿到一堆無類型 edges，仍得回讀兩張卡才知道關係，等於關係沒被預編譯、退回 O(N²)。 diff --git a/docs/SKILL.md b/docs/SKILL.md index a8f676e..728068a 100644 --- a/docs/SKILL.md +++ b/docs/SKILL.md @@ -87,29 +87,62 @@ else 2. **INDEX.md 裡已有條目，但 raw source 有新內容** → 更新對應 wiki 頁面，補充新資訊，不刪舊內容 3. **INDEX.md 裡沒有對應條目** → 新建 wiki 頁面 -### Wiki 頁面格式 +### Wiki 卡片格式（概念原子卡，存到 `cards//`） ```markdown -# [主題名稱] +--- +tags: [知識管理, AI協作, 方法論] +--- +# 概念全名 + +← [[/00-INDEX]] **來源**：`[raw source 相對路徑]` **最後更新**：YYYY-MM-DD ## 摘要 -[2-3 句話說明這份文件在講什麼] +[一句話核心] ## 重點 -- [要點 1] -- [要點 2] +- [自包含改寫的要點，不寫「詳見原文」] ## 關聯 -- [[本主題]] >> 謂詞（動詞短語） >> [[相關主題]] +- [[本卡]] >> 謂詞（動詞短語） >> [[他卡]] - [[原子筆記]] >> 是其最小單元 >> [[卡片盒筆記法]] ``` +### 架構：三層 + 標籤橫切（183 卡實證） + +``` +INDEX.md ← 頂層：標籤視圖（非資料夾列表） +TAXONOMY.md ← 標籤字典（禁止自創標籤） +cards// + ├── 00-INDEX.md ← 桶子索引（固定名，容器：只連不重寫） + └── <概念全名>.md ← 概念原子卡 +``` + +- **資料夾只是儲存桶，分類由 frontmatter `tags:` 承載**——不繼承原稿目錄，由 AI 重新組織。 +- **桶子索引固定名 `00-INDEX.md`**：`00-` 排序最前、一眼可辨，載入任何桶先讀它。 +- **frontmatter `tags:` 而非行內 `#tag`**：內文常用 `#`（如 `#猜想`），行內標籤會讓 ingest 分不清「分類」與「內文範例」污染 graph；frontmatter 零歧義。標籤只能用 `TAXONOMY.md` 列出的，**禁止自創**。 +- **麵包屑帶路徑**：H1 次行 `← [[/00-INDEX]]`。指 `00-INDEX` 因固定名跨桶撞名，**一律帶路徑**；卡片間連結用裸 `[[卡名]]`。 + +### 使用 typed-edge 三元組（不只裸 `[[wikilink]]`） + +整理時，發現內容與其他頁面有關聯，用**帶語義的三元組**寫進 `## 關聯`，而非只列裸 `[[頁面]]`。裸 `[[A]]` 只說「有關」、沒說關係，下游要建 knowledge graph 還得回讀兩張卡；三元組把關係也預編譯，ingest 直接 parse 出帶類型的有向邊。 + +格式 `A >> 謂詞 >> B`，規則： +1. **方向性**：必須讀成「A（謂詞）B」一句通順的話；A、B 順序＝主→賓真實方向。 +2. **謂詞用動詞 / 動詞短語**（反駁、奠基於、是…的實作），天然帶方向。 +3. **謂詞自由書寫**，不受控詞彙；下游對謂詞 embedding 時同義謂詞會自動聚類，但方向仍靠書寫順序保證。 +4. **向後相容**：純 `[[A]]` 仍合法（無類型邊），盡量補謂詞。 + +`>>` 為分隔語法，全程一致即可。這是 Karpathy LLM Wiki「知識互連」的強化版——連結不只存在，還帶類型與方向。 + +> **改寫時必守**：① 絕不寫入 raw source（只往 `cards//` 寫，事後驗 raw source 0 異動）；② 檔名＝卡片全名，冒號用全形「：」、斜線用全形「／」，全程一種字元避免斷鏈。 + ### 使用 typed-edge 三元組（不只裸 `[[wikilink]]`） 整理時，發現內容與其他頁面有關聯，用**帶語義的三元組**寫進 `## 關聯`，而非只列裸 `[[頁面]]`。裸 `[[A]]` 只說「有關」、沒說關係，下游要建 knowledge graph 還得回讀兩張卡；三元組把關係也預編譯，ingest 直接 parse 出帶類型的有向邊。 @@ -126,20 +159,24 @@ else ## 第五步：更新 INDEX.md 和 status.md -### INDEX.md 格式 +### INDEX.md 格式（頂層 = 標籤視圖） + +頂層 INDEX 按 `TAXONOMY.md` 的軸聚類，指向各桶子索引（帶路徑），不是平鋪頁面列表： ```markdown # Wiki Index -> 最後更新：YYYY-MM-DD HH:MM | 來源：cowork-scan | 總頁數：N +> 最後更新：YYYY-MM-DD HH:MM | 來源：cowork-scan | 總卡數：N -## 頁面列表 +### 知識管理 +- [[pkm/00-INDEX]] — PKM 知識管理（N 卡） -| 頁面 | 來源 | 摘要 | 最後更新 | -|------|------|------|----------| -| [[頁面名稱]] | `raw/path.md` | 一句話摘要 | YYYY-MM-DD | +### AI 協作 +- [[ai/00-INDEX]] — AI 協作（M 卡） ``` +桶子索引 `cards//00-INDEX.md` 是容器（只連不重寫，H2/H3 分節列出該桶卡片）。 + ### status.md 更新 在現有內容**末尾追加**（不覆蓋）： diff --git a/scripts/install.sh b/scripts/install.sh index 1bbba25..c1acd11 100644 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -164,6 +164,7 @@ download_if_missing "docs/README.md" "$REPO_URL/docs/README.md" if $WANT_WIKI; then create_dir ".claude/wiki" download_if_missing ".claude/wiki/INDEX.md" "$REPO_URL/.claude/wiki/INDEX.md" + download_if_missing ".claude/wiki/TAXONOMY.md" "$REPO_URL/.claude/wiki/TAXONOMY.md" download_if_missing ".claude/wiki/status.md" "$REPO_URL/.claude/wiki/status.md" download_if_missing ".claude/wiki/mistakes.md" "$REPO_URL/.claude/wiki/mistakes.md" download_if_missing ".claude/wiki/decisions-summary.md" "$REPO_URL/.claude/wiki/decisions-summary.md" diff --git a/scripts/update.sh b/scripts/update.sh index c8eb60d..f1d8122 100755 --- a/scripts/update.sh +++ b/scripts/update.sh @@ -5,7 +5,7 @@ # 核心安全原則：只覆蓋「模板/邏輯檔」，絕不碰「使用者資料檔」。 # ✅ 可覆蓋：hooks/*.sh、commands/*.md、TEMPLATE-*、wiki/INDEX.md # ——這些由模板維護，使用者不會手改，新版直接換掉。 -# 🔒 絕不碰：wiki/status.md、mistakes.md、decisions-summary.md、.wikiignore、 +# 🔒 絕不碰：wiki/status.md、mistakes.md、decisions-summary.md、TAXONOMY.md、.wikiignore、 # settings.json、CLAUDE.md # ——這些是使用者自己填的內容，覆蓋＝清空他的記憶與設定。 # @@ -138,6 +138,7 @@ if $HAS_WIKI; then keep_file ".claude/wiki/status.md" keep_file ".claude/wiki/mistakes.md" keep_file ".claude/wiki/decisions-summary.md" + keep_file ".claude/wiki/TAXONOMY.md" keep_file ".claude/wiki/.wikiignore" fi diff --git a/template/.claude/VERSION b/template/.claude/VERSION index bc80560..dc1e644 100644 --- a/template/.claude/VERSION +++ b/template/.claude/VERSION @@ -1 +1 @@ -1.5.0 +1.6.0 diff --git a/template/.claude/commands/wiki-init.md b/template/.claude/commands/wiki-init.md index 6672854..5037bce 100644 --- a/template/.claude/commands/wiki-init.md +++ b/template/.claude/commands/wiki-init.md @@ -61,20 +61,34 @@ ### 第三步：建立缺少的結構 -只建立不存在的目錄和檔案，**已有的一律不動**： +只建立不存在的目錄和檔案，**已有的一律不動**。 -目錄： +wiki 採**三層 + 標籤橫切**架構（183 卡實證，issue #8）： + +``` +.claude/wiki/ +├── INDEX.md ← 頂層：標籤視圖（不是資料夾列表） +├── TAXONOMY.md ← 標籤字典（分類骨架，禁止自創標籤） +├── status.md / mistakes.md / decisions-summary.md +└── cards/ + └── / ← 儲存桶（一般專案沿用 docs 分類；vault 由 AI 重新組織） + ├── 00-INDEX.md ← 桶子索引（固定名，容器：只連不重寫，H2/H3 分節） + └── <概念全名>.md ← 概念原子卡（一概念一檔，自包含） +``` + +關鍵原則：**資料夾只是儲存桶，分類由 frontmatter 標籤承載**。資料夾名不該硬繼承原稿目錄——原稿目錄是「人為了整理草稿」分的，wiki 連分類都該由 AI 重新組織。 + +> **桶子索引固定叫 `00-INDEX.md`**（issue #6）：`00-` 前綴讓它排序最前、一眼可辨（像 README 之於資料夾），AI 載入任何 `cards//` 一律先讀它，不必猜。檔內 H1 仍寫主題名（如 `# PKM 知識管理`），語意不丟。 + +一般專案仍可同時建 `docs/` 分類樹（SDD 等）： ``` docs/{1-vision,2-architecture/decisions,3-specs,4-guides,5-records/{incidents,test-reports},6-user} -.claude/wiki/ ``` -（純 PKM vault 不需要 `docs/` 分類樹時，可只建 `.claude/wiki/`。） +（純 PKM vault 不需要 `docs/` 分類樹時，只建 `.claude/wiki/`。） 檔案（不存在才建）： -- `.claude/wiki/INDEX.md` -- `.claude/wiki/status.md` -- `.claude/wiki/mistakes.md` -- `.claude/wiki/decisions-summary.md` +- `.claude/wiki/INDEX.md`、`TAXONOMY.md` +- `.claude/wiki/status.md`、`mistakes.md`、`decisions-summary.md` - `docs/README.md`（一般專案才需要） ### 第四步：訪談（每次一個問題） @@ -91,57 +105,79 @@ docs/{1-vision,2-architecture/decisions,3-specs,4-guides,5-records/{incidents,te （第二步確認後執行） -**不搬動原文**。逐份讀 raw source，改寫萃取成 `.claude/wiki/` 裡的自包含條目： +**不搬動原文**。逐份讀 raw source，改寫萃取成 `cards//` 裡的自包含原子卡： -- **概念原子化**：一個 wiki 頁面講一個主題，不是一篇原文對一頁。原文太雜就拆，多份相關原文就合。 -- **自包含**：讀 wiki 條目就懂，不必回去翻原文。把口語、重複、時間順序的流水帳，改寫成結構化的知識。 -- **保留來源指針**：每條標 `**來源**：原文相對路徑`，是為了可追溯，不是要使用者回去讀。 -- **互相連結（typed-edge 三元組）**：`## 關聯` 不要只列裸 `[[頁面]]`——那只說「有關」，沒說關係是什麼，下游要建 knowledge graph 還得回讀兩張卡。改寫成帶語義的三元組（見下方規則）。 +- **概念原子化**：一張卡講一個概念，不是一篇原文對一張卡。原文太雜就拆，多份相關原文就合。 +- **自包含**：讀卡就懂，不必回去翻原文。把口語、重複、流水帳改寫成結構化知識，**不寫「詳見原文」**。 +- **保留來源指針**：每卡標 `**來源**：原文相對路徑`，為可追溯，不是要使用者回去讀。 +- **frontmatter 標籤分類**（見下方）：分類走 frontmatter `tags:`，不靠資料夾、不靠行內 `#tag`。 +- **互相連結（typed-edge 三元組）**：`## 關聯` 不只列裸 `[[頁面]]`，改寫成帶語義的三元組（見下方）。 -wiki 條目格式： +卡片格式（每張卡）： ```markdown -# [主題名稱] +--- +tags: [知識管理, AI協作, 方法論] +--- +# 概念全名 + +← [[/00-INDEX]] **來源**：`[raw source 相對路徑]` **最後更新**：YYYY-MM-DD ## 摘要 -[2-3 句說明這個主題的核心] +[一句話核心] ## 重點 -- [改寫後的要點，自包含、不依賴原文] +- [自包含改寫的要點，不依賴原文] ## 關聯 -- [[本主題]] >> 謂詞（動詞短語） >> [[相關主題]] +- [[本卡]] >> 謂詞（動詞短語） >> [[他卡]] - [[原子筆記]] >> 是其最小單元 >> [[卡片盒筆記法]] -- [[筆記墳場]] >> 是的反面教訓 >> [[筆記要重複使用而非複製貼上]] ``` -**typed-edge 規則**（把「關係」也預編譯，下游 ingest 直接 parse 出帶類型的有向邊）： -1. **方向性**：`A >> 謂詞 >> B` 必須能讀成「A（謂詞）B」一句通順的話；A、B 順序就是主→賓的真實方向。 +**麵包屑用帶路徑 wikilink**（issue #7）：H1 次行放 `← [[/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` 當字典，**禁止自創**以保持 graph 乾淨）： + - 領域（主軸，1-3 個）：如 知識管理／學習認知／AI協作／生產力／系統設計／工具教學 + - 形態（副軸，0-2 個）：方法論／工具實作／觀點主張／架構設計／案例經驗 + - 一般開發專案的軸可不同（如 子系統／層級／決策類型），由 AI 依專案性質提出、寫進 TAXONOMY.md。 + +**typed-edge 規則**（issue #5，把「關係」也預編譯，下游 ingest 直接 parse 出帶類型的有向邊）： +1. **方向性**：`A >> 謂詞 >> B` 必須讀成「A（謂詞）B」一句通順的話；A、B 順序就是主→賓真實方向。 2. **謂詞用動詞 / 動詞短語**（反駁、奠基於、是…的實作），動詞天然帶方向。 -3. **謂詞自由書寫，不受控詞彙**：下游若對謂詞做 embedding，同義謂詞會自動聚類；但 embedding 分不清方向，方向仍靠書寫順序保證。 -4. **向後相容**：純 `[[A]]` 仍合法（視為無類型邊），但盡量補謂詞。 +3. **謂詞自由書寫，不受控詞彙**：下游對謂詞 embedding 時同義謂詞會自動聚類；但方向仍靠書寫順序保證。 +4. **向後相容**：純 `[[A]]` 仍合法（視為無類型邊），盡量補謂詞。 -> `>>` 是分隔語法，repo 可自選慣例符號——但同一個 repo 全程一致。 +> `>>` 是分隔語法，repo 可自選符號，但全程一致。 -INDEX.md 是**概念索引**，指向 wiki 內部條目（非原文）： -```markdown -## 概念索引 -| 條目 | 來源 | 一句話 | 最後更新 | -|------|------|--------|----------| -| [[主題名稱]] | `raw/path.md` | 一句話摘要 | YYYY-MM-DD | -``` +**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//`，明寫「絕不寫入 pages/journals/docs 原稿」；事後用上面的 `git status` 驗。 +> 2. **檔名 = 卡片全名**，否則 `[[全名]]` 對不到檔。冒號用全形「：」、斜線用全形「／」，**全程一種字元**，避免 `/`、`∕`、`：` 混用斷鏈。 +> 3. **量大用 Haiku 並行改寫**，主模型只切概念邊界＋審稿＋修跨資料夾斷鏈。 告知： ``` ✅ wiki-init 完成 建立了：[列出新建的目錄和檔案] 跳過了：[列出已有因此不動的] -改寫了：[N 份原文 → M 條 wiki 條目] +改寫了：[N 份原文 → M 張原子卡、K 條 typed-edge] +原文驗證：pages/ journals/ git status 0 異動 ✅ 下一步：用 /wiki-capture 把重要決策存進 wiki ``` diff --git a/template/.claude/wiki/INDEX.md b/template/.claude/wiki/INDEX.md index 0bc3239..0d3e89d 100644 --- a/template/.claude/wiki/INDEX.md +++ b/template/.claude/wiki/INDEX.md @@ -25,12 +25,19 @@ --- -## 概念索引（由 /wiki-init 填入） +## 頂層索引：標籤視圖（由 /wiki-init 填入） -由 CC 改寫原文後填入，**指向 wiki 內部條目**（非指回原文）。原文是唯讀 SSoT，wiki 是改寫過的記憶： +由 CC 改寫原文後填入。原文是唯讀 SSoT，wiki 是改寫過的記憶。 +頂層 INDEX 是**標籤視圖**（非資料夾列表），按 `TAXONOMY.md` 的軸聚類，指向各桶子索引： ```markdown -| 條目 | 來源 | 一句話 | 最後更新 | -|------|------|--------|----------| -| [[主題名稱]] | `raw/path.md` | 一句話摘要 | YYYY-MM-DD | +### 知識管理 +- [[pkm/00-INDEX]] — PKM 知識管理（N 卡） + +### AI 協作 +- [[ai/00-INDEX]] — AI 協作（M 卡） ``` + +> 結構：頂層 INDEX（標籤視圖）→ `cards//00-INDEX.md`（桶子索引，固定名）→ 概念原子卡。 +> 指 `00-INDEX` **一律帶路徑** `[[bucket/00-INDEX]]`（固定名跨桶撞名）；卡片間用裸 `[[卡名]]`。 +> 分類由卡片 frontmatter `tags:` 承載，標籤字典見 `TAXONOMY.md`。詳見 `/wiki-init` 規範。 diff --git a/template/.claude/wiki/TAXONOMY.md b/template/.claude/wiki/TAXONOMY.md new file mode 100644 index 0000000..647fbd4 --- /dev/null +++ b/template/.claude/wiki/TAXONOMY.md @@ -0,0 +1,41 @@ +# TAXONOMY.md — 標籤字典 + +> wiki 卡片的 frontmatter `tags:` **只能用這裡列出的標籤**，禁止自創。 +> 為什麼禁止自創：標籤是 graph 的分類骨架，自由增生會讓同類卡片分散、下游聚類失準。 +> 要新增標籤 → 先加進這份字典，再用。維護者：CC（由 /wiki-init 初始化、隨 wiki 演進補充）。 + +--- + +## 分類採雙軸（一張卡可多重歸屬） + +分類由 **frontmatter `tags:`** 承載，不靠資料夾、不靠行內 `#tag`。 +一張卡同時掛「領域 1-3 個 + 形態 0-2 個」，可從任一軸過濾。 + +### 領域（主軸，每卡 1-3 個） + +> 由 /wiki-init 依專案性質提出。以下為 PKM / 知識型 vault 的實證一組，請按你的專案調整： + +- `知識管理` +- `學習認知` +- `AI協作` +- `生產力` +- `系統設計` +- `工具教學` + +（一般開發專案的領域軸可能是：`子系統A` / `子系統B` / `基礎設施` / `前端` / `後端` …） + +### 形態（副軸，每卡 0-2 個） + +- `方法論` +- `工具實作` +- `觀點主張` +- `架構設計` +- `案例經驗` + +--- + +## 規則 + +1. **禁止自創**：要用新標籤先加進本檔。 +2. **領域 vs 形態分開**：領域是「講什麼主題」，形態是「以什麼形式呈現」，不要混。 +3. **頂層 INDEX.md 的標籤視圖依本字典的軸聚類**——字典改了，INDEX 視圖跟著更新。