# arcrun

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

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

---

> ## 🤖 給 AI 操盤手（Claude Code 等）
>
> 如果使用者把這個 repo / 網站丟給你、要你用 arcrun 做自動化——**你的第一步**：
>
> ```
> npm i -g arcrun && acr install-harness
> ```
>
> 這會把 arcrun 的防護（mindset Skill、CLAUDE.md 提醒、防做歪 hook、`/arcrun` 指令）裝進使用者**當前專案**，裝完你就有完整指引。
>
> **裝前先記住**：使用者選 arcrun = 不要自己寫 Python/Node 一次性腳本；打外部 API 寫 recipe；不自製零件；所有 CLI 操作你來做。完整啟動指南見 [`llms.txt`](llms.txt)。

---

## 為什麼做這個？

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 帳號跑整套。一次裝好，之後就是你的，不依賴任何人的服務。

你總共只需要做 4 件事（步驟 1-4），其餘 CLI 自動完成、你只是看著機器跑。

### 1. 申請 Cloudflare 帳號（免費）

到 [dash.cloudflare.com/sign-up](https://dash.cloudflare.com/sign-up) 註冊。免費方案（Workers free tier）就足夠跑起來。

註冊後你需要兩個東西——**Account ID** 和 **API Token**：

**Account ID**：登入後在 [dash.cloudflare.com](https://dash.cloudflare.com) 隨便進一個區段，網址列會是 `dash.cloudflare.com/<這串就是 Account ID>`；或在右側欄 "Account ID" 直接複製。

**API Token**：到 [My Profile → API Tokens](https://dash.cloudflare.com/profile/api-tokens) → **Create Token** → **Create Custom Token**，給以下權限（CLI 用它建 KV / 部署 Worker）：

| 類型 | 項目 | 權限 |
|---|---|---|
| Account | Workers Scripts | Edit |
| Account | Workers KV Storage | Edit |
| Account | Workers R2 Storage | Edit |

建好後**複製那串 token**（只會顯示一次）。CLI 不代管你的憑證——你自己建、自己持有。

### 2. 安裝 Cloudflare CLI（wrangler）

CLI 部署 Worker 時會用到 wrangler。先裝它：

```bash
npm i -g wrangler
```

### 3. 安裝 arcrun CLI

```bash
npm i -g arcrun
```

### 4. 一鍵初始化（其餘全自動）

```bash
acr init --self-hosted
```

CLI 會問你 **Account ID** 和 **API Token**（步驟 1 取得的），貼上後它自動完成：

```
→ 驗證 Cloudflare 憑證... ✓
→ KV WEBHOOKS... ✓   （建 7 個 KV namespace，已存在則重用）
→ R2 WASM_BUCKET... ✓
→ workers.dev subdomain: your-account
→ 下載部署物 + 部署 Worker（從 GitHub 拉預編譯 wasm，用你的 CF token 部署）...
  ✓ 部署完成：19 個 Worker 全部成功
→ seed 10 個 API recipe... ✓
✓ Cloudflare 資源就緒（7 KV + R2）
✓ 設定寫入 ~/.arcrun/config.yaml
```

你不需要懂 git、不需要懂 tinygo、不需要手動建任何東西——預編譯好的零件（`.wasm`）直接從 GitHub 下載，用**你自己的** CF token 部署到**你的**帳號。

**最後一步（手動，CLI 會印提示）**：設定加密金鑰 secret。這一步刻意不自動化（密鑰不進工具流程）：

```bash
# CLI 會印出確切指令，照貼即可。三個 Worker 共用同一把 key：
wrangler secret put ENCRYPTION_KEY --name arcrun-cypher-executor
wrangler secret put ENCRYPTION_KEY --name arcrun-auth-static-key
wrangler secret put ENCRYPTION_KEY --name arcrun-auth-service-account
# 生成一把 key：node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

完成。之後有新版零件，跑 `acr update` 一樣自動拉新、重部署。

> 想先不碰 Cloudflare、純在本機感受語法？`acr init --local` 然後直接跳到下面「寫一個工作流」。

---

## 裝好之後：開始用

### 寫一個工作流

`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
```

### 要打外部 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` 引用它。

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

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

### 部署 + 觸發

```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>                    查看執行記錄
acr update                         self-hosted：拉新版零件/引擎並重新部署到你的 CF
```

> 給 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)