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」）

範例：

{
  "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_ 存在）