Leo
3fa5cda796
KBDB_BASE_URL 由安裝時的 AI 自動填（查 CF subdomain 拼基本盤 URL），不寫死 toml、不叫人填。 - scripts/install.sh：whoami → 查 subdomain → wrangler secret put → wrangler deploy - .dev.vars.example：整合測試本地基本盤慣例（.dev.vars 已 gitignore） Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2.5 KiB
2.5 KiB
KBDB-graph 插件安裝 — Design
目標
用戶給一個 github 網址，AI 就能把 KBDB-graph 插件裝到用戶自己的 CF 帳號，全程零填寫。 類比：像裝 Postgres 的 AGE 擴充——掛在已有的基本盤（arcrun/kbdb）上。
核心原則：KBDB_BASE_URL 由 AI 自動填，不是人填
| 反例（不要） | 正解 |
|---|---|
| 叫人填 wrangler.toml | toml 留 ""，AI 安裝時填 |
| 叫人填 .env | 不用 .env；部署用 wrangler secret，本地測試用 .dev.vars |
| 叫人去查自己 worker URL | AI 用 CF API 自動查 subdomain 拼出來 |
URL 確定性論證（為何 AI 必然查得到）
- URL =
https://arcrun-kbdb.<subdomain>.workers.devarcrun-kbdb：基本盤 worker name，固定。<subdomain>：用戶 CF 帳號的 workers.dev 子域，GET /accounts/{id}/workers/subdomain查得到。
- 能 deploy ⟹ 能查 URL：兩者用同一套 CF 憑證（wrangler 登入）。AI 要 deploy 插件就必然已能操作用戶 CF，故必然查得到 subdomain。不存在「能裝卻查不到」。
- 預設 workers.dev，不要求自訂域名 → 安裝時不問人。自訂域名是進階選項，另走 config。
安裝流程（scripts/install.sh）
輸入：github 網址（用戶提供）
前提：用戶已 wrangler login（自己的 CF 帳號）
1. git clone <插件網址>
2. wrangler whoami → account_id
3. GET /accounts/{account_id}/workers/subdomain → subdomain
4. BASE = https://arcrun-kbdb.<subdomain>.workers.dev
（或：若基本盤這次一起裝，直接取其 wrangler deploy 輸出的 URL）
5. wrangler secret put KBDB_BASE_URL ← 填 BASE（不寫進 git）
6. wrangler deploy → 插件上線
輸出：插件 workers.dev URL（AI 回報給用戶）
參考既有實作：arcrun docs/3-specs/arcrun/sdk-and-website/self-hosted-init.md（同套路：CF API 查 subdomain + 注入 config + workers_dev 對外）。
測試 base URL（兩層）
- 單元測試：
tests/mock-client.ts，不打網路，KBDB_BASE_URL 留空。日常主力。 - 整合測試：本地起基本盤
cd ../arcrun/kbdb && wrangler dev（如 localhost:8787），插件.dev.vars（gitignore）寫KBDB_BASE_URL=http://localhost:8787。
不變條件（守 KBDB 鐵律）
- 安裝過程不建表、不跑 migration（插件零 migration）。基本盤的表由 arcrun/kbdb 維護。
- 插件只透過
KBDB_BASE_URL的 HTTP API 與基本盤互動，安裝後亦然。