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/tasks.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

8.6 KiB
Raw Blame History

Tasks — Component Registry Canon

對應 SDD：design.md 上次更新：2026-05-07

狀態 legend：[ ] 待辦 / [🔄] 進行中 / [x] 完成

Phase 0：前置（已完成）

  • 0.1 u6u-mcp Zod 4 → Zod 3 降版修 tools/list _zod undefined bug（2026-05-07）
  • 0.2 u6u-mcp service binding inkstone-component-registry → arcrun-registry（2026-05-07）
  • 0.3 確認 mcp.finally.click/mcp/mcp 端對端通，tools/list 回 14 個 tool（2026-05-07）

Phase 1：Backfill Index（半天，立即見效）

  • 1.1 探查 registry 既有 endpoint：發現
    • 既有 POST /components 強制要 wasm bytes（multipart 或 base64），跑沙盒驗收 + 寫 R2 + 寫 KV
    • cypher-executor 已不從 R2 動態載 wasm（line 32 標 R2 路徑作廢，零件用獨立 Worker URL）
    • 結論：R2 是 legacy，registry 真正用途是 metadata 索引給 AI 搜尋
    • 決策：加新 endpoint POST /components/index-only 接 contract（無 wasm、無沙盒），專供 backfill 跟「已部署但未索引」零件用
  • 1.1.1 加 src/actions/indexOnlyComponent.ts（metadata-only 寫 KV，冪等）
  • 1.1.2 加 src/routes/components.ts 的 POST /index-only route
  • 1.1.3 部署 + smoke test（contract 驗證 + 錯誤處理通過）
  • 1.2 寫 matrix/arcrun/registry/scripts/backfill-index.mjs（zero-build node script，用 js-yaml）
  • 1.3 dry-run 確認 30 個 component 全 parse 通
  • 1.4 跑真 backfill（過程中發現並修了兩個 schema 問題）：
    • schema enum category 補 auth / ai / platform（types.ts）
    • max_cold_start_ms 上限放寬 50 → 500（auth/ai 含 crypto 需要）
    • no_network_syscall / no_filesystem_syscall 改 optional
    • max_size_kb 上限放寬 2048 → 8192
    • index-only route 對缺 gherkin/description/tags 的零件補 placeholder（不擋索引）
  • 1.5 驗證：MCP u6u_search_components("kbdb") 回 3 個零件（kbdb_ingest / kbdb_create_block / kbdb_patch_block）
  • 1.6 驗證：acr parts list CLI 端對端能列
  • 1.7 驗證：registry KV 30 entries（30 created + 30 idx 共 60 keys）

Phase 1.5：砍 R2 dead storage（先於 Phase 2，清架構斷層）

2026-05-07 加入。R2 wasm 路徑早已 dead（cypher-executor 不從 R2 讀），保留只會誤導 AI。 SDD design.md 的「Phase 5 用戶自製零件 R2 上傳」一併廢止。

  • 1.5.1 改 submitComponent.ts：移除 R2 寫入段落，保留 KV 寫入
  • 1.5.2 移除 wrangler.toml 的 [[r2_buckets]] WASM_BUCKET binding
  • 1.5.3 移除 types.ts Bindings 的 WASM_BUCKET: R2Bucket
  • 1.5.4 既有 wasm_r2_key 欄位保留為 deprecated（queryComponents 仍會讀 legacy record）
  • 1.5.5 廢止 arcrun-wasm R2 bucket（30 天觀察期後 → 2026-06-07 之後 wrangler r2 bucket delete）
  • 1.5.6 部署 + smoke test：search 端對端通過（kbdb 找到 3 個零件）

Phase 2：部署即註冊（1-2 天）

  • 2.1 選擇方案：CI step（github actions）— 在 wrangler deploy 之後 curl /index-only
  • 2.2 寫 registry/scripts/register-component.sh（本地 + CI 共用 SSOT，python3 + pyyaml 解 YAML，curl POST registry）
  • 2.3 改 .github/workflows/deploy.yml tier1 deploy step 後加 "Register component in registry" step（degraded mode：失敗只 warning）
  • 2.4 本地驗 bash scripts/register-component.sh kbdb_ingest → 200 + already_indexed
  • 2.5 真正 push 一個新零件驗 CI hook 端對端（需要等下次新增零件時驗）
  • 2.6 文件化：docs/contributing-components.md「新增零件的標準流程」
  • 2.7 廢止 u6u_publish_component tool 的「需手動 publish」假設（rebrand 一起做）

Phase 3：Discoverability（半天）

  • 3.1 改 GitHub richblack/arcrun README
    • 移除「21 個零件」這種寫死數字
    • 加「跑 acr parts list 或 MCP search 看當前清單」
    • 加 badge：![components](https://registry.arcrun.dev/badge/components.svg)
  • 3.2 加 matrix/arcrun/registry/src/routes/badge.ts
    • GET /badge/components.svg 回 shields.io 格式 SVG
    • count 從 KV 即時 query
    • cache 1 分鐘（Cache-Control: max-age=60）
  • 3.3 改 MCP u6u_get_component_guide tool（之後改名 arcrun_*）
    • 開頭加「鐵律：動工前必須先 search_components，找不到才 publish」
  • 3.4 onboarding kit GitHub template repo（建議名 arcrun-quickstart）
    • 三件套：CLAUDE.md / .cursor/rules/arcrun.mdc / AGENTS.md
    • 強制：「呼叫 Claude/任何 AI 前，先 list MCP tools；arcrun MCP 已連線時，禁止用 Python 直打 HTTP API」
    • 內附範例 hello workflow 跟 component
  • 3.5 寫 onboarding doc：docs/onboarding-third-party-engineer.md
    • 第三方工程師如何 30 秒內讓 AI 學會用 arcrun

Phase 4：u6u → arcrun Rebrand（1 天，最後做）

規劃做完 Phase 1-3 驗證 OK 才動 rebrand，避免邊改邊驗。

4.1 Repo & Worker

  • 4.1.1 git mv matrix/u6u-mcp matrix/arcrun-mcp（或 cp + rm，視 git history 偏好）
  • 4.1.2 改 matrix/arcrun-mcp/wrangler.toml：
    • name = "u6u-mcp" → name = "arcrun-mcp"
    • 加 route mcp.arcrun.dev/*，舊 studio.finally.click/mcp* 保留 1 個月
  • 4.1.3 改 package.json：@inkstone/u6u-mcp-worker → @arcrun/mcp-worker

4.2 Tool 前綴改名

  • 4.2.1 14 個 tool 檔案 rename：u6u_*.ts → arcrun_*.ts
  • 4.2.2 每個 tool 內部 server.tool("u6u_xxx", ...) 改 server.tool("arcrun_xxx", ...)
  • 4.2.3 src/tools/registry.ts import 路徑全改
  • 4.2.4 src/index.ts serverInfo.name 從 u6u-mcp-server 改 arcrun-mcp-server

4.3 文件

  • 4.3.1 README.md 全文 u6u → arcrun
  • 4.3.2 GUIDE.md 同上
  • 4.3.3 GitHub richblack/arcrun README 補 MCP 段落（之前沒提）
  • 4.3.4 任何提到 u6u-mcp / mcp.finally.click 的 docs 更新

4.4 用戶記憶

  • 4.4.1 ~/.claude/projects/.../memory/MEMORY.md 加 arcrun MCP entry
    • URL: https://mcp.arcrun.dev/mcp/mcp
    • tool 前綴: arcrun_*
    • finally.click 過渡期到何時
  • 4.4.2 polaris/mira/CLAUDE.md 提到 daemon / arcrun / MCP 的部分對齊新命名

4.5 過渡期（舊 endpoint 不立刻砍）

  • 4.5.1 舊 mcp.finally.click/mcp/mcp 加回應 header Deprecation: true + Link: <https://mcp.arcrun.dev/mcp/mcp>; rel="successor-version"
  • 4.5.2 舊 worker 繼續服務 30 天（2026-06-07 為止）
  • 4.5.3 廢止排程：2026-06-07 後舊 worker 改回 410 Gone + 提示換新 URL

4.6 驗證

  • 4.6.1 mcp.arcrun.dev/mcp/mcp initialize + tools/list + 一個 tool call 全通
  • 4.6.2 我的 Claude Code config 切到新 URL，用 mcp__arcrun__search_components 端對端測
  • 4.6.3 grep u6u 在 matrix/arcrun-mcp/ 結果為 0（除了 changelog 紀錄）

風險追蹤

  • 風險 1：backfill 跑進去發現某些 contract.yaml 格式跟 registry 期望不一樣 → 緩解：dry-run 先看，必要時補 contract 欄位
  • 風險 2：Phase 4 rebrand 期間用戶 client 設定亂 → 緩解：過渡期 + Deprecation header
  • 風險 3：自動註冊 hook 失敗導致部署被擋 → 緩解：degraded mode（warning 不 fail）

Known Issues（吃狗糧發現的，先記錄）

KI-1：u6u-mcp README URL 寫錯

  • README 寫 mcp.finally.click/mcp，實際是 mcp.finally.click/mcp/mcp（basePath + route）
  • 影響：用戶照 README 裝完試打不通
  • 解法：rebrand 時順便修

KI-2：inkstone-component-registry 跟 arcrun-registry 並存

  • 兩個 worker 都活著，u6u-mcp 之前指錯
  • inkstone-component-registry 是舊版（2026-03-24）、arcrun-registry 是現役（2026-04-16）
  • 解法：Phase 1 backfill 完成後，inkstone-component-registry worker 廢止

KI-3：search 對自然語言不夠靈敏（吃狗糧第一個發現）

  • 現象：
    • search("從 KBDB 讀取或查詢 block") → 0 結果
    • search("kbdb") → 3 結果（kbdb_ingest / kbdb_patch_block / kbdb_create_block）
  • 根因：搜尋走 embedding（bge-m3）相似度，但既有零件清單少（30 個）+ description 寫得正式，自然語言整句的 embedding 跟 description 距離太遠
  • 影響：致命 — AI 第一句永遠是自然語言整句，回 0 就會放棄 search 改寫 Python
  • 解法（Phase 3 處理）：
    1. embedding search 之外加 keyword fallback（split query → 對 canonical_id / display_name / tags 做 ILIKE）
    2. 或 lower threshold（目前 SCORE_THRESHOLD = 0.5，可能過高）
    3. MCP get_component_guide 教 AI 「找不到時拆關鍵字再 search」
  • 優先級：P1（會擋推廣）
Reference in New Issue View Git Blame Copy Permalink