arcrun — AI workflow execution engine (clean history)

Self-hosted 開源：WASM 零件 + recipe + cypher-executor，跑在你自己的 Cloudflare。此為重建的乾淨歷史起點（移除曾誤 commit 的 GCP SA 金鑰，舊歷史保留在 richblack/arcrun 與本地 backup 分支）。含： - acr init --self-hosted installer（建 KV/R2 + codeload 拉預編譯 wasm + wrangler deploy + seed recipe） - recipe push 把關（資料外流提醒 + 打通檢查） - 19 個正當零件預編譯 wasm（claude_api/km_writer/kbdb_upsert_block 排除：違反 DECISIONS §1） - CLI / cypher-executor / registry / 完整 SDD Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-03 15:52:38 +08:00
commit 922a57fe34
485 changed files with 89356 additions and 0 deletions
@@ -0,0 +1,312 @@
+# 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）：
+
+```json
+{
+  "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（從範例改 > 從零寫）
+
+```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：
+
+```typescript
+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）
+
+```yaml
+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
+```yaml
+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 完成）。