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,246 @@
+# Requirements: LI (LLM Interface) for arcrun
+
+> 把 arcrun 平台對「AI 操盤手」的完整使用面，當成 first-class product 設計。
+> 對比：以前做網站要 user-friendly（UI），現在 AI 是主要用戶（LI）。
+
+---
+
+## 背景
+
+arcrun 是 n8n-like workflow 平台，平台本身的 end-user 有兩類：
+- **人類**：透過 arcrun-gui canvas / arcrun.dev landing 操作
+- **AI agent**：透過 MCP / API 操作（Claude Code、Cursor、Codex、自製 agent 等）
+
+過去設計集中在「人」（UI / docs）。AI 對 arcrun 的「可用性」沒被當第一公民。
+
+### 證據：3 天 mira dogfood 累積的 14 個痛點（baseline）
+
+| 編號 | 痛點 | 性質 |
+|---|---|---|
+| 1 | 新零件 deploy 要手動 dashboard 點 workers.dev | platform DX |
+| 2 | CF 同 zone self-fetch 死鎖 | platform infra |
+| 3 | `http_request` 4xx 回 success=true cascade | error semantics |
+| 4 | interpolateString array stringified | dev experience |
+| 5 | `kbdb_upsert_block` 沒在 `WASM_HTTP_RUNNER_IDS` 白名單 | discovery |
+| 6 | `resumeFromPaused` paused_node_id 沒 namespace | implicit behavior |
+| 7 | `acr validate` 不認「對每個 X」 | validator stale |
+| 8 | cron 從零寫起 | feature gap |
+| 9 | CF Pages 沒接 auto-deploy | infra setup |
+| 10 | watcher self-fetch 死鎖（剛解） | architecture |
+| 11 | skill 改要寫 python script | tooling gap |
+| 12 | 不知道有什麼零件可用 | **LI gap** |
+| 13 | 不知道現有 workflow 怎麼長 | **LI gap** |
+| 14 | trace / log 看不到結構化的 | **LI gap** |
+
+**14 個裡有 7 個（編號 3-7, 12-14）純粹是 LI 缺失**。如果 LI 完整，等於把 50% 的踩坑時間還給開發者。
+
+---
+
+## 目標用戶（personas）
+
+### P1：Claude Code / Cursor 等 IDE-embedded AI（主力）
+
+特徵：
+- 跟 leo 一起 pair programming
+- 有 file access、shell 能力
+- 透過 MCP / curl / SDK 跟 arcrun 對話
+
+需求：
+- 知道 arcrun 全貌（不靠人類解釋）
+- 知道目前用戶有什麼資產（workflow / component / template / credential）
+- 寫 YAML 不靠猜
+- 部署前能 dry-run
+- 部署後能看執行結果
+- 卡住能 introspect + ask
+
+### P2：用戶私人 agent（次要，未來）
+
+特徵：
+- 在 mira / 用戶 app 內跑
+- 透過 MCP 對 arcrun
+- 沒有檔案系統，只有 HTTP
+
+需求：基本同 P1，但**完全靠 MCP**（沒 grep / file read fallback）
+
+### P3：自製腳本 / SDK 使用者
+
+不在本 SDD 範圍。SDK 既有規格走 `.agents/specs/arcrun/sdk-and-website/`。
+
+---
+
+## 範圍（系統涵蓋）
+
+LI 不是「新建一個 service」，是**跨 5 個既有系統的橫向 layer**：
+
+| 系統 | 既有狀態 | LI 涵蓋的部分 |
+|---|---|---|
+| **arcrun cypher-executor** | 31 HTTP 路由 | 哪些對外、哪些 AI 該看得到 |
+| **arcrun registry** | component 管理 Worker | discovery layer |
+| **arcrun-mcp**（目前 `matrix/u6u-mcp/`，本 SDD M5 改名） | 15 MCP tools（HTTP→MCP 薄包裝） | 主擴張面（gap-fill） |
+| **arcrun-gui**（目前 `matrix/u6u-gui/`，本 SDD M5 改名） | 人類 canvas IDE | 取其 endpoint 觀念，不取其 UI 元素 |
+| **kbdb** | 50 個 HTTP 路由 | KBDB 該不該直接給 AI、用什麼姿勢 |
+| **arcrun CLI (acr)** | Node CLI | LI 不依賴 CLI（CLI 是人的工具） |
+
+---
+
+## 非範圍（這個 SDD 不處理）
+
+- 不處理 GUI 設計 / 視覺
+- 不處理 SDK（Python/JS）API 設計
+- 不處理 user OAuth flow
+- 不重新設計 KBDB schema（只決定 LI 該包什麼 API）
+- 不重新設計 cypher binding 語法
+
+---
+
+## 功能需求（FR）
+
+### FR-1：AI 一條指令就能上手 arcrun
+
+- 提供 `AGENTS.md`（onboarding doc），AI 載入就能用
+- MCP server URL 寫進 doc，「直接 connect」一步搞定
+- 不需讀 SDD / 不需 grep codebase / 不需問人
+
+### FR-2：完整 CRUD + Discovery 對等
+
+人類在 arcrun-gui 能做的 8 個動作（list_workflows / get / update / execute / search_components / get_component / list_templates / list_credentials），**MCP 至少同等覆蓋**，不能有「人類能做但 AI 不能做」的 gap。
+
+### FR-3：Dry-run 是預設行為
+
+- `validate_workflow(yaml)` MCP tool（取既有 `/validate` 路由）
+- `preview_workflow(yaml, input)` 不寫入 KV，模擬執行
+- AI 養成習慣「先 dry-run 再 push」
+
+### FR-4：可診斷的 trace
+
+- `get_execution_trace(execution_id)` 回結構化 JSON：每個 node 的 status / input / output / error / duration
+- `list_paused_executions()` 列卡住的執行（callback 沒回時 debug 用）
+- 不靠 `wrangler tail` 純文字
+
+### FR-5：錯誤訊息是「給 AI 看的下一步」
+
+所有 MCP tool error response 必須含：
+- `error_code`（穩定字串 enum，可程式化 catch）
+- `human_message`（描述）
+- `next_actions`（陣列，可選：「call X」/「執行 Y」/「修改 Z」）
+
+範例：
+```json
+{
+  "error_code": "component_not_in_whitelist",
+  "human_message": "零件 'filter' 不在用戶可用清單",
+  "next_actions": [
+    "call list_components() 看完整可用清單",
+    "若該零件需平台啟用，告訴用戶執行 `acr enable filter`",
+    "若是自製零件，先 push 零件再 push workflow"
+  ]
+}
+```
+
+### FR-6：AI 可以回報問題
+
+- `report_feedback(workflow_name, issue_type, description, ...)` MCP tool
+- 結構化 enum issue_type（防自由文字難聚合）
+- 寫進 KBDB 成 `agent-feedback` block，可被定期 review
+- AI 規範「順利 / 卡住 / 不確定 都該 call」（透過 AGENTS.md 強制）
+
+### FR-7：Implicit telemetry 不依賴 AI 自覺
+
+- cypher-executor 每次 deploy / execute / fail 自動寫 `agent-telemetry` block
+- 含 client_user_agent（哪個 AI 用的）、error_message、duration
+- 不依賴 AI 主動 call，平台自己收
+
+### FR-8：Skill blocks 可重用
+
+- 「pattern / playbook」存 KBDB type=`agent-skill`
+- MCP `list_skills(tag)` / `get_skill(id)` 給 AI 查
+- 範例：`build_watcher_workflow` / `debug_paused_workflow` / `migrate_http_to_trigger_workflow`
+
+### FR-9：範例庫可搜尋
+
+- `search_examples(use_case)` 給 use case → 回相似 workflow YAML
+- 範例存 `registry/examples/` git + 一份 index 在 KV
+- 進階：semantic search（既有 KBDB `/search/embed`）
+
+### FR-10：定期 review 機制（自動化）
+
+- `agent_feedback_weekly_review` workflow（**arcrun 自己跑**）
+- 每週一聚合 feedback + telemetry，產出 Top N 痛點 + 建議
+- 寫進 `arcrun-roadmap` KBDB block
+
+---
+
+## 非功能需求（NFR）
+
+### NFR-1：向下相容
+
+LI 在「擴張」階段（M1-M4）不破壞既有：
+- M1-M4 階段：arcrun-mcp 既有 15 tool 保留，新增 13 個 tool（pre-rename）
+- arcrun-gui 不動
+- cypher-executor 既有路由不改 contract（只加新 endpoint）
+
+M5（rename）階段是 breaking change（leo 拍板），需事前公告。
+
+### NFR-2：transport 不鎖死
+
+MCP 主，但 HTTP 同等可用（讓沒 MCP 客戶端的 agent 也可用）。每個 MCP tool 都對應一個 HTTP endpoint。
+
+### NFR-3：error contract 穩定
+
+`error_code` enum 是 public API，加新值是 minor，移除值是 major。版本化。
+
+### NFR-4：feedback 數據可外部 export
+
+`agent-feedback` / `agent-telemetry` 走 KBDB `/blocks` 標準 API，任何 AI / 人都能拉。不鎖死在 dashboard。
+
+### NFR-5：覆蓋率可量化
+
+- 「人類在 arcrun-gui 能做但 MCP 不能做」清單必須能列出
+- 每次 LI 改動後，這份清單往 0 收斂
+
+---
+
+## 成功指標
+
+| 指標 | 量測 | 目標 |
+|---|---|---|
+| 新 AI agent 上手時間（從 zero 到第一個 workflow 部署） | 手動實驗 | < 10 min |
+| 一次 workflow 部署需要的 MCP call 次數 | telemetry | < 5 calls |
+| AI 回報「文件不清楚」週次數 | feedback aggregation | 持續下降 |
+| 「MCP 缺工具」issue 類型佔比 | feedback type ratio | < 10% |
+| Implicit telemetry 與 explicit feedback 比例 | 計數 | 9:1 不算問題（implicit 量大正常） |
+| Coverage gap（人類能做 vs AI 能做） | 手動審查 | 0 |
+
+---
+
+## 風險與假設
+
+### 假設
+- MCP 是主要 AI 接觸點（不是 SDK / CLI）
+- AI 願意按 AGENTS.md 規範 call feedback tool
+- KBDB 能承載 telemetry 量級（短期：< 1000 events / day）
+
+### 風險
+
+| 風險 | 應對 |
+|---|---|
+| AI 不照 AGENTS.md 規範用 | implicit telemetry 不依賴自覺，仍能收 data |
+| MCP tool 設計錯誤越改越亂 | 每個 tool 有 contract test，error_code enum 版本化 |
+| feedback 雜訊太多無法 review | review workflow 用 LLM 聚合，不靠人讀原始 |
+| arcrun-mcp 重構搞壞既有用戶 | 用戶量還很少（dogfood 階段），一次切換可接受；切換前公告 |
+| KBDB telemetry 量爆掉 | sample rate / 老資料自動 archive |
+
+---
+
+## 決策（2026-05-16 leo 拍板）
+
+1. **deployment 名稱**：✅ `mcp.arcrun.dev` 單一 URL
+   - `mcp.finally.click` 直接退場，不並存
+   - 理由（leo）：「finally.click 是還沒申請新網址的暫用，那是一個服務，arcrun 是底層」
+2. **u6u branding 整體退場**：✅ u6u 命名全部改 arcrun
+   - `u6u-mcp` repo → `arcrun-mcp`
+   - `u6u-gui` repo → `arcrun-gui`
+   - 工具命名 `u6u_*` → `arcrun_*`（**單一 rename，不留 alias 也不留 deprecation 期**）
+   - 理由：「u6u 不存在，改成 Arcrun」
+3. **AGENTS.md 位置**：✅ repo `arcrun/AGENTS.md` + 自動同步 KBDB block（兩面都拿到）
+4. **feedback 寫入需 auth**：✅ 驗 ak_ 存在即可（防 spam，tier 低不查餘額）