chore: template 1.9.x 知識庫遷移 → system-dev/

把 system-dev-template 1.9.x 的知識庫基建搬進 git（從功能 PR 拆出，獨立成筆）： - system-dev/wiki/：LLM 記憶系統（principles 鐵律 + 5 張 ingest 卡 + INDEX/TAXONOMY + status/mistakes） - system-dev/docs/：SDD 新家（3-specs/ + 2-architecture/ + README/SKILL）；ingest-pipeline SDD 從 docs/3-specs/ 搬來 - system-dev/scripts/：install/update - .claude/：wiki/SDD harness（commands + hooks：session-recall / sdd-guard / wiki-secret-scan） SDD 位置統一：docs/3-specs/ingest-pipeline → system-dev/docs/3-specs/ingest-pipeline （對齊 SDD guard hook 預期路徑 + template 1.9.x 規約）。純基建遷移，不含任何功能程式碼（src/tests/contracts 在功能 PR #3）。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-26 20:45:18 +08:00
parent dffefdcdc2
commit 06e901f590
36 changed files with 2635 additions and 45 deletions
@@ -0,0 +1,17 @@
+# ingest 餵食器
+
+> 桶子索引（容器：只連不重寫）。kbdb-ingest-plugin 的核心知識卡。
+> 跨專案藍圖：InkStoneCo `docs/3-specs/mira-dissolve/`。SDD：`docs/3-specs/ingest-pipeline/`。
+
+## 架構與定位
+- [[掛載架構]] — base→graph→ingest 三層堆疊、API 邊界、無環
+- [[採取優先於萃取]] — 路徑 A（採取本地三元組）vs 路徑 B（裸原文 extract）
+
+## 契約
+- [[envelope-契約]] — ingest→graph 唯一耦合面：送什麼、禁送什麼、向量化打標分工
+
+## 萃取
+- [[extract-模型策略]] — 用戶選意圖、品質門檻白名單、Haiku/Claude 分層、升級閘
+
+## 主職
+- [[跨repo織網]] — 匯總多 repo 三元組，織單一 repo 看不到的橋與異見
@@ -0,0 +1,43 @@
+---
+tags: [契約邊界, 契約規格, 架構設計]
+gloss: ingest→graph 的唯一耦合面——一個來源檔一次萃取產出的候選 envelope，規定 ingest 能送什麼、禁送什麼。
+---
+# envelope 契約
+
+← [[ingest/00-INDEX]]
+
+**來源**：`contracts/ingest-candidate.json`（凍結形式契約，逐字依原文）、`docs/3-specs/ingest-pipeline/design.md`
+**最後更新**：2026-06-26
+
+> 這是**凍結的形式契約**。欄位的精確 schema 以 `contracts/ingest-candidate.json` 為唯一真相，**逐字依原文**；本卡只距離化「設計意圖與職責切割」，不取代 schema。
+
+## 摘要
+
+`IngestCandidateEnvelope` 是 ingest 與 graph 之間唯一的耦合面：一個 envelope ＝一個 canonical MD 一次萃取的候選產物。
+
+## 重點
+
+- **頂層三必填**：`source`（來自哪個檔 + 快照鍵）、`extractor`（哪個模型/tier 萃的）、`triplets`（邊，至少一條）。另有選填 `nodes[]`（節點層附帶資訊）。`additionalProperties: false` 全程鎖死。
+- **source = 指回原文的指標 + append-only 快照鍵**：`uri`（`github:<owner>/<repo>@<path>`）+ `content_hash`。同一 uri 後續 envelope **取代**前一批（latest-wins），不疊加；同 hash → graph no-op 跳過。
+- **取代語意歸 graph，ingest 一無所知**：同 uri 出新 hash 時，graph 把舊 active 實例 PATCH 成 deprecated、append 新批 active（可查/rollback/清）。ingest 只管送新批。
+- **向量化分工（leo 2026-06-26 升格成契約）**：ingest 在 `nodes[].embed` / `triplets[].predicate_embed` **打標**「要不要向量化、embed 什麼（名+gloss / 謂詞裸詞）」；base/KBDB embed 模組**讀標執行**實際 embedding。**ingest 自己不算向量**（呼應 [[掛載架構]]「准運算不准碰儲存」、principles「不算向量 normalize」）。
+- **ingest 能送**：原始 s/p/o + `source.*` + `extractor.*` + `nodes[].gloss/aliases/entity_type/embed` + `confidence` + 謂詞向量打標。
+- **ingest 禁送（graph 領域，絕不可送）**：`id`（record id）/ `clusters` / `bridge_score` / `created_at` / `updated_at` / triplet 上的 `subject_entity_type|object_entity_type`（類型只走 `nodes[]`）。結構符號（`>>`/`←`）與給人讀的散文（`## 摘要`）也不進 envelope。
+- 這是**【輸入候選】不是【已存三元組】**（後者見 graph 的 triplet.json）。
+
+## 實體
+
+- **IngestCandidateEnvelope**（envelope／凍結契約）— ingest→graph 唯一耦合面，一個來源檔一次萃取的候選產物。
+- **向量化打標**（embed/predicate_embed 標記）— ingest 標哪些 node/謂詞要 embed、embed 什麼，自己不執行 embedding。
+- **讀標執行**（base embed 模組）— base/KBDB 讀 ingest 的標去做實際 embedding 的分工角色。
+- **content_hash**（快照鍵）— 來源檔內容 hash，graph 據此判 no-op 或寫新快照。
+- **禁送欄位**（graph 領域）— id/clusters/bridge_score/時間戳/邊上 type，由 graph 算、ingest 絕不送。
+
+## 關聯
+### 內文知識關係（端點＝上方 `## 實體` 正規名）
+- 向量化打標 >> 配對分工 >> 讀標執行
+- IngestCandidateEnvelope >> 禁止攜帶 >> 禁送欄位
+- content_hash >> 充當 >> IngestCandidateEnvelope
+### 卡片關係（卡對卡）
+- [[envelope-契約]] >> 約束 >> [[掛載架構]]
+- [[envelope-契約]] >> 承載產出於 >> [[extract-模型策略]]
@@ -0,0 +1,41 @@
+---
+tags: [萃取策略, 模型策略]
+gloss: ingest 走路徑 B 萃裸原文時的模型選擇與品質把關策略——用戶選意圖、品質門檻白名單、淺萃預設 Haiku、深萃 Claude、JSON-fail 升級閘。
+---
+# extract 模型策略
+
+← [[ingest/00-INDEX]]
+
+**來源**：`docs/3-specs/ingest-pipeline/{requirements,design}.md`、`CLAUDE.md`、`contracts/ingest-candidate.json`（extractor.tier）
+**最後更新**：2026-06-26
+> 跨專案完整版在 InkStoneCo `docs/3-specs/mira-dissolve/design.md §6.6`。本卡距離 ingest 內部要點。
+
+## 摘要
+
+只在路徑 B（裸原文萃取）才用。模型由用戶選「意圖」非「型號」，有品質門檻白名單把關，預設淺萃、必要時升級深萃。
+
+## 重點
+
+- **用戶選意圖非型號**：像 `/model` 那樣選意圖（要快/要深），不是選具體型號。
+- **品質門檻白名單**：模型要入白名單須過門檻——萃得出「深層暗示」+「中文過關」。難度隨來源分層：AI 報告弱模型夠、人類 vault（口語、暗示多）須好模型。
+- **兩 tier**（對應 envelope `extractor.tier`）：`shallow` = Workers AI 淺萃（預設 Haiku，走 API 便宜）；`deep` = Claude 深萃 via CC（走月費不走 API）。
+- **JSON-fail 升級閘**：淺萃 JSON 解析失敗 / 萃出過稀 → 自動升級到 deep 重萃。
+- **第一版不 embed**：embed 等 base vectorize 就緒（InkStoneCo T2.4）；ingest 本來就不算向量（見 [[envelope-契約]] 打標分工），第一版連打標執行端都還沒接，先跑萃取本身。
+- 模型測試集（中文 + 人類暗示樣本、轉回歸測試）為 deferred（SDD T3.3），先跑預設。
+
+## 實體
+
+- **品質門檻白名單** — 模型須萃得出深層暗示+中文過關才入選的把關機制。
+- **淺萃**（shallow tier／Workers AI／預設 Haiku）— 便宜快速的預設萃取層，走 API。
+- **深萃**（deep tier／Claude via CC）— 較貴較準的萃取層，淺萃失敗時升級，走月費。
+- **JSON-fail 升級閘** — 淺萃解析失敗或過稀時自動升 deep 的閘門。
+- **選意圖非型號** — 用戶像 /model 那樣選萃取意圖、而非指定具體模型的選擇方式。
+
+## 關聯
+### 內文知識關係（端點＝上方 `## 實體` 正規名）
+- JSON-fail 升級閘 >> 觸發升級到 >> 深萃
+- 淺萃 >> 升級為 >> 深萃
+- 品質門檻白名單 >> 把關 >> 選意圖非型號
+### 卡片關係（卡對卡）
+- [[extract-模型策略]] >> 屬於路徑B於 >> [[採取優先於萃取]]
+- [[extract-模型策略]] >> 產物送進 >> [[envelope-契約]]
@@ -0,0 +1,41 @@
+---
+tags: [掛載架構, 架構設計]
+gloss: kbdb-ingest-plugin 在 KBDB 堆疊裡的位置——掛在 graph 上、graph 掛在 base 上的最薄餵食器層。
+---
+# 掛載架構
+
+← [[ingest/00-INDEX]]
+
+**來源**：`CLAUDE.md`、`README.md`、`docs/3-specs/ingest-pipeline/design.md`
+**最後更新**：2026-06-26
+
+## 摘要
+
+KBDB 是三層堆疊：base 管儲存、graph 管三元組領域與查詢、ingest 是最薄的餵食器，只透過 API 往上一層 POST 候選。
+
+## 重點
+
+- 三層由下而上：`base KBDB（arcrun/kbdb）` 管儲存（D1 三表 + CRUD API）→ `kbdb-graph-plugin` 管三元組領域 + 圖查詢，並開 `POST /triplets/ingest` 寫入端 → `kbdb-ingest-plugin`（本 repo）純餵食器：拉 + 採取/萃取 + 跨庫織網。
+- 每層只透過上一層的 **HTTP API** 互動，不碰其內部結構。ingest 只打 graph 的寫入端，從不直連 base。
+- ingest 內部資料流：SourceAdapter（GitHub 拉 + content-hash，`source.uri = github:owner/repo@path`）→ 採取或 extract → 跨 repo 匯總織網 → POST envelope。
+- **無環**：graph 永不回呼 ingest。觸發只能從下游發起方向之外（webhook/排程，或 KBDB MCP `refresh` 代轉），下游圖層不主動驅動上游餵食器。
+- 命名只養一個品牌 Arcrun，本元件功能名當水管：`ingest`。
+
+## 實體
+
+> 本卡關鍵實體（graph node）。
+
+- **kbdb-ingest-plugin**（本 repo／餵食器）— KBDB 堆疊最薄一層，純 POST 候選 envelope 給 graph、不碰儲存。
+- **kbdb-graph-plugin**（graph 層）— 三元組領域與圖查詢層，對 ingest 開 `POST /triplets/ingest` 寫入端。
+- **base KBDB**（arcrun/kbdb／基本盤）— 最底儲存層，D1 三表 + CRUD API，ingest 與 graph 都不繞過它直碰表。
+- **SourceAdapter** — ingest 內部從 GitHub 拉 repo 並算 content-hash 的元件。
+
+## 關聯
+### 內文知識關係（端點＝上方 `## 實體` 正規名）
+- kbdb-ingest-plugin >> 掛載於 >> kbdb-graph-plugin
+- kbdb-graph-plugin >> 掛載於 >> base KBDB
+- kbdb-ingest-plugin >> POST候選給 >> kbdb-graph-plugin
+- SourceAdapter >> 隸屬於 >> kbdb-ingest-plugin
+### 卡片關係（卡對卡）
+- [[掛載架構]] >> 受約束於 >> [[envelope-契約]]
+- [[掛載架構]] >> 展開為 >> [[採取優先於萃取]]
@@ -0,0 +1,39 @@
+---
+tags: [ingest管線, 萃取策略, 架構設計]
+gloss: ingest 取得三元組的兩條路徑——優先「採取」本地 CC 已建好的三元組，無則才自己「萃取」裸原文。
+---
+# 採取優先於萃取
+
+← [[ingest/00-INDEX]]
+
+**來源**：`CLAUDE.md`、`README.md`、`docs/3-specs/ingest-pipeline/{requirements,design}.md`
+**最後更新**：2026-06-26
+
+## 摘要
+
+ingest 拿三元組有兩條路：路徑 A 採取（拉本地已建好的）優先，路徑 B 萃取（自己萃裸原文）是 fallback。
+
+## 重點
+
+- **路徑 A 採取（優先）**：repo 用了 system-dev-template、本地 CC 已建好三元組 + gloss → ingest 直接拉取，不重萃。
+- **路徑 B 萃取（fallback）**：裸原文、本地沒三元組 → ingest 自己 extract 出候選 (s,p,o) + gloss。
+- **為什麼採取優先**：知識連結長在「生產的當下」（local CC 有 LLM Wiki 指引、有完整脈絡），本地萃成效更好；下游 ingest 只有單檔/跨庫視角，臨時補的 gloss 會貼不合（＝胡扯）。所以 gloss 與三元組同階段由 local CC 建，不留給 ingest 補。
+- 兩路共同收斂到：跨 repo 匯總 → 織跨庫關聯 → POST envelope。**跨庫織網才是 ingest 不可取代的主職**（見 [[跨repo織網]]），採取/萃取只是取得素材的前段。
+- extract 的模型與品質細節見 [[extract-模型策略]]。
+
+## 實體
+
+- **採取**（路徑 A／拉）— ingest 直接拉本地 CC 已建好三元組+gloss、不重萃的取得方式。
+- **萃取**（路徑 B／extract／fallback）— 本地無三元組時，ingest 自己從裸原文萃出候選 (s,p,o)+gloss。
+- **gloss** — 一句話描述某 node 是什麼，供下游 base embed normalize 同義詞用。
+- **system-dev-template**（精耕模板）— 讓 local CC 在知識生產當下建好三元組+gloss 的模板，決定一個 repo 走採取或萃取。
+
+## 關聯
+### 內文知識關係（端點＝上方 `## 實體` 正規名）
+- 採取 >> 優先於 >> 萃取
+- 採取 >> 依賴於 >> system-dev-template
+- gloss >> 產出於 >> 採取
+- 萃取 >> 退而求其次補 >> gloss
+### 卡片關係（卡對卡）
+- [[採取優先於萃取]] >> 細節見 >> [[extract-模型策略]]
+- [[採取優先於萃取]] >> 服務於 >> [[跨repo織網]]
@@ -0,0 +1,37 @@
+---
+tags: [ingest管線, 掛載架構, 觀點主張]
+gloss: ingest 的主職與護城河——匯總多 repo 三元組、織出單一 repo 本地看不到的跨庫橋與異見。
+---
+# 跨 repo 織網
+
+← [[ingest/00-INDEX]]
+
+**來源**：`CLAUDE.md`、`README.md`、`docs/3-specs/ingest-pipeline/requirements.md`（R4）
+**最後更新**：2026-06-26
+
+## 摘要
+
+採取/萃取只是取素材；ingest 真正不可取代的價值，是匯總多個 repo 的三元組、織出單一 repo 在本地看不到的跨庫關聯。
+
+## 重點
+
+- **為什麼本地做不到**：單一 repo 的 local CC 只看得到自己庫內的知識；跨庫的「橋」（A 庫概念連到 B 庫概念）和「異見」（兩庫對同一概念說法相左）唯有把多 repo 三元組匯到一處才浮現。這是 ingest 的主職，不是採取/萃取的附屬。
+- **命題（護城河）**：不是「更好的 notes RAG」（紅海），而是**跨所有 vault 的圖**——Obsidian/Logseq 結構上做不到的那層。護城河是累積的圖，不是這份程式碼。
+- 織網發生在採取/萃取**之後**、POST envelope **之前**的匯總階段（見 [[掛載架構]] 資料流）。
+- 與「無環」「純 API」並存：織網是 ingest 端的運算（准），結果仍只透過 [[envelope-契約]] POST 給 graph，不碰儲存。
+
+## 實體
+
+- **跨repo織網**（跨庫織網／主職）— 匯總多 repo 三元組、織出跨庫橋與異見的 ingest 核心職責。
+- **跨庫橋**（bridge）— 一個 repo 概念連到另一 repo 概念的跨庫關聯，單庫本地看不到。
+- **跨庫異見** — 兩個庫對同一概念說法相左之處，匯總後才浮現。
+- **跨所有 vault 的圖**（護城河）— ingest 的命題：累積的跨庫圖，而非程式碼本身，才是護城河。
+
+## 關聯
+### 內文知識關係（端點＝上方 `## 實體` 正規名）
+- 跨repo織網 >> 浮現出 >> 跨庫橋
+- 跨repo織網 >> 浮現出 >> 跨庫異見
+- 跨repo織網 >> 構成 >> 跨所有 vault 的圖
+### 卡片關係（卡對卡）
+- [[跨repo織網]] >> 接續於 >> [[採取優先於萃取]]
+- [[跨repo織網]] >> 輸出走 >> [[envelope-契約]]