Leo
c4351e4b7f
README: add language comparison table in contributing section, explain AI writing quality differences and why TinyGo is recommended for official components. CONTRIBUTING: full rewrite with separate TinyGo + AssemblyScript sections, each with AI prompt templates, code templates, build commands, and test commands. Rust documented as supported with basic setup reference. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
299 lines
9.4 KiB
Markdown
299 lines
9.4 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:
|
||
- "start >> 完成後 >> transform"
|
||
- "transform >> 完成後 >> output"
|
||
config:
|
||
transform:
|
||
input: "{{start.text}}"
|
||
```
|
||
|
||
執行：
|
||
|
||
```bash
|
||
acr run hello --input text="Hello, world"
|
||
```
|
||
|
||
不需要帳號、不需要部署、不需要 API Key。直接感受 workflow 跑起來是什麼感覺。
|
||
|
||
---
|
||
|
||
### 玩法二：把 Workflow 推到 Cloudflare 雲端執行
|
||
|
||
workflow 放到 Cloudflare KV，任何地方都能觸發（Webhook、cron、前端按鈕）。
|
||
|
||
**你需要的只是一個免費的 Cloudflare 帳號和一個 KV namespace。**
|
||
|
||
```bash
|
||
acr init
|
||
```
|
||
|
||
互動式問答引導你完成設定：Cloudflare Account ID、KV Namespace ID、API Token、Email。取得 API Key 後，credential 和 workflow 都只存在你自己的 CF KV，arcrun.dev 不儲存任何東西。
|
||
|
||
設定 credential：
|
||
|
||
```yaml
|
||
# credentials.yaml — 不要提交至 git（已自動加入 .gitignore）
|
||
gmail_token: "ya29.your-google-oauth-token"
|
||
telegram_bot_token: "1234567890:ABCxxx"
|
||
```
|
||
|
||
```bash
|
||
acr creds push credentials.yaml # AES-GCM 加密後存入你的 KV
|
||
```
|
||
|
||
部署並執行：
|
||
|
||
```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 請求 | — |
|
||
|
||
**控制流**
|
||
|
||
| 零件 | 說明 |
|
||
|------|------|
|
||
| `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 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)
|