Arcrun/README.md

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 在本機跑：

npm i -g arcrun
acr init --local

建立 hello.yaml：

name: hello
flow:
  - "input >> 完成後 >> transform"
config:
  transform:
    component: string_ops
    operation: upper

執行：

acr run hello --input input="Hello, world"

結果：HELLO WORLD

不需要帳號、不需要部署、不需要 API Key。直接感受 workflow 跑起來是什麼感覺。

---

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

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

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

acr init

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

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

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

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

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

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

部署並執行：

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

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

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 帳號。你的零件庫、你的執行引擎、你說了算。

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 幫你配置它，而不是等人工寫好一個現成的封裝。

# 讓 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：

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 配置範本：

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 一起貼給它，指定語言（TinyGo 或 AssemblyScript），它生成源碼和 component.contract.yaml，你編譯、測試、提交：

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 — 創始人，產品設計與架構決策
• Claude Sonnet（Anthropic） — 核心實作夥伴，負責零件開發、executor 架構、CLI 實作與程式碼審查

歡迎加入：CONTRIBUTING.md