Files

T

Leo d2618758e2 docs(sdd): SDD 生命週期鐵律遷移 + SDD 位置統一到 system-dev/docs/3-specs/

- 位置統一：舊 docs/3-specs/ 五份 SDD git mv 到 system-dev/docs/3-specs/，舊位置留 README 指針
- 狀態判定：0 份 active（無現行開發，合法）；paused×3（ingest-contract/kbdb-graph-extraction/plugin-install，等跨 repo 接通）；closed×2 入 archive/（arcrun-key-auth/blocks-edit-api 死件，附封存原因）
- 鋪檔（自 system-dev-template v1.15.0）：SDD-LIFECYCLE.md、pending-changes.md、sdd-guard.sh 新版、sdd-check.md、sdd-active-check.sh
- hook 掛載：settings.json PreToolUse Write|Edit 加 sdd-guard.sh
- CLAUDE.md：SDD 鐵律段（濃縮五條＋0-active 註明重啟先升 active）＋修正遷移後舊路徑
- 驗證：sdd-active-check exit 0；guard pipe-test 0-active 擋 code 寫入(exit 2)/md 放行(exit 0)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-17 17:04:12 +08:00

6.8 KiB

Raw Blame History

status, superseded_by

status	superseded_by
paused

ingest-contract — 設計

藍圖在頂層：本 SDD 只放 kbdb-graph-plugin 內部實作細節。跨專案脈絡（為什麼拆 ingest/graph、mira 蒸發、整體資料流）見 InkStoneCo docs/3-specs/mira-dissolve/（design + requirements）。 對應交辦：kbdb-graph-plugin #1（T3）。鐵律：API-as-Wall / 零建表 / 零 SQL / 零 migration。embedding/語義 normalize 屬 base 模組，graph 只調不自算。圖在插件層記憶體組裝。

1. 範圍

graph 插件補上寫入端：收 ingest 送來的 ingest-candidate envelope，正規化後以「翻 triplet 的 status slot」做 deprecate-then-append 取代，並讓查詢面 active-only。查詢面（search/traverse/neighbors）已成熟，本批只補 active 過濾。

不在本批：圖工具併入 KBDB MCP 的註冊薄殼（需 arcrun 配合，見 §6）；semantic normalize 端到端（依賴 base embed 部署）。

2. 邊界契約

唯一入口契約 = contracts/ingest-candidate.json（已搬入，T3.1）。要點見 contracts/README.md。 graph 收件後負責的領域欄位（ingest 禁送）：id / clusters / bridge_score / created_at / triplet 上的 *_entity_type。additionalProperties:false → 違規欄位 422。

3. template slot 變更（T3.2 / 3.2b）

現況（src/lib/templates.ts，已核實）：

TRIPLET_SLOTS 無 status / superseded_by。
ENTITY_SLOTS 無 gloss。

要加：

triplet：status（active | deprecated，預設 active）、superseded_by（指向取代它的新 record id，空＝未被取代）。
entity：gloss（一句話描述，供「詞+gloss」語義 normalize 的 embedding 對象）。

⚠️ ensureTemplate early-return 陷阱（前置警示 1，已核實）

KbdbClient.ensureTemplate（src/lib/kbdb-client.ts:120）命中既有 template 即 return，不會把新 slot 補進已 seed 的 template。只改 TRIPLET_SLOTS 陣列對既有環境無效。

對策：ensureTemplate 改為「命中既有 → 比對 slot 差集 → 缺的走 base PATCH /templates/:id 補上」，而非 early-return。新環境（template 不存在）走原 POST /templates 路徑不變。如此既有 + 全新環境都正確收斂，不需另跑一次性遷移腳本。

4. KbdbClient.updateRecord（前置警示 2，已核實）

client 現有 createRecord / getRecord / listRecordsByTemplate，無 record 層 PATCH（updateEntry 是 entry 層，不是 record）。

新增 updateRecord(recordId, values) → 呼叫 base PATCH /records/:id（base #6 已就緒）。deprecate（翻 status）與 rollback（翻回 status）都靠它。

5. POST /triplets/ingest（核心，T3.3）

純函式 action（src/actions/triplet-ingest.ts，<100 行，第一參數收 KbdbClient），route 只驗證 + 呼叫。流程：

驗證 envelope：Zod schema 鏡射 ingest-candidate.json，additionalProperties:false → 禁送欄位（如 bridge_score）回 422。
idempotency：以 source.uri 為鍵查該來源現存 active triplet 的 content_hash（存進 triplet 的某 slot，見下）。同 hash → no-op 回 {skipped:true}。
deprecate-then-append：新 hash → 查該 uri 所有 active triplet，逐筆 updateRecord(id, {status:'deprecated', superseded_by:<新批暫不知 id，二階段或留空>})，再 append 新批 active。
回應：{ ingested: N, deprecated: M, skipped: false }。

content_hash / source.uri 存哪

triplet record 需記住它來自哪個 snapshot 才能做 idempotency 與 active-only。沿用既有 source_block_id 不夠（那是 Logseq block）。設計：triplet template 增記 source_uri + content_hash slot（屬 §3 同批 slot 變更，非建表）。active-only 與 deprecate 都按 source_uri 分組。

註：superseded_by 指向「取代它的新 record id」。新批 record 是 append 後才有 id → 若要精確回填，deprecate 分兩步（先 append 拿 id，再翻舊批 status + superseded_by）。先 append 後 deprecate 比較安全（中途失敗不會留下「全無 active」的空窗）。

6. 查詢 active-only（T3.5）

traverse / search / neighbors 從 records 組鄰接表前，先 filter(status === 'active')（預設值缺省視為 active，相容舊資料）。active 集合永遠乾淨，deprecated 仍可查（rollback / 考古）但不進圖遍歷。

7. 跨 repo 協調點：圖工具併入 KBDB MCP（T3.6，需 arcrun 配合）

圖工具（traverse / neighbors / get_source）+ refresh 要併進 arcrun 的 KBDB MCP（u6u-mcp-server），不另起 graph 獨立 MCP。

graph repo 端能備好的：圖查詢的 HTTP API + 邏輯、get_source 端點（T3.7）、refresh 代轉 ingest 的端點。
需 arcrun 端動的：MCP 工具註冊薄殼那層 → 標清在 issue #1，由總管協調。本批不擅自開獨立 graph MCP。
refresh 紅線（T3.6b）：只能人發起的 MCP 調用觸發，禁掛排程/webhook 自動 refresh（否則變回 fan-out，踩 flag 紅線）。
T3.6d：整合時移除 search-query.ts 代理 base 關鍵字那條（重複，關鍵字歸 KBDB MCP）。

7.5 get_source / refresh 落地（C 段，已實作）

get_source（graph-source.ts + GET /graph/source/:name）：給節點名 → 回觸及它的 active triplet 的來源指標（uri / anchor / block_id / content_hash），按 uri+anchor 去重。為此 triplet template 增 source_anchor slot（ingest 從 source.anchor 帶入）。
refresh（graph-refresh.ts + POST /graph/refresh）：純被動代轉 ingest 重抓+萃。graph 自己不抓不萃（ingest 純餵食器職責）。
- 🚫 紅線：只人發起 MCP 調用觸發，無排程/webhook。
- ingest 對象 = KBDB_INGEST_URL（env，T4 就緒前留空）。未設 → 誠實回 {forwarded:false}，不假綠。
search keyword 收斂（T3.6d）：POST /search 移除公開 keyword 模式（重複 KBDB MCP kbdb_search），收斂為 suggest-only。keywordSearch helper 保留為 suggest 內部建構塊。

8. 不做 / 延後

graph CLI（T3.7b）：延後。人少在命令行 traverse、AI 用不到 → 不做（非省工，是不誤導 AI 以為有這條路）。
semantic normalize（T3.2c）：本批先 exact-only，semantic 留接口。base embed（Arcrun #7）部署後才端到端，屆時標「待 base embed 部署驗」。

9. 樂高法遵循

每個 action <100 行、一檔一事、無狀態（狀態走 base API 持久化）。
route 不含業務邏輯，只 makeKbdbClient(c.env) + 驗證 + 呼叫 action。
測試走 tests/mock-client.ts，不打真網路。

6.8 KiB Raw Blame History Unescape Escape