system-dev-template/docs/3-specs/wiki-architecture/design.md

wiki-architecture — Design

狀態：已結案（2026-06-26，KB 端 183 卡實跑壓測全綠，1,029 條三元組、端點 0 缺陷；驗收明細見 tasks.md） 建立：2026-06-26 | 最後更新：2026-06-26 負責人：leo（uncle6me-web）

---

一句話說明

在「用戶所有檔案一律改寫成 wiki cards」的新架構下，用 push（CC 行動前必主動看見）vs pull（CC 按需檢索） 為唯一判準，重新決定 wiki/ 下每個檔的存廢——只有「不看就出事的盲區」獨立 push，其餘知識（含決策、原則）全是 cards、由 INDEX 多角度索引。

---

背景與問題

舊架構（1.4.0 前）部分內容「指向原文」，wiki/ 下因此長出一組固定特殊檔（status / mistakes / decisions-summary / TAXONOMY / INDEX），當時把它們當「天經地義的結構」。

1.4.1 起改成所有原文一律改寫成 cards，但沒有人回頭重新推導這組特殊檔在新架構下還成不成立。結果：

• 「原則 / 願景」（如「不污染用戶根目錄」「目標用戶 low-code」）無處可記——decisions-summary 裝「單筆決策」、cards 裝「概念知識」，原則落在縫裡。
• 每次想記原則，就糾結「要不要再加一個特殊檔」——這是打補丁，不是設計。

根因：用「是不是特殊知識」當分類判準是錯的維度。正確判準是 retrieval 行為：CC 做事時，這東西會不會被動看見？

---

範圍

包含（In Scope）

• 確立 push/pull 判準，重新決定 wiki/ 每個檔的存廢。
• 把 decisions-summary 降級為 cards + INDEX 視圖。
• 新增 principles 進 push 清單（hook 主動注入）。
• INDEX 升級為「多角度視圖」的家：新增角度 = CC 改 INDEX，不必問用戶開檔。
• 同步 wiki-init.md / SKILL.md / INDEX 範本 / session-start hook。

不包含（Out of Scope）

• 不改 cards 本身的三層+標籤架構（issue #8 的設計不動）。
• 不改 TAXONOMY 的字典機制。
• 不動 install-layout 的檔案落點（那是另一份 SDD）。
• 不強制遷移既有用戶的 decisions-summary 內容（向後相容，見下）。

---

設計

核心判準：push vs pull

push：CC 行動前必須主動出現在 context（session 開始就注入）。 pull：CC 想到要查、或載入相關卡時才看見。

判準的邏輯支點——mistakes 必須 push：mistakes 防的是「CC 不自覺的盲區」。一個你不知道存在的錯，你不會主動去檢索。靠 CC 自覺去查「自己沒自覺的盲區」是自相矛盾的 → 所以 pull 模式對 mistakes 邏輯上失效，必須 push。

同理推 principles：「不污染用戶根目錄」這種準繩，不主動注入，CC 設計時很可能沒想到要服從就做了（本專案實證：CC 這幾輪反覆忘記 low-code 用戶與不污染原則，正因它們沒被 push）。原則也是不自覺的盲區 → 必須 push。

每個檔的存廢（依判準推導）

檔案	push / pull	邏輯理由	命運
status.md	push	不是知識，是專案「此刻時態狀態」；不看會重做已完成的事	留（hook 注入）
mistakes.md	push	防不自覺盲區；pull 邏輯失效（見上）	留（hook 注入）
principles.md	push	原則是會被遺忘的盲區；不注入 CC 設計時不服從（實證）	新增（hook 注入）
decisions-summary.md	pull	「遇設計判斷才查」——CC 面對決策時自然會查既有決策，pull 夠用；決策本身是知識內容＝card	降級：內容歸 cards，INDEX 提供「決策角度」視圖
TAXONOMY.md	（元資料）	是 cards 的分類字典＝cards 的前提，邏輯上不可能是 card	留（元資料，非 push 非 pull）
INDEX.md	（入口）	索引本身；升級為多角度視圖的家	留並強化
cards/	pull	一切知識內容（原文摘要、AI 筆記、lesson、決策、原則內容…）都在這	不變

收斂結論：只有「不是知識（status、TAXONOMY）」和「索引本身（INDEX）」獨立；所有知識內容都是 cards。push 清單＝會變的狀態 + 會重犯的錯 + 會忘記的原則（status / mistakes / principles）。

push 的實作機制（propose，非待定）

從 AI 的 context 行為推導，三類 push 的注入形態不同——判準是「這東西需要全文才能避免出事，還是一行就夠觸發 CC 去查」：

push 項	注入形態	理由（從 AI 行為推）
status	全文	短、且 CC 必須知道精確的「下一步是什麼」才不重做；摘要會漏掉關鍵的當前 task 編號
principles	全文（一行一條）	原則本身就該寫成「一行一條」的精煉準繩（不污染根目錄、用戶是 low-code…）。全文注入成本低、且原則是「行動前必服從」的硬約束，不能只給標題讓 CC 自己決定要不要展開——它不會
mistakes	標題清單 + 一行症狀，全文按需 pull	mistakes 可能累積到數十條、含長 context；全文會撐爆。但「標題 + 症狀」一行足以讓 CC 認出「我正要做的事撞到某條」→ 再展開讀全文。這裡 push 的是「觸發認出」，不是「完整內容」

關鍵：principles 全文 push、mistakes 摘要 push，差異來自——原則是「短而硬的約束」（全文成本低、漏一條就違反），mistakes 是「長而多的教訓」（全文太貴，但摘要足以觸發檢索）。這個區分本身就是「為 AI 設計」的判斷。

context 預算保護：principles 應設「條數上限」（如 ≤15 條，超過代表該合併或下放成 card）；mistakes 摘要每條限一行。

INDEX 作為「多角度視圖」的家

• INDEX 不再只是「標籤視圖」，而是所有檢索角度的入口：標籤角度、決策角度、（未來）任何角度。
• 新增一個角度 = CC 在 INDEX.md 加一節，不必新增實體特殊檔、不必問用戶。這直接解決「AI 想累積新類別卻要問用戶開檔」的問題。
• principles/mistakes 雖獨立 push，但在 INDEX 也該有指標（讓 pull 路徑也找得到）。

原則的歸屬（回答原始提問）

「不污染用戶根目錄」「目標用戶 low-code」等：

• 內容寫成 principles（push 檔）+ 必要時 card。
• CC 思考「怎麼設計」時，因 principles 被 push，行動前就看見，不必主動查。
• 累積新原則 = CC 寫進 principles + INDEX 補指標，永不問用戶開檔。

---

技術限制

• push 注入量受 context 預算限制：不可無腦全文注入 mistakes+principles+status（會撐爆每 session context）。需「摘要 push + 全文按需 pull」。
• 向後相容：既有用戶的 decisions-summary.md 已有內容 → 不可刪。降級指「不再是必備特殊檔」，既有的保留為一張「決策彙總卡」或 INDEX 視圖，內容不丟。
• bash 3.2 相容（hook 改動）。
• 不破壞 issue #8 的 cards 三層+標籤架構。

---

採集規範升級：內文實體關係 + ## 實體 區塊（issue #11，183 卡實證）

現行三元組/gloss 做窄了。從 Logseq vault 183 卡落地暴露：三元組只示範「卡對卡」（把既有 [[雙鏈]] 加動詞，資訊量沒增加）；gloss 只描述卡標題這一個 node，內文實體（graph node）無處放描述。

決策	選擇	理由
三元組抓什麼	內文實體間關係（卡對卡只是其中一類）	知識圖譜價值在內文概念關係（原子筆記 >> 對立於 >> 傳統筆記），不是重複雙鏈
內文實體描述放哪	卡片新增 ## 實體 區塊：正規名（同義詞）— 一句描述，集中放、不縮排、不重複	內文實體也是 graph node，需描述句供下游 embedding normalize（黃仁勳 vs Jensen Huang）。生產者是 AI 不會邊寫邊漏，不需縮排防漏；集中最利下游一實體一 embedding
## 關聯 結構	拆兩層：內文知識關係（端點裸文字，對應 ## 實體 詞條）+ 卡片關係（卡對卡 [[]]）	內文三元組端點用裸文字避免 Logseq 紅色斷鏈；靠字面一致對應實體表
端點對齊	升級成「強制自檢動作」：寫完逐條把 A/B 拿去 ## 實體 比對，沒完全相同的正規名 → 改詞或補實體表	comment 實證：光寫規則 Haiku 會略過（端點對不齊 14 條）；寫成自檢動作後 14→0。這是 Haiku 量產的盲點，跑 1-2 張看不出、跑 12 張才暴露
謂詞	明寫「用動詞、禁名詞」	否則 Haiku 寫出 >> 存儲格式 >>、>> 操作體驗 >> 讀不通的名詞謂詞
實體要描述、謂詞不要	實體補 gloss 描述句，謂詞裸詞即可	實體同義詞字面差遠需描述拉近；謂詞同義詞（參考/參照）字面本就近，裸詞 embed 自動聚類

範圍界線：本升級只談採集端（卡片該寫什麼）。「哪些 token 進向量庫、怎麼去重」屬下游 ingest（另立 kbdb-ingest-plugin#1），不混進 skill。 兩路徑同步：SKILL.md（Cowork）+ wiki-init.md（CC）一致。

---

驗收標準

• push/pull 判準寫進 wiki-init.md 與 SKILL.md，成為 CC/Cowork 共同規則。
• principles 進 push：session-start hook 注入 status + mistakes重點 + principles重點，且總注入量有節制（摘要而非全文）。
• INDEX 範本含「多角度視圖」說明 + 明示「新增角度改 INDEX 不開新檔」。
• decisions-summary 在文件中重新定位為「pull / INDEX 視圖」，既有內容相容保留。
• 一個原則（如「不污染用戶根目錄」）實際寫進 principles，驗證 CC 開 session 會被動看見。
• hook bash -n 過。

---

相關文件

• SDD: install-layout（檔案落點，姊妹 SDD）
• memory: user-profile-lowcode、internal-docs-not-pushed
• 觸發：本專案 CC 反覆遺忘 low-code 用戶與不污染原則 → 暴露「原則無 push 通道」