Files

T

Leo d2618758e2 docs(sdd): SDD 生命週期鐵律遷移 + SDD 位置統一到 system-dev/docs/3-specs/

- 位置統一：舊 docs/3-specs/ 五份 SDD git mv 到 system-dev/docs/3-specs/，舊位置留 README 指針
- 狀態判定：0 份 active（無現行開發，合法）；paused×3（ingest-contract/kbdb-graph-extraction/plugin-install，等跨 repo 接通）；closed×2 入 archive/（arcrun-key-auth/blocks-edit-api 死件，附封存原因）
- 鋪檔（自 system-dev-template v1.15.0）：SDD-LIFECYCLE.md、pending-changes.md、sdd-guard.sh 新版、sdd-check.md、sdd-active-check.sh
- hook 掛載：settings.json PreToolUse Write|Edit 加 sdd-guard.sh
- CLAUDE.md：SDD 鐵律段（濃縮五條＋0-active 註明重啟先升 active）＋修正遷移後舊路徑
- 驗證：sdd-active-check exit 0；guard pipe-test 0-active 擋 code 寫入(exit 2)/md 放行(exit 0)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-17 17:04:12 +08:00

2.6 KiB

Raw Blame History

status, superseded_by

status	superseded_by
paused

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.dev
- arcrun-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 與基本盤互動，安裝後亦然。

2.6 KiB Raw Blame History Unescape Escape