Leo
06e901f590
把 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>
44 lines
3.4 KiB
Markdown
44 lines
3.4 KiB
Markdown
---
|
||
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-模型策略]]
|