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>
90 lines
5.1 KiB
Markdown
90 lines
5.1 KiB
Markdown
# CLAUDE.md — KBDB-graph 插件開發規範
|
||
|
||
> **上游約束（InkStoneCo 總管）**：此目錄（原 matrix/kbdb，已改名 kbdb-graph-plugin）是 InkStoneCo 子專案，受頂層知識庫約束。
|
||
> 動工前讀 `github.com/uncle6me-web/InkStoneCo` 的 CLAUDE.md + `docs/3-specs/matrix-rearrange/`。
|
||
> **定位（leo 2026-06-13）**：此 repo = **KBDB-graph 插件**（triplet 採集 + graph 查詢），類比 **Apache AGE 之於 Postgres**。基本盤 = `arcrun/kbdb`（D1 三表 + CRUD API），**不在這裡、不動它**。
|
||
> **本目錄專屬交棒見 `docs/HANDOFF-kbdb-plugin.md`**，SDD 見 `docs/3-specs/kbdb-graph-extraction/`。
|
||
|
||
> 本檔案由 Claude Code 自動讀取。所有在此目錄下的開發必須遵守以下規則。
|
||
|
||
---
|
||
|
||
## 🔒 KBDB 鐵律（leo 2026-06-14 拍板，最高原則，違反會被 hook exit 2 擋下）
|
||
|
||
決策全文：`InkStoneCo/docs/3-specs/matrix-rearrange/DECISION-kbdb-v3-baseplane.md`。
|
||
|
||
1. **任何人不准動表** — 禁 `CREATE/ALTER/DROP TABLE`。那 3 表只有基本盤維護者（leo）能改。
|
||
2. **插件不准直接接觸表** — 禁 `SELECT/INSERT/UPDATE/DELETE`、禁 `JOIN`、禁 `.prepare(...sql...)`、禁綁 D1/Vectorize/AI。
|
||
3. **讀寫全走基本盤 API/CLI/MCP** — 插件與 AI/人同一條路（薄殼原則）。base URL = `KBDB_BASE_URL` env var。
|
||
4. **新資料類型 = 建 template + 填 slot，永不建表** — triplet=`template='triplet'`、entity=`template='entity'`，走 `POST /templates`+`POST /records`。
|
||
5. **零 migration、零 SQL** — 插件目錄無 `migrations/`。SQL 只存在於基本盤 worker 內部。
|
||
|
||
> 比 AGE-on-Postgres 更嚴：AGE 能讀 Postgres 表，KBDB 插件連表都不許碰，必須透過基本盤 API。真正的 API-as-Wall。
|
||
> **誠實限制**：hook 擋語法層明顯 SQL；藏在 helper 裡的繞道擋不了 → 文檔（本檔）+ hook 都不可省。想到「建表」時只准 template/slot。
|
||
|
||
### 掛載架構
|
||
|
||
```
|
||
基本盤 arcrun/kbdb（不動） KBDB-graph 插件（本 repo）
|
||
─ entries / templates / entry_values ─ triplet template 定義 + graph 查詢函式
|
||
─ CRUD API: ─ 寫 triplet → POST /records (template=triplet)
|
||
POST /entries POST /templates ─ 查圖 → GET /records/by-template/triplet
|
||
POST /records GET /entries/search → 插件層【記憶體】組鄰接表跑圖演算法
|
||
GET /records/by-template/:tpl ─ entity 正規化 → template='entity'（exact match）
|
||
─ 唯一對外通道 = src/lib/kbdb-client.ts
|
||
```
|
||
基本盤 API 契約詳見 `docs/3-specs/kbdb-graph-extraction/design.md`。
|
||
**基本盤缺口**（base 無 `PUT/DELETE /records/:id`、無 vectorize 語意搜尋）標 `[→arcrun]`，不得為此自建表。embedding/語意搜尋屬基本盤 optional embed 模組，**不是插件職責**。
|
||
|
||
---
|
||
|
||
## Wiki 讀取順序（LLM 記憶系統，CC 維護）
|
||
|
||
| 檔案 | 時機 | 用途 |
|
||
|------|------|------|
|
||
| `.claude/wiki/status.md` | session 開始第一件事 | 當前進度、下一步 |
|
||
| `.claude/wiki/mistakes.md` | 做新功能前 | 已知誤解、避坑清單 |
|
||
| `.claude/wiki/decisions-summary.md` | 設計判斷時 | 架構決策摘要 |
|
||
|
||
文件分類規則見 `docs/README.md`；SDD 在 `docs/3-specs/[子系統]/`（design.md + tasks.md），動手前必須有這兩個檔案。
|
||
session 結束用 `/wiki-update` 更新 status.md，被糾正後 `/wiki-capture` 寫進 mistakes.md。
|
||
|
||
---
|
||
|
||
## 樂高法硬性限制（Layer 1）
|
||
|
||
- `src/actions/` 目錄下的檔案**嚴禁超過 100 行**，建議 50-80 行
|
||
- **一檔一事**：每個 action 只做一件具體的事
|
||
- **無狀態**：Action 不保存記憶體狀態，所有狀態透過參數傳遞或走基本盤 API 持久化（**不碰 D1/Vectorize**）
|
||
- Route 檔案（`src/routes/`）**不含業務邏輯**，僅驗證參數 + `makeKbdbClient(c.env)` + 呼叫 action
|
||
|
||
## 目錄結構
|
||
|
||
```
|
||
src/
|
||
├── lib/ ← kbdb-client.ts（唯一對外 API 通道）、templates.ts（插件 template 定義）
|
||
├── actions/ ← 核心業務邏輯（純函數，< 100 行，第一參數收 KbdbClient）
|
||
├── routes/ ← HTTP 入口（Hono route，只做驗證 + 呼叫 action）
|
||
├── types.ts ← 型別定義（= contracts）
|
||
└── index.ts ← Worker 進入點（只掛 triplets/graph/entities/search 路由）
|
||
```
|
||
|
||
## 開發流程
|
||
|
||
1. 在 `types.ts` 定義輸入/輸出型別
|
||
2. 在 `tests/` 寫測試（走 `tests/mock-client.ts` 的 mock KbdbClient，不打真網路）
|
||
3. 在 `actions/` 實作邏輯（透過 `KbdbClient` 讀寫，零 SQL）
|
||
4. 在 `routes/` 建立 HTTP 入口
|
||
|
||
---
|
||
|
||
## 技術棧
|
||
|
||
- **Framework**: Hono（OpenAPIHono）
|
||
- **資料層**: 全走基本盤 arcrun/kbdb HTTP API（`KBDB_BASE_URL`）。**插件本身無 D1/Vectorize/AI 綁定。**
|
||
- **Validation**: Zod
|
||
- **Testing**: Vitest（純 node + mock client）
|
||
- **部署**: wrangler 直推 Cloudflare，**不開 Actions**（避免再被 flag，見頂層鐵律）
|
||
|
||
> 2026-06-14：按 leo 鐵律改寫完成。21 個違規直接 SQL action 全改走基本盤 API；刪除所有 migrations（插件零建表）；移除 D1/Vectorize/AI 綁定。基本盤規範歸 `arcrun/kbdb`。
|