Leo
4516cdee4b
- landing/: Next.js 15 app for arcrun.dev (dashboard, integrations, API docs, login). Deploys via Cloudflare Pages — CI scan skips this via pages_build_output_dir marker. - builtins/: minimal Hono Worker at arcrun-builtins (/init for one-shot component registry seeding). initComponents logic is flagged stale in src/index.ts for future rewrite. - BETA_TEST.md: pre-launch validation playbook. - README.md: updated to match current arcrun.dev / acr CLI flow. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
321 lines
10 KiB
Markdown
321 lines
10 KiB
Markdown
# 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)
|