docs(arcrun): AGENTS.md v1 — AI onboarding (LI SDD M1.1)
對應 SDD .agents/specs/llm-interface/ M1.1。 LI (LLM Interface) 第一份文件：任何 AI agent 載入這份就能用 arcrun， 不用讀 SDD 內部架構、不用 grep codebase、不用問人。 包含： - 30 秒「what is arcrun」 - MCP 連線配置（Claude Desktop / Cursor / 自製 agent 通用） - 5 個核心概念（Component / Cypher binding / FOREACH / Paused-resume / api_key） - 你的第一個 workflow（list → validate → push → run → trace 5 步） - URL 慣例 + CF self-fetch 死鎖警示 - 常見錯誤 + error_code → 下一步 mapping - 「不確定的時候」標準流程 - report_feedback 規範（**必做**） - KBDB 速覽 + cron watcher 範例 - meta-規範：寫 workflow 的 AI 自己的習慣 901 words / 263 lines（控制在 5-8K tokens 內），純繁體中文。 CI 自動同步 KBDB block (type=agent-onboarding) 之後再做（M1.1 另一個 subtask）。 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,263 @@
|
|||||||
|
# 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：看有什麼零件可用
|
||||||
|
```
|
||||||
|
list_components()
|
||||||
|
```
|
||||||
|
回 ~30 個零件名單。常用：`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 校驗
|
||||||
|
```
|
||||||
|
validate_yaml(yaml)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 4：部署
|
||||||
|
```
|
||||||
|
push_workflow(yaml)
|
||||||
|
```
|
||||||
|
回 `{webhook_url: 'https://cypher.arcrun.dev/webhooks/named/hello_world/trigger'}`。
|
||||||
|
|
||||||
|
### Step 5：觸發測試
|
||||||
|
```
|
||||||
|
run_workflow('hello_world', {name: 'leo'})
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 6：看結果
|
||||||
|
```
|
||||||
|
get_execution_trace(execution_id)
|
||||||
|
```
|
||||||
|
結構化回 per-node status / input / output / duration。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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` 陣列，照著修 |
|
||||||
|
| `paused_awaiting_resume` | workflow 在等 callback（claude_api 等） | **正常**，wait 或 call `get_execution_trace` 看狀態 |
|
||||||
|
| `dependency_unavailable` | 下游 API（Claude / Gmail / KBDB）掛 | retry，仍掛 → 公告型 issue |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. 不確定的時候，按這個順序
|
||||||
|
|
||||||
|
1. **不知道有什麼零件可用** → `list_components()` / `get_component_contract(id)`
|
||||||
|
2. **不知道用戶有什麼 workflow** → `list_workflows()`
|
||||||
|
3. **想看零件 input/output schema** → `get_component_contract('xxx')`
|
||||||
|
4. **要不要 dry-run** → 預設 yes，永遠先 `validate_yaml` 再 `push_workflow`
|
||||||
|
5. **觸發後不知道結果** → `get_execution_trace(execution_id)`，paused 不算錯
|
||||||
|
6. **有沒有現成範例可參考** → `search_examples('rag llm chain')`（M3 完成後可用）
|
||||||
|
7. **有沒有 playbook** → `list_skills() / get_skill(id)`（M3 完成後可用）
|
||||||
|
8. **不知道下一步** → 看任何 error response 的 `next_actions` 陣列
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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 分鐘自動跑。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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 完成）。
|
||||||
Reference in New Issue
Block a user