Leo/Arcrun
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fb2d0b0c2d0520d5457b7ad3acfbbcc99f44de5c
Arcrun/README.md
T
Leo fb2d0b0c2d feat(self-hosted): acr init --self-hosted installer + recipe push 把關 + commit 部署 wasm 
讓任何 CC 用自己的 CF 帳號一鍵 self-host arcrun（戰法轉 self-hosted 開源）。

Task 1 — acr init --self-hosted installer（用戶只給 CF Account ID + token，其餘自動）：
- cli/src/lib/cf-api.ts: CfAccountClient（驗 token / 建 KV 冪等 / 建 R2 / 查 workers.dev subdomain）
- cli/src/lib/deploy.ts: 從 GitHub codeload tarball 拉部署物 → 注入用戶 KV id → wrangler deploy
  （tier1 component-builds 先、tier2 cypher-executor/registry 後；部分失敗誠實回報不假綠）
- cli/src/lib/api-recipe-seeds.ts: 10 個現役 API recipe 種子（KBDB 採 Supabase 模式）
- cli/src/commands/init.ts: initSelfHosted() 改寫成 installer 流程
- cli/src/commands/update.ts: acr update（拉新 ref 重部署）
- cypher-executor/scripts/seed-api-recipes.ts: prod 補灌腳本

Task 2 — recipe 入庫把關（封鎖自製零件後，CC 唯一能擴充的是 recipe）：
- cli/src/commands/recipe.ts: 新增 probeRecipeEndpoint 打通檢查（提醒級不硬擋，
  含模板誠實說明待 run 才知，401/403 標多半缺 credential 非 bug）
- 資料外流提醒沿用既有 obtainExposureConsent（非 TTY 拒絕）

部署物產製：commit 預編譯 wasm 進 repo（推翻 rule 05「wasm 不 commit」）：
- .gitignore: 放行 .component-builds/**/component.wasm（registry 中間產物仍排除）
- 只 commit 19 個正當零件 wasm；claude_api / km_writer / kbdb_upsert_block 排除
  （非薄殼、是把工作流硬塞進零件，違反 DECISIONS §1，待降級）
- rule 05 同步記錄此慣例變更 + 膨脹 trade-off

SDD: sdk-and-website/self-hosted-init.md（installer 定案）、
     component-gatekeeping/recipe-push-gatekeeping.md（recipe 把關）
README 重寫成單一 self-hosted 路徑。CLI typecheck exit 0。

未完（待 richblack）：push 此 commit 到 GitHub 後 codeload 才拿得到 wasm；
用第二 CF 帳號端對端驗收 acr init --self-hosted。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-02 18:44:41 +08:00

9.4 KiB
Raw Blame History

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 帳號跑整套。一次裝好，之後就是你的。

1. 取得 Cloudflare 憑證

你需要一個 CF 帳號，並在 dashboard 建一個 API Token（權限：Workers Scripts Edit + KV Storage Edit + Workers R2 Storage Edit）。CLI 不代管你的憑證——你自己建、自己持有。

2. 一鍵初始化

npm i -g arcrun
acr init --self-hosted

貼上 CF Account ID + API Token，CLI 自動：建立所需 KV、部署所有 Worker（含執行引擎 cypher-executor 與全部零件）、啟用 workers.dev、寫回設定。跑完會提示你手動設定 runtime secret（如 ENCRYPTION_KEY），這一步刻意不自動化（secret 不進工具流程）。

想先不碰 Cloudflare、純在本機感受語法？acr init --local 然後 acr run。

3. 寫一個工作流

hello.yaml：

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

acr run hello --input input="Hello, world"   # → HELLO WORLD

4. 要打外部 API？寫一個 recipe（不是做零件）

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

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

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

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

6. 部署 + 觸發

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>                    查看執行記錄

給 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

Reference in New Issue View Git Blame Copy Permalink