Leo/Arcrun
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
268cca9865327a36c3dacd09f9155b3cf98426ec
Arcrun/.agents/specs/component-registry-canon/design.md
T
Leo 497f92a268 feat(arcrun): recipe system + resumable workflow + component registry canon 
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>
2026-05-07 15:52:19 +08:00

6.7 KiB
Raw Blame History

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 一併納入。
Reference in New Issue View Git Blame Copy Permalink