From 6b49f35925b9270cd603d1a6c69c6d3af25f22c4 Mon Sep 17 00:00:00 2001 From: richblack Date: Thu, 25 Jun 2026 21:51:30 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20wiki=20=3D=20AI=20=E6=94=B9=E5=AF=AB?= =?UTF-8?q?=E7=9A=84=E8=A8=98=E6=86=B6=EF=BC=88=E6=8B=BF=E6=8E=89=E7=B4=A2?= =?UTF-8?q?=E5=BC=95=E6=A8=A1=E5=BC=8F=EF=BC=89+=20=E9=87=8F=E5=A4=A7?= =?UTF-8?q?=E5=BB=BA=E8=AD=B0=20Haiku=EF=BC=88issue=20#4=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 修正 1.4.0 方向：索引 vs 改寫不該是兩種並列模式。記憶系統的目的是 讓 AI 之後讀得快——不管 vault 或一般開發，原文都是亂的，只做指回原文 的索引等於每次重新解析、沒省到。wiki 的價值在「改寫一次，之後每次讀都便宜」。 - 拿掉索引模式，改寫成 wiki 是所有專案的唯一預設。 - 唯一例外：不可改動的正式文件（須逐字讀）才用指針指回原文。 - 量大時主動建議派 Haiku subagent 並行改寫，主模型負責切概念與審稿。 - INDEX.md 範本統一成概念索引指向 wiki 內部條目。 Co-Authored-By: Claude Opus 4.8 (1M context) --- CHANGELOG.md | 14 ++++++ template/.claude/VERSION | 2 +- template/.claude/commands/wiki-init.md | 70 ++++++++++---------------- template/.claude/wiki/INDEX.md | 17 +++---- 4 files changed, 49 insertions(+), 54 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 80b1372..536c4d6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,20 @@ --- +## 1.4.1 — wiki = AI 改寫的記憶（拿掉索引模式）+ 量大建議 Haiku（issue #4） + +**修正 1.4.0 的方向**：1.4.0 把「索引 vs 改寫」做成兩種並列模式，預設一般專案走索引、只有 vault 走改寫。這方向錯了—— + +> **記憶系統的目的是讓 AI 之後讀得快。** 不管 vault 還是一般開發專案，人類原文都是亂的（重複、流水帳、半成品）。若 wiki 只是指回原文的索引，每次未來用都得重新解析那團亂＝沒省到。**wiki 的價值就在「改寫一次，之後每次讀都便宜」。** + +**變更** +- `wiki-init.md` **拿掉索引模式**，改寫成 wiki 是**所有專案的唯一預設**（vault 與一般開發一致）。原文＝唯讀 SSoT，wiki＝AI 改寫過的記憶，AI 是總編輯。 +- 唯一例外：原文是不可改動的正式文件（簽署規格／法規／合約，須逐字讀）才用指針指回原文並註明「逐字依原文」。 +- **量大建議用 Haiku**：逐份原文改寫成 wiki 格式是重複、機械、判斷成本低的工作，正適合 Haiku。原文數量多時，命令會主動建議派 Haiku subagent 並行改寫，主模型只負責切概念、定條目邊界、審稿與互連。 +- `INDEX.md` 範本：統一成「概念索引指向 wiki 內部條目」，不再提索引模式。 + +--- + ## 1.4.0 — wiki-init 新增「草稿改寫模式」：AI 當總編輯（issue #4） **背景**：在 Logseq vault（234 篇 pages + journals）壓測 `/wiki-init`，發現它整套指令語言只有「分類歸檔／導航」，把人和 AI 都導向做出一個 `[[原文檔名]]` 指回原文的**索引**。但 PKM / vault 使用者的心智模型常是相反的——原文只是**草稿**（轉錄稿、隨手記），要 AI **改寫萃取成自包含 wiki**，之後讀 wiki 就好、不必回原文。template 沒區分這兩種，且預設了「原文是成品」。 diff --git a/template/.claude/VERSION b/template/.claude/VERSION index 88c5fb8..347f583 100644 --- a/template/.claude/VERSION +++ b/template/.claude/VERSION @@ -1 +1 @@ -1.4.0 +1.4.1 diff --git a/template/.claude/commands/wiki-init.md b/template/.claude/commands/wiki-init.md index 3480cbe..d7b52dd 100644 --- a/template/.claude/commands/wiki-init.md +++ b/template/.claude/commands/wiki-init.md @@ -1,32 +1,25 @@ # /wiki-init — 初始化或接入 LLM Wiki 系統 初始化這個專案的 LLM Wiki 記憶系統。 -新專案建立空白結構，已有專案掃描現有文件並建立 wiki。 +新專案建立空白結構，已有專案掃描現有文件並**改寫**成 wiki。 --- -## 兩種 wiki 形狀：索引 vs 改寫（先決定，決定整個 wiki 的樣子） +## 核心概念：wiki 是 AI 改寫過的記憶，不是原文索引 -同一句「整理 wiki」，使用者要的可能是相反的兩件事。**原文的角色不同，wiki 的形狀就完全不同**： +記憶系統的目的，是讓 AI **之後讀得快**。但人類寫的原始文件——不管是 vault 的隨手記、開發專案的會議記錄、規格草稿、散落的 `.md`——天生是亂的：重複、流水帳、半成品、口語。 -| | **索引模式** | **草稿改寫模式（AI 當總編輯）** | -|---|---|---| -| 原文角色 | **成品**，wiki 的目的地 | **一次性草稿**（錄音轉錄、隨手記），萃取完可不看 | -| AI 做什麼 | 分類、歸檔、建導航 | **改寫萃取**成自包含、適於 AI 讀的條目 | -| INDEX 連結 | `[[原文檔名]]` 指回原文 | 指向 wiki **內部**的改寫條目 | -| 使用者問問題 | AI 說「去看原文 X」 | AI **直接從 wiki 回答**，不必回原文 | -| 適合誰 | 一般程式專案、規格文件 | PKM / Logseq / Obsidian vault、知識部落格 | +如果 wiki 只是一份 `[[原文檔名]]` 指回原文的**索引**，那每次未來要用都得重新解析那團亂，等於沒省到。**wiki 的價值在於「改寫一次，之後每次讀都便宜」**。 -> **核心概念**：草稿改寫模式裡，人類寫的原文是 **SSoT**（真理來源），但實際要長期保存、被反覆讀的是 **AI 改寫整理過的 wiki**。AI 是「總編輯」——把降低書寫壓力而隨手寫下的草稿，改寫成自包含、概念原子化、互相連結的知識條目。 +所以原則對**所有專案**一致（不分 vault 或一般開發）： -### 怎麼決定模式（第零步，最先做） +> 人類寫的原文是 **SSoT**（真理來源，永遠唯讀）。 +> 但實際要長期保存、被 AI 反覆讀的是 **AI 改寫整理過的 wiki**。 +> **AI 是總編輯**——把原文改寫成自包含、概念原子化、互相連結、適於 AI 讀的知識條目。 -1. **偵測 vault 類型**（同 install.sh 邏輯）：根目錄有 `logseq/` → Logseq；有 `.obsidian/` → Obsidian；都沒有 → 一般專案。 -2. **挑預設並說明，給一次切換機會**： - - **偵測到 PKM vault（Logseq/Obsidian）** → **預設草稿改寫模式**。明確告知一句： - > 「偵測到 [Logseq/Obsidian] vault，PKM 筆記通常是草稿——我會用**草稿改寫模式**：把原文萃取改寫成自包含 wiki，之後讀 wiki 就好。若你的筆記其實是成品、只想要指回原文的索引，回我『索引模式』。」 - - **一般專案** → **預設索引模式**（分類歸檔、INDEX 指回原文）。一句帶過，使用者要改寫再說。 -3. 模式定了再往下走。**raw source 永遠唯讀**——兩種模式都只往 `.claude/wiki/` 寫，絕不改動、搬移、重新命名原文。 +唯一例外：原文是**不可改動的正式文件**（簽署過的規格、法規、合約），必須逐字讀原文——這種才在 wiki 裡用指針指回去，並註明「逐字依原文」。除此之外，一律改寫。 + +**raw source 永遠唯讀**：所有產出只往 `.claude/wiki/` 寫，絕不改動、搬移、重新命名原文。 --- @@ -39,36 +32,33 @@ - 根目錄有沒有 `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. 遞迴找出所有 `.md` 檔案（vault 模式只讀偵測到的 raw source：Logseq 的 `pages/`+`journals/`、Obsidian 根目錄 `.md`） +1. 遞迴找出 raw source 裡所有 `.md` 檔案 2. **先套用 `.claude/wiki/.wikiignore`**：命中 pattern 的檔案整個排除，不讀不編入。 - 若 `.wikiignore` 不存在，從範本建立一份（預設排除 `.env`/`*.pem`/`*secret*` 等） - 被排除的檔案在清單裡標「🚫 .wikiignore 排除」，**不可被覆蓋** -3. 對其餘檔案標注處理計畫（依模式不同）： - - **索引模式**：標注建議分類位置和信心度 - - **草稿改寫模式**：標注「會萃取成哪些 wiki 條目」（一份原文可能拆成多個概念原子條目，多份原文也可能合併成一條） +3. 對其餘檔案標注**改寫計畫**：會萃取成哪些 wiki 條目。一份原文可能拆成多個概念原子條目，多份相關原文也可能合併成一條。 4. 列出清單給使用者確認，**停下來等確認** +> **量大時建議用 Haiku 改寫**：逐份原文「改寫成 wiki 格式」是重複、機械、判斷成本低的工作——正適合 Haiku。原文數量多（如數十、上百份）時，主動建議： +> 「共 N 份原文要改寫，這類逐份萃取很適合用 Haiku 並行處理（便宜、夠快）。要我派 Haiku subagent 改寫嗎？」 +> 得同意後，用 Task / subagent 把每份原文（或每批）丟給 Haiku 改寫，主模型只負責切分概念、定條目邊界、最後審稿與互連。 + > 機敏防護（三層）： > - **L1 .wikiignore**：整檔排除（這一步） > - **L2 行內標記**：檔案要編入但某段不要 → 遇到 `` … `` 之間的內容**略過**，只留「（此處機敏，已略過）」 > - **L3 hook**：萬一機敏值仍被寫進 wiki，`wiki-secret-scan.sh` 會 exit 2 擋下 > 編入任何檔案前，先檢查是否含密碼/金鑰/個資——有就改記「位置」而非「值」。 -**索引模式的分類規則**（草稿改寫模式跳過，改用第五步的萃取格式）： -``` -有明確子系統 + 設計內容 → docs/3-specs/[子系統]/ -解釋為什麼做某個決定 → docs/2-architecture/decisions/ -說明怎麼操作 → docs/4-guides/ -記錄發生過的事 → docs/5-records/ -給外部使用者看的 → docs/6-user/ -不確定 → 列為「待確認」，問使用者 -``` - ### 第三步：建立缺少的結構 只建立不存在的目錄和檔案，**已有的一律不動**： @@ -97,19 +87,13 @@ docs/{1-vision,2-architecture/decisions,3-specs,4-guides,5-records/{incidents,te 把答案填進 `CLAUDE.md`（如果存在）或建立新的。 -### 第五步：產出 wiki（依模式分流） +### 第五步：改寫成 wiki（AI 當總編輯） （第二步確認後執行） -#### 索引模式 - -按照確認好的分類**移動/歸檔**檔案，完成後更新 `CLAUDE.md` 的路徑引用，INDEX.md 列出 `[[原文檔名]]` 導航。 - -#### 草稿改寫模式（AI 當總編輯） - **不搬動原文**。逐份讀 raw source，改寫萃取成 `.claude/wiki/` 裡的自包含條目： -- **概念原子化**：一個 wiki 頁面講一個主題，不是一篇原文對一頁。原文太雜就拆，多份相關草稿就合。 +- **概念原子化**：一個 wiki 頁面講一個主題，不是一篇原文對一頁。原文太雜就拆，多份相關原文就合。 - **自包含**：讀 wiki 條目就懂，不必回去翻原文。把口語、重複、時間順序的流水帳，改寫成結構化的知識。 - **保留來源指針**：每條標 `**來源**：原文相對路徑`，是為了可追溯，不是要使用者回去讀。 - **互相連結**：用 `[[頁面名稱]]` 連到相關條目（Karpathy LLM Wiki 的核心——知識互連，不是孤島）。 @@ -131,7 +115,7 @@ wiki 條目格式： - [[相關 wiki 頁面]] ``` -INDEX.md 在此模式是**概念索引**，指向 wiki 內部條目（非原文）： +INDEX.md 是**概念索引**，指向 wiki 內部條目（非原文）： ```markdown ## 概念索引 | 條目 | 來源 | 一句話 | 最後更新 | @@ -145,9 +129,9 @@ INDEX.md 在此模式是**概念索引**，指向 wiki 內部條目（非原文 告知： ``` -✅ wiki-init 完成（模式：索引／草稿改寫） +✅ wiki-init 完成 建立了：[列出新建的目錄和檔案] 跳過了：[列出已有因此不動的] -[草稿改寫模式] 萃取了：[N 份原文 → M 條 wiki 條目] +改寫了：[N 份原文 → M 條 wiki 條目] 下一步：用 /wiki-capture 把重要決策存進 wiki ``` diff --git a/template/.claude/wiki/INDEX.md b/template/.claude/wiki/INDEX.md index 44f0d79..0bc3239 100644 --- a/template/.claude/wiki/INDEX.md +++ b/template/.claude/wiki/INDEX.md @@ -25,15 +25,12 @@ --- -## 索引（由 /wiki-init 填入，形狀依模式而定） +## 概念索引（由 /wiki-init 填入） -初始化後由 CC 填入，兩種模式形狀不同： +由 CC 改寫原文後填入，**指向 wiki 內部條目**（非指回原文）。原文是唯讀 SSoT，wiki 是改寫過的記憶： -- **索引模式**（一般專案）：`[[原文檔名]]` 導航，指回原文。 -- **草稿改寫模式**（PKM vault）：概念索引，指向 wiki **內部**改寫條目，不指回原文。 - - ```markdown - | 條目 | 來源 | 一句話 | 最後更新 | - |------|------|--------|----------| - | [[主題名稱]] | `raw/path.md` | 一句話摘要 | YYYY-MM-DD | - ``` +```markdown +| 條目 | 來源 | 一句話 | 最後更新 | +|------|------|--------|----------| +| [[主題名稱]] | `raw/path.md` | 一句話摘要 | YYYY-MM-DD | +```