Leo
2a8c259d08
🔴 修的病：這個框架 repo 自己的 5 份 SDD 全部被 .gitignore 擋在版控之外， 只活在一台硬碟上——clone 不到、雲端 CC 讀不到、沒備份。SDD 是進度真相源， 「框架 repo 沒吃自己的狗糧」。 依據 D22（已翻案）：Gitea private 除機敏值外全 push，雲端工人靠 clone，docs 缺＝斷糧； 只有 GitHub mirror 才嚴篩，而 docs 整包已在 github-publish-exclude.txt。 .gitignore 改法：整條擋 → 只擋子項（/*）+ 逐個放行真 SDD。 與 template/ 底下逐位元組相同的自裝副本（TEMPLATE-sdd/、SDD-LIFECYCLE.md）續擋。 新增 docs/3-specs/jdd-dual-profile/（status: draft，等 leo confirm 才升 active）： JDD（PM 軌 root/journeys/角色權限/站號 sprint）與雙 profile 合成一卷， 33 條 task／6 phase，每條掛服務哪條 Gherkin（G1–G7）。 新增 hook 6 支、改既有 hook 1 支。**0 行實作**。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
141 lines
10 KiB
Markdown
141 lines
10 KiB
Markdown
# 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 通道」
|