Leo/Arcrun
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rewrite README — AI-first positioning, 3 quick-start modes

Browse Source 
- Lead with the AI collaboration pain points (token cost, debug friction)
- Position vs n8n: same concept, AI-friendly syntax
- 3 quick-start paths: local (no CF needed), cloud (KV only), self-hosted
- Reframe 21 components: http_request + AI config beats 100 fixed wrappers
- Component contribution section: emphasize AI writes the component
- Updated project positioning table (drop paid tier mention)
- Add acknowledgements with Claude Sonnet as co-author

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
richblack
2026-04-16 13:39:32 +08:00
parent e630fca2df
commit 2da65c43a9
1 changed files with 154 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+154 -101
View File
@@ -1,85 +1,127 @@
# arcrun # arcrun
**AI Workflow Execution Engine** — 以 WASM 零件為基礎的 Cloudflare Workers 工作流平台。 **讓 AI 把想法直接變成自動化工作流，而不是一行一行寫程式。**
定義一個 workflow，串接 Gmail、Telegram、Google Sheets 等服務，無需伺服器，直接跑在 Cloudflare Edge。 ---
## 為什麼做這個？
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 License | | **開源核心** | cypher-executor、21 個 WASM 零件、credentials Worker、CLI（`acr`） | MIT |
| **Hosted SaaS** | 一行指令取得 API Key，使用 arcrun.dev 的執行引擎與公眾零件庫，credential 永遠在你自己的 CF KV | 免費 | | **Hosted** | 一行取得 API Key，workflow 和 credential 永遠在你自己的 Cloudflare KV | 免費 |
| **InkStone 付費** | KBDB 向量搜尋、Graph 查詢、Persona SDK、MatchGPT | 付費方案 | | **Self-hosted** | Fork 後自行部署，完全掌控 | MIT |
**你的 credential 和 workflow 永遠在你自己的 Cloudflare KV，arcrun.dev 不儲存它們。** 人用也完全沒問題。但每一個設計決定都優先問：「AI 用起來方不方便？」
--- ---
## 快速開始 — Standard 模式（推薦，零部署） ## 快速開始
只需在 Cloudflare 建立一個 KV namespace，其餘由 arcrun.dev 處理。 ### 玩法一：從你的電腦直接執行（最快，不需要 Cloudflare）
### 安裝 CLI 安裝 CLI，立刻寫一個 workflow 在本機跑：
```bash ```bash
npm i -g arcrun npm i -g arcrun
acr init --local
``` ```
### 1. 初始化 建立 `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 ```bash
acr init acr init
``` ```
互動式問答： 互動式問答引導你完成設定：Cloudflare Account ID、KV Namespace ID、API Token、Email。取得 API Key 後，credential 和 workflow 都只存在你自己的 CF KV，arcrun.dev 不儲存任何東西。
- Cloudflare Account ID
- USER_KV Namespace ID（在 [CF Dashboard](https://dash.cloudflare.com) 建立一個 KV）
- CF API Token（只需 KV Edit 權限）
- Email（取得 arcrun.dev API Key）
### 2. 設定 Credential 設定 credential：
建立 `credentials.yaml`（已自動加入 `.gitignore`）：
```yaml ```yaml
# credentials.yaml — 不要提交至 git！ # credentials.yaml — 不要提交至 git（已自動加入 .gitignore）
gmail_token: "ya29.your-google-oauth-token" gmail_token: "ya29.your-google-oauth-token"
telegram_bot_token: "1234567890:ABCxxx" telegram_bot_token: "1234567890:ABCxxx"
``` ```
上傳加密 credential 至你的 CF KV：
```bash ```bash
acr creds push credentials.yaml acr creds push credentials.yaml # AES-GCM 加密後存入你的 KV
``` ```
### 3. 部署 Workflow 部署並執行：
建立 `newsletter_subscribe.yaml`： ```bash
acr push newsletter.yaml
acr run newsletter --input email=user@example.com
```
範例 workflow（訂閱電子報，發感謝信 + 記錄到 Google Sheets）：
```yaml ```yaml
name: newsletter_subscribe name: newsletter_subscribe
description: 訂閱電子報，發感謝信並記錄到 GSheets
flow: flow:
- "input >> 完成後 >> send_thanks" - "input >> 完成後 >> send_thanks"
- "input >> 完成後 >> save_to_sheet" - "input >> 完成後 >> save_to_sheet"
- "send_thanks >> 完成後 >> output"
- "send_thanks >> 失敗時 >> notify_error" - "send_thanks >> 失敗時 >> notify_error"
- "save_to_sheet >> 完成後 >> output"
config: config:
send_thanks: send_thanks:
to: "{{input.email}}" to: "{{input.email}}"
subject: "感謝訂閱！" subject: "感謝訂閱！"
body: "歡迎加入！" body: "歡迎加入，我們很高興你在這裡。"
# access_token 由 credentials.yaml 的 gmail_token 自動注入 # gmail_token 從 credentials.yaml 自動注入，不需要手動填
save_to_sheet: save_to_sheet:
action: write
spreadsheet_id: "your-sheet-id" spreadsheet_id: "your-sheet-id"
range: "訂閱者!A:B" range: "訂閱者!A:B"
values: [["{{input.email}}", "{{input.timestamp}}"]] values: [["{{input.email}}", "{{input.timestamp}}"]]
@@ -89,75 +131,72 @@ config:
text: "發信失敗：{{input.email}}" text: "發信失敗：{{input.email}}"
``` ```
部署：
```bash
acr push newsletter_subscribe.yaml
```
### 4. 執行
```bash
acr run newsletter_subscribe --input email=user@example.com timestamp=2026-01-01
```
--- ---
## 快速開始 — Self-hosted 模式 ### 玩法三：完全 Self-hosted
自行部署所有 Worker 到你的 Cloudflare 帳號。 Fork 後把全部 Worker 部署到你自己的 Cloudflare 帳號。你的零件庫、你的執行引擎、你說了算。
```bash ```bash
# 1. 部署 cypher-executor cd cypher-executor && wrangler deploy
cd cypher-executor cd ../credentials && wrangler deploy
wrangler deploy cd ../registry && wrangler deploy
# 2. 部署 credentials Worker
cd ../credentials
wrangler deploy
# 3. 初始化 CLI（Self-hosted 模式）
acr init --self-hosted acr init --self-hosted
``` ```
做好零件後可以推回 arcrun 公眾庫，讓所有人受益（見[貢獻零件](#貢獻零件)）。
--- ---
## Workflow YAML 語法 ## Workflow 語法
### 三元組格式
``` ```
"A >> 關係詞 >> B" "A >> 關係詞 >> B"
``` ```
### 合法關係詞 這就是全部。每一行是一條邊，描述 A 之後發生什麼事。
| 關係詞 | 英文別名 | 說明 | | 關係詞 | 別名 | 說明 |
|--------|----------|------| |--------|------|------|
| `完成後` | `ON_SUCCESS` | 上游成功後執行 | | `完成後` | `ON_SUCCESS` | A 成功後執行 B |
| `失敗時` | `ON_FAIL` | 上游失敗時執行 | | `失敗時` | `ON_FAIL` | A 失敗時執行 B |
| `對每個` | `FOREACH` | 迭代執行 | | `對每個` | `FOREACH` | 對 A 的每個元素執行 B |
| `條件滿足時` | `IF` | 條件分支 | | `條件滿足時` | `IF` | 條件為真時執行 B |
| `ON_CLICK` | — | 前端點擊觸發 | | `CALLS_SUBFLOW` | — | 呼叫另一個 workflow |
| `CALLS_SUBFLOW` | — | 呼叫子 workflow |
> `PIPE` 已棄用，請改用 `完成後` 或 `ON_SUCCESS`。 整個 workflow 通常不超過十行，AI 一眼掃完不需要捲動。
--- ---
## 零件列表（21 個） ## 零件
### 整合類（需要 Credential） ### 關於零件數量
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 | | 零件 | 說明 | 所需 Credential |
|------|------|-----------------| |------|------|-----------------|
| `gmail` | Gmail 發信 | `gmail_token`（Google OAuth） | | `gmail` | Gmail 發信 | `gmail_token` |
| `google_sheets` | Google Sheets 讀寫 | `google_oauth`（Google OAuth） | | `google_sheets` | Google Sheets 讀寫 | `google_oauth` |
| `telegram` | Telegram Bot 發訊息 | `telegram_bot_token` | | `telegram` | Telegram Bot 發訊息 | `telegram_bot_token` |
| `line_notify` | LINE Notify 發訊息 | `line_token` | | `line_notify` | LINE Notify 發訊息 | `line_token` |
| `http_request` | HTTP 請求（手動設 headers） | — | | `http_request` | 任意 HTTP 請求 | — |
### 控制流 **控制流**
| 零件 | 說明 | | 零件 | 說明 |
|------|------| |------|------|
@@ -167,11 +206,11 @@ acr init --self-hosted
| `switch` | 多路路由 | | `switch` | 多路路由 |
| `wait` | 延遲等待 | | `wait` | 延遲等待 |
### 資料處理 **資料處理**
| 零件 | 說明 | | 零件 | 說明 |
|------|------| |------|------|
| `set` | 設定/賦值 | | `set` | 設定/賦值變數 |
| `filter` | 陣列過濾 | | `filter` | 陣列過濾 |
| `merge` | 合併物件 | | `merge` | 合併物件 |
| `string_ops` | 字串操作 | | `string_ops` | 字串操作 |
@@ -179,52 +218,55 @@ acr init --self-hosted
| `array_ops` | 陣列操作 | | `array_ops` | 陣列操作 |
| `date_ops` | 日期操作 | | `date_ops` | 日期操作 |
### AI 類 **AI 類**
| 零件 | 說明 | | 零件 | 說明 |
|------|------| |------|------|
| `ai_transform_compile` | AI 轉換規則編譯（Workers AI） | | `ai_transform_compile` | 自然語言描述 → 轉換規則（Workers AI） |
| `ai_transform_run` | AI 轉換執行 | | `ai_transform_run` | 執行編譯好的 AI 轉換規則 |
### 其他 **其他**
| 零件 | 說明 | | 零件 | 說明 |
|------|------| |------|------|
| `validate_json` | JSON Schema 驗證 | | `validate_json` | JSON Schema 驗證 |
| `cron` | Cron 排程觸發 | | `cron` | Cron 排程觸發 |
取得任一零件的 config 範本： 取得任一零件的 workflow 配置範本：
```bash ```bash
acr parts scaffold gmail acr parts scaffold gmail
``` ```
### 貢獻零件
零件是 TinyGo 編譯的 `.wasm` 檔案，stdin 進 JSON、stdout 出 JSON，就這樣。
**AI 可以直接幫你寫零件。** 把 API 文件和 [CONTRIBUTING.md](CONTRIBUTING.md) 一起貼給它，它生成 `main.go` 和 `component.contract.yaml`，你編譯、測試、提交：
```bash
acr parts publish ./my-component/
# 沙盒自動驗收（體積、syscall 掃描、Gherkin 測試）
# 通過後立即可用，等人工審核後對所有人開放
```
每個零件都帶統計數字（執行次數 × 成功率），真實使用數據說話。
--- ---
## CLI 指令 ## CLI 指令
``` ```
acr init 互動式初始化設定 acr init 互動式初始化（local / cloud / self-hosted）
acr creds push [file] 上傳加密 credentials 至 CF KV acr creds push [file] 加密並上傳 credentials
acr push <workflow.yaml> 部署 workflow acr push <workflow.yaml> 部署 workflow
acr run <name> [--input] 執行 workflow acr run <name> [--input k=v] 執行 workflow
acr validate <workflow.yaml> 執行前驗證 acr validate <workflow.yaml> 執行前驗證（零件存在、credential 已上傳）
acr parts 列出所有零件（含統計） acr parts 列出所有零件（含執行統計）
acr parts scaffold <comp> 取得 config 範本 acr parts scaffold <comp> 取得零件的 workflow config 範本
acr parts publish <dir> 提交零件至公眾庫 acr parts publish <dir> 提交零件至公眾庫
acr list 列出已部署的 workflow acr list 列出已部署的 workflow
acr logs <name> 查看執行記錄 acr logs <name> 查看執行記錄
```
---
## 貢獻零件
詳見 [CONTRIBUTING.md](CONTRIBUTING.md)。
```bash
# 提交零件至公眾 registry（審核通過後對所有人開放）
acr parts publish ./my-component/
``` ```
--- ---
@@ -232,3 +274,14 @@ acr parts publish ./my-component/
## License ## License
MIT MIT
---
## 致謝
arcrun 的核心架構、21 個 WASM 零件、CLI 工具鏈與這份文件，由以下貢獻者共同打造：
- **[@richblack](https://github.com/richblack)** — 創始人，產品設計與架構決策
- **[Claude Sonnet](https://claude.ai)（Anthropic）** — 核心實作夥伴，負責零件開發、executor 架構、CLI 實作與程式碼審查
歡迎加入：[CONTRIBUTING.md](CONTRIBUTING.md)