Leo
fbd375f7ac
- status.md：2026-06-26 進度（PR #2、T3 A/B/C 段完成、跨 repo 待接、缺口表） - decisions-summary.md：先 append 後 deprecate / idempotency slot / ensureTemplate slot-diff / refresh 純被動代轉 - mistakes.md：照字面刪 action 沒查反向依賴 / 拿錯 gate(tsc) 誤判改壞 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
70 lines
5.9 KiB
Markdown
70 lines
5.9 KiB
Markdown
# 架構決策摘要
|
||
|
||
> 遇到設計判斷時查這裡。
|
||
> 完整脈絡在 docs/2-architecture/decisions/。
|
||
|
||
---
|
||
|
||
## KBDB-graph 定位 — 2026-06-13
|
||
**結論**：本目錄 = KBDB 的 graph 插件（triplet 採集 + graph 查詢），獨立成 repo，類比 Apache AGE 之於 Postgres。
|
||
**原因**：graph 能力較龐大、非基本儲存功能、leo 產權、較複雜 → 不留 arcrun。基本盤（block CRUD，D1 三表）= `arcrun/kbdb`，不在本目錄。
|
||
**詳細**：`docs/HANDOFF-kbdb-plugin.md`；來源 InkStoneCo 頂層 `matrix-rearrange` Phase 2 (R2)。
|
||
|
||
## 🔒 KBDB 鐵律 + 插件 API-as-Wall 形態 — 2026-06-14（最高原則）
|
||
**結論**：插件【絕不碰表、零 SQL、零 migration】，讀寫全走基本盤 arcrun/kbdb HTTP API。新資料類型=建 template+填 slot，永不建表（連插件自建獨立 D1 都不行）。任何人不准動表（CREATE/ALTER/DROP）。embedding/語意搜尋屬基本盤 optional embed 模組，非插件職責。
|
||
**原因**：比 AGE-on-Postgres 更嚴——AGE 能讀 Postgres 表，KBDB 插件連表都不許碰。真正的 API-as-Wall。鐵律已 hook 化（`.claude/hooks/pre-{write,bash}-guard-no-table.sh`，違反 exit 2）。
|
||
**詳細**：`InkStoneCo/docs/3-specs/matrix-rearrange/DECISION-kbdb-v3-baseplane.md` + ADR `docs/2-architecture/decisions/0001-api-as-wall.md`。
|
||
|
||
## 獨立 repo 名 — 2026-06-14
|
||
**結論**：獨立 repo = **public `uncle6me-web/kbdb-graph-plugin`**（leo 拍板，沿用目錄名）。無 .github/workflows（不開 Actions）。
|
||
**原因**：插件與基本盤 action 層零耦合，抽出乾淨。
|
||
**詳細**：`docs/3-specs/kbdb-graph-extraction/design.md`。
|
||
|
||
## 掛載介面 = 基本盤 API（非共用 D1）— 2026-06-14（推翻原判斷）
|
||
**結論**：插件掛載 = HTTP API（`KBDB_BASE_URL`），**不共用 D1、不直接 SQL、不建 VIEW**。圖在插件層記憶體從 records 組裝。
|
||
**原因**：⚠️ 原版「AGE-on-Postgres 共用 D1 + DB 掛載介面」是**讀違規現狀（插件直接 SQL 讀 blocks/entry_values）推出來的錯判斷**——那些直接 SQL 是違規歷史產物，不是設計依據。鐵律 > 現狀。
|
||
**詳細**：design.md「掛載介面 = 基本盤 API」節 + mistakes.md「讀違規現狀推翻鐵律」。
|
||
|
||
## 安裝契約：KBDB_BASE_URL 安裝時 AI 填 — 2026-06-14
|
||
**結論**：`KBDB_BASE_URL` 不寫死 toml、不叫人填。安裝時 AI 查 CF subdomain 拼 `https://arcrun-kbdb.<subdomain>.workers.dev`，`wrangler secret put` + `wrangler deploy`。本地整合測試用 `.dev.vars`（非 .env）。
|
||
**原因**：因部署而異（每個 self-hosted 用戶 subdomain 不同），但確定性可算（能 deploy 就能查 subdomain，同套 CF 憑證）。
|
||
**詳細**：`scripts/install.sh`；參考 arcrun `docs/3-specs/arcrun/sdk-and-website/self-hosted-init.md`。
|
||
|
||
## ~~萬物皆 Block（KBDB v3）~~ — 2026-02-28（已淘汰，2026-06-14 修正）
|
||
**結論**：⚠️ 本目錄那套帶獨立 `blocks` 表 + 0001/0005 CREATE TABLE 的「v3」是**長歪的違規殘留，已刪**。基本盤真身 = `arcrun/kbdb` 3 表（`entries/templates/entry_values`，`entry_type='block'` 表達 block，不需獨立 blocks 表）。
|
||
**原因**：「萬物皆 Block」獨立 blocks 表違反「不建表」鐵律。基本盤規範歸 arcrun/kbdb，本 repo CLAUDE.md 已裁剪。
|
||
**詳細**：DECISION-kbdb-v3-baseplane.md 一節「原提問的前提是錯的」。
|
||
|
||
## 避免再被 GitHub flag（上游鐵律）— 沿用
|
||
**結論**：禁跨 repo 自動同步 Actions；部署繞開 GitHub（wrangler / scp）；新 repo 預設不開 Actions。
|
||
**原因**：當初 monorepo→多 worker 的 Actions 自動同步 + 高頻 API 害帳號被 flag。
|
||
**詳細**：InkStoneCo 頂層 CLAUDE.md。
|
||
|
||
## ingest 取代用「先 append 後 deprecate」— 2026-06-26（總管採納，優於頂層原寫法）
|
||
**結論**：`POST /triplets/ingest` 同 source.uri 出新 content_hash 時，**先 append 新批 active，再翻舊批 status=deprecated**。非頂層 SDD 原寫的「deprecate-then-append」。
|
||
**原因**：先翻舊批會出現「全無 active」的中途空窗（若 append 失敗）；先 append 保證任一時刻都有 active 集合可查。總管已回頭把頂層 design §5 對齊成此寫法。
|
||
**詳細**：`docs/3-specs/ingest-contract/design.md` §5；issue #1 總管確認 comment。
|
||
|
||
## idempotency 鍵存進 triplet template slot — 2026-06-26
|
||
**結論**：triplet template 增 `source_uri`+`content_hash`（+`source_anchor` 供 get_source）slot 承載 ingest idempotency；按 `source_uri` 分組 deprecate、同 hash no-op。`source_block_id`（Logseq）不夠用。
|
||
**原因**：純 plugin 領域 slot（base 不需知道），合鐵律（slot 非建表）；contract `ingest-candidate.json` 本就有 source.uri+content_hash，落地存進 slot 是自然動作，**不改 contract**。
|
||
**詳細**：`design.md` §3/§5；issue #1。
|
||
|
||
## ensureTemplate 改 slot-diff 補丁 — 2026-06-26
|
||
**結論**：`ensureTemplate` 命中既有 template 時，比對 slot 差集 → 缺的走 base `PATCH /templates/:id` 補上（**取代原 early-return**）。
|
||
**原因**：原 early-return 不補新 slot → seed 後新增的 slot（status/gloss…）對既有環境永遠進不來。slot-diff 讓既有+全新環境都自動收斂，免另跑一次性遷移腳本。
|
||
**詳細**：`src/lib/kbdb-client.ts`；issue #1 前置警示1。
|
||
|
||
## refresh 純被動代轉（人發起，守 fan-out 紅線）— 2026-06-26
|
||
**結論**：`POST /graph/refresh` 只代轉 ingest 重抓+萃，**只能人發起調用觸發**，禁排程/webhook/cron 自動 refresh。graph 自己不抓不萃（ingest 純餵食器職責）。
|
||
**原因**：自動 fan-out 正是當初害 GitHub flag 的模式。`KBDB_INGEST_URL` 未設時誠實回 `forwarded:false`，不假綠。
|
||
**詳細**：`src/actions/graph-refresh.ts`；issue #1 T3.6b。
|
||
|
||
---
|
||
|
||
格式：
|
||
## [主題] — [YYYY-MM-DD]
|
||
**結論**：[一句話]
|
||
**原因**：[簡短說明]
|
||
**詳細**：docs/2-architecture/decisions/[對應檔案]
|