Vincent5588 Wiki

CLAUDE

閱讀時間約 33 分鐘

Vincent5588_Wiki — LLM Wiki 維護指南

本檔給未來進來的 LLM agent（Claude Code / Cowork / Codex / Cursor 等）讀。 規範您在維護本 vault 時要遵守的結構、慣例、工作流程。 模式來源：Andrej Karpathy LLM Wiki Pattern 套用 plugin：karpathy-wiki-pattern v1.3.5

0. 版本歷程

版本日期主要變動
v1.02026-04-26LLM Wiki 骨架初建（raw / wiki 雙層 + PARA + Zettelkasten）
v1.12026-04-26raw/ 子分類（01-articles / 02-papers / …）
v1.22026-04-26plugin v1.2：三段式 ingest pipeline、連結 provenance（強/推/外部）、god-node 偵測、ingest audit report
v1.32026-04-27plugin v1.3：entity 自動分類到 <domain>/<type>/、PARA_ROUTING 路由 raw 檔、Mode B backfill 整理舊 entity
v1.3.12026-04-27plugin v1.3.1：新增 wiki-repair skill（跟 lint 配對：lint 偵測 / repair 修補）
v1.3.22026-04-27plugin v1.3.2：(a) wiki-ingest SKILL.md step 7 補 wiki/index.md 同步 4 條；(b) wiki-lint 加 cross-domain basename collision 偵測（lint 從 5 component × 20 改 5×16 + collision×20）。第 8 個 type person 因應 Andrej Karpathy entity 加入
v1.3.32026-04-27plugin v1.3.3：wiki-notion-sync 支援 per-domain notebook 結構（每個 domain 在 Notion 各成一個父頁）
v1.3.42026-04-27plugin v1.3.4：修 Notion title 含 emoji 前綴 → 雙 emoji 顯示問題；batch 大小實務上限改 3
v1.3.52026-04-28/29vault patch：(a) wiki/tools/lint.py — NFC Unicode 正規化修 macOS NFD filename 假孤兒問題；(b) wiki/daily/YYYY/MM/ — 每日異動日誌，按年月分層；(c) §3.1 步驟數 12→13，補 step 8「寫 wiki/daily/」；(d) §3.1 新增「必更新檔案清單」速查表
v1.3.62026-05-02vault patch：(a) §10 新增「規則 D：英文 quote 必加繁中翻譯」；(b) §10 新增「規則 E：寫檔前先提案 / show-before-write」（來自朱騏 + Boris Plan 模式）；(c) §16 新增「Mermaid 渲染規則」收錄三個踩坑（list parser / parallelogram shape / circled digit fix）；(d) Dataview live block 修 GROUP BY 後 key/rows.X[0] 用法；(e) §10 新增「經驗法則 1：同源 ingest 整批一起審」（wiki-status-promote 首跑驗證）；(f) §4 新增「status 詞彙精確化說明」（draft/stable/deprecated 三條鐵則 + LLM agent 引用規則 + wiki-lint 整合）
v1.3.72026-05-02plugin upgrade：把 staging 版 wiki-status-promote 正式打包進 plugin（第 7 個 skill）。內含 SKILL.md + PROMOTE_RULES.md + PROMOTE_TEMPLATE.md + promote.py（含 --output-format=review-queue flag 支援團隊認領模式）。.plugin 檔在 wiki/dist/karpathy-wiki-pattern-v1.3.7.plugin（92.4 KB），Cowork 拖入安裝即可。新 vault 安裝 plugin 將直接有 7 個 skill。同時 §10 新增「經驗法則 2：同主題第 2 篇 raw → 補 source 而非建新 entity」（瓦基書評實戰驗證）

1. Vault 結構（三層 + PARA + Zettelkasten）

Vincent5588_Wiki/
├── raw/                    ← Layer 1：原始素材
│   │                          - content 永遠唯讀
│   │                          - 檔案會被 PARA_ROUTING 搬走（v1.3）
│   ├── 01-articles/        ← inbox 子分類（暫存，ingest 後會路由出去）
│   ├── 02-papers/
│   ├── 03-transcripts/
│   ├── 04-meeting-notes/
│   ├── 05-books/
│   └── 09-archive/         ← archive fallback（依 YYYY-MM/ 分月）
│
├── wiki/                   ← Layer 2：LLM 維護的編譯產物
│   ├── entities/           ← v1.3 階層：<domain>/<type>/<basename>.md
│   │   ├── pam/            （HR 績效考核系統）
│   │   │   ├── process/    （流程 / SOP）
│   │   │   ├── system/     （服務 / 模組）
│   │   │   ├── concept/    （資料模型 / 抽象概念）
│   │   │   ├── rule/       （計分 / 限制 / 政策）
│   │   │   ├── artifact/   （PDF / 報表）
│   │   │   └── role/       （角色 / 職責）
│   │   ├── claude/         （Claude 生態：產品 / 提示工程 / 工作流）
│   │   ├── wiki/           （karpathy-wiki-pattern plugin 自身）
│   │   └── callit/         （CallIT 工單系統重生計畫）
│   ├── maps/               ← 跨主題 mermaid 地圖
│   ├── index.md            ← 主目錄（必須能裝進單一 context window）
│   ├── log.md              ← 變更日誌（append-only）
│   └── reports/            ← v1.2 起 ingest / lint audit report
│
├── 00-Inbox/               ← PARA: 未分類想法（使用者主導）
│   └── Daily/
├── 10-Notes/               ← PARA: 永久筆記（Zettelkasten）
├── 20-Projects/<X>/sources/← PARA: 進行中專案（PARA_ROUTING 寫入 sources/）
├── 30-Areas/<Y>/sources/   ← PARA: 長期領域（同上）
├── 40-Resources/           ← PARA: 主題資源
│   ├── Claude/             Claude 學習指南（16 章）
│   ├── PAM/                PAM 系統技術知識庫（25 份）
│   └── ...
├── 50-Archive/             ← PARA: 已封存
├── Templates/              筆記模板
└── Attachments/            圖片 / PDF 附件

2. 三大規則（最重要）

規則 A：raw/ 內容唯讀，但檔案會被路由（v1.3 修正）

  • ✅ 你讀 raw/ 內檔的內容
  • ❌ 你永不修改 raw/ 內檔的內容
  • ✅ ingest 完成後，依 v1.3.0 PARA_ROUTING 可以移動 raw 檔到 PARA 子資料夾或 raw/09-archive/YYYY-MM/
  • ❌ 你永不重新命名 raw 檔（basename 是穩定識別碼，重新命名會斷既有引用）
  • 理由：raw 內容是真理錨點；但 raw/ 根目錄是 inbox，不該長期堆檔

規則 B：wiki/ 完全由你維護

  • 攝取（Ingest）→ 建/改 wiki/entities/<domain>/<type>/ 頁面
  • 必須同步：
    • wiki/index.md（⚠️ v1.3.0 skill 沒明寫這條，vault 規則優先）
    • wiki/log.md
  • 每頁必有 frontmatter（含 v1.3 必填欄位 domain、type、status — 詳見 §4）

規則 C：使用者 PARA 資料夾（00-50, Templates）

  • 內容你別碰（除非使用者明確要求）
  • 唯一例外：v1.3.0 PARA_ROUTING 把 raw 檔搬到 20-Projects/<X>/sources/ 等 sources 子資料夾 — 這是允許的，且只能寫 sources/ 子層，不動原有檔案

3. 四個核心操作

3.1 Ingest — 攝取新素材

當使用者說「處理 raw/xxx」、「ingest xxx」、「依 CLAUDE.md 處理這份檔」：

1. 讀取 raw/{path}/{file}
2. 跟使用者確認 / 討論關鍵重點（除非明確說「不要問直接做」）
3. 對每個 atomic 概念：
   a. 推論 domain（pam / claude / wiki / callit / 新 domain，reuse-first）
   b. 推論 type（v1.3 標準 8 種詞彙，reuse-first）
   c. 寫到 wiki/entities/<domain>/<type>/<basename>.md
4. 為相關既有概念加 backlink（避免孤兒頁）
5. 標記與既有 wiki 的矛盾，提醒使用者
6. **更新 wiki/index.md**（⚠️ 必做：新增條目連結 + 更新 header 計數/日期）
7. 在 wiki/log.md 追加 ingest 紀錄（table 一行）
8. **寫 wiki/daily/YYYY/MM/YYYY-MM-DD.md**（⚠️ 必做，見 §15）
   - 當天首次操作：新建當日 daily note（資料夾 `wiki/daily/YYYY/MM/` 若不存在則建立）
   - 同天多次操作：在既有 daily note 的 ## 詳細 下繼續追加
9. 依 PARA_ROUTING 提案 raw 目的地（候選 1：PARA / 候選 2：09-archive）
10. 等使用者裁決，才搬 raw 檔
11. 同步更新所有引用該 raw 的 entity（frontmatter source: + 內文 §引用）
12. 在 wiki/log.md 追加一筆 route 紀錄（table 一行）
13. 回報使用者：影響了哪些頁、矛盾、後續該調查的主題

每次 ingest 必更新的檔案清單（速查）：

#檔案內容步驟
①wiki/entities/<domain>/<type>/<X>.md新建 / 更新 entitystep 3
②wiki/index.md新增條目連結 + 更新計數/日期step 6
③wiki/log.mdingest 紀錄（table 一行）step 7
④wiki/daily/YYYY-MM-DD.md當日詳細異動（建或追加）step 8
⑤entity frontmatter source:routing 完成後更新路徑step 11
⑥wiki/log.mdroute 紀錄（table 一行）step 12

3.2 Query — 查詢

當使用者問問題（如「根據 wiki/，X 跟 Y 的差異是」）：

1. 先讀 wiki/index.md 找相關概念
2. 讀對應 wiki/entities/<domain>/<type>/X.md（不是讀 raw/）
3. 綜合答案，引用用 [[wiki-link]]（用 basename，Obsidian 自動解析路徑）
4. 如果 wiki 有缺：告訴使用者「wiki 沒這部分，要我從 raw/{x} ingest 嗎？」
5. 如果這次的分析有持久價值，問使用者：「要不要存成 wiki/entities/<domain>/<type>/Z.md？」

3.3 Lint — 健康檢查

當使用者說「lint」、「檢查 wiki」、「巡 wiki」：

1. 掃 wiki/entities/ 全部頁面（遞迴穿過 <domain>/<type>/）
2. 列出問題：
   - 孤兒頁（length(file.inlinks) = 0）
   - 矛盾聲明
   - 缺失概念（被 [[X]] 引用但沒對應頁）
   - god-nodes（v1.2：inlinks 多但內文薄）
   - 推斷連結密度過高（v1.2：?? 占比過高）
   - source: 路徑壞掉（v1.3 建議加入）
3. 對每個問題，提建議。**不自動修補，等使用者批准**
4. 列出值得新 ingest 的主題
5. 給健康度評分（0-100）
6. 在 wiki/log.md 追加紀錄

⚠️ lint 只偵測 + 提建議，不修補。批量修補規劃用 wiki-repair skill（待建，尚未存在）。

3.4 Migration / Backfill — 一次性結構升級（v1.3 新增）

當 plugin 升版或結構規範變動，需要一次性整理既有 entity：

1. 觸發詞：「migrate to v1.3」、「整理現有 entities」、「backfill」、「把舊的也分類」
2. 走 wiki-ingest 的 Mode B：
   a. 掃 wiki/entities/ 全部 .md
   b. 對每份檔推論新的 <domain>/<type>
   c. 產 dry-run plan（移動表 + frontmatter 改動表）
   d. 等使用者批准（"go" / "execute" / "looks good"）
3. 執行：
   a. 建新資料夾
   b. 改 frontmatter（疊加 / 取代由使用者決定）
   c. 移檔（basename 不變 → wiki-link 自動安全）
   d. 在 wiki/log.md 追加 migration 紀錄
4. 跑一次 lint 看健康度有沒有掉

4. wiki/entities/ 頁面格式（v1.3）

必要 frontmatter

---
title: "頁面標題"                 # 顯示用，盡量簡潔
type: process | concept | role | artifact | pattern | system | rule | person
                                  # v1.3.2 標準 8 種詞彙（不能自創）
                                  # person 在 v1.3.2 加入（Karpathy entity）
domain: pam | claude | wiki | callit | adventure-tour | <new>
                                  # 主題域，kebab-case ASCII，reuse-first
status: draft | stable | deprecated
                                  # 詳細定義見下方「status 詞彙精確化說明」
tags: [主題1, 主題2]              # 自由標籤，不限詞彙
source:                           # 來源（PARA_ROUTING 後路徑會被改寫）
  - "[[20-Projects/X/sources/原始檔]]"
  - "[[40-Resources/Y/某文件]]"
created: YYYY-MM-DD
updated: YYYY-MM-DD               # 每次有意義改動就 bump
aliases: [別名1, 別名2]           # 選填，跨語言/縮寫
---

type 詞彙說明（v1.3）

type意義本 vault 範例
process流程 / SOP / 工作流年度結算流程、LDAP 認證流程
concept抽象概念 / 模型 / 原理上下文壓縮、需求單生命週期
role角色 / 職責角色 HR Reviewer Approver
artifact具體文件 / 報表 / 範本考核表單 PDF、CLAUDE.md（專案手冊）
pattern可重複使用的技巧 / 用法Chain of Thought、五層式架構、四種使用模式
system系統 / 服務 / 模組GradingService、CallIT 系統、wiki-ingest
rule規則 / 政策 / 約束等第天花板、單號流水號規則
person真實人物（v1.3.2 新增）Andrej Karpathy

舊版（v1.2 之前）使用過的 product / feature / service / tool / technique / reference 已停用。Mode B backfill 時會強制映射到 v1.3 詞彙。

status 詞彙精確化說明（v1.3.6 新增）

值何時用誰決定對 LLM 的意義
draft剛 ingest 或內容仍在迭代系統預設（wiki-ingest 寫入時）LLM 引用時應加「（draft，未驗證）」警告
stable經人類審查 / 業務裁決 / 被 ≥3 entity 引用且無爭議你（半自動：wiki-status-promote 提案 → 你批准）LLM 可放心引用作為知識依據
deprecated過時 / 被替代 / 內容單薄無價值你（半自動：promote 標 🔴 候選 → 你批准）LLM 一律不該用作答案來源（即使被引用到）

🚨 三條鐵則

  1. status 變動永遠需要人類批准——系統做提案、show、執行；你做判斷、批准。不存在「年齡夠老 = 自動 stable」的規則。
  2. stable 是 trust marker，不是 mtime——看到 stable 應該代表「我相信這條知識」而不是「這檔很久沒動」。日期只是 promote 時的「該不該被審」加分信號。
  3. deprecated ≠ delete——deprecated 是「不要再用、但保留歷史 backlink」。要真的刪除，是另一個動作（lint 提示後人類執行）。

對 LLM agent 的引用規則

當你（任何進入此 vault 的 LLM agent）回答使用者問題並引用某 entity 時：

status: stable     → 直接引用，不必加註
status: draft      → 引用時必須在句尾加「（draft，未驗證）」
status: deprecated → 不該引用；如果使用者特別要求看舊資料才引用，
                     並標明「⚠️ 此 entity 已 deprecated，內容過時」

→ 這條規則跟 Bookkeeping by LLM 哲學配合：人類做信任分級、LLM 嚴格遵守分級。

跟 wiki-lint 的整合

wiki-lint 跑時會產生 status 健康度指標：

  • draft 比例 > 30% → 🔴 提示需要跑 promote
  • deprecated 沒加 ## ⚠️ Deprecated 區塊 → 🟡 標警告
  • stable 但 inlinks=0 + 90 天沒被 query → 🟡 提示是否該降回 draft 重審

內容結構建議

# 標題
 
> 一句話定義 / 摘要。
 
## 為什麼存在 / 核心要點
 
- 重點 1（用自己語言整合，不直接複製 raw）
- 重點 2
 
## 與其他概念的關係
 
### 強連結（原文明確提及）
- [[相關概念 A]] — 關係描述
 
### 推斷連結（LLM 認為相關，待確認）
- [[相關概念 B]] ?? — 推斷描述
 
### 深入閱讀
- [[40-Resources/X]] / [[wiki/maps/Y]]
 
## 來源出處
 
- [[20-Projects/X/sources/原始檔]] §3.2
 
## 待解 / 矛盾（如有）
 
> 標記未解決的問題或矛盾，等下次 ingest 解決
- ⚠️ 此處與 [[相關概念 C]] 描述衝突，待釐清

5. wiki/index.md 維護規則

  • 必須能裝進單一 context window（建議 < 4000 token）
  • 用主題分類組織（建議按 domain，再依 type 細分），不用平鋪
  • 條目格式：- [[X]] — 一行摘要（< 30 字）（用 basename，Obsidian 自動解析路徑）
  • 超過 100 條時，考慮分裂成多個 sub-index（如 index-pam.md、index-claude.md）

⚠️ 每次 ingest 必同步更新（即使 v1.3.0 skill 沒寫這步，依 §3.1 step 6）。

6. 命名規範

entity 檔名（basename）

  • 用主題核心關鍵字，盡量短
    • ✅ Transformer.md、等第天花板.md、Andrej Karpathy.md
    • ❌ Transformer 是一種神經網路架構.md（太長）
  • 中英混用 OK
  • 不用底線、用空白：Layer Normalization.md（Obsidian wiki-link 友好）
  • basename 是穩定識別碼：移動資料夾時不換 basename（換了會斷 wiki-link）

資料夾（v1.3 新增）

  • <domain> 與 <type> 都 kebab-case ASCII（不用中文，不用底線）
    • ✅ pam、claude、callit、claude-code（如新建）
    • ❌ PAM、HR_系統、行政、ClaudeCode
  • reuse-first：一個主題只開一個 domain — 別發明同義詞（已有 pam 就別開 human-resources）
  • type 用 v1.3 標準 7 種；新 type 慎開，先想能不能塞既有

衝突檢查

寫 entity 之前，檢查：

  1. 同 basename 是否已存在於別的 <domain>/<type>/ → 通知使用者（§8）
  2. 接近的同義詞是否已存在 → 考慮合併或加區分詞

7. 與既有 PAM/Claude 知識庫的關係

使用者已有：

  • 40-Resources/Claude/ — Claude 學習指南（16 章）
  • 40-Resources/PAM/ — PAM 績效考核系統技術文件（25 份）

這些是穩定文件，不要動。

但可以從這些文件中抽 atomic 概念建到 wiki/entities/，例如：

  • 從 40-Resources/PAM/03-功能模組/通知系統.md 抽 wiki/entities/pam/system/通知系統.md
  • 從 40-Resources/Claude/11-MCP 建置與使用.md 抽 wiki/entities/claude/concept/MCP 三層架構.md

抽出時，wiki entity 是精簡 + 跨主題連結版，原文件保留為深入閱讀資料（在 entity 的 ### 深入閱讀 區塊放 link）。

8. 衝突處理

同 basename 跨 domain（v1.3 新增）

如果同 basename 出現在兩個不同的 <domain>/<type> 下，Obsidian wiki-link 會 ambiguous。發生時：

  1. 不要兩邊都建
  2. 必通知使用者，提兩個解法供選：
    • (a) 合併成一頁（選一個 domain）
    • (b) 改 basename 加區分詞（如「公告系統 (PAM)」「公告系統 (CallIT)」）

內容衝突（同概念不同陳述）

當你發現新 ingest 跟既有 wiki/ 衝突：

  1. 不要直接改既有頁面
  2. 在新頁開頭加 ⚠️ 衝突 區塊說明
  3. 在既有頁面加 ⚠️ 待釐清 區塊（指到新頁）
  4. 通知使用者：「找到衝突 X vs Y，要怎麼處理？」
  5. 等使用者裁決才更新

9. 你能用的工具

本 vault 已啟用 Dataview 外掛 — 可在 index / maps / 任意頁放 query。

列出某 domain 全部 entity

TABLE WITHOUT ID file.link AS "頁面", type AS "Type", status AS "狀態", updated AS "最後更新"
FROM "wiki/entities"
WHERE domain = "callit"
SORT type, file.name

最近更新 10 個

TABLE WITHOUT ID file.link AS "頁面", domain AS "Domain", type AS "Type", updated AS "最後更新"
FROM "wiki/entities"
SORT updated DESC
LIMIT 10

找 draft 狀態待審 entity

LIST
FROM "wiki/entities"
WHERE status = "draft"
LIST
FROM "wiki/entities"
WHERE length(file.inlinks) = 0

10. 使用者風格偏好

  • 語言：繁體中文為主，技術名詞 / API 名稱 / 程式碼可用英文
  • 格式：表格、bullet points、emoji 都歡迎，但不要過度
  • 簡潔：偏好「能讀完」的長度，不要灌水
  • 引用：用 wiki-link [[ ]]，不要用 markdown link [text](path.md)
  • 避免：過度道歉、過度誇讚、過度免責聲明
  • 行動：要動手做就動手，不要每件事都先問

規則 D：英文 quote 必加繁中翻譯（v1.3.6 新增）

使用者明確指示：「非常歡迎引用原文，最好的方式是加上繁體中文翻譯。」

引用任何英文原文 quote 時，必須在原文 quote 下方緊接著一條繁中翻譯 quote。格式：

> "Original English text from the source."
>
> 繁中：「翻譯。」

範例（標準寫法）

> "The wiki is a persistent, compounding artifact."
>
> 繁中：「Wiki 是一個持久且不斷複利的產物。」

規則細節

  1. 兩條 quote 用空白 > 分隔——讀起來像「原文 → 翻譯」的對照組
  2. 翻譯前綴用「繁中：」三字 + 全形冒號，方便視覺辨識
  3. 翻譯本身用「「」」全形雙引號包起來
  4. 短句（< 10 詞）也要翻——別偷懶
  5. 專有名詞 / 技術名詞（CLAUDE.md / RAG / token 等）不必翻，原文照舊
  6. 若原文有 粗體 強調，翻譯也要對應加粗
  7. 多句長 quote 維持原文段落結構，翻譯也分段對應

不適用情境

  • 純技術名詞引用（“PostToolUse hook” 不必翻成「使用後鉤子」）
  • code block 裡的英文（bun run format 不翻）
  • 標題、書名（直接引用即可）

為什麼這條規則重要

(a) Vincent 的 vault 是繁中為主，英文 quote 不翻會破壞閱讀流暢度
(b) 翻譯本身是再次理解的過程，強迫 LLM 不只是複製貼上原文
(c) 未來查詢 / 跨檔搜尋時，繁中關鍵字也找得到原文意思

經驗法則 1：同源 ingest 整批一起審（v1.3.6 新增）

來源：2026-05-02 wiki-status-promote 首跑（callit domain）的 Compounding 飛輪觀察。

當一份 raw 文件 ingest 出 N 個 entity，其中一個 entity 升 stable（譬如 需求單生命週期 4/27 業務裁決後升 stable），其他 N-1 個應一次性審查整批升 stable——它們的可信度根源於同一個業務確認過的 source，沒理由分散處理。

實踐：跑 wiki-status-promote 時，看到某 domain 有任一個 stable 的 entity，自動推薦該 domain 內所有同 source 的 draft 一起進入候選清單。

經驗法則 2：同主題第 2 篇 raw → 補 source 而非建新 entity（v1.3.7 新增）

來源：2026-05-02 ingest 瓦基《風靡歐美的卡片盒筆記法》發現跟既有 卡片盒筆記法 12 法則 100% 重疊。

當不同 raw 描述同一個主題、同一個概念，且既有 entity 已存在（特別是 stable 狀態）時：

✅ 正確動作：把新 raw 路徑加進既有 entity 的 source: 列表，bump updated ❌ 錯誤動作：建一個「卡片盒筆記法 12 法則 v2」之類的新 entity（重複 = 違反 reuse-first）

為什麼

  • 多 source 增強可信度：1 個 source 可能誤讀，2 個獨立 source 同方向 = 高可信度。
  • 避免分裂：建 v2 後 wiki-link [[卡片盒筆記法 12 法則]] 指向不明、backlink 也分裂。
  • Compounding：每次新 raw 來都補強既有，不從零再建。

判斷流程

新 raw 進來時：

1. 跑 wiki-query 看既有 entity 有沒有覆蓋這主題
2. 有 ≥ 70% 重疊 → 補 source（本法則）
3. 有 < 70% 重疊但有新 atomic 概念 → 抽**新概念**建 entity，舊 source 仍補進相關既有 entity
4. 完全新主題 → 標準 ingest 流程（Mode A）

例外：何時該建新 entity

  • 新 raw 提了既有沒寫的 atomic 概念（譬如某書評提到原書沒有的「卡片盒回饋迴圈」這種衍生概念）
  • 不同主流 / 流派 / 時代的同主題（譬如 BASB 跟 Zettelkasten 都講第二大腦但派別不同 → 各建一個 hub）
  • 同主題但從不同角度切入（譬如 CLAUDE.md（專案手冊） vs CLAUDE.md 4 層機制 vs Compounding Engineering 都圍繞 CLAUDE.md 但角度不同）

實際操作（CLI 版）

# 找新 raw 影響的既有 entity
grep -lr "source:" wiki/entities/ | xargs grep -l "<既有 source 的 basename>"
 
# 對每個 entity 在 source: 加新 raw 的 wikilink，並 bump updated

→ 配 wiki-status-promote 看到「multi-source entity」可加分（信號權重）。

規則 E：寫檔前先提案（show before write）（v1.3.6 新增）

使用者明確同意：對檔案系統的任何寫入動作必須先在對話中讓我看 → 確認 → 才動手。

來源：朱騏 task-template-distill skill 經驗 + Boris Plan 模式 三階段「Plan → Refine → Auto-accept」。

必須先提案的動作

  • 建立新 entity / map / daily / log（新檔）
  • 大規模改 entity 內容（譬如重寫一個 entity 主體）
  • 移動 / 改名檔案
  • 改 frontmatter 結構（type、domain、status 等）
  • 批次操作（譬如 wiki-repair 一次改 N 個檔）
  • 寫 plugin / skill / 工具腳本

不需要先提案的動作

  • 純讀取（Read / Glob / Grep）
  • bash 查詢類（ls / find / wc -l）
  • 用 wikilink 給連結（不寫檔的話）
  • 跑 wiki-lint / wiki-query 等唯讀 skill
  • 顯示計算結果

提案的格式

我要做：[動作描述]
影響檔案：[路徑列表]
變動內容（節錄）：
   ...

確認後執行？

短任務（單檔小編輯）可省略格式，但必須在動手前在訊息中描述清楚。

為什麼這條規則重要

(a) 不可逆成本：AI 寫錯後刪檔 / 重整 / 改連結每一步都是隱性成本（朱騏：Claudian 多建一份 Template 害他要花時間刪掉）
(b) 使用者校正方向：reviewing draft 是 vault 品質的 last mile（沒這步 LLM 容易腦補）
(c) 養成 LLM 自我約束：寫進規則後，LLM 自己會先停下來想「這要不要提案」

例外條款

  • 使用者明確說「直接改」「不要再問」「OK 照做」 → 後續 ≤30 分鐘內可省略提案
  • 使用者批准了一個多步驟計畫 → 步驟內的每個動作不必再個別提案
  • 但新建檔案 / 改 vault CLAUDE.md 永遠要提案，不論前面同意過什麼

跟規則 A 的關係

規則 A：「raw/ 內容唯讀」是「不准動的清單」。
規則 E：「寫檔前先提案」是「動之前的儀式」。
兩者疊加 = vault 安全雙保險。

11. Quick Reference

使用者說你應該
「處理 raw/xxx」Ingest（§3.1）
「ingest xxx」Ingest
「migrate to v1.3」/「整理現有 entities」/「backfill」Mode B Backfill（§3.4）
「根據 wiki，問題 Y」Query（§3.2）
「巡一下 wiki」Lint（§3.3）
「健康檢查」Lint
「批量修 wiki」暫時手工修；待 wiki-repair skill 上線後改用
「批次升 stable」/「審草稿」/「promote drafts」wiki-status-promote skill（staging at wiki/_skill-staging/wiki-status-promote/）
「我加了一份新檔到 raw/」等具體指示 ingest，不要自動 ingest
「整理一下這份」問清楚是要 ingest 到 wiki/ 還是只是摘要

12. 詳細參考

  • 完整 LLM Wiki 模式說明：Karpathy LLM Wiki 模式
  • Plugin v1.3.0 SKILL 文件（含 ENTITY_TEMPLATE / ORGANIZATION / PARA_ROUTING / MIGRATION 等 references）：
    • karpathy-wiki-pattern/skills/wiki-ingest/SKILL.md
    • karpathy-wiki-pattern/skills/wiki-lint/SKILL.md
    • karpathy-wiki-pattern/skills/wiki-query/SKILL.md
    • karpathy-wiki-pattern/skills/wiki-compile/SKILL.md
    • karpathy-wiki-pattern/skills/wiki-notion-sync/SKILL.md

13. v1.3.0 已知缺口（v1.3.2 patch 進度）

#缺口狀態
1wiki-ingest skill 沒寫 index.md 同步步驟✅ v1.3.2 修：SKILL.md 加 step 7 (a)–(d) 明文要求；同時保留本 CLAUDE.md §3.1 step 6
2wiki-lint 只偵測不修補✅ v1.3.1 修：wiki-repair skill 出來了
3wiki-lint 沒明列 source: 路徑壞掉檢查部分修：v1.3.1 lint.py 改 rglob、v1.3.2 加 collision 偵測；source 路徑壞掉仍待 wiki-refresh（v1.4）
4沒有 wiki/maps/ 自動更新機制未修：用 wiki-compile 重跑或手工調整
5source 更新後 entity 跟不上未修：v1.4 wiki-refresh 設計筆記已寫，待實作

14. 工具 SOP — 永遠 recursive 掃 entities/（v1.3.2 補）

v1.3 改用 wiki/entities/<domain>/<type>/X.md 階層結構之後，任何只掃 flat root 的工具都會錯漏資料。歷史上踩過：v1.2 lint.py 用 glob 不遞迴 → 漏 95 個 entity。v1.3.2 改 rglob 修好。

寫工具 / 腳本掃 wiki/entities/ 的 SOP：

語言 / 工具✅ 對❌ 錯
Python pathlibPath("wiki/entities").rglob("*.md")Path("wiki/entities").glob("*.md")
Python globglob("wiki/entities/**/*.md", recursive=True)glob("wiki/entities/*.md")
PowerShellGet-ChildItem wiki/entities -Recurse -Filter *.mdGet-ChildItem wiki/entities -Filter *.md（無 -Recurse）
Bash findfind wiki/entities -name '*.md'find wiki/entities -maxdepth 1 -name '*.md'
DataviewFROM "wiki/entities"（預設遞迴，沒事）—
Obsidian wiki-link[[X]]（basename，沒事）—

檢查清單（寫新工具時）：

  1. ☐ 是否會掃 wiki/entities/？若是，必須遞迴
  2. ☐ 是否會掃 wiki/maps/？同上
  3. ☐ 是否會掃 raw/？raw 是平的不影響，但若 v1.4 後 raw 也階層化要注意
  4. ☐ 用什麼 API？rglob / ** / -Recurse / find 任一
  5. ☐ 有沒有 -maxdepth 1 / 沒加 recursive=True 之類的 footgun？

例外：以下情境不該 recursive：

  • 只看 top-level domain 列表 → path.glob("*/") 取一層
  • 只看某 domain 的 type 子資料夾 → path.glob("*/") 在 domain 路徑下取一層
  • 用「漏掃 = 隔離」當沙盒設計 → 明確註明，不該 silent

lint.py 自帶的保險絲（v1.3.2）：

跑 lint 時會輸出 total_pages。如果這個數字明顯小於你直觀記得的 entity 數，一定是 recursion 沒做對。

lint.py 版本優先順序（v1.3.3 補）：

Plugin 版唯讀無法就地 patch。Vault 本地保留修正版：

wiki/tools/lint.py   ← 優先使用（v1.3.5，含 NFC Unicode 正規化）

跑 lint 時：

# ✅ 優先用 vault 版（有 NFC fix）
python3 /path/to/vault/wiki/tools/lint.py /path/to/vault/wiki
 
# ❌ 不要用 plugin 版（沒有 NFC fix，macOS NFD filename 會誤報假孤兒）
# python3 /...plugin.../skills/wiki-lint/lint.py ...

NFC 問題說明：macOS APFS 把含變音符的 filename（如 Sönke Ahrens.md）存成 NFD（o + combining diaeresis U+0308），但 markdown 內文 [[Sönke Ahrens]] 用 NFC（ö U+00F6）。Python 直接比對 NFD ≠ NFC → 假 orphan + 假 missing。wiki/tools/lint.py 加了 unicodedata.normalize('NFC', ...) 修好此問題。

15. Daily Log — 每日異動日誌（v1.3.5）

每次操作後，除了在 wiki/log.md 加一行 table 紀錄外，當天的詳細異動寫到 wiki/daily/YYYY/MM/YYYY-MM-DD.md。

結構

wiki/
├── log.md              ← 保留：每筆一行 table，索引用
├── daily/              ← 每日詳細異動，按年月分層
│   └── 2026/
│       └── 04/
│           ├── 2026-04-28.md
│           ├── 2026-04-29.md
│           └── ...

建檔規則：寫當日 daily 前，先確認 wiki/daily/YYYY/MM/ 資料夾存在，不存在則建立。

log.md（保持簡潔 table）

wiki/log.md 只保留：

  • frontmatter + 標題
  • table header + 每筆一行紀錄
  • 格式範本

舊的「詳細條目」區段（## 詳細 下面的長段）不再往 log.md 追加，改寫到 daily note。

daily/YYYY/MM/YYYY-MM-DD.md 格式

---
title: "Wiki Daily Log — YYYY-MM-DD"
tags: ["wiki-daily", "log"]
date: YYYY-MM-DD
---
 
# 📅 YYYY-MM-DD Wiki 異動日誌
 
## 摘要
 
| 操作 | 影響頁面 | 備註 |
|------|---------|------|
| ... | ... | ... |
 
---
 
## 詳細
 
### [操作名稱]
 
...詳細說明...
 
---
 
← 回到 [[wiki/log|wiki/log]] | [[wiki/index|wiki/]]

觸發時機

  • 每次有 Ingest / Repair / Backfill / 大型 Update 操作後，都要建或更新當天的 daily note
  • 單次小修（加 1 條 backlink、改 frontmatter）可以只寫 log.md table，不必開 daily note

16. Mermaid 渲染規則（v1.3.6 新增）

寫 mermaid 圖時要避開的三個坑。詳細範例見 Mermaid 渲染陷阱 entity。

黃金法則

node label 第一個字元（或前幾個字元）只要看起來像 Markdown 語法符號就會出事。 node label 含特殊字元時一律加引號 ["..."]。

三個必避坑

坑觸發 pattern正解
#1：Ordered list 解析[1. text] 或 [1) text]（連加引號 ["1) text"] 也可能踩）改用圈圈數字 ["① text"]、全形數字、或 ["Step 1: text"]
#2：Parallelogram shape[/text] 開頭被當成平行四邊形語法加引號 ["/text"]
#3：HTML tag 誤判< 開頭可能被當 HTML加引號 ["<x>"]

編號 nodes 的標準寫法（給數字流程用）

✅ 標準：用圈圈數字
flowchart LR
    A["① 第一步"]
    B["② 第二步"]

⚠️ 風險：用 1) 1. 即使加引號也可能被部分 mermaid 版本當 list
flowchart LR
    A["1) 第一步"]   ← Obsidian 實測會壞

❌ 一定壞：不加引號
flowchart LR
    A[1. 第一步]

圈圈數字對照表（Unicode）

1–910–1314–20
① ② ③ ④ ⑤ ⑥ ⑦ ⑧ ⑨⑩ ⑪ ⑫ ⑬⑭ ⑮ ⑯ ⑰ ⑱ ⑲ ⑳

21+ 沒有圈圈數字了。需要更多就用 Step 21: 前綴或 emoji 數字 2️⃣1️⃣（但 emoji 在 mermaid node 渲染不一定漂亮）。

Slash 指令的正確寫法

✅ ["/loop 5m"]               ← 加引號
✅ ("/batch text")             ← 用圓角 shape
❌ [/loop 5m]                  ← 被當 parallelogram

subgraph 標題

✅ subgraph X["立刻可做"]      ← 中文加引號最安全
✅ subgraph X[立刻可做]        ← 純中文也 OK
❌ subgraph X[1. 第一階段]     ← 一樣會踩坑 #1

寫完必做的事

  1. ☐ 在 Obsidian 預覽渲染一次（不要寫完就 commit）
  2. ☐ 看到「Unsupported markdown: list」→ 找 [數字
  3. ☐ 看到「Parse error: Expecting SQE got PE」→ 找 [數字)
  4. ☐ 看到節點變平行四邊形 → 找 [/

詳細踩坑紀錄：Mermaid 渲染陷阱

關係圖譜

反向連結