feat: install.sh 偵測 vault 類型寫入 raw source + Cowork 整理 skill

- install.sh：建立 CLAUDE.md 前偵測資料夾類型，寫入對應 raw source - logseq/ → pages/, journals/ - .obsidian/ → 根目錄 .md - 都沒有 → docs/（維持原行為）宣告區塊對 vault 明令不得搬動/改名 .md，整理只寫進 .claude/wiki/。已有 CLAUDE.md 一律不覆蓋，改列提醒手動補。 - docs/SKILL.md：給 claude.ai Cowork 的 wiki-cowork-scan skill，與 CC 共用同一套偵測與整理規則。 - README：新增 vault 支援、Cowork 整理兩節，更新目錄樹。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-25 20:01:21 +08:00
parent 25cb4d1f63
commit d10659bd2d
3 changed files with 286 additions and 2 deletions
@@ -11,7 +11,13 @@ CC 是個優秀的工程師，但不是個好的專案經理。它會猛衝完
 | 系統 | 解決什麼 | 核心機制 |
 |------|---------|---------|
 | **SDD 系統** | 全局觀、先想再做 | 動手前必須有 design.md + tasks.md |
-| **LLM Wiki** | 記憶累積、文件有序 | 雙空間：docs/（人寫）+ .claude/wiki/（CC 整理）|
+| **LLM Wiki** | 記憶累積、文件有序 | 雙空間：原始文件（人寫）+ .claude/wiki/（AI 整理）|
+
+> **不只程式碼專案、不只 Claude Code。** LLM Wiki 現在也認得 **Logseq / Obsidian vault**——
+> 安裝時自動偵測你在哪種資料夾，把對應的「原始文件來源」寫進 `CLAUDE.md`，整理 wiki 時只讀那裡、
+> 絕不搬動 vault 結構（見下方「不只程式碼，也認得 Logseq / Obsidian vault」）。
+> 整理者也不限 Claude Code——**claude.ai 的 Cowork** 可以用同一套規則掃描、整理你本機的所有 wiki
+> （見下方「Cowork 也能整理 wiki」）。

 - SDD：它已經很流行了，做的最徹底應該是 Amazon Kiro，但台灣無法付費，用這個方式比什麼酷炫方式更好，逼 CC 不隨心所欲。
 - LLM Wiki：是大神 Karpathy 提出的最新的 RAG 想法，這是 Pre-compile 做法，比你公司買的用嵌入模型切割文件成向量的方式更優更不瑣碎，而且執行容易。
@@ -92,6 +98,42 @@ curl -sSL https://raw.githubusercontent.com/uncle6me-web/system-dev-template/mai

 ---

+## 不只程式碼，也認得 Logseq / Obsidian vault
+
+LLM Wiki 原本假設「原始文件放在 `docs/`」，但 Logseq、Obsidian 這類筆記 vault 有自己的目錄慣例。
+現在 `install.sh` 會在建立 `CLAUDE.md` 之前**自動偵測資料夾類型**，把對應的「原始文件來源（raw source）」寫進 `CLAUDE.md`：
+
+| 偵測到 | vault 類型 | raw source（原始文件來源）|
+|--------|-----------|---------------------------|
+| `logseq/` 資料夾 | Logseq | `pages/`、`journals/` |
+| `.obsidian/` 資料夾 | Obsidian | 根目錄下所有 `.md` |
+| 都沒有 | 一般專案 | `docs/`（維持原行為）|
+
+寫進 `CLAUDE.md` 的這段宣告是**給 AI 讀的指令**——它告訴整理者「原始文件在哪、整理 wiki 時只讀那裡」，
+而且對 vault **明令不得搬動、改名、重新分類 `.md`**，整理結果一律只寫進 `.claude/wiki/`。
+這樣面對筆記 vault 也不會破壞它原本的結構，筆記不會變得不可讀。
+
+> **已有 `CLAUDE.md`？** 一律不覆蓋（維持「已有的不動」原則），改在安裝結尾**列出該補的宣告**提醒你手動貼。
+
+---
+
+## Cowork 也能整理 wiki
+
+整理 wiki 的人不再只有終端機裡的 Claude Code——**claude.ai 的 Cowork** 也可以。
+`docs/SKILL.md` 提供一個給 Cowork 用的 skill（`wiki-cowork-scan`），它與 CC 的 `/wiki-init`、`/wiki-capture`
+**共用同一套規則**：
+
+- 掃描 `~/Documents` 下所有裝了 system-dev-template（含 `.claude/wiki/`）的資料夾
+- 用**和 `install.sh` 一致的偵測邏輯**判斷每個資料夾是一般專案 / Logseq / Obsidian
+- 只讀 raw source、只往 `.claude/wiki/` 增補（不覆蓋、不刪除），**絕不動** raw source、`CLAUDE.md`、`logseq/`、`.obsidian/`、`assets/`
+
+**CC 與 Cowork 輸出格式相同**，任一方整理過的內容，另一方看到就跳過或補充，不重複也不覆蓋。
+適合掛在 Cowork 的定期排程，讓本機所有 wiki 自動保持更新。
+
+> 想用：把 `docs/SKILL.md` 提供給你的 Cowork 當 skill 參考，再對它說「整理 wiki」即可。
+
+---
+
 ## 目錄說明

 ```
@@ -114,7 +156,8 @@ system-dev-template/
 │
 └── docs/               ← 這個 repo 自己的說明
    ├── why.md          ← 設計理念
-    └── wishlist.md     ← 待補功能與已完成記錄
+    ├── wishlist.md     ← 待補功能與已完成記錄
+    └── SKILL.md        ← 給 claude.ai Cowork 的 wiki 整理 skill（wiki-cowork-scan）
 ```

 ---
@@ -0,0 +1,177 @@
+---
+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（如果存在）
+- 含有 `<!-- wiki:ignore -->` 標記的區段
+
+### 整理邏輯
+
+每個 raw source 檔案，判斷：
+
+1. **INDEX.md 裡已有對應條目，且 raw source 未修改** → 跳過
+2. **INDEX.md 裡已有條目，但 raw source 有新內容** → 更新對應 wiki 頁面，補充新資訊，不刪舊內容
+3. **INDEX.md 裡沒有對應條目** → 新建 wiki 頁面
+
+### Wiki 頁面格式
+
+```markdown
+# [主題名稱]
+
+**來源**：`[raw source 相對路徑]`
+**最後更新**：YYYY-MM-DD
+
+## 摘要
+
+[2-3 句話說明這份文件在講什麼]
+
+## 重點
+
+- [要點 1]
+- [要點 2]
+
+## 關聯
+
+- [[相關 wiki 頁面]]
+```
+
+### 使用 `[[wikilink]]` 語法
+
+整理時，如果發現內容與其他 wiki 頁面有關聯，加上 `[[頁面名稱]]` 連結。這是 Karpathy LLM Wiki 的核心機制——知識會互相連結，不是孤立的筆記。
+
+---
+
+## 第五步：更新 INDEX.md 和 status.md
+
+### INDEX.md 格式
+
+```markdown
+# Wiki Index
+
+> 最後更新：YYYY-MM-DD HH:MM | 來源：cowork-scan | 總頁數：N
+
+## 頁面列表
+
+| 頁面 | 來源 | 摘要 | 最後更新 |
+|------|------|------|----------|
+| [[頁面名稱]] | `raw/path.md` | 一句話摘要 | YYYY-MM-DD |
+```
+
+### 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 的目標）
@@ -76,6 +76,58 @@ echo ""
 echo "📦 安裝模組：$MODULE"
 echo ""

+# ── 偵測 vault 類型 → 決定 raw source（原始文件）路徑 ──────────
+# 為什麼：這個模板原本假設「原始文件在 docs/」，但 Logseq / Obsidian
+#   這種 PKM vault 有自己的目錄慣例，整理時不能照 docs/ 那套搬動，
+#   否則會破壞 vault 結構、讓筆記變不可讀。
+#   偵測結果寫進 CLAUDE.md，讓 CC 和未來的 Cowork skill 都知道
+#   「該讀／該整理哪裡」而不是亂動。
+#   必須在建立 CLAUDE.md 之前跑完。
+VAULT_TYPE=""
+RAW_SOURCE=""
+if [ -d "logseq" ]; then
+  VAULT_TYPE="logseq"
+  RAW_SOURCE="pages/, journals/"
+elif [ -d ".obsidian" ]; then
+  VAULT_TYPE="obsidian"
+  RAW_SOURCE="./ （整個 vault 根目錄的 .md）"
+else
+  VAULT_TYPE="docs"
+  RAW_SOURCE="docs/"
+fi
+echo "🗂️  偵測到 vault 類型：$VAULT_TYPE → raw source：$RAW_SOURCE"
+echo ""
+
+# 把「raw source 宣告區塊」吐出來，給新建的 CLAUDE.md append 或
+# 給已存在的 CLAUDE.md 當手動補貼的提示。內容對 CC / Cowork 都是
+# 機器可讀的指令（明確路徑 + 不可破壞 vault 結構的約束）。
+emit_raw_source_block() {
+  cat <<BLOCK
+
+---
+
+## 原始文件空間（raw source）
+
+> 安裝時偵測到的 vault 類型：**$VAULT_TYPE**
+> CC 與 Cowork 整理／讀取「人寫的原始文件」時，**只在這裡找、只在這裡動**。
+
+| 項目 | 值 |
+|------|----|
+| vault 類型 | \`$VAULT_TYPE\` |
+| raw source | \`$RAW_SOURCE\` |
+
+**約束（CC 與 Cowork 都必須遵守）**
+
+- 整理 wiki／知識時，原始文件**一律從上方 raw source 路徑讀取**，不要假設是 \`docs/\`。
+BLOCK
+  if [ "$VAULT_TYPE" != "docs" ]; then
+    cat <<BLOCK
+- 這是 **$VAULT_TYPE vault**：保留它原本的目錄與檔名慣例，**不得搬動、改名、重新分類** \`.md\` 檔，
+  以免破壞 vault 結構造成筆記不可讀。整理只在 \`.claude/wiki/\` 產出，**不動 raw source 本身**。
+BLOCK
+  fi
+}
+
 # ── 工具函式 ──────────────────────────────────────
 create_dir() {
  if [ ! -d "$1" ]; then
@@ -179,8 +231,14 @@ else
 fi

 # ── CLAUDE.md：只在完全不存在時建立 ────────────────
+# 新建時把偵測到的 raw source 宣告 append 進去（在建立的當下寫入，
+# 不回頭改使用者既有的 CLAUDE.md，維持「已有不覆蓋」原則）。
 if [ ! -f "CLAUDE.md" ]; then
  download_if_missing "CLAUDE.md" "$REPO_URL/CLAUDE.md"
+  if [ -f "CLAUDE.md" ]; then
+    emit_raw_source_block >> CLAUDE.md
+    CREATED+=("CLAUDE.md ← 已寫入 raw source 宣告（$VAULT_TYPE）")
+  fi
 else
  SKIPPED+=("CLAUDE.md (已存在，請手動加入對應區塊)")
 fi
@@ -201,6 +259,12 @@ echo "────────────────────────

 # CLAUDE.md 已存在 → 依模組提醒手動加區塊
 if [ -f "CLAUDE.md" ]; then
+  if ! grep -q "raw source" CLAUDE.md; then
+    echo ""
+    echo "📌 CLAUDE.md 已存在但缺少 raw source 宣告（偵測到 vault 類型：$VAULT_TYPE）。"
+    echo "   請手動把以下區塊貼進去，讓 CC 與 Cowork 知道原始文件在哪、不要亂動 vault："
+    emit_raw_source_block | sed 's/^/   /'
+  fi
  if $WANT_WIKI && ! grep -q "wiki/status.md" CLAUDE.md; then
    echo ""
    echo "📌 CLAUDE.md 已存在但缺少 wiki 讀取順序，請手動加入："