Leo
efe8e165cf
按 leo 鐵律（2026-06-14）把插件從「直接 SQL 操作基本盤表」改寫成 「只透過基本盤 arcrun/kbdb HTTP API 讀寫」。零建表、零 migration、零 SQL。 - 新增 src/lib/kbdb-client.ts：唯一對外通道，封裝 entries/templates/records API - 新增 src/lib/templates.ts：triplet/entity template 定義（替代建表） - 改寫 21 個違規 action（triplet/graph/entity/search）→ 走 client，圖在插件層記憶體組裝 - 移除所有 migrations、D1/Vectorize/AI 綁定；embedding/語意搜尋歸基本盤 optional 模組 - index.ts 只掛 triplets/graph/entities/search 路由；基本盤路由歸 arcrun/kbdb - 測試改走 mock client（純 node）；裁剪 CLAUDE.md 只留 graph 插件 + 鐵律 - 修正 SDD design.md「讀現狀推翻鐵律」的錯誤判斷（共用 D1 → API-as-Wall） Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
41 lines
3.6 KiB
Markdown
41 lines
3.6 KiB
Markdown
# HANDOFF: KBDB triplet/graph → 改名 **KBDB-graph**，作為 KBDB 插件獨立（2026-06-13）
|
||
|
||
來源：InkStoneCo 頂層 `.agents/specs/matrix-rearrange/` Phase 2（R2）。
|
||
**指針式考古**：相關歷史素材在 InkStoneCo `_archive/`，照路徑挖，不複製。
|
||
|
||
## 定位（leo 2026-06-13 澄清）
|
||
|
||
此目錄 `matrix/kbdb-graph-plugin`（原 matrix/kbdb，已改名）作為 **KBDB-graph**，是**原有 KBDB 的插件**獨立：
|
||
- **原有 KBDB（基本盤）** = `arcrun/kbdb`：D1 三表（blocks/templates/slots）的基本儲存讀寫，已併進 arcrun。
|
||
- **KBDB-graph（本目錄→獨立 repo）** = 掛在基本盤之上的 triplet 採集 + graph 查詢能力。**類比 Apache AGE 之於 Postgres**——插件掛在基本儲存上，不取代它。
|
||
- **為何獨立**：它比較龐大、不是基本存儲功能；且 leo 產權、較複雜。故獨立成 repo，不留在 arcrun。
|
||
- **由此目錄的 CC 自行 `git init` + 推 GitHub**（命名 `KBDB-graph`，帳號 leo 定/uncle6me-web）。
|
||
|
||
## ⚠️ 重大修正（leo 2026-06-14）：插件現狀違反 KBDB 鐵律，要改寫
|
||
|
||
**先讀總管決策 `InkStoneCo/.agents/specs/matrix-rearrange/DECISION-kbdb-v3-baseplane.md`。**
|
||
|
||
你之前的 design.md 把「現狀代碼直接 SQL 讀 entry_values/blocks」當成「AGE-on-Postgres 訊號」、跑去問「要不要共用 D1 直接 SQL」——**這是讀現狀推翻鐵律的錯**。你自己的 CLAUDE.md 第 83 行就寫了「禁止繞過 API 直接 D1 操作 — API-as-Wall」。現狀代碼是違規的歷史產物，不是設計依據。
|
||
|
||
### KBDB 鐵律（leo 拍板，最高原則）
|
||
1. **任何人都不准動表**（CREATE/ALTER/DROP）。只有基本盤維護者能改那 3 表，你不行。
|
||
2. 新資料類型=建 template，永不建表。triplet=`template='triplet'` 寫進 entry_values。
|
||
3. 插件**不准直接接觸表**（禁 SELECT/INSERT/JOIN），讀寫**全走基本盤 API**。
|
||
4. 插件層全程禁 SQL。
|
||
|
||
### 正確形態
|
||
- 基本盤=arcrun/kbdb（3 表 + CRUD API：templates/entries/records/search 端點，已存在），**不動**。它用 `entry_type='block'` 表達 block，無獨立 blocks 表。
|
||
- 你=`triplet` template 定義（`contracts/triplet.json`）+ graph 查詢函式。寫 triplet→調基本盤 records/entries API；查圖→調基本盤 search API 取 entry_values 在插件層組裝。**零建表、零 migration、零 SQL。**
|
||
|
||
## 待辦（由本目錄 CC 執行）
|
||
|
||
1. **改寫成走 API/薄殼**（核心）：`triplet-crud` 的 `INSERT INTO entry_values`、graph/entity 的 `SELECT FROM ...` → 改調基本盤 API（或 MCP/CLI 薄殼，與 AI/人同一條路）。寫 triplet=建 `template='triplet'` + 填 slot（調 `POST /templates`、`POST /records`）；查圖=調 search/records API 取回再組裝。**注意**：arcrun 的 MCP/CLI 目前還沒 KBDB tool（要 arcrun 端先補，見 arcrun HANDOFF §2），在那之前先直調基本盤 HTTP API。
|
||
2. **刪除違規 migrations**：`0001_init`/`0005_universal_table` 等含 `CREATE TABLE` 的全刪（插件不建表）。triplets VIEW 改用 API 查 + 插件層組裝。
|
||
3. **改名 `KBDB-graph` + `git init` + 推 GitHub**（帳號 leo 定）。由本 CC 自己推。
|
||
4. **裁剪 CLAUDE.md**：移除整套 KBDB v3 基本盤規範（那屬 arcrun/kbdb），只留 graph 插件相關 + 上面鐵律。
|
||
5. 部署繞開 GitHub（wrangler 直推），禁跨 repo 同步 Actions（[[github-flagged-risk]]）。
|
||
|
||
## 注意
|
||
- 本目錄現**無獨立 git**。改名後 `git init` + remote（帳號 leo 定），由本 CC 推。
|
||
- arcrun 端基本盤已正確（3 表 + API），不需升 v3、不需搬基本盤。對應交棒見 arcrun `docs/HANDOFF-matrix-rearrange.md` §2。
|