From 37070fe5062ce7e51f26d31e347b472375b0a0cb Mon Sep 17 00:00:00 2001 From: richblack Date: Thu, 25 Jun 2026 21:44:39 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20wiki-init=20=E6=96=B0=E5=A2=9E=E8=8D=89?= =?UTF-8?q?=E7=A8=BF=E6=94=B9=E5=AF=AB=E6=A8=A1=E5=BC=8F=EF=BC=88AI=20?= =?UTF-8?q?=E7=95=B6=E7=B8=BD=E7=B7=A8=E8=BC=AF=EF=BC=89+=20bump=201.4.0?= =?UTF-8?q?=EF=BC=88issue=20#4=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit wiki-init 原本整套指令只有「分類歸檔／導航」，把人和 AI 都導向做出 [[原文檔名]] 指回原文的索引。但 PKM/vault 使用者常要的是相反的： 原文是草稿，要 AI 改寫萃取成自包含 wiki，讀 wiki 就好不必回原文。 - 開頭新增模式分岔（索引 vs 草稿改寫），附對照表。 - 偵測到 Logseq/Obsidian vault → 預設草稿改寫模式，但問一句可切回。 - 一般專案 → 維持索引模式（向下相容）。 - 草稿改寫格式寫進命令本身（概念原子化、自包含、來源指針、wikilink）， 與 Cowork docs/SKILL.md 一致。 - INDEX.md 範本支援兩種形狀。 Co-Authored-By: Claude Opus 4.8 (1M context) --- CHANGELOG.md | 15 +++++ template/.claude/VERSION | 2 +- template/.claude/commands/wiki-init.md | 83 +++++++++++++++++++++++--- template/.claude/wiki/INDEX.md | 13 +++- 4 files changed, 102 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ca8ecf4..80b1372 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,21 @@ --- +## 1.4.0 — wiki-init 新增「草稿改寫模式」：AI 當總編輯（issue #4） + +**背景**：在 Logseq vault（234 篇 pages + journals）壓測 `/wiki-init`，發現它整套指令語言只有「分類歸檔／導航」，把人和 AI 都導向做出一個 `[[原文檔名]]` 指回原文的**索引**。但 PKM / vault 使用者的心智模型常是相反的——原文只是**草稿**（轉錄稿、隨手記），要 AI **改寫萃取成自包含 wiki**，之後讀 wiki 就好、不必回原文。template 沒區分這兩種，且預設了「原文是成品」。 + +**新增** +- `wiki-init.md` 開頭新增**模式分岔（第零步）**：索引模式 vs **草稿改寫模式（AI 當總編輯）**，附對照表講清楚原文角色、INDEX 連結、回答方式的差異。 + - **偵測到 PKM vault（Logseq/Obsidian）→ 預設草稿改寫模式**，但明確問一句讓使用者可切回索引模式。 + - **一般專案 → 預設索引模式**（維持原行為，向下相容）。 +- 草稿改寫模式的產出規則（第五步）：概念原子化、自包含、保留來源指針（可追溯但不必回讀）、`[[wikilink]]` 互連——與 claude.ai Cowork 的 `docs/SKILL.md` 改寫邏輯**一致**，CC / Cowork 兩條路徑產出同一種 wiki。 +- `INDEX.md` 範本：草稿模式下改成「概念索引」指向 wiki **內部**改寫條目，而非指回原文。 + +**不變**：raw source 永遠唯讀，兩種模式都只往 `.claude/wiki/` 寫，絕不搬移/改名原文。 + +--- + ## 1.3.1 — 修：update.sh 不再覆蓋客製的 pre-write-guard.sh（issue #3） **修正** diff --git a/template/.claude/VERSION b/template/.claude/VERSION index 3a3cd8c..88c5fb8 100644 --- a/template/.claude/VERSION +++ b/template/.claude/VERSION @@ -1 +1 @@ -1.3.1 +1.4.0 diff --git a/template/.claude/commands/wiki-init.md b/template/.claude/commands/wiki-init.md index 8512fc9..3480cbe 100644 --- a/template/.claude/commands/wiki-init.md +++ b/template/.claude/commands/wiki-init.md @@ -5,13 +5,38 @@ --- +## 兩種 wiki 形狀：索引 vs 改寫（先決定，決定整個 wiki 的樣子） + +同一句「整理 wiki」，使用者要的可能是相反的兩件事。**原文的角色不同，wiki 的形狀就完全不同**： + +| | **索引模式** | **草稿改寫模式（AI 當總編輯）** | +|---|---|---| +| 原文角色 | **成品**，wiki 的目的地 | **一次性草稿**（錄音轉錄、隨手記），萃取完可不看 | +| AI 做什麼 | 分類、歸檔、建導航 | **改寫萃取**成自包含、適於 AI 讀的條目 | +| INDEX 連結 | `[[原文檔名]]` 指回原文 | 指向 wiki **內部**的改寫條目 | +| 使用者問問題 | AI 說「去看原文 X」 | AI **直接從 wiki 回答**，不必回原文 | +| 適合誰 | 一般程式專案、規格文件 | PKM / Logseq / Obsidian vault、知識部落格 | + +> **核心概念**：草稿改寫模式裡，人類寫的原文是 **SSoT**（真理來源），但實際要長期保存、被反覆讀的是 **AI 改寫整理過的 wiki**。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/` 寫，絕不改動、搬移、重新命名原文。 + +--- + ## 執行流程 ### 第一步：偵測專案狀態 檢查以下項目，判斷是新專案還是已有專案： - 根目錄有沒有 `.claude/wiki/` -- 根目錄有沒有 `docs/` +- 根目錄有沒有 `docs/`（或 vault 的 `pages/`、`journals/`、根目錄 `.md`） - 有沒有散落的 `.md` 檔案 **新專案**（幾乎空的）→ 直接建立結構，跳到第三步 @@ -19,11 +44,13 @@ ### 第二步：已有專案的掃描（已有專案才執行） -1. 遞迴找出所有 `.md` 檔案 +1. 遞迴找出所有 `.md` 檔案（vault 模式只讀偵測到的 raw source：Logseq 的 `pages/`+`journals/`、Obsidian 根目錄 `.md`） 2. **先套用 `.claude/wiki/.wikiignore`**：命中 pattern 的檔案整個排除，不讀不編入。 - 若 `.wikiignore` 不存在，從範本建立一份（預設排除 `.env`/`*.pem`/`*secret*` 等） - 被排除的檔案在清單裡標「🚫 .wikiignore 排除」，**不可被覆蓋** -3. 對其餘檔案標注建議位置和信心度 +3. 對其餘檔案標注處理計畫（依模式不同）： + - **索引模式**：標注建議分類位置和信心度 + - **草稿改寫模式**：標注「會萃取成哪些 wiki 條目」（一份原文可能拆成多個概念原子條目，多份原文也可能合併成一條） 4. 列出清單給使用者確認，**停下來等確認** > 機敏防護（三層）： @@ -32,7 +59,7 @@ > - **L3 hook**：萬一機敏值仍被寫進 wiki，`wiki-secret-scan.sh` 會 exit 2 擋下 > 編入任何檔案前，先檢查是否含密碼/金鑰/個資——有就改記「位置」而非「值」。 -分類規則： +**索引模式的分類規則**（草稿改寫模式跳過，改用第五步的萃取格式）： ``` 有明確子系統 + 設計內容 → docs/3-specs/[子系統]/ 解釋為什麼做某個決定 → docs/2-architecture/decisions/ @@ -51,13 +78,14 @@ 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` +- `docs/README.md`（一般專案才需要） ### 第四步：訪談（每次一個問題） @@ -69,18 +97,57 @@ docs/{1-vision,2-architecture/decisions,3-specs,4-guides,5-records/{incidents,te 把答案填進 `CLAUDE.md`（如果存在）或建立新的。 -### 第五步：已有專案的文件歸檔 +### 第五步：產出 wiki（依模式分流） （第二步確認後執行） -按照確認好的分類移動檔案，完成後更新 `CLAUDE.md` 的路徑引用。 +#### 索引模式 + +按照確認好的分類**移動/歸檔**檔案，完成後更新 `CLAUDE.md` 的路徑引用，INDEX.md 列出 `[[原文檔名]]` 導航。 + +#### 草稿改寫模式（AI 當總編輯） + +**不搬動原文**。逐份讀 raw source，改寫萃取成 `.claude/wiki/` 裡的自包含條目： + +- **概念原子化**：一個 wiki 頁面講一個主題，不是一篇原文對一頁。原文太雜就拆，多份相關草稿就合。 +- **自包含**：讀 wiki 條目就懂，不必回去翻原文。把口語、重複、時間順序的流水帳，改寫成結構化的知識。 +- **保留來源指針**：每條標 `**來源**：原文相對路徑`，是為了可追溯，不是要使用者回去讀。 +- **互相連結**：用 `[[頁面名稱]]` 連到相關條目（Karpathy LLM Wiki 的核心——知識互連，不是孤島）。 + +wiki 條目格式： +```markdown +# [主題名稱] + +**來源**：`[raw source 相對路徑]` +**最後更新**：YYYY-MM-DD + +## 摘要 +[2-3 句說明這個主題的核心] + +## 重點 +- [改寫後的要點，自包含、不依賴原文] + +## 關聯 +- [[相關 wiki 頁面]] +``` + +INDEX.md 在此模式是**概念索引**，指向 wiki 內部條目（非原文）： +```markdown +## 概念索引 +| 條目 | 來源 | 一句話 | 最後更新 | +|------|------|--------|----------| +| [[主題名稱]] | `raw/path.md` | 一句話摘要 | YYYY-MM-DD | +``` + +> 與 claude.ai Cowork 的 `docs/SKILL.md` 改寫邏輯一致，兩條路徑（CC / Cowork）產出同一種 wiki。 ### 第六步：完成報告 告知： ``` -✅ wiki-init 完成 +✅ wiki-init 完成（模式：索引／草稿改寫） 建立了：[列出新建的目錄和檔案] 跳過了：[列出已有因此不動的] +[草稿改寫模式] 萃取了：[N 份原文 → M 條 wiki 條目] 下一步：用 /wiki-capture 把重要決策存進 wiki ``` diff --git a/template/.claude/wiki/INDEX.md b/template/.claude/wiki/INDEX.md index 6bbfa30..44f0d79 100644 --- a/template/.claude/wiki/INDEX.md +++ b/template/.claude/wiki/INDEX.md @@ -25,6 +25,15 @@ --- -## 快速導航（由 /wiki-init 填入） +## 索引（由 /wiki-init 填入，形狀依模式而定） -（初始化後由 CC 根據專案特性填入） +初始化後由 CC 填入，兩種模式形狀不同： + +- **索引模式**（一般專案）：`[[原文檔名]]` 導航，指回原文。 +- **草稿改寫模式**（PKM vault）：概念索引，指向 wiki **內部**改寫條目，不指回原文。 + + ```markdown + | 條目 | 來源 | 一句話 | 最後更新 | + |------|------|--------|----------| + | [[主題名稱]] | `raw/path.md` | 一句話摘要 | YYYY-MM-DD | + ```