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>
This commit is contained in:
2026-06-26 20:45:18 +08:00
parent dffefdcdc2
commit 06e901f590
36 changed files with 2635 additions and 45 deletions
@@ -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 跳過。
- **取代語意歸 graphingest 一無所知**:同 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-模型策略]]