arcrun

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

arcrun 是一套給 AI（Claude Code）用的 harness：你叫 CC 用 arcrun 開發自動化時，它知道能用什麼、不能做什麼，做錯了有機制擋住——讓 CC 順暢、且不容易做歪。

---

為什麼做這個？

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

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

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

問題三：第三方依賴是單點故障。 每多依賴一個不可掌控的第三方（含 SaaS 平台本身），就多一個會掛掉、會漲價、會關服務的風險。

解法：把邏輯寫成純文字工作流，跑在你自己的 Cloudflare 上。 想到工作流你可能想到 n8n。方向一樣，但 arcrun 為 AI 優先設計、且開源自架：

	n8n	arcrun
語法	JSON / 拖拉介面，動輒數千行	三行 Cypher，AI 和人都能直接讀
context 消耗	大，容易超出 window	極小，整個 workflow 幾十個 token
擴充方式	GUI 拖拉，人類操作	寫一段 recipe（純文字），AI 自己會寫
執行環境	需自架或付費訂閱	部署到你自己的 Cloudflare，你說了算

核心假設：最好的 AI 協作工具，應該讓 AI 自己能讀、能寫、能執行、能除錯——而且整套跑在你掌控的環境裡。

---

核心概念：零件 vs recipe（最重要，先讀這個）

arcrun 只有兩種東西，分清楚就不會做歪：

零件（primitive）— 固定的一小套，由維護者管理，你不自製

• 是 WASM 程式，要部署，幾乎不變。只有四類：
  1. 流程控制：if_control / switch / filter / foreach_control / try_catch / wait
  2. 資料處理：string_ops / number_ops / array_ops / date_ops / set / merge / validate_json
  3. http_request：打任意 HTTP
  4. credential（auth）：auth_static_key / auth_service_account / auth_oauth2 / auth_mtls（背後自動注入，你不直接擺）
• 零件不對外連特定服務。 任何「打某個固定 API endpoint」的東西都不是零件——那是 recipe。
• 新增零件走 GitHub PR（人 merge 把關），不是 self-service。日常開發你不會也不該自製零件。

recipe — 你（或 AI）能自由擴充的東西，純文字，不用部署

• recipe = http_request + 一組固定設定（endpoint / method / headers / body 模板）。
• 要打 Notion / Slack / 你自己的 API？寫一個 recipe，不是做一個零件。
• recipe 是純文字、不用 deploy、改一次零成本。AI 讀得懂 API 文件就能幫你組出 recipe。

一句話判準：要打一個固定的外部 endpoint → recipe。要做流程控制 / 資料處理 / 通用 HTTP → 用既有零件。其他大部分情況 → 直接寫工作流把它們串起來。

---

快速開始（Self-hosted）

arcrun 是 self-hosted 開源：你用自己的 Cloudflare 帳號跑整套。一次裝好，之後就是你的，不依賴任何人的服務。

你總共只需要做 4 件事（步驟 1-4），其餘 CLI 自動完成、你只是看著機器跑。

1. 申請 Cloudflare 帳號（免費）

到 dash.cloudflare.com/sign-up 註冊。免費方案（Workers free tier）就足夠跑起來。

註冊後你需要兩個東西——Account ID 和 API Token：

Account ID：登入後在 dash.cloudflare.com 隨便進一個區段，網址列會是 dash.cloudflare.com/<這串就是 Account ID>；或在右側欄 "Account ID" 直接複製。

API Token：到 My Profile → API Tokens → Create Token → Create Custom Token，給以下權限（CLI 用它建 KV / 部署 Worker）：

類型	項目	權限
Account	Workers Scripts	Edit
Account	Workers KV Storage	Edit
Account	Workers R2 Storage	Edit

建好後複製那串 token（只會顯示一次）。CLI 不代管你的憑證——你自己建、自己持有。

2. 安裝 Cloudflare CLI（wrangler）

CLI 部署 Worker 時會用到 wrangler。先裝它：

npm i -g wrangler

3. 安裝 arcrun CLI

npm i -g arcrun

4. 一鍵初始化（其餘全自動）

acr init --self-hosted

CLI 會問你 Account ID 和 API Token（步驟 1 取得的），貼上後它自動完成：

→ 驗證 Cloudflare 憑證... ✓
→ KV WEBHOOKS... ✓   （建 7 個 KV namespace，已存在則重用）
→ R2 WASM_BUCKET... ✓
→ workers.dev subdomain: your-account
→ 下載部署物 + 部署 Worker（從 GitHub 拉預編譯 wasm，用你的 CF token 部署）...
  ✓ 部署完成：19 個 Worker 全部成功
→ seed 10 個 API recipe... ✓
✓ Cloudflare 資源就緒（7 KV + R2）
✓ 設定寫入 ~/.arcrun/config.yaml

你不需要懂 git、不需要懂 tinygo、不需要手動建任何東西——預編譯好的零件（.wasm）直接從 GitHub 下載，用你自己的 CF token 部署到你的帳號。

最後一步（手動，CLI 會印提示）：設定加密金鑰 secret。這一步刻意不自動化（密鑰不進工具流程）：

# CLI 會印出確切指令，照貼即可。三個 Worker 共用同一把 key：
wrangler secret put ENCRYPTION_KEY --name arcrun-cypher-executor
wrangler secret put ENCRYPTION_KEY --name arcrun-auth-static-key
wrangler secret put ENCRYPTION_KEY --name arcrun-auth-service-account
# 生成一把 key：node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

完成。之後有新版零件，跑 acr update 一樣自動拉新、重部署。

想先不碰 Cloudflare、純在本機感受語法？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？寫一個 recipe（不是做零件）

# 上傳一個打外部 API 的 recipe（push 時會幫你檢查打不打得通）
acr recipe push my_api_recipe.yaml

recipe 裡寫好 endpoint / method / body 模板，credential 由 auth 自動注入。workflow 裡用 component: <recipe 名> 或 component: rec_xxxx 引用它。

上傳 credential（client 端加密，明文不離開你的機器）

acr auth-recipe list              # 看支援哪些服務的認證
acr auth-recipe scaffold notion   # 取得 credentials.yaml 範本
acr creds push credentials.yaml   # AES-GCM 加密後上傳到你自己的 KV

部署 + 觸發

acr push newsletter.yaml          # 部署，取得 Webhook URL
acr run newsletter --input email=user@example.com

⚠️ 部署對外 webhook = 把東西暴露給外界。 acr push 產生的 trigger URL 任何拿到的人都能打。CLI 會在這類動作前提醒你——確認後就是你的責任（你可以選擇加上 API Key 限制 / 權限）。

---

Workflow 語法

"A >> 關係詞 >> B"

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

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

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

---

為什麼零件這麼少？（這是特性，不是缺陷）

你可能覺得「才這幾個零件，n8n 有幾百個」。但 n8n 那幾百個零件，本質多半是「把一個 HTTP request 包成某服務的格式」。在 arcrun，那些全部是 recipe——純文字、AI 幫你寫、不用等誰先做好封裝。

對 AI 來說，一個彈性的 http_request + recipe，比一百個固定零件封裝更好用：AI 讀得懂 API 文件，直接組出正確的 recipe，不必等有人做「Notion 零件」。

零件少 = 攻擊面小、要驗證的東西少、整套能塞進 AI 的 context。長尾交給 recipe，核心保持精簡，是刻意的設計。

---

recipe 入庫把關（誠實說明）

• 自有庫（你的 self-hosted）：acr recipe push 時 CLI 會 (1) 提醒會不會把資料/服務暴露給外界、(2) 幫你實打一次看 API 通不通（2xx）。這是提醒級——arcrun 不替你做授權判斷，打不打得通最終由發 API key 的服務裁決。打不通會誠實標原因（例：缺 credential），不會假裝成功。
• 公共庫（未來）：recipe 要貢獻給別人用、進公共庫時，由維護者機制檢核「實際打通、真收到成功回傳」（投稿者不能自己驗證自己）。此機制在第一期之後啟用。

---

CLI 指令

acr init --self-hosted             一鍵部署到你的 Cloudflare（貼 token，其餘自動）
acr init --local                   純本機體驗語法，不需 Cloudflare
acr creds push [file]              client 端加密並上傳 credentials
acr recipe push <file>             上傳 API recipe（push 時提醒暴露 + 檢查打通）
acr push <workflow.yaml>           部署 workflow，取得 Webhook URL
acr run <name> [--input k=v]       執行 workflow
acr validate <workflow.yaml>       執行前驗證格式 / 關係詞 / credential
acr parts                          列出可用的核心零件
acr parts scaffold <comp>          取得零件的 workflow config 範本
acr auth-recipe list               列出支援的第三方服務認證
acr auth-recipe scaffold <service> 取得 credentials.yaml 範本 + workflow 範例
acr list                           列出已部署的 workflow
acr logs <name>                    查看執行記錄
acr update                         self-hosted：拉新版零件/引擎並重新部署到你的 CF

給 AI 操盤手：開始前讀 .claude/rules/06-mindset.md（或 arcrun-mindset Skill）——它說明 arcrun 的世界觀（工作流是 default、零件稀有且不自製、一切外部 API 皆 recipe），讓你一開始就走在正路上。

---

設計原則（節錄）

• 減少對不可控第三方的依賴：核心 MIT 開源、self-hosted、workflow 是你擁有的純文字。
• 解耦 / 原子化：零件、recipe、執行引擎彼此可獨立替換。
• arcrun 是 AI 用的工具：需要 AI 判斷時是操盤的 CC 自己做，工作流裡不內嵌回頭呼叫 LLM 的節點。
• 誠實：stub / 未驗證就如實標明，不假裝成功；完成以客觀證據（HTTP status / trace）為準。

完整決策見 DECISIONS.md。

---

License

MIT

---

致謝

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

• @richblack — 創始人，產品設計與架構決策
• Claude（Anthropic） — 實作夥伴：零件開發、executor 架構、CLI 實作與程式碼審查

歡迎加入：CONTRIBUTING.md