kbdb-graph-plugin/system-dev/docs/SKILL.md

name, description

name	description
wiki-cowork-scan	掃描本機 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	只讀，不動
system-dev/wiki/	唯一輸出地點，只增不覆
CLAUDE.md	不動
logseq/、.obsidian/、assets/	絕對不動

CC 和 Cowork 輸出格式相同，任何一方整理過的內容，另一方看到就跳過或補充，不覆蓋。

---

第一步：發現所有目標資料夾

掃描 ~/Documents（遞迴深度 3 層），找出所有含 system-dev/wiki/ 的資料夾。

~/Documents/
  project-a/system-dev/wiki/     ← ✅ 目標
  Logseq/system-dev/wiki/        ← ✅ 目標
  其他資料夾/                  ← ❌ 跳過

找到後列出清單，告訴使用者：「找到 N 個 wiki 資料夾，開始整理。」

---

第二步：對每個資料夾偵測 vault 類型

進入每個目標資料夾的根目錄（system-dev/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 狀態

進入 system-dev/wiki/，讀取：

• INDEX.md：目前已有哪些 wiki 頁面（多角度視圖入口）
• status.md：上次整理時間、進度
• principles.md（如果有）：本專案跨全局的設計原則——整理時必須服從

目的：知道哪些已整理過，只處理新增或有變動的 raw source，不重複整理。

---

第四步：整理規則

核心判準：push vs pull（wiki 是給 AI 看的）

整理任何內容前，先判斷它該進 push 檔 還 cards（pull）——判準是「CC 做事時會不會被動看見」：

• push 檔（status.md / mistakes.md / principles.md）：CC session 開始就被 hook 注入。給「CC 不會主動查、但不看就出事」的東西。
• pull（cards/）：CC 想到要查才看見。一切知識內容（原文摘要、AI 筆記、決策、概念…）都寫成 cards。

內容	去哪	理由
當前進度、下一步	status.md（push 全文）	時態狀態，不看會重做
跨全局設計原則（一行一條，≤15）	principles.md（push 全文）	會被遺忘的盲區，CC 設計時必服從
踩坑、被糾正的誤解	mistakes.md（push 摘要+按需展開）	防 CC 不自覺的盲區
決策、原文摘要、概念知識、其餘一切	cards/<bucket>/（pull）	知識內容；CC 面對時自然會查

decisions-summary.md 已降級為 cards + INDEX 決策視圖（決策＝知識內容）。既有的保留為相容，不刪。 CC 與 Cowork 共用此判準，產出一致：任一方寫進 push 檔或 cards，另一方看到就跳過或補充，不覆蓋。

讀 raw source

逐一讀取 raw source 的 .md 檔。跳過：

• 檔名以 . 開頭的隱藏檔
• .wikiignore 裡列出的 glob pattern（如果存在）
• 含有 <!-- wiki:ignore --> 標記的區段

整理邏輯

每個 raw source 檔案，判斷：

1. INDEX.md 裡已有對應條目，且 raw source 未修改 → 跳過
2. INDEX.md 裡已有條目，但 raw source 有新內容 → 更新對應 wiki 頁面，補充新資訊，不刪舊內容
3. INDEX.md 裡沒有對應條目 → 新建 wiki 頁面

Wiki 卡片格式（概念原子卡，存到 cards/<bucket>/）

---
tags: [知識管理, AI協作, 方法論]
gloss: 一句話定義這個概念是什麼（給下游語義 normalize 用，選填、deep tier 才產）
---
# 概念全名

← [[<bucket>/00-INDEX]]

**來源**：`[raw source 相對路徑]`
**最後更新**：YYYY-MM-DD

## 摘要

[一句話核心]

## 重點

- [自包含改寫的要點，不寫「詳見原文」]

## 關聯

- [[本卡]] >> 謂詞（動詞短語） >> [[他卡]]
- [[原子筆記]] >> 是其最小單元 >> [[卡片盒筆記法]]

架構：三層 + 標籤橫切（183 卡實證）

INDEX.md              ← 頂層：標籤視圖（非資料夾列表）
TAXONOMY.md           ← 標籤字典（受控擴充：先查重再登記）
cards/<bucket>/
  ├── 00-INDEX.md     ← 桶子索引（固定名，容器：只連不重寫）
  └── <概念全名>.md    ← 概念原子卡

• 資料夾只是儲存桶，分類由 frontmatter tags: 承載——不繼承原稿目錄，由 AI 重新組織。
• 桶子索引固定名 00-INDEX.md：00- 排序最前、一眼可辨，載入任何桶先讀它。
• frontmatter tags: 而非行內 #tag：內文常用 #（如 #猜想），行內標籤會讓 ingest 分不清「分類」與「內文範例」污染 graph；frontmatter 零歧義。標籤只能用 TAXONOMY.md 列出的；禁止繞過字典在卡片直接冒新標籤，但字典可受控擴充（遇新軸先查重、確認非同義詞，再登記進本 repo 的 TAXONOMY.md）。
• 麵包屑帶路徑：H1 次行 ← [[<bucket>/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/<bucket>/ 寫，事後驗 raw source 0 異動）；② 檔名＝卡片全名，冒號用全形「：」、斜線用全形「／」，全程一種字元避免斷鏈。

---

第五步：更新 INDEX.md 和 status.md

INDEX.md 格式（頂層 = 標籤視圖）

頂層 INDEX 按 TAXONOMY.md 的軸聚類，指向各桶子索引（帶路徑），不是平鋪頁面列表：

# Wiki Index

> 最後更新：YYYY-MM-DD HH:MM | 來源：cowork-scan | 總卡數：N

### 知識管理
- [[pkm/00-INDEX]] — PKM 知識管理（N 卡）

### AI 協作
- [[ai/00-INDEX]] — AI 協作（M 卡）

桶子索引 cards/<bucket>/00-INDEX.md 是容器（只連不重寫，H2/H3 分節列出該桶卡片）。

status.md 更新

在現有內容末尾追加（不覆蓋）：

## 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/ 資料夾
• ❌ 刪除 system-dev/wiki/ 裡已有的頁面（只增補，不刪除）
• ❌ 把機敏資訊（密碼、金鑰、個資）寫進 wiki（遇到跳過並記錄）
• ❌ 整理沒有 system-dev/wiki/ 的資料夾（那不是這個 skill 的目標）