From e0ff0065649955655e70b8779c4971da763af5c7 Mon Sep 17 00:00:00 2001 From: richblack Date: Fri, 26 Jun 2026 14:13:42 +0800 Subject: [PATCH] =?UTF-8?q?fix:=20=E8=A3=9C=E8=A3=9D=20Cowork=20wiki=20ski?= =?UTF-8?q?ll(docs/SKILL.md)+=20CLAUDE.md=20=E5=8A=A0=20wiki/gloss=20?= =?UTF-8?q?=E5=B0=8E=E8=88=AA=20+=20bump=201.8.1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cowork(claude.ai)整理 wiki 的規則檔 docs/SKILL.md(含 typed-edge、frontmatter 標籤、gloss)從來沒被裝到用戶端:install.sh 沒下載、template/docs/ 發佈源也缺檔, claude.ai 來掃時身上零規則。CC 平時讀的 CLAUDE.md 也沒指向採集規則,造成「CC 說 找不到 gloss 指引」。 - template/docs/SKILL.md 新增(補發佈源,install 才有得下載) - install.sh 加下載 docs/SKILL.md(wiki 模組) - update.sh 加 update_file docs/SKILL.md(可覆蓋規則檔) - template/CLAUDE.md 加「整理 wiki 的方法」導航,CC+Cowork 雙明示 gloss 規則所在 Co-Authored-By: Claude Opus 4.8 (1M context) --- CHANGELOG.md | 9 ++ scripts/install.sh | 4 + scripts/update.sh | 2 + template/.claude/VERSION | 2 +- template/CLAUDE.md | 14 +++ template/docs/SKILL.md | 233 +++++++++++++++++++++++++++++++++++++++ 6 files changed, 263 insertions(+), 1 deletion(-) create mode 100644 template/docs/SKILL.md diff --git a/CHANGELOG.md b/CHANGELOG.md index c0d5f28..b52ec63 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,15 @@ --- +## 1.8.1 — 補裝 Cowork 的 wiki skill（`docs/SKILL.md`）+ CLAUDE.md 加 wiki/gloss 導航 + +發現 Cowork（claude.ai）整理 wiki 的規則檔 `docs/SKILL.md`（含 typed-edge、frontmatter 標籤、**gloss**）**從來沒被安裝到用戶端**：install.sh 沒下載它，連 `template/docs/` 發佈源都缺這檔 → claude.ai 來掃時身上沒任何 wiki 規則。同時 CC 平時讀的 CLAUDE.md 沒指向採集規則，導致「CC 說找不到 gloss 指引」。這版把兩條路徑都補上。 + +- **補發佈源**：`template/docs/SKILL.md` 新增（從根 docs 同步），install.sh 才有得下載。 +- **install.sh**：wiki 模組加一行下載 `docs/SKILL.md`。 +- **update.sh**：加 `update_file docs/SKILL.md`，舊專案更新會帶上（規則檔，可覆蓋）。 +- **CLAUDE.md 模板**：新增「整理 wiki 的方法」導航段，明示 CC（`/wiki-init`）與 Cowork（`docs/SKILL.md`）的採集規則所在地，gloss 不再「藏」在指令內文裡讓 CC 找不到。 + ## 1.8.0 — wiki 採集加「萃 gloss」（每個 node 一句說明，供下游語義 normalize） 下游 KBDB 要做語義 normalize：對「entity 名 + gloss（一句說明）」一起 embedding 求相似度自動歸一同義詞。但本地 wiki 採集只萃三元組、沒萃 gloss。原則是 gloss 該在知識生產當下由 local CC/Cowork 建（下游只有單檔／跨庫視角編不出好 gloss），不留給下游 ingest 臨時補。（issue #9） diff --git a/scripts/install.sh b/scripts/install.sh index aca2f33..c66b0e5 100644 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -247,6 +247,10 @@ if $WANT_WIKI; then # wiki 相關 hooks：接關 + 機敏掃描 download_if_missing ".claude/hooks/session-start-recall.sh" "$REPO_URL/.claude/hooks/session-start-recall.sh" download_if_missing ".claude/hooks/wiki-secret-scan.sh" "$REPO_URL/.claude/hooks/wiki-secret-scan.sh" + + # Cowork（claude.ai）整理 wiki 用的 skill：與 CC 的 /wiki-init 共用同一套規則 + # （含 typed-edge、frontmatter 標籤、gloss）。沒這支 → claude.ai 來掃時身上沒規則。 + download_if_missing "docs/SKILL.md" "$REPO_URL/docs/SKILL.md" fi # ── SDD 模組 ────────────────────────────────────── diff --git a/scripts/update.sh b/scripts/update.sh index a48e8ad..fc72ad6 100755 --- a/scripts/update.sh +++ b/scripts/update.sh @@ -147,6 +147,8 @@ if $HAS_WIKI; then update_file ".claude/commands/wiki-capture.md" "$TEMPLATE_URL/.claude/commands/wiki-capture.md" update_file ".claude/commands/wiki-update.md" "$TEMPLATE_URL/.claude/commands/wiki-update.md" update_file ".claude/commands/wiki-recall.md" "$TEMPLATE_URL/.claude/commands/wiki-recall.md" + # Cowork（claude.ai）的 wiki 整理 skill：規則檔，可覆蓋 + update_file "docs/SKILL.md" "$TEMPLATE_URL/docs/SKILL.md" # wiki 的「使用者資料」：絕不碰 keep_file ".claude/wiki/status.md" diff --git a/template/.claude/VERSION b/template/.claude/VERSION index 27f9cd3..b9268da 100644 --- a/template/.claude/VERSION +++ b/template/.claude/VERSION @@ -1 +1 @@ -1.8.0 +1.8.1 \ No newline at end of file diff --git a/template/CLAUDE.md b/template/CLAUDE.md index 274495d..e03564d 100644 --- a/template/CLAUDE.md +++ b/template/CLAUDE.md @@ -44,6 +44,20 @@ --- +## 整理 wiki 的方法（採集規則所在地） + +> 要「採集／改寫 wiki」時，完整規則（三層架構、frontmatter 標籤、typed-edge 三元組、**gloss 定義句**） +> 不在本檔，而在下表。**動手採集前先讀對應那份**，不要憑印象做。 + +| 由誰整理 | 規則檔（採集當下必讀） | +|----------|------------------------| +| **Claude Code（CC）** | `/wiki-init`（初始化／採集）、`/wiki-capture`（存結論），規則寫在指令內文 | +| **Claude.ai（Cowork）** | `docs/SKILL.md`（skill `wiki-cowork-scan`），與 CC 共用同一套規則 | + +兩條路徑**輸出格式相同、規則一致**：gloss、typed-edge、標籤的寫法在兩份裡都有，任一方整理過另一方不覆蓋。 + +--- + ## 規範索引 | 檔案 | 內容 | diff --git a/template/docs/SKILL.md b/template/docs/SKILL.md new file mode 100644 index 0000000..647f78b --- /dev/null +++ b/template/docs/SKILL.md @@ -0,0 +1,233 @@ +--- +name: wiki-cowork-scan +description: "掃描本機 Documents 下所有裝了 system-dev-template 的資料夾，自動整理 LLM Wiki。支援一般專案、Logseq vault、Obsidian vault 三種結構，偵測方式與 install.sh 一致。觸發時機：使用者說「整理 wiki」「幫我掃 wiki」「更新我的 wiki」「wiki 掃描」，或 Cowork cron 定期觸發。" +--- + +# Wiki Cowork Scan + +## 核心原則 + +這個 skill 與 Claude Code 的 `/wiki-init` `/wiki-capture` 共用同一套規則： + +| 層 | 規則 | +|------------|-------------------------------------------| +| raw source | 只讀，不動 | +| `.claude/wiki/` | 唯一輸出地點，只增不覆 | +| `CLAUDE.md` | 不動 | +| `logseq/`、`.obsidian/`、`assets/` | 絕對不動 | + +**CC 和 Cowork 輸出格式相同，任何一方整理過的內容，另一方看到就跳過或補充，不覆蓋。** + +--- + +## 第一步：發現所有目標資料夾 + +掃描 `~/Documents`（遞迴深度 3 層），找出所有含 `.claude/wiki/` 的資料夾。 + +``` +~/Documents/ + project-a/.claude/wiki/ ← ✅ 目標 + Logseq/.claude/wiki/ ← ✅ 目標 + 其他資料夾/ ← ❌ 跳過 +``` + +找到後列出清單，告訴使用者：「找到 N 個 wiki 資料夾，開始整理。」 + +--- + +## 第二步：對每個資料夾偵測 vault 類型 + +進入每個目標資料夾的**根目錄**（`.claude/wiki/` 的上兩層），依序判斷： + +### 判斷順序（與 install.sh 一致） + +``` +if 根目錄有 logseq/ 資料夾 + → vault 類型：Logseq + → raw source：pages/、journals/ + → 忽略：logseq/、assets/ + +else if 根目錄有 .obsidian/ 資料夾 + → vault 類型：Obsidian + → raw source：根目錄下所有 .md（排除 .obsidian/ 內的檔案） + +else + → vault 類型：一般專案 + → raw source：docs/ 下所有 .md +``` + +--- + +## 第三步：讀取現有 wiki 狀態 + +進入 `.claude/wiki/`，讀取： + +- `INDEX.md`：目前已有哪些 wiki 頁面 +- `status.md`：上次整理時間、進度 +- `log.md`（如果有）：誰動過什麼 + +目的：**知道哪些已整理過，只處理新增或有變動的 raw source**，不重複整理。 + +--- + +## 第四步：整理規則 + +### 讀 raw source + +逐一讀取 raw source 的 `.md` 檔。跳過： +- 檔名以 `.` 開頭的隱藏檔 +- `.wikiignore` 裡列出的 glob pattern（如果存在） +- 含有 `` 標記的區段 + +### 整理邏輯 + +每個 raw source 檔案，判斷： + +1. **INDEX.md 裡已有對應條目，且 raw source 未修改** → 跳過 +2. **INDEX.md 裡已有條目，但 raw source 有新內容** → 更新對應 wiki 頁面，補充新資訊，不刪舊內容 +3. **INDEX.md 裡沒有對應條目** → 新建 wiki 頁面 + +### Wiki 卡片格式（概念原子卡，存到 `cards//`） + +```markdown +--- +tags: [知識管理, AI協作, 方法論] +gloss: 一句話定義這個概念是什麼（給下游語義 normalize 用，選填、deep tier 才產） +--- +# 概念全名 + +← [[/00-INDEX]] + +**來源**：`[raw source 相對路徑]` +**最後更新**：YYYY-MM-DD + +## 摘要 + +[一句話核心] + +## 重點 + +- [自包含改寫的要點，不寫「詳見原文」] + +## 關聯 + +- [[本卡]] >> 謂詞（動詞短語） >> [[他卡]] +- [[原子筆記]] >> 是其最小單元 >> [[卡片盒筆記法]] +``` + +### 架構：三層 + 標籤橫切（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` 列出的；**禁止繞過字典在卡片直接冒新標籤**，但字典可受控擴充（遇新軸先查重、確認非同義詞，再登記進本 repo 的 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「知識互連」的強化版——連結不只存在，還帶類型與方向。 + +### 萃 gloss（node 一句說明，供下游語義 normalize） + +每張卡＝一個 entity / graph node。deep tier 改寫時，frontmatter 補一句 `gloss:`——這個 node 是什麼的一句定義。下游 KBDB 對「entity 名 + gloss」一起做 embedding 求相似度，自動歸一同義詞（比只對名字準、比手維護 alias 表自動）。 + +- **在知識生產的當下、由整理者（CC / Cowork）建**：gloss 跟三元組同階段萃，**不留給下游 ingest 臨時補**——下游只有單檔／跨庫視角，編不出貼合的 gloss。 +- **選填、deep tier 才產**：淺萃不浪費。 +- **gloss ≠ 摘要**：`gloss` 是 frontmatter 給機器 normalize 的定義句（「X 是…」）；`## 摘要` 是給人讀的核心句。 +- **對齊下游 envelope**：frontmatter `gloss:` 對應 ingest envelope 的 `nodes[].gloss`。 + +> **改寫時必守**：① 絕不寫入 raw source（只往 `cards//` 寫，事後驗 raw source 0 異動）；② 檔名＝卡片全名，冒號用全形「：」、斜線用全形「／」，全程一種字元避免斷鏈。 + +### 使用 typed-edge 三元組（不只裸 `[[wikilink]]`） + +整理時，發現內容與其他頁面有關聯，用**帶語義的三元組**寫進 `## 關聯`，而非只列裸 `[[頁面]]`。裸 `[[A]]` 只說「有關」、沒說關係，下游要建 knowledge graph 還得回讀兩張卡；三元組把關係也預編譯，ingest 直接 parse 出帶類型的有向邊。 + +格式 `A >> 謂詞 >> B`，規則： +1. **方向性**：必須讀成「A（謂詞）B」一句通順的話；A、B 順序＝主→賓真實方向。 +2. **謂詞用動詞 / 動詞短語**（反駁、奠基於、是…的實作），天然帶方向。 +3. **謂詞自由書寫**，不受控詞彙；下游對謂詞 embedding 時同義謂詞會自動聚類，但方向仍靠書寫順序保證。 +4. **向後相容**：純 `[[A]]` 仍合法（無類型邊），盡量補謂詞。 + +`>>` 為分隔語法，全程一致即可。這是 Karpathy LLM Wiki「知識互連」的強化版——連結不只存在，還帶類型與方向。 + +--- + +## 第五步：更新 INDEX.md 和 status.md + +### INDEX.md 格式（頂層 = 標籤視圖） + +頂層 INDEX 按 `TAXONOMY.md` 的軸聚類，指向各桶子索引（帶路徑），不是平鋪頁面列表： + +```markdown +# Wiki Index + +> 最後更新：YYYY-MM-DD HH:MM | 來源：cowork-scan | 總卡數：N + +### 知識管理 +- [[pkm/00-INDEX]] — PKM 知識管理（N 卡） + +### AI 協作 +- [[ai/00-INDEX]] — AI 協作（M 卡） +``` + +桶子索引 `cards//00-INDEX.md` 是容器（只連不重寫，H2/H3 分節列出該桶卡片）。 + +### status.md 更新 + +在現有內容**末尾追加**（不覆蓋）： + +```markdown +## YYYY-MM-DD HH:MM｜cowork-scan + +- vault 類型：[Logseq / Obsidian / 一般專案] +- 掃描檔案：N 個 +- 新增頁面：N 個 +- 更新頁面：N 個 +- 跳過：N 個（未變動） +``` + +--- + +## 第六步：回報結果 + +整理完所有資料夾後，輸出摘要： + +``` +✅ Wiki 整理完成 + +資料夾 1：~/Documents/project-a + 類型：一般專案 + 新增：3 頁，更新：1 頁，跳過：12 頁 + +資料夾 2：~/Documents/Logseq + 類型：Logseq vault + 新增：5 頁，更新：2 頁，跳過：47 頁 + +總計：8 頁新增，3 頁更新 +``` + +--- + +## 絕對禁止 + +- ❌ 修改任何 raw source 檔案 +- ❌ 修改 `CLAUDE.md` +- ❌ 動 `logseq/`、`.obsidian/`、`assets/` 資料夾 +- ❌ 刪除 `.claude/wiki/` 裡已有的頁面（只增補，不刪除） +- ❌ 把機敏資訊（密碼、金鑰、個資）寫進 wiki（遇到跳過並記錄） +- ❌ 整理沒有 `.claude/wiki/` 的資料夾（那不是這個 skill 的目標）