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

feat(self-hosted): acr init --self-hosted installer + recipe push 把關 + commit 部署 wasm

Browse Source 
讓任何 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>
This commit is contained in:
richblack
2026-06-02 18:44:41 +08:00
parent 51d40ee515
commit fb2d0b0c2d
35 changed files with 1448 additions and 224 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+93 -207
View File
@@ -2,56 +2,81 @@
**讓 AI 把想法直接變成自動化工作流，而不是一行一行寫程式。**
arcrun 是一套**給 AI（Claude Code）用的 harness**：你叫 CC 用 arcrun 開發自動化時，它知道能用什麼、不能做什麼，做錯了有機制擋住——讓 CC 順暢、且不容易做歪。
---
## 為什麼做這個？
AI 愈來愈強，但跟 AI 協作還是很有摩擦：
AI 愈來愈強，但跟 AI 協作做自動化還是很有摩擦：
**問題一：AI 調 API 太耗 token。**
每次讓 AI 幫你查資料、發郵件、寫入試算表，它都要在對話裡描述、確認、執行，token 燒很快。更好的做法是讓 AI 把任務寫成一次性的程式，之後直接執行。
每次讓 AI 幫你查資料、發信、寫試算表，它都要在對話裡描述、確認、執行，token 燒很快。更好的做法是讓 AI 把任務寫成一次性的工作流，之後直接執行。
**問題二：AI 寫程式容易出 bug，debug 又耗時。**
讓 AI 從頭寫一個完整的爬蟲或自動化腳本，十次有八次要來回修。根本原因是零件沒有被複用——每次都是全新的程式。
**問題二：AI 從頭寫腳本容易出 bug。**
讓 AI 從零寫一整個自動化腳本，十次有八次要來回修。根本原因是邏輯沒被複用——每次都是全新的程式。
**解法：把邏輯寫成工作流，零件由社群反覆驗證。**
想到工作流，你可能想到 n8n。很好，arcrun 就是這個方向，但為 AI 優先設計：
**問題三：第三方依賴是單點故障。**
每多依賴一個不可掌控的第三方（含 SaaS 平台本身），就多一個會掛掉、會漲價、會關服務的風險。
**解法：把邏輯寫成純文字工作流，跑在你自己的 Cloudflare 上。**
想到工作流你可能想到 n8n。方向一樣，但 arcrun 為 AI 優先設計、且**開源自架**：
| | n8n | arcrun |
|---|---|---|
| 語法 | JSON / 拖拉介面，檔案動輒數千行 | 三行 Cypher，AI 和人都能直接讀 |
| 語法 | JSON / 拖拉介面，動輒數千行 | 三行 Cypher，AI 和人都能直接讀 |
| context 消耗 | 大，容易超出 window | 極小，整個 workflow 幾十個 token |
| 零件擴充 | GUI 拖拉，人類操作 | CLI 一行，AI 自己寫零件、自己提交 |
| 執行環境 | 需要自架或付費訂閱 | 從本機一行指令跑起來 |
| 擴充方式 | GUI 拖拉，人類操作 | 寫一段 recipe（純文字），AI 自己會寫 |
| 執行環境 | 需自架或付費訂閱 | 部署到**你自己的** Cloudflare，你說了算 |
arcrun 的核心假設：**最好的 AI 協作工具，應該讓 AI 自己能讀、能寫、能執行、能除錯。**
核心假設：**最好的 AI 協作工具，應該讓 AI 自己能讀、能寫、能執行、能除錯——而且整套跑在你掌控的環境裡。**
---
## 專案定位
## 核心概念：零件 vs recipe（最重要，先讀這個）
| 層級 | 內容 | 授權 |
|------|------|------|
| **開源核心** | cypher-executor、21 個 WASM 零件、credentials Worker、CLI（`acr`） | MIT |
| **Hosted** | 一行取得 API Key，workflow 和 credential 永遠在你自己的 Cloudflare KV | 免費 |
| **Self-hosted** | Fork 後自行部署，完全掌控 | MIT |
arcrun 只有兩種東西，分清楚就不會做歪：
人用也完全沒問題。但每一個設計決定都優先問：「AI 用起來方不方便？」
### 零件（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）
### 玩法一：從你的電腦直接執行（最快，不需要 Cloudflare）
arcrun 是 self-hosted 開源：你用自己的 Cloudflare 帳號跑整套。一次裝好，之後就是你的。
安裝 CLI，立刻寫一個 workflow 在本機跑：
### 1. 取得 Cloudflare 憑證
你需要一個 CF 帳號，並在 dashboard 建一個 **API Token**（權限：Workers Scripts Edit + KV Storage Edit + Workers R2 Storage Edit）。CLI 不代管你的憑證——你自己建、自己持有。
### 2. 一鍵初始化
```bash
npm i -g arcrun
acr init --local
acr init --self-hosted
```
建立 `hello.yaml`：
貼上 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`：
```yaml
name: hello
@@ -63,95 +88,35 @@ config:
operation: upper
```
執行：
```bash
acr run hello --input input="Hello, world"
acr run hello --input input="Hello, world" # → HELLO WORLD
```
結果：`HELLO WORLD`
不需要帳號、不需要部署、不需要 API Key。直接感受 workflow 跑起來是什麼感覺。
---
### 玩法二：把 Workflow 推到 Cloudflare 雲端執行
workflow 部署到 arcrun.dev，任何地方都能觸發（Webhook、cron、前端按鈕）。
**你只需要一個 email。** 不需要 Cloudflare 帳號、不需要 API Token。
### 4. 要打外部 API？寫一個 recipe（不是做零件）
```bash
acr init
# 上傳一個打外部 API 的 recipe（push 時會幫你檢查打不打得通）
acr recipe push my_api_recipe.yaml
```
互動式設定，輸入 email 自動取得 API Key，workflow 和 credential 以 API Key 隔離，多租戶安全。
recipe 裡寫好 endpoint / method / body 模板，credential 由 auth 自動注入。workflow 裡用 `component: <recipe 名>` 或 `component: rec_xxxx` 引用它。
上傳 credential（加密後才送出，arcrun.dev 只存密文）：
### 5. 上傳 credential（client 端加密，明文不離開你的機器）
```bash
# 查看某服務需要哪些 credential（以 Notion 為例）
acr auth-recipe scaffold notion
# 建立 credentials.yaml，填入取得的 token
# 查看所有支援的服務
acr auth-recipe list
acr auth-recipe list # 看支援哪些服務的認證
acr auth-recipe scaffold notion # 取得 credentials.yaml 範本
acr creds push credentials.yaml # AES-GCM 加密後上傳到你自己的 KV
```
```bash
acr creds push credentials.yaml # AES-GCM 加密後上傳，token 不離開你的機器
```
加密金鑰在 `acr init` 時已自動取得並存入 config，不需要手動設定。
部署並執行：
### 6. 部署 + 觸發
```bash
acr push newsletter.yaml
acr push newsletter.yaml # 部署，取得 Webhook URL
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 公眾庫，讓所有人受益（見[貢獻零件](#貢獻零件)）。
> ⚠️ **部署對外 webhook = 把東西暴露給外界。** `acr push` 產生的 trigger URL 任何拿到的人都能打。CLI 會在這類動作前提醒你——確認後就是你的責任（你可以選擇加上 API Key 限制 / 權限）。
---
@@ -161,147 +126,68 @@ acr init --self-hosted
"A >> 關係詞 >> B"
```
這就是全部。每一行是一條邊，描述 A 之後發生什麼事。
這就是全部。每一行是一條邊，描述 A 之後發生什麼。
| 關係詞 | 別名 | 說明 |
|--------|------|------|
| `完成後` | `ON_SUCCESS` | A 成功後執行 B |
| `失敗時` | `ON_FAIL` | A 失敗時執行 B |
| `對每個` | `FOREACH` | 對 A 的每個元素執行 B |
| `對每個` | `FOREACH` | 對 A 的每個元素執行 B（支援 `對每個 X` 命名）|
| `條件滿足時` | `IF` | 條件為真時執行 B |
| `CALLS_SUBFLOW` | — | 呼叫另一個 workflow |
整個 workflow 通常不超過十行，AI 一眼掃完不需要捲動。
整個 workflow 通常不超過十行，AI 一眼掃完不需捲動。
---
## 零件
## 為什麼零件這麼少？（這是特性，不是缺陷）
### 關於零件數量
你可能覺得「才這幾個零件，n8n 有幾百個」。但 n8n 那幾百個零件，本質多半是「把一個 HTTP request 包成某服務的格式」。在 arcrun，那些**全部是 recipe**——純文字、AI 幫你寫、不用等誰先做好封裝。
arcrun 目前有 21 個核心零件，你可能覺得不夠用——畢竟 n8n 有幾百個。
對 AI 來說，一個彈性的 `http_request` + recipe，比一百個固定零件封裝更好用：AI 讀得懂 API 文件，直接組出正確的 recipe，不必等有人做「Notion 零件」。
但大多數 n8n 零件的本質都是：把一個 HTTP request 包裝成特定服務的格式。arcrun 的 `http_request` 零件本身就能做同樣的事，差別是：**你讓 AI 幫你配置它，而不是等人工寫好一個現成的封裝。**
零件少 = 攻擊面小、要驗證的東西少、整套能塞進 AI 的 context。**長尾交給 recipe，核心保持精簡**，是刻意的設計。
```bash
# 讓 AI 幫你設定一個 Notion 整合
acr parts scaffold http_request
# AI 填入 Notion API endpoint、headers、body 格式，你貼上 API Key，搞定
```
---
對 AI 來說，一個彈性的 `http_request` 零件比一百個固定封裝更好用——因為 AI 能讀懂 API 文件，直接組出正確的配置，不需要等有人做 Notion 零件。
## recipe 入庫把關（誠實說明）
### 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：
```bash
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 配置範本：
```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 測試）
# 通過後立即可用，等人工審核後對所有人開放
```
每個零件都帶統計數字（執行次數 × 成功率），真實使用數據說話。
- **自有庫（你的 self-hosted）**：`acr recipe push` 時 CLI 會 (1) 提醒會不會把資料/服務暴露給外界、(2) 幫你實打一次看 API 通不通（2xx）。這是**提醒級**——arcrun 不替你做授權判斷，打不打得通最終由發 API key 的服務裁決。打不通會誠實標原因（例：缺 credential），不會假裝成功。
- **公共庫（未來）**：recipe 要貢獻給別人用、進公共庫時，由維護者機制檢核「實際打通、真收到成功回傳」（投稿者不能自己驗證自己）。此機制在第一期之後啟用。
---
## CLI 指令
```
acr init 互動式初始化（local / cloud / self-hosted）
acr creds push [file] 加密並上傳 credentials
acr push <workflow.yaml> 部署 workflow
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 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 list 列出支援的第三方服務認證
acr auth-recipe scaffold <service> 取得 credentials.yaml 範本 + workflow 範例
acr recipe push <file> 上傳自訂 API recipe
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`](DECISIONS.md)。
---
## License
@@ -312,9 +198,9 @@ MIT
## 致謝
arcrun 的核心架構、21 個 WASM 零件、CLI 工具鏈與這份文件，由以下貢獻者共同打造：
arcrun 的核心架構、WASM 零件、CLI 工具鏈與這份文件，由以下貢獻者共同打造：
- **[@richblack](https://github.com/richblack)** — 創始人，產品設計與架構決策
- **[Claude Sonnet](https://claude.ai)（Anthropic）** — 核心實作夥伴，負責零件開發、executor 架構、CLI 實作與程式碼審查
- **Claude（Anthropic）** — 實作夥伴：零件開發、executor 架構、CLI 實作與程式碼審查
歡迎加入：[CONTRIBUTING.md](CONTRIBUTING.md)