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

Design: LI (LLM Interface) for arcrun

v0.1 — 2026-05-16 對應 requirements.md（同目錄）

---

1. 設計哲學

過去 (UI 時代)	現在 (LI 時代)
使用者是人，要學軟體	使用者是 AI，要被軟體 onboard
操作靠視覺、滑鼠	操作靠 MCP tool call
錯誤訊息是技術 stack trace	錯誤訊息是「下一步該做什麼」
文件是 long-form 教學	文件是結構化 schema + 可程式查
用戶教學是 onboarding 課程	「教學」是 MCP 工具自己會回 hint
回饋靠 helpdesk 工單	回饋是 MCP tool（AI 直接 call）

原則：

1. discoverable — AI 不靠 grep / 不靠人就能知道有什麼
2. idempotent — 同樣輸入兩次結果一樣，可預測
3. dry-run by default — preview 是預設、commit 是 explicit
4. structured errors — error 是 JSON 含 next_actions，不是字串
5. closed loop — AI 卡住的 data 自動回流，平台 self-improving

---

2. 系統架構

┌────────────────────────────────────────────────────────────────┐
│                        AI agent (Claude / Cursor / ...)         │
└──────────────────┬──────────────────────────────┬───────────────┘
                   │                              │
                   │ ① Read AGENTS.md             │ ② MCP tool calls
                   ▼                              ▼
┌────────────────────────┐   ┌──────────────────────────────────┐
│   AGENTS.md            │   │   arcrun-mcp (擴張 u6u-mcp)        │
│   (repo + KBDB block)  │   │   25 tools, 5 categories          │
└────────────────────────┘   └──────────────┬───────────────────┘
                                            │
                ┌────────┬─────────┬────────┴────────┬──────────┐
                ▼        ▼         ▼                 ▼          ▼
        ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐
        │ cypher- │ │registry │ │  kbdb   │ │ Skills  │ │ Examples │
        │executor │ │         │ │         │ │ (KBDB)  │ │ (git+KV) │
        │ 31 路由 │ │         │ │ 50 路由 │ │         │ │          │
        └─────────┘ └─────────┘ └─────────┘ └─────────┘ └──────────┘
                                  ▲
                                  │ ③ AI 部署完 / 卡住 call feedback
                                  │
                    ┌─────────────┴──────────────┐
                    │ report_feedback / agent-telemetry │
                    │ (寫進 KBDB)                       │
                    └─────────────┬──────────────┘
                                  │ ④ 每週聚合
                                  ▼
                    ┌──────────────────────────────┐
                    │ agent_feedback_weekly_review │
                    │ (arcrun workflow, dogfood)   │
                    │ → arcrun-roadmap KBDB block  │
                    └──────────────────────────────┘

---

3. 五層 LI 模型

Layer 0：Onboarding（AGENTS.md）

位置：

• arcrun/AGENTS.md（repo 根，git 可讀）
• KBDB type=agent-onboarding block（MCP get_onboarding_doc() 拉）

結構（控 5-8K tokens）：

1. 30 字 What — 「arcrun 是用 YAML 把零件串成 workflow 的平台」
2. 5 個核心概念 — component / cypher binding YAML / FOREACH / paused-resume / api_key
3. 連線：「在你的 MCP config 加 https://mcp.arcrun.dev/mcp，bearer ak_xxx」
4. 第一個 workflow（minimal example） — 10 行 YAML，含部署 + 觸發
5. 5 個 URL 慣例與為什麼（workers.dev vs arcrun.dev / KBDB endpoints）
6. 常見錯誤 5 個 + 怎麼讀
7. 不確定的時候：明確列「先 call list_X 再下手」
8. 回報機制：完成任何 workflow deploy / 卡住，必須 call report_feedback

部署機制：

• repo arcrun/AGENTS.md 是 source of truth
• GH Actions 監聽該檔變動 → 自動 PATCH KBDB onboarding block
• MCP get_onboarding_doc() 從 KBDB 讀（最新）

---

Layer 1：arcrun-mcp（主戰場）

1.1 命名與部署

• Server URL: https://mcp.arcrun.dev/mcp（新增 route，對應 mcp.finally.click 既有 worker）
• 過渡：u6u-mcp Worker rename arcrun-mcp，雙路由（finally.click + arcrun.dev）並存 90 天
• Tool prefix: 統一 arcrun_*（既有 u6u_* 加 alias 對應，舊名 deprecation 公告）

1.2 Tool 完整清單（25 個，5 類）

A. Onboarding & Discovery（5 tools）

Tool	對應 HTTP	用途
arcrun_get_onboarding	KBDB GET /blocks?type=agent-onboarding	拉 AGENTS.md 內容
arcrun_list_components	registry GET /components	所有可用零件 + 1 行 desc
arcrun_get_component_contract	registry GET /components/:id	input/output schema + gherkin tests
arcrun_list_recipes	cypher GET /recipes + /auth-recipes	API recipe 一覽
arcrun_search_examples	KBDB POST /search（type=workflow-example）	用 use case 搜範例

B. Workflow CRUD（7 tools）

Tool	對應 HTTP	用途
arcrun_list_workflows	cypher GET /webhooks/named	用戶現有 workflow
arcrun_get_workflow	cypher GET /webhooks/named/:name	拿 YAML / graph
arcrun_validate_yaml	cypher POST /validate	dry-run 校驗，不部署
arcrun_push_workflow	cypher POST /webhooks/named	部署（也含 validate）
arcrun_delete_workflow	cypher DELETE /webhooks/named/:name	刪
arcrun_preview_workflow	新增 POST /preview	不寫 KV、模擬 execute
arcrun_diff_workflow	新增 POST /webhooks/named/:name/diff	既有 vs 新 YAML 差異

C. Execution & Trace（5 tools）

Tool	對應 HTTP	用途
arcrun_run_workflow	cypher POST /webhooks/named/:name/trigger	觸發 + 回 execution_id
arcrun_get_execution_trace	新增 GET /executions/:id	結構化 trace（per-node status）
arcrun_list_recent_executions	新增 GET /workflows/:name/executions?limit=10	最近 N 次
arcrun_list_paused_executions	新增 GET /executions/paused	卡 callback 的
arcrun_resume_execution	cypher POST /workflows/resume	手動 resume

D. Component & Recipe Management（4 tools）

Tool	對應 HTTP	用途
arcrun_search_components	registry POST search	語意搜尋
arcrun_publish_component	registry POST publish	上 WASM
arcrun_create_recipe	cypher POST /recipes	建 API recipe
arcrun_create_auth_recipe	cypher POST /auth-recipes	建 auth recipe

E. Feedback & Skills（4 tools）

Tool	對應 HTTP	用途
arcrun_report_feedback	KBDB POST /blocks（type=agent-feedback）	AI 主動回報
arcrun_list_skills	KBDB GET /blocks?type=agent-skill	列可用 playbook
arcrun_get_skill	KBDB GET /blocks/:id	拿 skill 內容
arcrun_publish_skill	KBDB POST /blocks（type=agent-skill）	AI 把學到的存回去

1.3 Tool contract 統一規範

每個 tool 都遵守：

Input：

• Zod schema declarative
• 每個參數有 .describe('...')（給 AI 看的）
• optional 標 default

Output（成功）：

{
  ok: true,
  data: T,
  hints?: string[],  // optional next-step suggestion，e.g.「你剛部署了，可 call run_workflow 測試」
}

Output（失敗）：

{
  ok: false,
  error_code: 'enum_value',
  human_message: string,
  next_actions: string[],   // 可程式化的下一步
  detail?: unknown,         // 原始錯誤（debug）
}

1.4 error_code enum（v1，可加不可刪）

error_code	對應狀況
auth_missing	api_key 沒帶
auth_invalid	api_key 無效
not_found	workflow / block 不存在
validation_failed	YAML / schema 不過
component_not_found	零件 ID 沒對應
component_not_in_whitelist	零件存在但 cypher-executor 不認
paused_awaiting_resume	workflow 在等 callback
rate_limited	太頻繁
internal_error	平台 bug（含 detail）
dependency_unavailable	下游服務（claude / mira daemon / KBDB）掛

---

Layer 2：Skill blocks（KBDB-native playbook）

2.1 Schema

type AgentSkill = {
  id: string;
  type: 'agent-skill';
  page_name: `skill-${slug}`;
  content: string;          // markdown playbook
  tags_json: string[];      // ['watcher', 'debug', 'rag', ...]
  source: 'manual' | 'auto-extracted';
  metadata_json: {
    when_to_use: string;
    example_use_case: string;
    contributed_by?: string; // agent user_agent
    success_count?: number;
  };
};

2.2 種子 skill（先建 5 個，以 mira 經驗為本）

skill page_name	用途
skill-build_watcher_workflow	cron 掃資料 → 觸發處理（mira_feed_watcher pattern）
skill-debug_paused_workflow	claude_api / 任何 async callback paused 怎麼追
skill-migrate_http_to_trigger_workflow	self-fetch 換 trigger_workflow（剛踩過的）
skill-rag_with_arcrun	用 KBDB + claude_api 做 RAG
skill-add_new_wasm_component	從 TinyGo 寫到 deploy 全流程

2.3 自動萃取機制（後期）

agent_feedback_weekly_review 跑出來的 Top patterns，LLM 包成 skill draft，leo review 後 publish。

---

Layer 3：Examples（可搜尋的範例庫）

3.1 存放

• arcrun/registry/examples/{slug}/
  • workflow.yaml
  • description.md（解決什麼問題、怎麼 trigger、預期結果）
  • tags.json（["webhook", "llm", "cron", ...]）
• CI build 出 examples-index.json 推 KBDB（type=workflow-example，內容是 YAML + tags）

3.2 搜尋

• arcrun_search_examples(use_case) 走 KBDB /search（既有 semantic）
• 命中 → 回 YAML + description + 「你可以基於這個改 X」hint

3.3 第一批範例（10 個）

slug	用途
webhook-to-slack	簡單轉發
cron-watcher	mira_feed_watcher 簡化版
llm-classify	claude_api 分類
rag-search-answer	從 KBDB 找 context → 回答
email-summary	gmail → claude → telegram
pdf-to-blocks	convert → ingest
github-issue-bot	webhook → claude → 留 comment
daily-digest	cron → 多源聚合 → 推送
parallel-fanout	一份輸入分發多 workflow
error-retry	try_catch + wait + retry

---

Layer 4：Telemetry & Feedback Loop

4.1 兩條線

explicit feedback (AI call)        implicit telemetry (platform auto-log)
        │                                       │
        ▼                                       ▼
   KBDB block type=                    KBDB block type=
   agent-feedback                      agent-telemetry
        │                                       │
        └──────────────┬───────────────────────┘
                       ▼
              agent_feedback_weekly_review
              (arcrun workflow, 週一 9am cron)
                       ▼
              LLM 聚合 + 分類
                       ▼
              KBDB block type=arcrun-roadmap
              （leo 收到 + 寫進 mira 河道）

4.2 agent-feedback schema

type AgentFeedback = {
  type: 'agent-feedback';
  content: string;            // description 原文
  source: 'mcp-tool-call';
  user_id: string;            // 用戶 namespace
  metadata_json: {
    workflow_name?: string;
    issue_type: 'doc_unclear' | 'tool_missing' | 'error_unhelpful'
              | 'unexpected_behavior' | 'feature_request' | 'success_story';
    retry_count?: number;
    blocked: boolean;
    suggested_fix?: string;
    agent_user_agent: string; // 'claude-code/1.x' etc
  };
  tags_json: ['agent-feedback', `issue:${issue_type}`];
};

4.3 agent-telemetry schema

type AgentTelemetry = {
  type: 'agent-telemetry';
  source: 'cypher-executor';
  metadata_json: {
    event_type: 'deploy_success' | 'deploy_fail' | 'run_success'
              | 'run_fail' | 'validation_error' | 'mcp_tool_call';
    workflow_name?: string;
    component_id?: string;
    error_code?: string;
    duration_ms: number;
    api_key_hash: string;  // 雜湊，不存原值
    agent_user_agent: string;
  };
};

寫入點：

• webhook-handlers.executeWebhookGraph 完成（成功 / 失敗都記）
• routes/webhooks-named.ts push（deploy 記）
• routes/cypher.ts validate 失敗（validation_error 記）
• arcrun-mcp 每個 tool call wrap 記（mcp_tool_call）

4.4 隱私

• api_key 一律 SHA-256 截前 16 字元（不可逆，可聚合）
• workflow content 不 log（只記 name）
• 用戶看自己的 telemetry：MCP arcrun_my_telemetry(limit)，只回自己 hash

4.5 weekly review workflow

name: agent_feedback_weekly_review
description: 每週一聚合 AI 回饋 + telemetry，產出 Top 痛點

flow:
  - "weekly_cron >> ON_SUCCESS >> fetch_feedback"
  - "fetch_feedback >> ON_SUCCESS >> fetch_telemetry"
  - "fetch_telemetry >> ON_SUCCESS >> aggregate"
  - "aggregate >> ON_SUCCESS >> llm_summarize"
  - "llm_summarize >> ON_SUCCESS >> publish_roadmap_block"
  - "publish_roadmap_block >> ON_SUCCESS >> notify_telegram"

config:
  weekly_cron:
    component: cron
    cron_expr: "0 9 * * 1"  # 週一 9 am UTC
  fetch_feedback:
    component: kbdb_get
    type: 'agent-feedback'
    created_after: "{{ now - 7d }}"
    limit: 500
  fetch_telemetry:
    component: kbdb_get
    type: 'agent-telemetry'
    created_after: "{{ now - 7d }}"
    limit: 5000
  aggregate:
    component: filter   # 或寫個 `group_by` 邏輯零件
    items: "{{fetch_feedback.blocks}}"
    group_by: 'metadata_json.issue_type'
  llm_summarize:
    component: claude_api
    prompt: |
      你是 arcrun 平台的回饋分析師。下面是這週 AI agent 的所有回饋 +
      telemetry 失敗事件。請：
      1. 列 Top 5 痛點（含證據引用）
      2. 為每個痛點建議具體改動（文件 / MCP tool / 錯誤訊息）
      3. 評估嚴重程度（blocked AI vs 略不便）
      
      Feedback：{{aggregate}}
      Telemetry 失敗事件：{{fetch_telemetry.blocks}}
  publish_roadmap_block:
    component: kbdb_create_block
    type: 'arcrun-roadmap'
    page_name: 'roadmap-week-{{date.iso_week}}'
    content: "{{llm_summarize.data.text}}"
  notify_telegram:
    component: telegram
    chat_id: "{{ leo_chat_id }}"
    text: "Arcrun 週報出爐：{{publish_roadmap_block.data.id}}"

這個 workflow 是 dogfood inception：arcrun 自己跑分析 arcrun 自己。

---

4. Coverage Matrix（人類 vs AI）

這份表是 NFR-5「覆蓋率可量化」的具體實踐。每個 release 重新檢視。

4.1 人類 GUI 能做的事 × LI 對應

人類在 u6u-gui 做的	LI MCP 工具	對等？
看現有 workflow 列表	arcrun_list_workflows	✅
點開 workflow 看 YAML	arcrun_get_workflow	✅
編輯 workflow YAML	arcrun_push_workflow（含 update）	✅
執行 workflow	arcrun_run_workflow	✅
看執行結果	arcrun_get_execution_trace	✅（新增）
翻零件庫	arcrun_list_components + search	✅
看零件 contract	arcrun_get_component_contract	✅
上傳 WASM 零件	arcrun_publish_component	✅
設 credential	arcrun_create_recipe + （手動 push credential）	⚠️ 部分（credential 提交需安全考量，AI 不全自動）
翻歷史執行	arcrun_list_recent_executions	✅（新增）
看 paused 工作流	arcrun_list_paused_executions	✅（新增）
手動 resume	arcrun_resume_execution	✅
視覺化 canvas 拖拉	—	❌（純視覺，LI 不複製）
看排版 prototype	—	❌（同上）
Flip UI/Logic view	—	❌（同上）
Action log（操作軌跡）	arcrun_my_telemetry	✅（含更多資料）

Gap：3 個視覺類動作 LI 不需要對等；其他全等。

4.2 cypher-executor 31 路由 × LI 暴露

路由	LI 暴露？	工具
/health、/docs、/openapi.json	❌ infra	—
/execute	✅	arcrun_run_workflow（內部）
/cypher/search、/cypher/execute	✅	discovery 內部用
/workflows/resume	✅	arcrun_resume_execution
/webhooks/named*	✅	CRUD 對應 5 個 tools
/webhooks/* (anonymous)	❌ deprecated	—
/credentials*	⚠️	只 list + delete，POST 走人類流程（安全考量）
/recipes*、/auth-recipes*	✅	4 個 tools
/validate	✅	arcrun_validate_yaml
/auth/*、/register、/me*	❌ admin	—

新增需建路由：/preview、/executions/:id、/workflows/:name/executions、/executions/paused、/webhooks/named/:name/diff、/my-telemetry（共 6 個）

4.3 KBDB 50 路由 × LI 暴露

LI 不直接 expose KBDB 50 個路由。AI 透過 arcrun-mcp 的 abstracted tool（get_skill / list_skills / report_feedback 等）間接用 KBDB。

例外（值得直接 expose 的）：

• arcrun_kbdb_search(query) — 走 /search semantic
• arcrun_kbdb_get_block(id) — 看 block 內容（debug 用）

KBDB schema 設計 / triplets / records 這些屬於另一個 SDD（KBDB MCP），不在本 LI 範圍。

---

5. AGENTS.md 模板

# Arcrun for AI Agents

## What is Arcrun (30 sec)
Arcrun lets you compose Cloudflare Workers (WASM components) into workflows via YAML.
You write YAML, push to KV, trigger via webhook or cron. Each component is a
TinyGo/AssemblyScript WASM with stdin/stdout JSON I/O.

## Connect (one step)
Add to your MCP config:
\`\`\`json
{
  "mcpServers": {
    "arcrun": {
      "url": "https://mcp.arcrun.dev/mcp",
      "headers": {"Authorization": "Bearer $ARCRUN_API_KEY"}
    }
  }
}
\`\`\`
Get your ak_ key at https://arcrun.dev/me.

## Your first workflow (5 min)
1. `arcrun_list_components()` → see what's available
2. Write 3-line YAML in chat (assistant does this)
3. `arcrun_validate_yaml(yaml)` → confirm
4. `arcrun_push_workflow(yaml)` → deploy
5. `arcrun_run_workflow(name, input)` → test
6. `arcrun_get_execution_trace(id)` → see results

## Core concepts (5 things)
- **Component**: WASM Worker. Use existing or `arcrun_publish_component`.
- **Cypher binding YAML**: triplets `A >> relation >> B` define graph.
- **FOREACH**: `>> 對每個 X >> next_node` iterates lists.
- **Paused-resume**: claude_api etc pause workflow; resumes via callback.
- **api_key**: ak_xxx, all calls need this in MCP auth.

## URL conventions (why this matters)
- `cypher.arcrun.dev` = orchestration API (you push here)
- `arcrun-{kebab}.{user}.workers.dev` = component workers (workers.dev avoids CF self-fetch)
- `kbdb-*.arcrun.dev` = KBDB component workers (your data lives here)

## Common errors
| error_code | What to do |
|---|---|
| `component_not_found` | call `list_components`, check spelling |
| `validation_failed` | read `next_actions` field, fix YAML |
| `paused_awaiting_resume` | normal for claude_api; wait or `get_execution_trace` |
| `auth_invalid` | ak_ wrong, re-fetch from /me |

## Unsure? Do this:
- Don't know what's available → `list_components` / `list_workflows` / `search_examples`
- Don't know syntax → `get_skill('skill-build_X')` for playbooks
- Hit weird behavior → **MUST** call `report_feedback(issue_type='unexpected_behavior', ...)`

## Feedback (required)
After every workflow deploy or debug session, call:
\`\`\`
arcrun_report_feedback({
  workflow_name: '...',
  issue_type: 'success_story' | 'doc_unclear' | 'tool_missing' | 'error_unhelpful' | 'feature_request',
  description: '...',
  blocked: false,
  retry_count: N,
  suggested_fix: '...'  // optional
})
\`\`\`

Even "success" stories help — they tell us what's working.

---

6. Migration plan（u6u-mcp → arcrun-mcp）

6.1 不破壞

• u6u-mcp Worker rename arcrun-mcp（wrangler name 改）
• 兩個 hostname 並存：mcp.finally.click + mcp.arcrun.dev（route 加一條）
• 舊 tool 名（u6u_*）保留，加 alias 對應新名（arcrun_*）
• 90 天 deprecation 期，舊 tool call → 回 warning hint「u6u_X → 改用 arcrun_X」

6.2 新增 tools（按 phase）

Phase 1（gap-fill）：

• arcrun_validate_yaml（既有 /validate 已存，包 MCP 即可）
• arcrun_get_execution_trace（需 cypher-executor 新加 /executions/:id）
• arcrun_list_recent_executions（新 endpoint）
• arcrun_list_paused_executions（新 endpoint）
• arcrun_report_feedback（新 tool）
• arcrun_get_onboarding（KBDB read）

Phase 2（advanced）：

• arcrun_preview_workflow（新 endpoint，沒 KV side-effect）
• arcrun_diff_workflow
• arcrun_my_telemetry
• arcrun_search_examples（KBDB write + search 已存）
• arcrun_list_skills / arcrun_get_skill / arcrun_publish_skill

Phase 3（auto-loop）：

• agent_feedback_weekly_review workflow
• arcrun-roadmap block 生成
• LLM extract skill 自動化

---

7. 開發順序與里程碑

Milestone 1：可量測（1 週）

• 寫 AGENTS.md v1
• 加 implicit telemetry 寫入點（cypher-executor）
• 加 arcrun_report_feedback MCP tool
• 建 agent-feedback / agent-telemetry KBDB template
• 開始收 data

Milestone 2：gap-fill（1 週）

• u6u-mcp 補上 6 個 Phase 1 tools
• 新 endpoints 在 cypher-executor 加
• 每個 tool 結構化 error contract

Milestone 3：skill + example（1 週）

• 種子 5 個 skill blocks
• 種子 10 個 example workflows
• search_examples 跑通

Milestone 4：closed loop（半週）

• weekly_review workflow 部署
• 第一份 arcrun-roadmap block 產出
• leo 收到第一份週報

Milestone 5：rename + cleanup（1 週）

• u6u-mcp → arcrun-mcp 公開
• 舊 tool 加 deprecation warning
• AGENTS.md 同步 KBDB

---

8. 開放決策（待 leo）

決策	推薦	理由
MCP server URL	mcp.arcrun.dev（route 並存 mcp.finally.click 90 天）	品牌統一
擴張 u6u-mcp vs 建新	擴張 + rename	不 fork，零移轉痛
AGENTS.md 位置	arcrun/AGENTS.md + KBDB 自動同步	兩面都拿到
feedback 是否要 auth	要（驗 ak_ 存在即可，不查餘額）	防 spam
LI 是否包含 KBDB MCP	部分（abstracted），KBDB MCP 另立 SDD	範圍清楚
Telemetry 保留多久	90 天 hot + 1 年 cold archive	平衡 cost 與 review

---

9. 跨 SDD 連動

其他 SDD	連動點
credential-primitives-wasm	LI 不重做 auth，只用 auth_static_key 等既有零件
recipe-system	LI 暴露 recipe CRUD tool 對應
component-registry-canon	LI list_components / get_contract 走 registry
resumable-workflow	LI list_paused_executions / resume 用
u6u-platform-evolution	LI 是 evolution 之一，未來分 user-tier 時要考慮
mira-app (polaris/mira)	LI 是 mira dogfood 痛點轉化的產物，roadmap 含對 mira 的回饋