From 3a1faf19f4c47d379752e82fd0a929762ca879d2 Mon Sep 17 00:00:00 2001 From: richblack Date: Sun, 14 Jun 2026 21:25:46 +0800 Subject: [PATCH] =?UTF-8?q?docs(wiki):=20/wiki-capture=20=E2=80=94=20?= =?UTF-8?q?=E4=BF=AE=E6=AD=A3=E9=81=8E=E6=99=82=E6=B1=BA=E7=AD=96=20+=20?= =?UTF-8?q?=E6=96=B0=E5=A2=9E=20API-as-Wall=20ADR?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - decisions-summary.md：新增「KBDB 鐵律 + API-as-Wall」「安裝契約」； 修正過時兩條（「共用 D1 掛載」改 API；「萬物皆 Block v3」標已淘汰/違規殘留已刪） - 新增 ADR docs/2-architecture/decisions/0001-api-as-wall.md Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/wiki/decisions-summary.md | 31 ++++++++++---- .../decisions/0001-api-as-wall.md | 41 +++++++++++++++++++ 2 files changed, 64 insertions(+), 8 deletions(-) create mode 100644 docs/2-architecture/decisions/0001-api-as-wall.md diff --git a/.claude/wiki/decisions-summary.md b/.claude/wiki/decisions-summary.md index c914318..e0131e4 100644 --- a/.claude/wiki/decisions-summary.md +++ b/.claude/wiki/decisions-summary.md @@ -10,15 +10,30 @@ **原因**：graph 能力較龐大、非基本儲存功能、leo 產權、較複雜 → 不留 arcrun。基本盤（block CRUD，D1 三表）= `arcrun/kbdb`，不在本目錄。 **詳細**：`docs/HANDOFF-kbdb-plugin.md`；來源 InkStoneCo 頂層 `matrix-rearrange` Phase 2 (R2)。 -## 獨立 repo 名 + 邊界乾淨度 — 2026-06-14 -**結論**：獨立 repo = 新 repo `uncle6me-web/kbdb-graph-plugin`（leo 拍板，沿用目錄名）。grep 證實插件與基本盤 action 層零耦合，耦合只在 DB 層（讀 blocks/entry_values + triplets VIEW）。 -**原因**：乾淨的 AGE-on-Postgres，插件抽出無程式碼牽連；唯一要設計的是 DB 掛載介面。 -**詳細**：`docs/3-specs/kbdb-graph-extraction/design.md`（灰色地帶結論 + 掛載介面）。 +## 🔒 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`。 -## 萬物皆 Block（KBDB v3）— 2026-02-28 -**結論**：一張 Block 表 + type 欄位，禁 CREATE/ALTER TABLE，新資料類型用 template；API-as-Wall。 -**原因**：零 migration 擴充；所有讀寫經 API 不繞過直打 D1。 -**詳細**：`CLAUDE.md` 下半（v3 全規範，含基本盤，待裁剪只留 graph 插件相關）。 +## 獨立 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..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。 diff --git a/docs/2-architecture/decisions/0001-api-as-wall.md b/docs/2-architecture/decisions/0001-api-as-wall.md new file mode 100644 index 0000000..3caafe5 --- /dev/null +++ b/docs/2-architecture/decisions/0001-api-as-wall.md @@ -0,0 +1,41 @@ +# ADR 0001：KBDB 鐵律 — 插件 API-as-Wall（零碰表 / 零 SQL / 零 migration） + +- 狀態：已採納（Accepted） +- 日期：2026-06-14 +- 決策者：leo（總管） +- 提出：KBDB-graph 子 repo CC + +## 背景 + +KBDB-graph 插件（triplet 採集 + graph 查詢）原本直接以 SQL 讀寫基本盤的 `blocks`/`entry_values` 表（28×/31× SQL 引用），並帶獨立 `blocks` 表 + 0001/0005 `CREATE TABLE` migrations。子 repo 的 design.md 一度把這個「現狀」當成 **AGE-on-Postgres 訊號**，跑去問「要不要共用同一個 D1、直接 SQL 掛在基本盤表上」。 + +這是**讀違規現狀去推翻鐵律**——那些直接 SQL 是違反 API-as-Wall 的歷史產物，不是設計依據。 + +## 決策 + +KBDB 生態最高原則（leo 拍板）： + +1. **任何人不准動表** — 禁 `CREATE/ALTER/DROP TABLE`。那 3 表（`entries`/`templates`/`entry_values`）只有基本盤維護者能改。 +2. **插件不准直接接觸表** — 禁 `SELECT/INSERT/UPDATE/DELETE/JOIN`、禁 `.prepare(...sql...)`、禁綁 D1/Vectorize/AI。 +3. **讀寫全走基本盤 API/CLI/MCP** — 插件與 AI/人同一條路（薄殼原則）。唯一通道 = `src/lib/kbdb-client.ts`，指向 `KBDB_BASE_URL`。 +4. **新資料類型 = 建 template + 填 slot，永不建表** — triplet=`template='triplet'`、entity=`template='entity'`。連「插件自建獨立 D1（triplet_clusters 等）」都不行——那仍是建表。 +5. **零 migration、零 SQL** — 插件目錄無 `migrations/`。SQL 只存在於基本盤 worker 內部。 + +> 比 AGE-on-Postgres 更嚴：AGE 插件能直接讀 Postgres 表；KBDB 插件連表都不許碰，必須透過基本盤 API。真正的 API-as-Wall。 + +## 後果 + +- 圖不靠 DB VIEW，靠插件層從 triplet records 在**記憶體**組鄰接表跑演算法。 +- embedding / 語意搜尋屬基本盤 optional embed 模組（D1 only 之外的加購層），**非插件職責**；插件 entity 正規化降級 exact match、search 降級 keyword。 +- 基本盤缺口（無 `PUT/DELETE /records/:id`、無 vectorize）標 `[→arcrun]`，**不得**為此自建表或直連 D1。 +- 鐵律寫成 hook 強制（`.claude/hooks/pre-write-guard-no-table.sh`、`pre-bash-guard-no-table.sh`，違反 exit 2）。誠實限制：hook 擋語法層明顯 SQL，藏在 helper 裡的繞道擋不了 → 文檔 + hook 兩者都不可省。 + +## 關鍵教訓 + +**讀現狀 ≠ 設計依據。** 違規代碼會自我合理化。現狀與鐵律衝突時，改現狀，不是改鐵律。 + +## 相關 + +- 頂層決策全文：`InkStoneCo/docs/3-specs/matrix-rearrange/DECISION-kbdb-v3-baseplane.md` +- 改寫範圍：`docs/3-specs/kbdb-graph-extraction/design.md`、`tasks.md`（R-EXT-4） +- 教訓：`.claude/wiki/mistakes.md`「讀違規現狀推翻鐵律」