Leo/Arcrun
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
922a57fe3458dfda82bcc25d287cef93f8dab838
Arcrun/.agents/specs/component-registry-canon/design.md
T
uncle6me-web 922a57fe34 arcrun — AI workflow execution engine (clean history) 
Self-hosted 開源：WASM 零件 + recipe + cypher-executor，跑在你自己的 Cloudflare。

此為重建的乾淨歷史起點（移除曾誤 commit 的 GCP SA 金鑰，舊歷史保留在
richblack/arcrun 與本地 backup 分支）。含：
- acr init --self-hosted installer（建 KV/R2 + codeload 拉預編譯 wasm + wrangler deploy + seed recipe）
- recipe push 把關（資料外流提醒 + 打通檢查）
- 19 個正當零件預編譯 wasm（claude_api/km_writer/kbdb_upsert_block 排除：違反 DECISIONS §1）
- CLI / cypher-executor / registry / 完整 SDD

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-03 15:52:38 +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