Schema 變更日誌
Append-only。追蹤
AGENTS.md、CLAUDE.md與00-規範/的演進。每筆變更以### 變更 N:標題為小節,內含 Before / After / 動機 / 修訂的檔案 / 影響。不分月,因 schema 變更頻率低、需要完整歷史一覽。
歷史:變更 1-3 發生於 2026-04-28、本檔建立前,未抽出,仍保留於
log/2026-04.md的「Schema 變更」區段。本檔自變更 4 起為 schema 變更的單一事實來源。
2026-04-28
變更 4:log 從單檔改為 folder
結構變更:
- Before:根目錄
log.md單檔承載所有 ingest / lint / schema / 系統備忘條目 - After:
log/YYYY-MM.md月度檔承載 ingest / lint / 系統備忘log/schema.md單檔承載 schema 變更- 根目錄
log.md廢除
動機:
- 預期 ingest 高頻(每天多條),單檔長期會膨脹到 LLM 每次讀取吃大量 context
- 月度切片讓 query 只需讀近 1-2 個月;pipeline 路徑可預測(
log/YYYY-MM.md) - schema 變更頻率低、需要完整歷史一覽,獨立成單檔比按月切片更利於掃描
- 避免雙真相:根目錄不再保留
log.md,monthly 檔即唯一來源
修訂的檔案:
CLAUDE.md§2、§5.1.8、§5.2.3、§5.3、§8、§9- 新建
log/2026-04.md(從log.md整批複製)、log/schema.md - 刪除根目錄
log.md
Migration 計畫 / 影響:
- 既有
log.md內容整批複製到log/2026-04.md(保留 2026-04-28 當日所有條目原時間軸) - 變更 1-3 留在
log/2026-04.md內未抽出,因 1-3 確實發生於 2026-04-28,原始位置即正確時間軸;schema.md 從變更 4 起為單一事實來源 - vault 內 wiki / 來源頁未引用根目錄
log.md,無 wikilink 斷裂風險(10-來源/文章/2026-04-28-Karpathy-LLM-Wiki-gist.md提到的log.md是 Karpathy gist 內文摘要,屬不可變層的 frozen quote,不受影響)
2026-05-02
變更 5:§5.4 完成後 commit
結構變更:
- Before:CLAUDE.md §5 三個操作(ingest / query / lint)做完後沒有規定要 commit——LLM 維護者完成工作後,等使用者下指令才 commit;實務上常常多個 ingest 累積成一個巨大的 commit,難以審計。
- After:新增 §5.4「完成後 commit」——任何修改 vault 內容的操作完成後,自動 commit;一次操作 = 一個 commit;commit message 格式約定(
ingest:/lint:/schema:/wiki:)。
動機:
- 可審計:每個 ingest 變成獨立 commit,未來回頭看「這條 wiki 條目是哪份來源帶進來的」可直接
git log/git blame定位,不用翻log/YYYY-MM.md。 - 減少使用者負擔:使用者不用每次操作後再下「commit」指令;落地與 5.1-5.3 一氣呵成。
- Pipeline-readiness:未來腳本化跑 ingest 時,每個 ingest 自動 commit 是 batch 化的前提(CLAUDE.md §1「現在的每個決定都應假設未來會被腳本呼叫」)。
- 真實案例觸發:2026-05-02 一日內 ingest 兩份 李宏毅 來源(2026-05-02-Harness-Engineering駕馭工程 + 2026-05-02-AI-Agent-Context-Engineering系統化),兩個 ingest 改動的檔案在 git working tree 中混雜,事後拆分困難——這個事件直接觸發本規則制定。
修訂的檔案:
CLAUDE.md新增 §5.4- 本檔(
log/schema.md)追加變更 5
Migration 計畫 / 影響:
- 歷史不追溯:規則生效前的未 commit 工作(截至 2026-05-02 git working tree 中堆積的兩個 ingest)作為「規則前最後一次手動清理」整批處理——兩個 ingest 在 working tree 中已彼此混雜(多個 wiki 頁兩次 ingest 都改過),事後乾淨拆分代價高且易出錯,整批一個 ingest commit;schema 變更獨立一個 commit。規則生效後(即 commit b 之後)的 ingest 嚴格一一對應 commit。
- 無 wiki 結構影響:本規則不涉及任何頁的 frontmatter / heading / 路徑變更,wiki 層完全不受影響。
.obsidian/噪音檔處理:本規則明示.obsidian/app.json/.obsidian/graph.json等 Obsidian 自動寫入的 UI 狀態檔不納入 ingest commit——這些檔目前在 git tracking 內但屬於環境噪音;長期可考慮加入.gitignore,但本次規則僅規範 commit 行為,不動 tracking 設定(gitignore 由使用者主導決定)。
變更 6:§5.3 加入執行策略 + 死連豁免區
結構變更:
- Before:§5.3 只列檢查項清單(孤兒 / 死連 / 矛盾 / 過時 / frontmatter / 重複),未指定執行策略;上一輪 lint(log/2026-05.md,2026-05-01)發現 cluster-based subagent 並行掃描漏抓 項目盒子 死連,已自承「下次 lint 應追加死連專項掃描」的觀察,但未進 schema。
- After:§5.3 新增「執行策略」三步:(1) 死連專項先掃(消除跨 cluster 隱性 cluster 盲點)→ (2) cluster-based 並行掃描 → (3) 主 agent 收斂;同時新增「死連豁免區」三類(規範示例占位 / log+index narrative placeholder / 來源中觀察清單級的未 ingest 對象),明確哪些 grep 命中不算 lint 違規。
動機:
- 承接觀察結論:log/2026-05.md 已自承 cluster-based 漏網的根因,本次正式進 schema,避免下次 lint 重蹈覆轍。
- 降低 lint 噪音:vault 全域死連 grep 共 410 處,但其中 240 處在 log/index narrative(描述未來建頁)+ 11 處在規範示例(教學用占位)= 251 處(61%)是工作流副產品而非真死連。豁免區明示後,lint 工具能聚焦在真正的 108 wiki + 51 來源死連。
- Pipeline-readiness:未來腳本化跑 lint 時,豁免區就是 grep 過濾規則的可執行 docstring(CLAUDE.md §1:「現在的每個決定都應假設未來會被腳本呼叫」)。
修訂的檔案:
CLAUDE.md§5.3(含 last-updated)- 本檔追加變更 6
Migration 計畫 / 影響:
- 無 wiki 結構影響:本規則僅補強 lint 程序描述,不動任何頁的 frontmatter / heading / 路徑。
- 歷史 lint 結果不追溯重評:log/2026-04.md 的「全 vault 死連專項掃描」已是這個策略的 ad-hoc 實作;log/2026-05.md 的「項目盒子死連修正」已是其產物。歷史 lint 仍按當時規則理解。
- 觸發本次變更的 vault 狀態:2026-05-02 「分析 wiki 可優化部分」操作中,量化掃描出 410 處死連——若沒有豁免區,下次 lint 會被噪音淹沒。本變更是這個操作的副產品。
變更 7:§5.1.8 ingest narrative 重定位 + 來源模板新增 Ingest 筆記段
結構變更:
- Before:§5.1.8「追加 log/YYYY-MM.md」未限制條目體積;實踐中 ingest narrative 全寫進 log(每筆 200-800 字 / 2026-05.md 月才過 2 天就破 158KB / 1898 行 / 已超出 LLM 一次 read 上限)。同時 index.md 開頭也累積層層 nested 「最近修補」blockquote(已在同日 commit 17d3f57 砍除)。同一份 narrative 同時存在於 log + index + 來源頁三處,違反 §8「單一事實來源」精神。
- After:§5.1.8 拆分為「決策摘要」(≤ 1KB,寫進 log 月度檔:時間 / 來源路徑 / 新建頁 / 大幅更新頁 / 元命題 / 觀察清單)vs「narrative 主體」(詳細推理 / 跨頁影響鏈 / ASR-OCR 修訂註解 / 觀察清單長文,寫進來源頁的
## Ingest 筆記段)。五個來源模板(文章 / PDF / bundle / 圖片 / 手寫)皆新增該段,位於「## 提取概念」之後。
動機:
- 可讀性:log 月度檔回歸時間軸索引(pipeline 一次 grep 就拿到時間線),詳細推理留在來源頁(讀一份來源就看到完整 ingest 決策上下文,不用再跨檔追線索)。
- 不違反 §8 append-only:歷史月度檔不追溯瘦身;只規範未來 ingest 的寫法。
- 單一事實來源:未來 ingest narrative 只在來源頁的
## Ingest 筆記段一處;index.md 已於同日 commit 17d3f57 砍除「最近修補 narrative」+「最近 ingest 來源 段每筆 200-800 字」改為一行 pointer,配合本變更形成「log = 時間軸索引 / index = 結構導覽 / 來源頁 = ingest narrative 單一事實」三檔分工。 - Pipeline-readiness:log 條目 ≤ 1KB 之後,腳本可期望「一次 read 拿到整月 ingest 時間線」;來源頁 narrative 有穩定 heading(
## Ingest 筆記),可被切片。
修訂的檔案:
CLAUDE.md§5.1.8(含 last-updated)00-規範/模板/來源-文章.md00-規範/模板/來源-PDF.md00-規範/模板/來源-bundle.md00-規範/模板/來源-圖片.md00-規範/模板/來源-手寫筆記.md- 本檔追加變更 7
Migration 計畫 / 影響:
- 既有 77 個來源頁不主動加
## Ingest 筆記段:lazy migration——下次該頁因 ingest / lint 被觸碰時補;保留 git history 乾淨、不污染歷史 commit。 - 既有
log/2026-04.md/log/2026-05.mdnarrative 不動:合 §8 append-only;視為「規則前歷史 narrative」,下次寫起按新規則。歷史 narrative 雖長但仍是有效資料,只是 LLM 讀取時要分頁——可接受。 - 現有 ingest 範式不破壞:本變更只規範條目體積與位置,不改 ingest 步驟序列(仍是辨識類型 → 建來源頁 → 抽取候選 → 掃描 wiki → 更新 / 新建 → 互相連結 → 更新 index → 追加 log)。
- 本日 commit 17d3f57(index.md 結構重整)為配套變更:兩個 commit 邏輯耦合——index 砍掉的 narrative 與本變更要寫進來源頁 Ingest 筆記段的內容,是同一份 narrative 在 vault 中的兩個出口;commit 17d3f57 砍出口、本 commit 開新出口。
2026-05-03
變更 8:§5.5 觀察清單規範 + §3/§7 meta-concept 類型 + §8 衍生視圖原則
結構變更:
- Before:
- 觀察清單散落在
log/YYYY-MM.md各 ingest 區段內(log/2026-05.md 累積到 2828 行 / 30+ 個觀察清單 section / 96+ 條開放條目),無集中查詢點。 - 跨期重複條目沒有 dedup 機制(例:Paul-Graham 在曼報 EP63 + EP163 各列一次、SaaS 案例 cluster 在 BVP + OpenView 雙 ingest 各列 N 次)。
- 已超門檻的 MOC 候選(視覺設計 / 品牌設計 / 組織管理 / 個人品牌)沒有自動浮現機制——埋在 log 中無人盯。
- vault 既有頁類型只有
concept/entity/moc/source-*,無法承載「散在多頁但尚未統合的元層命題」(如 Why-first-家族 / 迭代精神 / 降低防禦反應)——pilot 收割時這類候選 9 條,明顯需要獨立分類。
- 觀察清單散落在
- After:
- 新建
觀察清單.md(vault 根目錄,wiki 元層;§5.5 規範)作為當前狀態快照,與 log 月度檔(時間軸歷史)互補。 - §5.5 定義六類分類(死連 stub / MOC 候選 / 待 ingest 外部資源 / 拆頁候選 / entity 升格 / Umbrella 元命題)+ 條目欄位(候選 / 加入日 / 來源 ingest / 觸發條件 / 當前進度)+ cluster 級條目格式 + ingest 同步規則 + 邊界釐清(與「未來累積方向」/ §5.3 死連豁免區的關係)。
- §7 frontmatter
type列舉值新增meta-concept;§320-Wiki/概念/註明可承載 meta-concept 子類型。 - §8 新增「衍生視圖明示性」原則:當前狀態快照型檔(如
觀察清單.md)必須可從 append-only 來源重生,不視為獨立事實來源;對應未來 lint 階段自動產出機制(roadmap Phase 3)。
- 新建
動機:
- 使用者體驗:vault 才 60 天就累積到「散落式追蹤已成本過高」的拐點——log/2026-05.md 30+ 觀察清單 section / 96+ 開放條目;4 個已超門檻 MOC 沒人盯(pilot 中浮現)。本變更前無法回答「目前還在追蹤什麼?」這個基本查詢。
- 不違反 §8 單一事實來源:透過明示「衍生視圖」性質區隔——log 月度檔仍是事件歷史的單一事實來源(不可改),
觀察清單.md是當前狀態的衍生視圖(可重生)。兩者性質不同、互補存在;衍生視圖原則進 §8 確保未來腳本化時不會誤把它當作獨立事實。 - 預埋 cross-period dedup 機制:跨期重複條目(同候選在多次 ingest 中出現)的合併規則進 §5.5,避免 N 次 ingest = N 條死連條目的清單暴增。
- Pipeline-readiness:六類分類 + 條目欄位定義為機器可解析的表格化格式(CLAUDE.md §1:「現在的每個決定都應假設未來會被腳本呼叫」)。Phase 3 lint 階段直接以此 schema 自動產出。
- 預埋 meta-concept 類型:pilot 9 條第六類候選的密度暴露 vault 既有頁類型不足;登錄類型佔位後,Phase 2 試做第一個 meta-concept(候選 Why-first-家族)時不需再動 schema。
- 觸發本次變更的具體事件:2026-05-03 與使用者討論「觀察清單散落 log 中的優化方向」→ 派 subagent 跑 pilot 收割(96+ 條開放、13+ 已消化、第六類浮現)→ 確認集中化值得做且 schema 改進信號明確 → 本變更落地。
修訂的檔案:
CLAUDE.md頂部 last-updated / §3 (20-Wiki/概念/描述) / §5.5 新增 / §7 type 列舉 / §8 第 6 條- 本檔(
log/schema.md)追加變更 8
Migration 計畫 / 影響:
- 本變更不獨立產出
觀察清單.md——schema 條文與檔案產出拆兩個 commit:本 commit 只動 schema;下個 commit「wiki: 新建 觀察清單.md」基於 pilot 結果產出 v1。 - 既有 log 月度檔的觀察清單條目不追溯遷移:合 §8 append-only。觀察清單.md v1 一次性從 pilot 結果建立、之後由 ingest 過程同步;歷史 log 內的觀察清單條目仍是時間軸事實,新檔是當前狀態快照,兩者並存無衝突。
- 既有 wiki 頁無結構影響:本變更不動既有 concept / entity / moc / source 頁的 frontmatter / heading / 路徑。
meta-concept類型雖然登錄,但實作模板與第一個 meta-concept 頁延後到 Phase 2(觸發時機:首個 meta-concept 試做)。 - 與 §5.3 lint 死連豁免區的耦合:第 3 類「觀察清單級提及」的判定來源原本只看 log;本變更後也涵蓋
觀察清單.md內條目。lint 工具未來實作時應以觀察清單.md為主要豁免來源(更準)+ log 為輔。 - Roadmap 對接:本變更為 Phase 1(schema 骨架 + 手動同步);Phase 2 補 cross-period dedup 細則 + 「未來累積方向」vs 觀察清單邊界實戰修正 + 第一個 meta-concept 試做;Phase 3 觀察清單.md 改為 lint 衍生產出。Phase 規劃見 2026-05-03 對話記錄(未進 schema,因規劃本身會隨實作微調)。
2026-07-11
變更 9:§5.4 Git 操作邊界
結構變更:
- Before:
AGENTS.md/CLAUDE.md§5.4 要求任何修改 vault 內容的操作完成後自動建立 git commit;secbrain-vaultskill 也把 commit behavior 納入 vault write 必遵規則。 - After:§5.4 改為「Git 操作邊界」:SecBrain vault 維護規則不要求 LLM agent 自動執行 git 相關動作;除非使用者明確要求,agent 不執行
git status、git diff、git add、git commit、git push,也不把 commit 當作完成條件。
動機:
- 使用者明確確認:SecBrain 相關 agent 不應因角色腳本而主動執行 git 動作。
- 2026-07-11 ingest Reading Outpost《焦慮的意義》時,agent 依舊規則嘗試檢查 git commit 條件,因 vault 內
.gitmetadata 不可用而把 issue 標為 blocked。根因不是內容 ingest 失敗,而是角色規則把 commit 誤設為完成條件。 - 對 SecBrain 這類 iCloud / rclone 掛載 vault,版本控制狀態不一定穩定暴露給 runtime;git 行為應改由使用者明確要求時才處理。
修訂的檔案:
AGENTS.md頂部 last-updated / §5.4CLAUDE.md頂部 last-updated / §5.4log/schema.mdfrontmatter / 變更 9secbrain-vaultskill:移除 commit behavior 要求,新增不主動跑 git 的邊界/root/holo_os/memories/projects/secbrain.md:更新專案記憶,標記 SecBrain 維護預設不主動執行 git
Migration 計畫 / 影響:
- 未來 SecBrain ingest / lint / schema / 直接建頁完成後,只需完成內容驗證與結果回報;不再自動跑 git,也不因沒有 commit 而標記 blocked。
- 若使用者明確要求 commit / diff / status,agent 可依該次指令處理;若 repo metadata 不可用,只回報原因,不自行初始化或修復 repo。
- 既有 schema 變更 5 保留為歷史紀錄,不追溯改寫;本變更是對舊規則的明確覆蓋。
2026-09-16
變更 10:發布可見性、Wiki 成熟度與來源 ingest 狀態分流
結構變更:
- Before:來源與 Wiki 共用
狀態/草稿、狀態/精煉中、狀態/穩定;模板預設把所有新頁標成草稿。另有歷史來源使用未註冊的狀態/已處理表示 ingest 完成,造成「內容成熟度」「ingest 流程完成度」「網站是否輸出」三種語意混用。 - After:
- Quartz 發布可見性只由 frontmatter
draft: true控制;欄位缺省或false代表可輸出。成熟度標籤不控制發布。 - Wiki 保留且只能擇一使用
狀態/草稿、狀態/精煉中、狀態/穩定,判斷依據改為結構、證據、連結、邊界與重大缺口。 - 來源頁改用
ingest-status: partial|complete|blocked表示流程狀態;新建或實質更新的來源頁必須填寫。來源類型標籤保留,成熟度標籤不再作為來源頁必填。
- Quartz 發布可見性只由 frontmatter
動機:
- 2026-09-16 盤點顯示:680 個 Wiki 全部仍是
狀態/草稿,精煉中/穩定都是 0;297 個來源中有 228 個草稿、22 個精煉中,另有 39 個狀態/已處理。現有標籤沒有形成可持續的升級流程。 - Quartz 的
@quartz-community/remove-draft只讀取 frontmatterdraft: true,不辨識狀態/草稿tag;既有命名容易讓維護者誤以為草稿標籤會阻止發布。 - 來源頁的 ingest 是否完成是工作流狀態,Wiki 的內容成熟度是知識品質判斷,兩者需要可被 pipeline 分別解析。
Migration 計畫 / 影響:
- Phase 1 pilot(本次):更新五種來源模板;將 2026-09-15 官方原典批次的 6 份來源標為
ingest-status: complete並移除成熟度 tag;將同批 3 個新 Wiki 由草稿升為精煉中。 - Lazy migration:既有來源頁不做無判斷的全庫字串替換;後續被 ingest / lint 實質觸碰時補
ingest-status、移除來源頁成熟度 tag。過渡期允許舊頁暫時缺少欄位。 - 歷史未註冊狀態:39 個
狀態/已處理由後續 lint 逐頁判讀成complete/partial/blocked,在完成遷移前不把已處理註冊為新 canonical tag。 - Wiki 遷移:現有 680 個 Wiki 依成熟度 rubric 分 cluster 審查;不以建立日期、篇幅或 backlink 數單一條件自動升級。
穩定暫不批次產生。 - 相容性:
ingest-status在過渡期對既有來源為 optional、對新建或實質更新來源為 required;不會讓目前 Quartz build 過濾舊頁。
修訂的檔案:
AGENTS.md/CLAUDE.md:更新契約與 frontmatter 狀態規則。00-規範/標籤分類.md:重新定義 Wiki 成熟度、來源 ingest 狀態與發布可見性。- 五個
00-規範/模板/來源-*.md:新增ingest-status: partial、移除來源頁的成熟度 tag。 - 6 份 2026-09-15 官方來源 + Paul-Graham / 預設存活 / 不可規模化的事:Phase 1 pilot。
- 本檔追加變更 10;
log/2026-09.md追加 pilot 執行摘要。
變更 11:完成全庫狀態遷移與一致性 gate
Migration 計畫(先記錄、再執行):
- 逐頁解析 297 份
source-*frontmatter 與內容,交叉檢查必要 metadata、來源素材、提取要點、提取概念、Wiki 回鏈與 ingest narrative;不直接把舊狀態字串一對一映射成新欄位。 - 將具備可追溯素材與提取結果的來源標為
ingest-status: complete;仍是空白佔位或缺少必要素材/提取的來源標為partial;只有因原文、附件、逐字稿或權限缺失而無法可靠處理者才標為blocked。 - 逐頁檢查 680 份 Wiki 的頁型結構、來源連結、跨頁連結、inbound link、已知缺口與適用邊界。符合「可供查詢、仍可擴充」者標為
狀態/精煉中;有關鍵缺口者留在狀態/草稿。 狀態/穩定不由 lint 自動授予。即使結構、來源數與連結密度達標,仍需能判斷 canonical 原典/多來源校準、主要異議與「近期不預期大改」;本次全庫機械一致性遷移不做這項過度推論。- 完成遷移後收緊契約:所有來源頁都必須有且只能有一個合法
ingest-status,不得再帶 Wiki 成熟度或歷史狀態/*tag;所有 Wiki 都必須且只能有一個成熟度 tag。新增 read-only consistency gate 防止回歸。
盤點與預定結果:
- 來源:遷移前 6 份已有
complete、291 份缺少欄位,且殘留草稿222、精煉中22、已處理39、其他未註冊歷史狀態 8。內容判讀後預定為complete295、partial2、blocked0。 - Wiki:680 份全都有至少一個來源連結與 inbound link,且沒有空白
[[ ]]或空白清單項目。預定為精煉中680、草稿0、穩定0;其中內容仍有明示待補方向者,其待補內容屬可擴充範圍,不構成阻止查詢的關鍵缺口。
影響與驗證計畫:
- 這次會更新 297 份來源頁與 677 份尚未遷移的 Wiki frontmatter;內容正文、wiki-link、檔名與
draft發布欄位不變。 - 所有被修改頁面的
updated統一更新為2026-09-16。 - 驗證包含:全庫狀態 gate、歷史
狀態/*來源 tag 歸零、Wiki 成熟度唯一性、Prettier、Quartz 全量 build,以及代表頁輸出檢查。
執行結果:
- 來源狀態完成遷移:295 份
complete、2 份partial、0 份blocked。兩份 partial 是Illustrator-技巧集與色彩搭配的歷史空白手寫佔位;已移除空白[[ ]],並在 ingest note 明載缺少實際原稿。來源頁的所有歷史狀態/*tag 已清零。 - 補齊 75 份早期來源缺少的
## Ingest 筆記;其中 6 份舊 schema 文章另補標準## 提取概念,7 份舊 heading 正規化為現行名稱。歷史不存在的 ingest 推理不回填,只記錄本次遷移事實。 - Wiki 680 份全部完成內容成熟度判讀並標為
狀態/精煉中;草稿 0、穩定 0。所有頁面都有來源連結與 inbound link;明示的待補方向屬可擴充範圍,未發現阻止可靠查詢的關鍵結構缺口。 - 新增
scripts/check-content-status.mjs:檢查來源狀態唯一性/合法值、來源 tag 邊界、complete 來源的提取概念與 ingest note,以及 Wiki 成熟度唯一性。
修訂的檔案:
AGENTS.md/CLAUDE.md:移除 lazy migration 過渡條款,將狀態一致性納入 lint 契約。00-規範/標籤分類.md:來源ingest-status改為全庫必填,來源狀態/*tag 正式列為違規。scripts/check-content-status.mjs:新增 read-only consistency gate。10-來源/297 份與20-Wiki/680 份:完成狀態判讀;實際 frontmatter 變更為來源 291 份、Wiki 677 份,pilot 已遷移頁維持原值。log/2026-09.md:追加本次全庫遷移摘要。