From d10659bd2d907a2c19b4e253accf30b8241236e9 Mon Sep 17 00:00:00 2001 From: richblack Date: Thu, 25 Jun 2026 20:01:21 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20install.sh=20=E5=81=B5=E6=B8=AC=20vault?= =?UTF-8?q?=20=E9=A1=9E=E5=9E=8B=E5=AF=AB=E5=85=A5=20raw=20source=20+=20Co?= =?UTF-8?q?work=20=E6=95=B4=E7=90=86=20skill?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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) --- README.md | 47 +++++++++++- docs/SKILL.md | 177 +++++++++++++++++++++++++++++++++++++++++++++ scripts/install.sh | 64 ++++++++++++++++ 3 files changed, 286 insertions(+), 2 deletions(-) create mode 100644 docs/SKILL.md diff --git a/README.md b/README.md index 70e1e6f..36e4fe6 100644 --- a/README.md +++ b/README.md @@ -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） ``` --- diff --git a/docs/SKILL.md b/docs/SKILL.md new file mode 100644 index 0000000..86aeeef --- /dev/null +++ b/docs/SKILL.md @@ -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（如果存在） +- 含有 `` 標記的區段 + +### 整理邏輯 + +每個 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 的目標） diff --git a/scripts/install.sh b/scripts/install.sh index caaac93..1bbba25 100644 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -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 < 安裝時偵測到的 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 <> 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 讀取順序，請手動加入："