Arcrun/.agents/specs/llm-interface/requirements.md

# Requirements: LI (LLM Interface) for arcrun

> 把 arcrun 平台對「AI 操盤手」的完整使用面，當成 first-class product 設計。
> 對比：以前做網站要 user-friendly（UI），現在 AI 是主要用戶（LI）。

---

## 背景

arcrun 是 n8n-like workflow 平台，平台本身的 end-user 有兩類：
- **人類**：透過 u6u-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 |
| **u6u-mcp** | 15 MCP tools（HTTP→MCP 薄包裝） | 主擴張面（gap-fill） |
| **u6u-gui** | 人類 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 對等

人類在 u6u-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 是新層，不破壞既有：
- u6u-mcp 既有 15 tool 全保留（廢棄走標準 deprecation）
- u6u-gui 不動
- cypher-executor 既有路由不改 contract

### 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：覆蓋率可量化

- 「人類在 u6u-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 聚合，不靠人讀原始 |
| u6u-mcp 重構搞壞既有 | 走 deprecation，舊 tool 留 90 天 |
| KBDB telemetry 量爆掉 | sample rate / 老資料自動 archive |

---

## 開放問題（待 leo 決策）

1. **deployment 名稱**：MCP server URL 用 `mcp.arcrun.dev` 還是沿用 `mcp.finally.click`？
   - 推薦：`mcp.arcrun.dev`（品牌一致，符合 mira CLAUDE.md §1.7）
2. **新 MCP vs 擴張 u6u-mcp**：在現有 u6u-mcp 加 tool，還是建 `arcrun-mcp` 取代？
   - 推薦：先擴張 u6u-mcp（避免 fork 痛），長期可改名
3. **AGENTS.md 放哪**：`arcrun/AGENTS.md` repo 根？還是 KBDB block？或兩個地方都？
   - 推薦：repo `arcrun/AGENTS.md` + KBDB 自動同步 block（讓沒 git access 的 AI 也能讀）
4. **feedback 寫入是否需 auth**：AI report bug 要不要 api_key？
   - 推薦：要（防 spam），但 tier 低（只要驗 ak_ 存在）