Leo
497f92a268
Three new platform capabilities + one component (kbdb_get) to enable
real AI workflow execution through cypher binding YAML.
## Recipe System (容器 + Recipe 模式)
SDD: .agents/specs/recipe-system/
- prompt_recipe schema (Zod): fragments + inputs + assembly + output
- recipe-expander.ts: expand recipe ref → real prompt by fetching KBDB blocks
+ pulling context fields with transforms (pluck_content / extract_field / etc)
- 7 transform whitelist: json_array / to_string / join / markdown_list /
extract_field / first / pluck_content
- graph-executor hooks: detect node.data.recipe → expand → inject into ctx
- output JSON parser (with markdown fence stripping for Claude-wrapped JSON)
- Stored in RECIPES KV under prompt_recipe:{name}
## Resumable Workflow (webhook callback resume)
SDD: .agents/specs/resumable-workflow/
- WorkflowPaused class + paused-runs.ts (persist/load/consume in EXEC_CONTEXT KV, 24h TTL)
- graph-executor: detect {pending:true, task_id} → persist state → throw WorkflowPaused
- cypher-handlers: catch → return {success:true, paused:true, task_id, run_id}
- POST /workflows/resume route: consume KV state → resumeFromPaused()
- Auto-inject callback_url for claude_api nodes (PUBLIC_BASE_URL or default cypher.arcrun.dev)
- claude_api/main.go: forward callback_url to Mira daemon, default timeout 25s→120s
- Idempotent (consume = load+delete)
## Component Registry Canon
SDD: .agents/specs/component-registry-canon/
- Add POST /components/index-only endpoint (metadata-only, no wasm/sandbox)
- Backfill script (mjs): scan registry/components/*/contract.yaml → submit to KV
- register-component.sh: SSOT for local + CI hook (deploy.yml change in next commit)
- Drop R2 dead storage from submitComponent + types + wrangler
- Schema relaxed: category enum + auth/ai/platform; cold_start 50→500ms; size 2→8MB
## kbdb_get component
- registry/components/kbdb_get/: TinyGo WASM, two modes (block_id / page_name list)
- .component-builds/kbdb_get/: WASI shim worker (kbdb-get.arcrun.dev)
End-to-end validation: AI uses MCP execute_workflow with recipe ref →
cypher-executor expands prompt from KBDB schema/skill blocks + drafts →
claude_api calls Mira daemon → daemon callback fires resume route →
workflow continues. Verified with real 2KB+ Karpathy LLM Wiki draft.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
163 lines
6.7 KiB
Markdown
163 lines
6.7 KiB
Markdown
# SDD: arcrun Component Registry 正典化（Component Registry Canon）
|
||
|
||
> 2026-05-07 建立。狗糧發現的根本問題：registry 活著但 index 空的，AI 找不到零件就會繞回 Python。
|
||
> 範圍：**讓 registry 成為零件 metadata 的 SSOT**，含 u6u → arcrun rebrand。
|
||
|
||
---
|
||
|
||
## 1. 問題
|
||
|
||
### 1.1 表象
|
||
- `registry.arcrun.dev/components/search?q=*` 永遠回 0 結果
|
||
- MCP `u6u_search_components` 找不到任何零件
|
||
- `acr parts list` 同樣空
|
||
|
||
### 1.2 根因
|
||
`matrix/arcrun/registry/components/` 下 30+ 個零件已經部署成獨立 Worker（kbdb_ingest, claude_api, kbdb_create_block, kbdb_patch_block, http_request, string_ops, ⋯），但**它們的 contract.yaml 沒有透過 `POST /components/submit` 進 registry index**。
|
||
|
||
部署路徑：
|
||
```
|
||
registry/components/{name}/main.go ← TinyGo 寫的零件
|
||
↓ tinygo build
|
||
.component-builds/{name}/component.wasm
|
||
↓ wrangler deploy
|
||
{name}.arcrun.dev (Worker) ← 零件可被 HTTP 呼叫了
|
||
|
||
registry index? ← 這步從來沒做
|
||
```
|
||
|
||
### 1.3 影響（吃狗糧的觀察）
|
||
- 新 AI（Claude / Gemini / Codex）進來不知道有什麼零件 → 自己寫 Python 直打 API
|
||
- arcrun 想推「AI-first 自服務」整個破功
|
||
- 文件寫得再好都救不了 — 因為 README 只能寫概念，零件清單必須是 API 動態查
|
||
|
||
---
|
||
|
||
## 2. 目標
|
||
|
||
**Registry 是零件 metadata 的 SSOT**：
|
||
|
||
- 零件 Worker 在跑 ⇔ registry 有對應 entry（雙向綁定）
|
||
- AI 透過 MCP `search_components` 永遠找得到所有現役零件
|
||
- README 不寫死數量，動態 badge 即時反映
|
||
- 第三方裝完 MCP 30 秒內能找到第一個可用零件
|
||
|
||
---
|
||
|
||
## 3. 三層設計
|
||
|
||
### Layer 1: 一次性 backfill（Phase 1）
|
||
|
||
掃 `matrix/arcrun/registry/components/*/component.contract.yaml`，把每個 contract POST 進 registry index。
|
||
|
||
工具：`matrix/arcrun/registry/scripts/backfill-index.ts`
|
||
- 讀檔 → 解析 YAML → 呼叫 registry submit endpoint
|
||
- idempotent：已存在不重複寫（registry 端要支援 upsert）
|
||
- 跳過沙盒驗收（這些零件已驗過、已部署，不用重跑 gherkin tests）
|
||
|
||
### Layer 2: 部署即註冊（Phase 2）
|
||
|
||
改 `.github/workflows/deploy.yml`：
|
||
- 通用掃描掃到 `.component-builds/{name}/wrangler.toml` 部署成功後
|
||
- post-deploy step 自動呼叫 registry submit（contract 從 `registry/components/{name}/component.contract.yaml` 讀）
|
||
|
||
零件 Worker 部署 ⇒ registry 自動更新。沒有「零件部署了但 registry 不知道」的可能。
|
||
|
||
### Layer 3: Discoverability（Phase 3）
|
||
|
||
- README 移除「21 個零件」這種寫死數字，改「跑 search 看當前清單」
|
||
- 加 badge endpoint `registry.arcrun.dev/badge/components.svg` 即時顯示數量
|
||
- MCP `get_component_guide` 開頭加鐵律：「動工前必須先 search，不是猜」
|
||
- onboarding kit GitHub template：CLAUDE.md / .cursor/rules / AGENTS.md 三件套，all 強制 search 優先
|
||
|
||
### Layer 4: u6u → arcrun Rebrand（Phase 4）
|
||
|
||
把 `matrix/u6u-mcp/` 跟所有 `u6u_*` tool 名搬到 arcrun 命名空間。
|
||
|
||
理由：
|
||
- u6u 是申請 arcrun.dev 之前的暫名，現在已過時
|
||
- 命名混亂阻礙推廣（「為什麼 arcrun 文件叫 u6u_*?」）
|
||
- 第三方看到 u6u 不知道是同一個產品
|
||
|
||
範圍：
|
||
1. 目錄：`matrix/u6u-mcp/` → `matrix/arcrun-mcp/`
|
||
2. Worker name：`u6u-mcp` → `arcrun-mcp`
|
||
3. Tool 前綴：`u6u_search_components` → `arcrun_search_components`（14 個 tool）
|
||
4. Hostname：`mcp.finally.click` → `mcp.arcrun.dev`（finally.click 保留 redirect 到 arcrun.dev 過渡期）
|
||
5. Repo / Worker 內部 ID：u6u-mcp-server → arcrun-mcp-server
|
||
6. README 全文：u6u → arcrun
|
||
7. user memory（CLAUDE.md / MEMORY.md）相關提及一併更新
|
||
8. inkstone-component-registry（舊 worker）廢止 → arcrun-registry 為唯一現役
|
||
|
||
**Rebrand 原則：**
|
||
- 用戶端 config（claude_desktop_config.json 等）給過渡期：兩個 URL 都活，舊的回 deprecation header 提示換新
|
||
- Tool 前綴 `u6u_*` → `arcrun_*` 沒有過渡期（一刀切，因為前綴是 AI 看的，不是用戶記憶肌肉）
|
||
- 文件 / repo 內所有 reference 立即改
|
||
|
||
---
|
||
|
||
## 4. 範圍邊界
|
||
|
||
**在本 SDD 範圍內：**
|
||
- ✅ Phase 1: backfill index
|
||
- ✅ Phase 2: 部署即註冊 hook
|
||
- ✅ Phase 3: README + badge + onboarding kit
|
||
- ✅ Phase 4: u6u → arcrun rebrand（含目錄 / worker / hostname / tool 前綴 / 文件）
|
||
|
||
**不在範圍內：**
|
||
- 新零件開發（這是 polaris 業務範圍）
|
||
- registry KV schema 改動（用既有結構）
|
||
- u6u-gui 的 rebrand（u6u-mcp 同 monorepo 但獨立 SDD）
|
||
- Phase 5（用戶自製零件 R2 上傳）— 等 Phase 4 完成後另開 SDD
|
||
|
||
**前置依賴（已完成）：**
|
||
- ✅ u6u-mcp Zod 4 → Zod 3 修復（2026-05-07）
|
||
- ✅ u6u-mcp service binding 改指 arcrun-registry（2026-05-07）
|
||
- ✅ arcrun-registry Worker 部署在 registry.arcrun.dev
|
||
|
||
---
|
||
|
||
## 5. 驗收標準
|
||
|
||
### Phase 1 驗收
|
||
- `u6u_search_components("kbdb")` 回非空結果，含 `kbdb_ingest` / `kbdb_create_block` / `kbdb_patch_block`
|
||
- `acr parts list` CLI 端對端能列出
|
||
- registry KV 內至少 30 entries
|
||
|
||
### Phase 2 驗收
|
||
- 部署任一既有零件後，registry 30 秒內 reflect 更新
|
||
- 部署一個全新零件，無需手動 publish，registry 自動有
|
||
- CI workflow 不會因 registry 寫入失敗就擋部署（degraded mode：寫入失敗 log warning 但不 fail）
|
||
|
||
### Phase 3 驗收
|
||
- README 沒有「21 個零件」「30 個零件」這種寫死數字
|
||
- badge SVG 渲染正確、數字跟 KV 一致
|
||
- onboarding kit clone 下來，照 README 跑能 30 秒內 list 到零件
|
||
|
||
### Phase 4 驗收
|
||
- `mcp.arcrun.dev/mcp/mcp` 通，回的 tool 名都是 `arcrun_*`
|
||
- 舊 `mcp.finally.click/mcp/mcp` 仍可用但回 deprecation header
|
||
- README / docs / GUIDE 全部 u6u 字樣消除
|
||
- `matrix/u6u-mcp/` 目錄不存在，改為 `matrix/arcrun-mcp/`
|
||
- 用戶記憶（`~/.claude/.../MEMORY.md`）arcrun MCP 設定範例已更新
|
||
|
||
---
|
||
|
||
## 6. 風險與緩解
|
||
|
||
| 風險 | 緩解 |
|
||
|---|---|
|
||
| backfill 把 contract 灌進去後，沙盒驗收覆蓋既有資料 | registry submit 加 `skip_acceptance=true` flag，僅 backfill 用 |
|
||
| 部署 hook 寫入失敗擋掉部署 | hook degraded mode：失敗只 warning，不 fail 部署 |
|
||
| Rebrand 把現役 client 弄壞 | 過渡期：舊 hostname 跟 worker 並存 1 個月 |
|
||
| Tool 前綴改名 AI 適應期 | 不過渡，一刀切（前綴是 system instruction 範圍，AI 一個 prompt 就學會）|
|
||
| 既有用戶 config 寫死 finally.click | 提前公告 + 過渡期 + 舊 endpoint 自動 redirect / proxy |
|
||
|
||
---
|
||
|
||
## 7. 變更紀錄
|
||
|
||
| 版本 | 日期 | 內容 |
|
||
|---|---|---|
|
||
| v1.0 | 2026-05-07 | 初版。吃狗糧發現 registry 空的，三層設計（backfill / auto-register / discoverability）+ u6u → arcrun rebrand 一併納入。 |
|