🛠 Wiki 維護實戰手冊
從 v1.0 到 v1.3.2 全套作業流程的實戰整理。 補充 CLAUDE 的「規範面」，本檔提供「動手做」的具體 SOP、觸發詞、踩坑經驗。 配套讀物：Karpathy LLM Wiki 模式（理論起源）
0. 為什麼這套 — 一句話版
把雜亂素材（網頁剪藏、會議紀錄、論文、對話 transcript）編譯成持續維護的 markdown 知識庫。一次編譯，永久受益，比 RAG 即時查碎片更可靠。
對你的現實意義：
- 學的東西不會散在各處 / 看完忘
- 跨主題能找到關聯（透過 wiki-link 雙鏈）
- 換 AI 工具也帶得走（純 markdown）
1. Vault 結構（v1.3 階層）
Vincent5588_Wiki/
├── CLAUDE.md ← LLM 維護規範（讀這個給 AI 看）
├── raw/ ← Layer 1：原始素材（content 唯讀）
│ ├── 01-articles/ inbox：網頁、技術文章
│ ├── 02-papers/ 論文 / PDF
│ ├── 03-transcripts/ Podcast / 會議轉錄
│ ├── 04-meeting-notes/ 會議紀錄 / 腦力激盪
│ └── 09-archive/YYYY-MM/ archive fallback
│
├── wiki/ ← Layer 2：LLM 編譯產物
│ ├── entities/<domain>/<type>/<X>.md v1.3 階層分類
│ ├── maps/ 跨主題 mermaid 圖
│ ├── index.md 主目錄（裝得進單一 context）
│ ├── log.md 變更日誌（append-only）
│ └── reports/ ingest / repair audit
│
├── 00-Inbox/ ← PARA: 未分類想法
├── 10-Notes/ ← PARA: Zettelkasten 永久筆記
├── 20-Projects/<X>/sources/ ← PARA: 在建專案 + raw routing 目的地
├── 30-Areas/<Y>/sources/ ← PARA: 長期領域
├── 40-Resources/ ← PARA: 主題資源（含本檔）
│ ├── Claude/ Claude 學習資料
│ ├── PAM/ PAM 系統技術文件
│ └── ...
└── 50-Archive/ ← PARA: 已封存
三層分工：
- raw/：真理錨點，AI 永不改 content（可移動檔案到 PARA / archive）
- wiki/：AI 完全維護，是「學完整理出來的知識網」
- PARA (00-50)：人主導的領域 / 專案 / 資源管理，AI 不碰除非走 PARA_ROUTING
2. 日常 4 個核心操作
2.1 Ingest — 把新素材編譯進 wiki
何時用：拿到一份新文章 / 規格 / 訪談，想抽取出可重用的概念。
怎麼觸發：把檔案放 raw/01-articles/（或對應子分類）後，跟 Cowork 說：
ingest raw/01-articles/your-file.md
或直接在 Cowork 用 slash command：/wiki-ingest
Cowork 會做的事（v1.3 完整 12 步）：
1. 讀 raw/{path}/{file}
2. 跟你確認重點 / 討論
3. 抽出 atomic 概念，每個推論 domain + type，寫到 wiki/entities/<domain>/<type>/
4. 為相關既有概念加 backlink
5. 標記矛盾（若有）
6. 更新 wiki/index.md
7. 在 wiki/log.md 追加 ingest 紀錄
8. 提案 raw 路由目的地（PARA 候選 + archive fallback）
9. 等你裁決，搬 raw 檔
10. 同步更新所有引用該 raw 的 entity sources
11. 在 wiki/log.md 追加 route 紀錄
12. 回報：影響哪些頁、矛盾、後續調查主題
實例（我們處理過的）：
你：ingest raw/01-articles/CallIT 資訊需求單系統重生計畫 - 方案設計書.md
Cowork：
- 抽出 6 個 atomic entity（CallIT 系統 / 五層式架構 / 需求單生命週期 /
LDAP 認證流程 / 單號流水號規則 / 歷史異動日誌）
- 新建 domain: callit（reuse-first 規則：找不到既有合適 domain 才開新）
- 標 3 個未解問題到「待解 / 矛盾」段，等業務確認
- 提案 raw 搬到 20-Projects/CallIT-重生計畫/sources/（建議 1）
或 raw/09-archive/2026-04/（fallback）
你回 1，Cowork 搬檔 + 更新 6 個 entity 的 source
2.2 Query — 問 wiki
何時用：想知道「我之前對 X 怎麼整理的？」、「PAM 的 Y 流程是什麼？」
怎麼觸發：
我 wiki 裡關於 X 怎麼說？
過去我對 Y 的決策是什麼？
/wiki-query
Cowork 會做的事：
1. 強制先讀 wiki/index.md 找候選頁
2. 深度閱讀 3-5 個對應 entity
3. 綜合答案，每條事實都附 [[wiki-link]] 引用
4. 結尾列引用源
5. 若 wiki 沒這部分 → 主動問「要從 raw 哪份 ingest 嗎？」
為什麼比直接問 Claude 強：答案錨定在你已編譯的知識，不是 Claude 模型記憶的通用內容。少幻覺、可追溯。
2.3 Lint — 健康檢查
何時用：每週日花 30 分鐘巡一次；或大批 ingest 後想看新增的 dangling refs。
怎麼觸發：
巡 wiki
lint wiki
健康度檢查
/wiki-lint
Cowork 會做的事：
1. 跑 lint.py 掃 wiki/entities/ + wiki/maps/
2. 產 5 維度評分（滿分 100）：
- Orphans (孤兒頁無人引用)：20
- Missing (引用到不存在的頁)：20
- Density (1-inlink 弱密度頁)：20
- Hubs (是否有強樞紐 ≥10 inlinks)：20
- God nodes (inlinks 多但內文薄的空殼)：20
3. 報告分 4 級優先：High / Medium / Writing / Informational
4. 給每條問題建議修法
5. ❌ 不自動套用修補 — 等你批准
6. 在 wiki/log.md 追加 lint 紀錄
評分對照：
| 分數 | 狀態 | 意義 |
|---|---|---|
| 90-100 | Excellent | 可上線 |
| 75-89 | Healthy | 持續維護中 |
| 60-74 | Needs maintenance | 該處理 |
| 40-59 | Major gaps | 大修 |
| < 40 | Restart consideration | 結構重整 |
我們最後跑出來 96/100，就是這個目標。
2.4 Repair — 套用修補（v1.3.1 新）
何時用：lint 跑出問題清單，想批量修。
怎麼觸發：
修補 wiki
fix wiki
批量修 wiki
/wiki-repair
Cowork 會做的事：
1. 跑 wiki-lint 拿 JSON
2. 跑 repair.py 把問題分類：
- auto-fixable (4 類)：壞 source / 缺 frontmatter / 死連結可解析 / 孤兒 backlink
- needs-review (3 類)：矛盾 / god-node / 重複 entity
3. 印 dry-run plan
4. 等你回 go / apply N / cancel
5. 套用 → 寫 wiki/reports/REPAIR_YYYYMMDD.md audit
6. 在 wiki/log.md 追加 repair 紀錄
重要原則：
- ❌ 不自動套用任何修補
- ✅ 永遠 dry-run + 你批准
- ✅ 套用是 atomic，失敗一條繼續其他
- ✅ 不改 basename（wiki-link 安全）
- ✅ 不跨 domain 自動合併
3. v1.3 entity 階層分類
domain — 主題域（reuse-first，自由發明）
當前 vault 用的：
| domain | 用途 | 範例 |
|---|---|---|
pam | 績效考核系統 | GradingService、年度結算流程 |
claude | Claude 生態 | Cowork、Claude Code、MCP 三層架構 |
wiki | karpathy-wiki-pattern plugin 自身 | wiki-ingest、wiki-lint |
callit | IT 工單系統重生計畫 | CallIT 系統、需求單生命週期 |
開新 domain 的時機：reuse-first 規則找不到合適的既有 domain 時，才開。
type — 物件類型（v1.3 標準 7 種）
| type | 意義 | 範例 |
|---|---|---|
process | 流程 / SOP / 工作流 | 年度結算流程、LDAP 認證流程 |
concept | 抽象概念 / 模型 | 上下文壓縮、需求單生命週期 |
role | 角色 / 職責 | 角色 HR Reviewer Approver |
artifact | 具體文件 / 報表 | 考核表單 PDF、CLAUDE.md（專案手冊） |
pattern | 可重複使用的技巧 | Chain of Thought、五層式架構、四種使用模式 |
system | 系統 / 服務 / 模組 | GradingService、CallIT 系統、wiki-ingest |
rule | 規則 / 政策 / 約束 | 等第天花板、單號流水號規則 |
舊版 type 詞彙（product / feature / service / tool / technique / reference）已全部停用，v1.3 backfill 時強制映射過。
路徑
wiki/entities/<domain>/<type>/<basename>.md
<basename> 是 entity 顯示名稱（中文 / 英文 / 空白都 OK），<domain> 與 <type> 是 kebab-case ASCII。
4. PARA Routing（v1.3 raw 路由）
ingest 完一份 raw 檔後，要決定它擺哪：
RAW: raw/01-articles/X.md
Entities extracted: N (主要 → domain Y/)
候選 1: 20-Projects/<相關專案>/sources/X.md (專案有對應)
候選 2: 30-Areas/<相關領域>/sources/X.md (長期領域)
候選 3: 40-Resources/<主題>/X.md (資源資料)
候選 4: raw/09-archive/YYYY-MM/X.md (archive fallback)
候選 5: <你自訂的路徑>
回 1/2/3/4/<custom>/skip
reuse-first 原則：先看既有 PARA 子資料夾能不能裝，能就用既有。要新建子資料夾 Cowork 會明確標 (create new folder)。
搬檔同時必做：所有引用該 raw 的 entity 之 source: 欄位同步改寫到新路徑（atomic，避免半新半舊）。
5. 真實場景對照
5.1 我學了一篇新文章 / 看完一個技術影片
1. 把文章存 raw/01-articles/your-file.md（轉錄稿存 raw/03-transcripts/）
2. 跟 Cowork 說「ingest raw/01-articles/your-file.md」
3. Cowork 會跟你討論抽哪些概念，可以把控
4. 決定 raw 搬哪裡（PARA 或 09-archive）
5. 完
5.2 想知道某個技術概念
1. 開新對話跟 Cowork 說「我 wiki 裡關於 X 怎麼說」
2. Cowork 讀 index → 找頁 → 綜合答案 + 引用
3. 若答不出來：「wiki 沒這部分，要我從 raw/{x} ingest 嗎？」
5.3 wiki 一段時間沒整理，想看健康度
1. 跟 Cowork 說「巡 wiki」
2. Cowork 給 0-100 評分 + 問題清單
3. 看哪些問題你想處理
4. 接著「修補 wiki」進 repair 流程，dry-run + 批准
5.4 一個既有 entity 內容過時想更新
直接在 Obsidian 編輯 entity，bump frontmatter 的 updated: 日期。或跟 Cowork 說「把 X 的 Y 段更新成 Z」。
5.5 plugin 升版要分發到其他電腦
1. cd 到 vault
2. powershell -ExecutionPolicy Bypass -File .\wiki\package-plugin-v1.3.x.ps1
3. wiki/dist/karpathy-wiki-pattern-v1.3.x.plugin 拿去其他電腦
4. 其他電腦：拖 .plugin 進 Cowork → 同意安裝 → 重啟
6. 已知坑 + 解法（這次踩過的）
6.1 Cowork session 路徑會換 GUID
症狀：寫死 local-agent-mode-sessions/<GUID>/... 的路徑，重啟 Cowork 就找不到。
對策：腳本裡用搜尋邏輯，掃 $env:APPDATA / $env:LOCALAPPDATA / ~/.claude 下的 plugin.json，比對 name == karpathy-wiki-pattern。優先選非 session 路徑（持久化在 .claude/plugins/）。
6.2 PowerShell 5.1 用 system 碼頁讀 .ps1
症狀：腳本含中文，PowerShell 用 Big5 讀 UTF-8 檔 → 中文變亂碼 → parse error。
對策：腳本程式碼純 ASCII；中文資料抽到 JSON 用 [System.IO.File]::ReadAllText(path, [System.Text.Encoding]::UTF8) 顯式讀。
6.3 PowerShell Out-File -Encoding UTF8 寫 BOM
症狀：Python 3.14 用 encoding="utf-8" 讀就炸 Unexpected UTF-8 BOM。
對策：Python 改用 encoding="utf-8-sig"（BOM 有沒有都吃）。
6.4 Dropbox sync 鎖檔
症狀：staging 寫進 Dropbox 內，立刻 zip 會被 Dropbox 鎖住 → Compress-Archive 失敗。
對策：用 .NET [System.IO.Compression.ZipFile]::CreateFromDirectory() + retry loop（每次間隔 2/4/6/8 秒，5 次後放棄）。或暫停 Dropbox 同步。
6.5 lint v1.2 不相容 v1.3 階層
症狀：entities_dir.glob("*.md") 不遞迴，v1.3 把檔放在 <domain>/<type>/ 子層 → lint 看不到 → total_pages: 3（只有 maps）。
對策：改用 rglob("*.md")。LEGITIMATE_PREFIXES 也要加 20-Projects/ 30-Areas/ 等 PARA tier，避免 source 路徑被誤報。
6.6 Edit 工具要求 Read 過
症狀：File has not been read yet。
對策：批量 Read（用 limit: 15 只讀前幾行省 token）→ 批量 Edit（parallel）。
6.7 同 basename 跨 domain（v1.3.2 已自動偵測）
症狀：pam/system/X.md 跟 claude/system/X.md 同名 → Obsidian wiki-link [[X]] 會 ambiguous。
v1.3.2 起 lint 自動偵測：跑 wiki-lint 會在 score breakdown 顯示 collisions 維度（×20 分權重最重）。為 0 才滿分。
對策：ingest 時必偵測，不允許自動建。改用「合併成一頁」或「加區分詞」（如 公告系統 (PAM) vs 公告系統 (CallIT)）。
6.8 跨資料夾 basename 衝突（lint 偵測不到）
症狀：40-Resources/People/Andrej Karpathy.md + wiki/entities/wiki/person/Andrej Karpathy.md → Obsidian 仍歧義，但 v1.3.2 lint 只掃 wiki/entities + wiki/maps，掃不到。
對策：ingest person / artifact 類 entity 時手動檢查 PARA 資料夾是否已有同名檔。發現時：刪空 stub、或重命名。
6.9 wiki-ingest 漏更新 wiki/index.md header（v1.3.2 已修）
症狀：ingest 完只加新 entity 連結到 index 內文，但 header 的「條目數 / 最後更新 / 分類」沒 bump。
v1.3.2 修：SKILL.md step 7 (a)–(d) 明文要求同步 4 件事（entity 連結 / domain 計數 / 條目數 / 最後更新日期）。
7. Plugin 維護 / 升版
升版觸發時機
| 情境 | 升 |
|---|---|
| 新增 / 改 skill | minor 號（v1.3.0 → v1.3.1） |
| 補 bug 不改規範 | patch 號（v1.3.1 → v1.3.2） |
| 結構規範大改（如 entity 階層） | major 號（v1.2 → v1.3） |
升版 SOP（這次走過的）
1. 在 wiki/_skill-staging/<skill>/ 寫新 / 改檔
2. install-<skill>.ps1 推到本機 plugin folder（如果有）
3. 跑 wiki-lint + wiki-repair 驗證影響範圍
4. 如果 vault entities 也要動（如 v1.3 backfill），跑對應遷移腳本
5. CLAUDE.md 升版（補 §0 版本歷程、相關段落）
6. 跑 package-plugin-vX.Y.Z.ps1 → wiki/dist/ 產 .plugin
7. 自動：plugin.json + README.md 一起重產
8. 手動驗收 .plugin 內容（可用 Expand-Archive 解壓查）
9. 分發 .plugin 給其他電腦
Major 升版（如 v1.2 → v1.3）必做
- vault 端跑 Mode B backfill 把舊 entities 遷到新結構（
migrate-to-vX.Y.Z.ps1） - CLAUDE.md 升版對齊新規範（重寫 §1 結構 / §3 操作步驟 / §4 frontmatter / §6 命名）
- 寫對應 audit report
8. 觸發詞速查
| 你說 | Cowork 觸發 |
|---|---|
| 「ingest raw/xxx」 / 「處理 raw/xxx」 | wiki-ingest（單檔） |
| 「把 X 編譯成 wiki」 / 「compile xxx into atomic」 | wiki-compile（長文檔） |
| 「migrate to v1.3」 / 「整理現有 entities」 / 「backfill」 | wiki-ingest Mode B |
| 「我 wiki 裡 X 怎麼說」 / 「query wiki」 | wiki-query |
| 「巡 wiki」 / 「lint wiki」 / 「健康度」 | wiki-lint |
| 「修補 wiki」 / 「fix wiki」 / 「批量修 wiki」 | wiki-repair |
| 「同步到 Notion」 / 「push 到 Notion」 | wiki-notion-sync |
slash command 全套：/wiki-ingest /wiki-compile /wiki-lint /wiki-repair /wiki-query /wiki-notion-sync
9. 相關文件
- CLAUDE — LLM 維護規範（給 AI 讀，本檔給人讀）
- Karpathy LLM Wiki 模式 — 原理 / 設計動機
- log — 變更歷史
- index — 主目錄
10. 心法
- 編譯 > RAG：一次編譯，永久受益
- 原子化 + 階層：一個概念一個頁面，按 domain/type 自然分類
- 連結 provenance：強連結 vs 推斷連結 ?? 分清楚
- lint 偵測 + repair 修補分離：偵測快、修補要批准
- 每次操作留 audit：log + report 雙層
- basename 穩定：移檔不改名，wiki-link 才不會斷
- AI 動手前先確認：dry-run plan + 你批准才動
- 持續迭代：v1.0 → v1.3.2 是兩個月內的事，每次升版有對應的 backfill / patch 流程
附錄 A：v1.3.1 收尾數字
98 entities + 3 maps / 4 domains × 5+ types
Health score: 65 → 96/100 (+31)
Plugin: v1.3.0 → v1.3.1（含 wiki-repair + lint patch）
打包: 63 KB .plugin 給其他電腦裝
附錄 B：v1.3.2 收尾數字
113 entities + 3 maps / 5 domains × 8 types（加 adventure-tour + person）
Health score: 96/100（維持）
Plugin: v1.3.1 → v1.3.2
+ wiki-ingest SKILL.md step 7 補 index 同步 4 條
+ wiki-lint cross-domain basename collision 偵測（5 component → 6 component）
+ lint score breakdown：5×16 + collisions×20 = 100
打包: 65 KB .plugin
附錄 C：完整 6 個 skill 對照表（v1.3.1+）
| Skill | 觸發詞 | 用途 |
|---|---|---|
| wiki-ingest | 「ingest raw/X」 | 單檔 raw → wiki entities |
| wiki-compile | 「把 X 編譯成 wiki」 | 長文檔 → 多 entity + map |
| wiki-lint | 「巡 wiki」 | 健康度檢查 + 評分 |
| wiki-repair | 「修 wiki」 | 修 lint 找到的問題 |
| wiki-query | 「查 wiki」 | 讀 wiki 答問題 |
| wiki-notion-sync | 「同步到 Notion」 | 推 entities 到 Notion |
完整生命週期：寫入（ingest/compile）→ 檢查（lint）→ 修補（repair）→ 讀取（query）→ 發布（notion-sync）。
附錄 D：實戰案例 — adventure-tour domain（戶外探險旅遊）
2026-04-27 的完整 v1.3 實戰：
- 首次 ingest（domain
tour-photo）：4 entities，新建 微信小程序框架選擇 / 小程序上線流程 / 戶外探險旅遊小程序的挑戰 / 戶外探險旅遊小程序核心功能清單 - scope 澄清後重做（domain
tour-photo→adventure-tour）：rename folder + entity 改名 + source 路徑同步 + 重寫 2 entity（5 維度 + 15 功能）+ 新建 5 entity（哲學 hub / Q&A / 安全 SOP / 離線設計 / 活動類型） - lib 選型 ingest（補完 14 entities）：小程序開發 lib 選型 hub + Vant Weapp / wenaox 離線狀態管理 / we-cropper 圖片裁切上傳 / 小程序開發工具鏈
→ 從這個案例可見 v1.3 的 domain rename + 重做 + 增量 ingest 三種模式都跑得通。同 cluster 內 14 個 entity 沒孤兒、沒衝突、跨層 backlinks 完整。
← 回到 Welcome