# arcrun

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

---

## 為什麼做這個？

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

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

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

**解法：把邏輯寫成工作流，零件由社群反覆驗證。**
想到工作流，你可能想到 n8n。很好，arcrun 就是這個方向，但為 AI 優先設計：

| | n8n | arcrun |
|---|---|---|
| 語法 | JSON / 拖拉介面，檔案動輒數千行 | 三行 Cypher，AI 和人都能直接讀 |
| context 消耗 | 大，容易超出 window | 極小，整個 workflow 幾十個 token |
| 零件擴充 | GUI 拖拉，人類操作 | CLI 一行，AI 自己寫零件、自己提交 |
| 執行環境 | 需要自架或付費訂閱 | 從本機一行指令跑起來 |

arcrun 的核心假設：**最好的 AI 協作工具，應該讓 AI 自己能讀、能寫、能執行、能除錯。**

---

## 專案定位

| 層級 | 內容 | 授權 |
|------|------|------|
| **開源核心** | cypher-executor、21 個 WASM 零件、credentials Worker、CLI（`acr`） | MIT |
| **Hosted** | 一行取得 API Key，workflow 和 credential 永遠在你自己的 Cloudflare KV | 免費 |
| **Self-hosted** | Fork 後自行部署，完全掌控 | MIT |

人用也完全沒問題。但每一個設計決定都優先問：「AI 用起來方不方便？」

---

## 快速開始

### 玩法一：從你的電腦直接執行（最快，不需要 Cloudflare）

安裝 CLI，立刻寫一個 workflow 在本機跑：

```bash
npm i -g arcrun
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 Key。直接感受 workflow 跑起來是什麼感覺。

---

### 玩法二：把 Workflow 推到 Cloudflare 雲端執行

workflow 部署到 arcrun.dev，任何地方都能觸發（Webhook、cron、前端按鈕）。

**你只需要一個 email。** 不需要 Cloudflare 帳號、不需要 API Token。

```bash
acr init
```

互動式設定，輸入 email 自動取得 API Key，workflow 和 credential 以 API Key 隔離，多租戶安全。

上傳 credential（加密後才送出，arcrun.dev 只存密文）：

```bash
# 查看某服務需要哪些 credential（以 Notion 為例）
acr auth-recipe scaffold notion

# 建立 credentials.yaml，填入取得的 token
# 查看所有支援的服務
acr auth-recipe list
```

```bash
acr creds push credentials.yaml   # AES-GCM 加密後上傳，token 不離開你的機器
```

加密金鑰在 `acr init` 時已自動取得並存入 config，不需要手動設定。

部署並執行：

```bash
acr push newsletter.yaml
acr run newsletter --input email=user@example.com
```

範例 workflow（訂閱電子報，發感謝信 + 記錄到 Google Sheets）：

```yaml
name: newsletter_subscribe

flow:
  - "input >> 完成後 >> send_thanks"
  - "input >> 完成後 >> save_to_sheet"
  - "send_thanks >> 失敗時 >> notify_error"

config:
  send_thanks:
    to: "{{input.email}}"
    subject: "感謝訂閱！"
    body: "歡迎加入，我們很高興你在這裡。"
    # gmail_token 從 credentials.yaml 自動注入，不需要手動填

  save_to_sheet:
    spreadsheet_id: "your-sheet-id"
    range: "訂閱者!A:B"
    values: [["{{input.email}}", "{{input.timestamp}}"]]

  notify_error:
    chat_id: "your-telegram-chat-id"
    text: "發信失敗：{{input.email}}"
```

---

### 玩法三：完全 Self-hosted

Fork 後把全部 Worker 部署到你自己的 Cloudflare 帳號。你的零件庫、你的執行引擎、你說了算。

```bash
cd cypher-executor && wrangler deploy
cd ../credentials && wrangler deploy
cd ../registry && wrangler deploy
acr init --self-hosted
```

做好零件後可以推回 arcrun 公眾庫，讓所有人受益（見[貢獻零件](#貢獻零件)）。

---

## Workflow 語法

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

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

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

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

---

## 零件

### 關於零件數量

arcrun 目前有 21 個核心零件，你可能覺得不夠用——畢竟 n8n 有幾百個。

但大多數 n8n 零件的本質都是：把一個 HTTP request 包裝成特定服務的格式。arcrun 的 `http_request` 零件本身就能做同樣的事，差別是：**你讓 AI 幫你配置它，而不是等人工寫好一個現成的封裝。**

```bash
# 讓 AI 幫你設定一個 Notion 整合
acr parts scaffold http_request
# AI 填入 Notion API endpoint、headers、body 格式，你貼上 API Key，搞定
```

對 AI 來說，一個彈性的 `http_request` 零件比一百個固定封裝更好用——因為 AI 能讀懂 API 文件，直接組出正確的配置，不需要等有人做 Notion 零件。

### 21 個核心零件

**整合類**（需要 Credential，credential 自動從加密 KV 注入，workflow yaml 裡看不到明文）

| 零件 | 說明 | 所需 Credential |
|------|------|-----------------|
| `gmail` | Gmail 發信 | `gmail_token` |
| `google_sheets` | Google Sheets 讀寫 | `google_oauth` |
| `telegram` | Telegram Bot 發訊息 | `telegram_bot_token` |
| `line_notify` | LINE Notify 發訊息 | `line_token` |
| `http_request` | 任意 HTTP 請求 | — |

**第三方服務整合（Auth Recipe，20 個）**

除了以上核心零件，arcrun 平台預建了 20 個常用服務的認證 recipe，使用方式與一般零件相同，只需上傳對應 credential：

```bash
acr auth-recipe list                    # 列出所有支援服務
acr auth-recipe scaffold notion         # 取得 credentials.yaml 範本 + workflow 範例
```

支援：Notion、Slack、GitHub、OpenAI、Anthropic、Airtable、Discord、Stripe、Twilio、SendGrid、HubSpot、Linear、Shopify、Resend、Supabase、Typeform、Jira、Google Sheets SA、Gmail SA、Google Drive SA

**控制流**

| 零件 | 說明 |
|------|------|
| `if_control` | 條件判斷 |
| `foreach_control` | 迴圈執行 |
| `try_catch` | 錯誤處理 |
| `switch` | 多路路由 |
| `wait` | 延遲等待 |

**資料處理**

| 零件 | 說明 |
|------|------|
| `set` | 設定/賦值變數 |
| `filter` | 陣列過濾 |
| `merge` | 合併物件 |
| `string_ops` | 字串操作 |
| `number_ops` | 數字運算 |
| `array_ops` | 陣列操作 |
| `date_ops` | 日期操作 |

**AI 類**

| 零件 | 說明 |
|------|------|
| `ai_transform_compile` | 自然語言描述 → 轉換規則（Workers AI） |
| `ai_transform_run` | 執行編譯好的 AI 轉換規則 |

**其他**

| 零件 | 說明 |
|------|------|
| `validate_json` | JSON Schema 驗證 |
| `cron` | Cron 排程觸發 |

取得任一零件的 workflow 配置範本：

```bash
acr parts scaffold gmail
```

### 貢獻零件

零件是 `.wasm` 檔案，stdin 進 JSON、stdout 出 JSON。用什麼語言編譯不重要，只要輸出符合 WASI preview1 的 `.wasm` 即可。

**arcrun 的零件主要由 AI 撰寫。** 這個設計決定影響了語言選擇：

| 語言 | 輸出大小 | AI 撰寫品質 | 學習曲線 | 備註 |
|------|---------|------------|---------|------|
| **TinyGo** | 極小（10–80KB） | 優秀 | 低（Go 語法簡單） | 官方零件首選；語法與 TS 差異夠大，AI 不易混淆 |
| **AssemblyScript** | 小（20–150KB） | 良好 | 低（TypeScript 語法） | 社群貢獻首選；TS 開發者上手最快 |
| **Rust** | 小–中（30–300KB） | 良好 | 高（Rust 所有權） | 效能最強；適合複雜演算法零件 |
| C / C++ | 小 | 尚可 | 高 | 不建議，現代語言更好 |

**注意：** AssemblyScript 與 TypeScript 語法高度相似，AI 有時會把純 TS 邏輯直接搬過來造成編譯錯誤。TinyGo 語法差異夠大，AI 出錯率較低。初期如果不確定選哪個，TinyGo 是最穩的選擇。

**AI 可以直接幫你寫零件。** 把 API 文件和 [CONTRIBUTING.md](CONTRIBUTING.md) 一起貼給它，指定語言（TinyGo 或 AssemblyScript），它生成源碼和 `component.contract.yaml`，你編譯、測試、提交：

```bash
acr parts publish ./my-component/
# 沙盒自動驗收（體積、syscall 掃描、Gherkin 測試）
# 通過後立即可用，等人工審核後對所有人開放
```

每個零件都帶統計數字（執行次數 × 成功率），真實使用數據說話。

---

## CLI 指令

```
acr init                           互動式初始化（local / cloud / self-hosted）
acr creds push [file]              加密並上傳 credentials
acr push <workflow.yaml>           部署 workflow
acr run <name> [--input k=v]       執行 workflow
acr validate <workflow.yaml>       執行前驗證（零件存在、credential 已上傳）
acr parts                          列出所有內建零件
acr parts scaffold <comp>          取得零件的 workflow config 範本
acr parts publish <dir>            提交零件至公眾庫
acr auth-recipe list               列出所有第三方服務整合（Notion、Slack 等）
acr auth-recipe info <service>     查看服務需要哪些 credential
acr auth-recipe scaffold <service> 取得 credentials.yaml 範本 + workflow 範例
acr recipe push <file>             上傳自訂 API recipe
acr list                           列出已部署的 workflow
acr logs <name>                    查看執行記錄
```

---

## License

MIT

---

## 致謝

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

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

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