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
commit 922a57fe34
485 changed files with 89356 additions and 0 deletions
@@ -0,0 +1,162 @@
+# 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 一併納入。 |
@@ -0,0 +1,159 @@
+# Tasks — Component Registry Canon
+
+> 對應 SDD：[design.md](design.md)
+> 上次更新：2026-05-07
+
+**狀態 legend**：`[ ]` 待辦 / `[🔄]` 進行中 / `[x]` 完成
+
+---
+
+## Phase 0：前置（已完成）
+
+- [x] 0.1 u6u-mcp Zod 4 → Zod 3 降版修 tools/list `_zod undefined` bug（2026-05-07）
+- [x] 0.2 u6u-mcp service binding `inkstone-component-registry` → `arcrun-registry`（2026-05-07）
+- [x] 0.3 確認 `mcp.finally.click/mcp/mcp` 端對端通，tools/list 回 14 個 tool（2026-05-07）
+
+---
+
+## Phase 1：Backfill Index（半天，立即見效）
+
+- [x] 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 跟「已部署但未索引」零件用
+- [x] 1.1.1 加 `src/actions/indexOnlyComponent.ts`（metadata-only 寫 KV，冪等）
+- [x] 1.1.2 加 `src/routes/components.ts` 的 `POST /index-only` route
+- [x] 1.1.3 部署 + smoke test（contract 驗證 + 錯誤處理通過）
+- [x] 1.2 寫 `matrix/arcrun/registry/scripts/backfill-index.mjs`（zero-build node script，用 js-yaml）
+- [x] 1.3 dry-run 確認 30 個 component 全 parse 通
+- [x] 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（不擋索引）
+- [x] 1.5 驗證：MCP `u6u_search_components("kbdb")` 回 3 個零件（kbdb_ingest / kbdb_create_block / kbdb_patch_block）
+- [ ] 1.6 驗證：`acr parts list` CLI 端對端能列
+- [x] 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 上傳」一併廢止。
+
+- [x] 1.5.1 改 `submitComponent.ts`：移除 R2 寫入段落，保留 KV 寫入
+- [x] 1.5.2 移除 `wrangler.toml` 的 `[[r2_buckets]] WASM_BUCKET` binding
+- [x] 1.5.3 移除 `types.ts` Bindings 的 `WASM_BUCKET: R2Bucket`
+- [x] 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`）
+- [x] 1.5.6 部署 + smoke test：search 端對端通過（kbdb 找到 3 個零件）
+
+## Phase 2：部署即註冊（1-2 天）
+
+- [x] 2.1 選擇方案：CI step（github actions）— 在 wrangler deploy 之後 curl `/index-only`
+- [x] 2.2 寫 `registry/scripts/register-component.sh`（本地 + CI 共用 SSOT，python3 + pyyaml 解 YAML，curl POST registry）
+- [x] 2.3 改 `.github/workflows/deploy.yml` tier1 deploy step 後加 "Register component in registry" step（degraded mode：失敗只 warning）
+- [x] 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（會擋推廣）