# arcrun

**讓 AI 把想法直接變成自動化工作流，而不是一行一行寫程式。**

arcrun 是一套**給 AI（Claude Code）用的 harness**：你叫 CC 用 arcrun 開發自動化時，它知道能用什麼、不能做什麼，做錯了有機制擋住——讓 CC 順暢、且不容易做歪。

---

## 為什麼做這個？

AI 愈來愈強，但跟 AI 協作做自動化還是很有摩擦：

**問題一：AI 調 API 太耗 token。**
每次讓 AI 幫你查資料、發信、寫試算表，它都要在對話裡描述、確認、執行，token 燒很快。更好的做法是讓 AI 把任務寫成一次性的工作流，之後直接執行。

**問題二：AI 從頭寫腳本容易出 bug。**
讓 AI 從零寫一整個自動化腳本，十次有八次要來回修。根本原因是邏輯沒被複用——每次都是全新的程式。

**問題三：第三方依賴是單點故障。**
每多依賴一個不可掌控的第三方（含 SaaS 平台本身），就多一個會掛掉、會漲價、會關服務的風險。

**解法：把邏輯寫成純文字工作流，跑在你自己的 Cloudflare 上。**
想到工作流你可能想到 n8n。方向一樣，但 arcrun 為 AI 優先設計、且**開源自架**：

| | n8n | arcrun |
|---|---|---|
| 語法 | JSON / 拖拉介面，動輒數千行 | 三行 Cypher，AI 和人都能直接讀 |
| context 消耗 | 大，容易超出 window | 極小，整個 workflow 幾十個 token |
| 擴充方式 | GUI 拖拉，人類操作 | 寫一段 recipe（純文字），AI 自己會寫 |
| 執行環境 | 需自架或付費訂閱 | 部署到**你自己的** Cloudflare，你說了算 |

核心假設：**最好的 AI 協作工具，應該讓 AI 自己能讀、能寫、能執行、能除錯——而且整套跑在你掌控的環境裡。**

---

## 核心概念：零件 vs recipe（最重要，先讀這個）

arcrun 只有兩種東西，分清楚就不會做歪：

### 零件（primitive）— 固定的一小套，由維護者管理，**你不自製**
- 是 WASM 程式，要部署，幾乎不變。**只有四類**：
  1. **流程控制**：`if_control` / `switch` / `filter` / `foreach_control` / `try_catch` / `wait`
  2. **資料處理**：`string_ops` / `number_ops` / `array_ops` / `date_ops` / `set` / `merge` / `validate_json`
  3. **`http_request`**：打任意 HTTP
  4. **credential（auth）**：`auth_static_key` / `auth_service_account` / `auth_oauth2` / `auth_mtls`（背後自動注入，你不直接擺）
- **零件不對外連特定服務。** 任何「打某個固定 API endpoint」的東西**都不是零件**——那是 recipe。
- 新增零件走 **GitHub PR**（人 merge 把關），不是 self-service。日常開發你**不會也不該**自製零件。

### recipe — 你（或 AI）能自由擴充的東西，純文字，不用部署
- recipe = `http_request` + 一組固定設定（endpoint / method / headers / body 模板）。
- 要打 Notion / Slack / 你自己的 API？**寫一個 recipe**，不是做一個零件。
- recipe 是純文字、不用 deploy、改一次零成本。AI 讀得懂 API 文件就能幫你組出 recipe。

> **一句話判準**：要打一個固定的外部 endpoint → **recipe**。要做流程控制 / 資料處理 / 通用 HTTP → 用既有**零件**。其他大部分情況 → 直接寫**工作流**把它們串起來。

---

## 快速開始（Self-hosted）

arcrun 是 self-hosted 開源：你用自己的 Cloudflare 帳號跑整套。一次裝好，之後就是你的。

### 1. 取得 Cloudflare 憑證

你需要一個 CF 帳號，並在 dashboard 建一個 **API Token**（權限：Workers Scripts Edit + KV Storage Edit + Workers R2 Storage Edit）。CLI 不代管你的憑證——你自己建、自己持有。

### 2. 一鍵初始化

```bash
npm i -g arcrun
acr init --self-hosted
```

貼上 CF Account ID + API Token，CLI 自動：建立所需 KV、部署所有 Worker（含執行引擎 cypher-executor 與全部零件）、啟用 workers.dev、寫回設定。跑完會提示你手動設定 runtime secret（如 `ENCRYPTION_KEY`），這一步刻意不自動化（secret 不進工具流程）。

> 想先不碰 Cloudflare、純在本機感受語法？`acr init --local` 然後 `acr run`。

### 3. 寫一個工作流

`hello.yaml`：

```yaml
name: hello
flow:
  - "input >> 完成後 >> transform"
config:
  transform:
    component: string_ops
    operation: upper
```

```bash
acr run hello --input input="Hello, world"   # → HELLO WORLD
```

### 4. 要打外部 API？寫一個 recipe（不是做零件）

```bash
# 上傳一個打外部 API 的 recipe（push 時會幫你檢查打不打得通）
acr recipe push my_api_recipe.yaml
```

recipe 裡寫好 endpoint / method / body 模板，credential 由 auth 自動注入。workflow 裡用 `component: <recipe 名>` 或 `component: rec_xxxx` 引用它。

### 5. 上傳 credential（client 端加密，明文不離開你的機器）

```bash
acr auth-recipe list              # 看支援哪些服務的認證
acr auth-recipe scaffold notion   # 取得 credentials.yaml 範本
acr creds push credentials.yaml   # AES-GCM 加密後上傳到你自己的 KV
```

### 6. 部署 + 觸發

```bash
acr push newsletter.yaml          # 部署，取得 Webhook URL
acr run newsletter --input email=user@example.com
```

> ⚠️ **部署對外 webhook = 把東西暴露給外界。** `acr push` 產生的 trigger URL 任何拿到的人都能打。CLI 會在這類動作前提醒你——確認後就是你的責任（你可以選擇加上 API Key 限制 / 權限）。

---

## Workflow 語法

```
"A >> 關係詞 >> B"
```

這就是全部。每一行是一條邊，描述 A 之後發生什麼。

| 關係詞 | 別名 | 說明 |
|--------|------|------|
| `完成後` | `ON_SUCCESS` | A 成功後執行 B |
| `失敗時` | `ON_FAIL` | A 失敗時執行 B |
| `對每個` | `FOREACH` | 對 A 的每個元素執行 B（支援 `對每個 X` 命名）|
| `條件滿足時` | `IF` | 條件為真時執行 B |
| `CALLS_SUBFLOW` | — | 呼叫另一個 workflow |

整個 workflow 通常不超過十行，AI 一眼掃完不需捲動。

---

## 為什麼零件這麼少？（這是特性，不是缺陷）

你可能覺得「才這幾個零件，n8n 有幾百個」。但 n8n 那幾百個零件，本質多半是「把一個 HTTP request 包成某服務的格式」。在 arcrun，那些**全部是 recipe**——純文字、AI 幫你寫、不用等誰先做好封裝。

對 AI 來說，一個彈性的 `http_request` + recipe，比一百個固定零件封裝更好用：AI 讀得懂 API 文件，直接組出正確的 recipe，不必等有人做「Notion 零件」。

零件少 = 攻擊面小、要驗證的東西少、整套能塞進 AI 的 context。**長尾交給 recipe，核心保持精簡**，是刻意的設計。

---

## recipe 入庫把關（誠實說明）

- **自有庫（你的 self-hosted）**：`acr recipe push` 時 CLI 會 (1) 提醒會不會把資料/服務暴露給外界、(2) 幫你實打一次看 API 通不通（2xx）。這是**提醒級**——arcrun 不替你做授權判斷，打不打得通最終由發 API key 的服務裁決。打不通會誠實標原因（例：缺 credential），不會假裝成功。
- **公共庫（未來）**：recipe 要貢獻給別人用、進公共庫時，由維護者機制檢核「實際打通、真收到成功回傳」（投稿者不能自己驗證自己）。此機制在第一期之後啟用。

---

## CLI 指令

```
acr init --self-hosted             一鍵部署到你的 Cloudflare（貼 token，其餘自動）
acr init --local                   純本機體驗語法，不需 Cloudflare
acr creds push [file]              client 端加密並上傳 credentials
acr recipe push <file>             上傳 API recipe（push 時提醒暴露 + 檢查打通）
acr push <workflow.yaml>           部署 workflow，取得 Webhook URL
acr run <name> [--input k=v]       執行 workflow
acr validate <workflow.yaml>       執行前驗證格式 / 關係詞 / credential
acr parts                          列出可用的核心零件
acr parts scaffold <comp>          取得零件的 workflow config 範本
acr auth-recipe list               列出支援的第三方服務認證
acr auth-recipe scaffold <service> 取得 credentials.yaml 範本 + workflow 範例
acr list                           列出已部署的 workflow
acr logs <name>                    查看執行記錄
```

> 給 AI 操盤手：開始前讀 `.claude/rules/06-mindset.md`（或 arcrun-mindset Skill）——它說明 arcrun 的世界觀（工作流是 default、零件稀有且不自製、一切外部 API 皆 recipe），讓你一開始就走在正路上。

---

## 設計原則（節錄）

- **減少對不可控第三方的依賴**：核心 MIT 開源、self-hosted、workflow 是你擁有的純文字。
- **解耦 / 原子化**：零件、recipe、執行引擎彼此可獨立替換。
- **arcrun 是 AI 用的工具**：需要 AI 判斷時是操盤的 CC 自己做，工作流裡**不內嵌**回頭呼叫 LLM 的節點。
- **誠實**：stub / 未驗證就如實標明，不假裝成功；完成以客觀證據（HTTP status / trace）為準。

完整決策見 [`DECISIONS.md`](DECISIONS.md)。

---

## License

MIT

---

## 致謝

arcrun 的核心架構、WASM 零件、CLI 工具鏈與這份文件，由以下貢獻者共同打造：

- **[@richblack](https://github.com/richblack)** — 創始人，產品設計與架構決策
- **Claude（Anthropic）** — 實作夥伴：零件開發、executor 架構、CLI 實作與程式碼審查

歡迎加入：[CONTRIBUTING.md](CONTRIBUTING.md)