Leo
5d99302681
leo 2026-05-16 拍板（除 dual-hostname 外照原設計）： 1. MCP URL: 單一 mcp.arcrun.dev，mcp.finally.click 直接退場（不並存） - 理由：finally.click 是還沒申請新網址的暫用，那是一個服務，arcrun 是底層 2. u6u branding 整體退場： - u6u-mcp repo → arcrun-mcp - u6u-gui repo → arcrun-gui - u6u_* tool prefix → arcrun_* - 一次切換，不留 alias，不留 deprecation 期 - 理由：u6u 不存在了 SDD 三件套同步更新： - requirements.md: 開放問題章節改決策紀錄；移除「保留 15 tool deprecation」自相矛盾 - design.md: §1.1 命名 + §6 migration plan + §8 決策表全部改成「單一切換」 - tasks.md: M5 重組成 6 個 sub-step（準備 / repo rename / tool rename / 舊 URL 退場 / 文件 / 連動 SDD 追蹤） 連動但不在本 SDD 範圍： - matrix/arcrun/.agents/specs/u6u-core-mvp/ 改名 - matrix/arcrun/.agents/specs/u6u-platform-evolution/ 改名 （M5.6 列出，另起 task 追蹤） Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
247 lines
9.3 KiB
Markdown
247 lines
9.3 KiB
Markdown
# 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 低不查餘額）
|