Arcrun/AGENTS.md

Arcrun for AI Agents

給 AI 操盤手（Claude Code、Cursor、Codex、自製 agent）的 onboarding。 載入這份就能用 arcrun，不需要讀 SDD 內部架構、不需要 grep codebase、不需要問人。

對應 SDD：.agents/specs/llm-interface/（v0.1，2026-05-16）

---

1. Arcrun 是什麼（30 秒）

Arcrun = 用 YAML 把 WASM 零件串成可重複執行 workflow 的平台。用戶寫 YAML，平台跑。

• 每個零件是 TinyGo / AssemblyScript 編譯的 .wasm，stdin/stdout JSON I/O
• 每個 workflow 是一份 cypher binding YAML，描述「節點 + 邊」的圖
• 觸發機制：HTTP webhook、cron、callback resume
• 部署完成回 webhook_url，用戶或下游服務 POST 即可執行

n8n 從手寫程式碼開始，arcrun 從 AI 描述開始：你跟用戶聊出他想要什麼自動化，你（AI）寫 YAML 部署，之後不需要 AI 也能跑。

---

2. 連線（一步搞定）

加到你的 MCP config（Claude Desktop / Cursor / 任何支援 MCP 的 client）：

{
  "mcpServers": {
    "arcrun": {
      "type": "http",
      "url": "https://mcp.arcrun.dev/mcp",
      "headers": {
        "Authorization": "Bearer ak_YOUR_API_KEY"
      }
    }
  }
}

暫時：M5 完成前 URL 仍是 https://mcp.finally.click/mcp，預計 2026-06 切。 Tool 命名暫時仍是 u6u_* prefix，M5 一次改 arcrun_*。 本 doc 描述目標狀態，實際用 list_* tool 取得當前可用名單。

取得 ak_ 金鑰：到 https://arcrun.dev/me（OAuth Google / GitHub 登入），右下角複製。

---

3. 五個核心概念

概念	一句話
Component（零件）	WASM Worker，獨立部署成 arcrun-{kebab}.{user}.workers.dev。用 list_components 看可用清單
Cypher binding	YAML 三元組 A >> 關係 >> B，定義 workflow 圖。常用關係：ON_SUCCESS / 對每個 X / IF
FOREACH	>> 對每個 item >> next_node 迭代陣列。item 變數自動可用
Paused-resume	claude_api 等需等外部 callback 的零件會「paused」，cypher-executor 透過 /workflows/resume 接續
api_key (ak_xxx)	所有 call 必帶（MCP header 或 workflow {{api_key}}），同時當 partition key

---

4. 你的第一個 workflow（5 分鐘 e2e）

Step 1：看有什麼零件可用

arcrun_list_components()        # 全部零件名單
# 或
arcrun_search_examples('rag')   # 範例庫搜尋（從 use case 找範本）
arcrun_list_skills()            # 看 playbook 清單
arcrun_get_skill('build_watcher_workflow')  # 拿特定 playbook 細節

常用零件：http_request、claude_api、kbdb_get、kbdb_create_block、telegram、gmail、cron、filter、trigger_workflow。

Step 2：寫 minimal YAML（從範例改 > 從零寫）

name: hello_world
description: 接 webhook，回個 hi

flow:
  - "input >> ON_SUCCESS >> say_hi"

config:
  say_hi:
    component: http_request
    url: "https://httpbin.org/post"
    method: POST
    body_json:
      hello: "{{input.name}}"

Step 3：dry-run 校驗

arcrun_validate_yaml(api_key, graph)

Step 4：部署

arcrun_push_workflow(api_key, yaml_content)

回 {name, webhook_url: 'https://cypher.arcrun.dev/webhooks/named/hello_world/trigger'}。

Step 5：觸發測試

arcrun_run_workflow(api_key, name='hello_world', input={name: 'leo'})

Step 6：看結果 / debug

arcrun_list_recent_executions(api_key, workflow_name='hello_world')
# 若 paused：
arcrun_list_paused_executions(api_key)
arcrun_get_execution_trace(api_key, task_id='task_XXX')

Step 7：回報（必做，見 §8）

arcrun_report_feedback(api_key, issue_type='success_story', description='...')

---

5. URL 慣例（很重要，搞錯會撞 522）

URL pattern	用途
cypher.arcrun.dev	Orchestration API（你的 workflow CRUD + trigger 走這）
arcrun-{kebab}.{user}.workers.dev	零件 worker（cypher-executor 走 workers.dev 對內 URL，避 CF 同 zone 自循環死鎖）
{kebab}.arcrun.dev	零件 worker 對外公開 URL（用戶 / 直接 curl 用，cypher-executor 不要走這）
kbdb-*.arcrun.dev	KBDB 操作（資料層）
mcp.arcrun.dev	MCP server（你用這個）
mcp.finally.click	MCP server 舊網址（過渡）

踩坑警示：cypher-executor 自打 cypher.arcrun.dev 或自打 arcrun-cypher-executor.*.workers.dev 都會撞 CF self-fetch 防護回 1042/522。要 in-process 觸發另一個 workflow，用內建零件 trigger_workflow（不是 http_request 自打）。

---

6. 常見錯誤 + 怎麼讀

error_code	含義	你該做什麼
auth_missing / auth_invalid	ak_ 沒帶 / 錯了	去 https://arcrun.dev/me 重拿，更新 MCP config
component_not_found	零件名打錯	call list_components() 看正確名
component_not_in_whitelist	零件存在但 cypher-executor 不認	告訴用戶聯絡平台維護者（這是平台 bug）
validation_failed	YAML / schema 不過	看 response 的 next_actions 陣列，照著修
running_async (status field)	workflow 已接受，在背景跑等 callback（claude_api 等）	正常，wait 或 call get_execution_trace 看狀態。舊名 paused_awaiting_resume 2026-05-16 改
dependency_unavailable	下游 API（Claude / Gmail / KBDB）掛	retry，仍掛 → 公告型 issue

---

7. 不確定的時候，按這個順序

1. 不知道有什麼零件可用 → arcrun_list_components() / arcrun_get_component_contract(id)
2. 不知道用戶有什麼 workflow → arcrun_list_workflows(api_key)
3. 想看零件 input/output schema → arcrun_get_component_contract('xxx')
4. 要不要 dry-run → 預設 yes，永遠先 arcrun_validate_yaml 再 arcrun_push_workflow
5. 觸發後不知道結果 → arcrun_list_recent_executions(api_key, name) / arcrun_get_execution_trace(api_key, task_id)，paused 不算錯
6. 有沒有現成範例可參考 → arcrun_search_examples('rag llm chain')（範例庫 10+ 個 workflow）
7. 有沒有 playbook → arcrun_list_skills() / arcrun_get_skill(slug)（5 個 playbook：watcher / paused-debug / migrate-trigger / rag / new-component）
8. 不知道下一步 → 看任何 error response 的 next_actions 陣列

過渡期 tool 命名注意

LI 開發中（2026-05-16~）。目前 arcrun-mcp 同時提供：

• arcrun_*（新規範，主用這套）：報 feedback / 工作流 CRUD / 執行 trace
• u6u_*（舊規範，等 M5 一次切）：component 操作、tag 操作、GUI context

舊 u6u_* 仍可用。其中 u6u_deploy_workflow 是壞的（呼叫不存在的 endpoint），用 arcrun_push_workflow 取代。

---

8. 回報機制（必做）

平台用回饋資料 self-improve。每次部署 workflow / 卡住 / 解掉問題後，call：

report_feedback({
  workflow_name: "hello_world",         // 你剛做的 workflow
  issue_type:
    | "success_story"        // 順利完成，值得記錄這個 pattern
    | "doc_unclear"          // AGENTS.md / skill / contract 講不清楚
    | "tool_missing"         // 該有的 MCP tool 沒有
    | "error_unhelpful"      // 錯誤訊息看不懂下一步
    | "unexpected_behavior"  // 跟我預期的不一樣
    | "feature_request",     // 我想要 X 功能
  description: "...",
  retry_count: 2,            // 你試了幾次才搞定
  blocked: false,            // 完全擋住嗎
  suggested_fix: "..."       // optional，你建議的修補
})

「success_story」也要報，那是告訴平台「這個 pattern 已經 work，可以推廣」。

不需要怕回報太多 — 你不報，平台拿 implicit telemetry（每個 deploy / run 平台自己 log）也會看到問題，但 explicit feedback 質感高很多。

---

9. KBDB（資料儲存）速覽

arcrun 的「資料庫」是 KBDB（Cloudflare D1）。萬物皆 block：note / wiki-page / chat / triplet / template / skill / feedback / 等，靠 type 區分。

工具：

• kbdb_get(type, block_id?, page_name?, ...) — 讀
• kbdb_create_block(type, content, ...) — 建
• kbdb_patch_block(block_id, content?, tags?, ...) — 改
• kbdb_upsert_block(page_name, content, ...) — page_name 當 idempotency key

寫 workflow 要 RAG / KM / 用戶資料持久化時，直接用這幾個 component（在 YAML component: kbdb_get 等）。

完整 KBDB API 將有獨立 SDD（kbdb-llm-interface），目前看 https://kbdb.finally.click/ui（Swagger）。

---

10. 範例：寫一個 cron watcher（最常見 pattern）

name: my_watcher
description: 每 5 分鐘掃未處理資料 → 觸發 wiki_synthesis

flow:
  - "watch_cron >> ON_SUCCESS >> list_unprocessed"
  - "list_unprocessed >> ON_SUCCESS >> filter_new"
  - "filter_new >> 對每個 item >> trigger_synthesis"

config:
  watch_cron:
    component: cron
    cron_expr: "*/5 * * * *"

  list_unprocessed:
    component: kbdb_get
    api_key: "{{api_key}}"
    type: "note"
    source: "user-input"
    limit: 20

  filter_new:
    component: filter
    items: "{{list_unprocessed.blocks}}"
    condition:
      key: "tags_json"
      op: "eq"
      value: "[]"

  trigger_synthesis:
    component: trigger_workflow     # 不要用 http_request 自打 — 會撞 CF self-fetch
    workflow_name: "wiki_synthesis"
    api_key: "{{api_key}}"
    input:
      api_key: "{{api_key}}"
      raw_block_id: "{{item.id}}"

部署完每 5 分鐘自動跑。

---

10.5 內建 magic vars（_ prefix reserved）

YAML 內可直接用以下變數，cypher-executor 自動展開為當下時間（UTC）：

變數	範例	用途
{{_today}}	2026-05-16	日 log / page_name
{{_yesterday}}	2026-05-15	digest 取昨日
{{_now}}	2026-05-16T09:30:00.123Z	ISO 8601
{{_now_unix}}	1778937000123	unix ms
{{_now_unix_s}}	1778937000	unix sec
{{_iso_week}}	2026-W20	weekly archive (本 doc 推薦)
{{_iso_week_num}} / {{_iso_year}}	20 / 2026	拆開用
{{_yyyymm}} / {{_yyyymmdd}}	202605 / 20260516	緊湊路徑
{{_year}} / {{_month}} / {{_day}} / {{_hour}} / {{_minute}}	各別 zero-padded	自己拼路徑
{{_weekday}}	0-6（0=日）	if-control
{{_iso_weekday}}	1-7（1=一）	ISO 風格

rule：_ prefix reserved for system，用戶自己 ctx 變數不要用 _ 開頭。

範例：weekly archive

publish_roadmap_archive:
  component: kbdb_upsert_block
  page_name: "roadmap-{{_iso_week}}"   # roadmap-2026-W20
  tags_json: '["weekly", "week:{{_iso_week}}"]'

---

11. 給寫 LI 的 AI 自己的 meta-規範

你（AI）在寫 arcrun workflow 時，遵守以下習慣會少踩坑：

1. 永遠先 list → validate → push → run → trace：5 步流程，缺一個都會多繞路
2. error 一定讀 next_actions：不是讀 human_message 然後猜
3. paused 不是錯：claude_api、外部 OAuth flow 都會 paused，正常
4. {{api_key}} 是 trigger context 帶進來的：手動觸發要在 body 帶；cron 觸發 cypher-executor 自動塞
5. 新增零件不在 list_components 出來的清單裡 → 平台沒部署該零件，告訴用戶「我們需要先做 component」，不是你寫 workflow 的鍋
6. 完成後 call report_feedback：哪怕 success_story，也回報。AI 用得順不順不能靠人類事後回顧

---

12. 進階參考

• 完整 SDD：matrix/arcrun/.agents/specs/llm-interface/
• 平台架構（rules）：matrix/arcrun/.claude/rules/
• 零件開發指南：call get_component_guide() MCP tool
• KBDB Swagger：https://kbdb.finally.click/ui
• 範例庫（M3 完成後）：registry/examples/
• 平台週報（M4 完成後）：KBDB block type=arcrun-roadmap

---

本 doc 是 source of truth。每次更新後 GH Actions 自動同步 KBDB block (type=agent-onboarding)，AI 可透過 get_onboarding MCP tool 拿最新版（M1 完成）。