Leo
fb2d0b0c2d
讓任何 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>
207 lines
9.4 KiB
Markdown
207 lines
9.4 KiB
Markdown
# 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. 一鍵初始化
|
||
|
||
```bash
|
||
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`：
|
||
|
||
```yaml
|
||
name: hello
|
||
flow:
|
||
- "input >> 完成後 >> transform"
|
||
config:
|
||
transform:
|
||
component: string_ops
|
||
operation: upper
|
||
```
|
||
|
||
```bash
|
||
acr run hello --input input="Hello, world" # → HELLO WORLD
|
||
```
|
||
|
||
### 4. 要打外部 API？寫一個 recipe（不是做零件）
|
||
|
||
```bash
|
||
# 上傳一個打外部 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 端加密，明文不離開你的機器）
|
||
|
||
```bash
|
||
acr auth-recipe list # 看支援哪些服務的認證
|
||
acr auth-recipe scaffold notion # 取得 credentials.yaml 範本
|
||
acr creds push credentials.yaml # AES-GCM 加密後上傳到你自己的 KV
|
||
```
|
||
|
||
### 6. 部署 + 觸發
|
||
|
||
```bash
|
||
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`](DECISIONS.md)。
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
MIT
|
||
|
||
---
|
||
|
||
## 致謝
|
||
|
||
arcrun 的核心架構、WASM 零件、CLI 工具鏈與這份文件，由以下貢獻者共同打造：
|
||
|
||
- **[@richblack](https://github.com/richblack)** — 創始人，產品設計與架構決策
|
||
- **Claude（Anthropic）** — 實作夥伴：零件開發、executor 架構、CLI 實作與程式碼審查
|
||
|
||
歡迎加入：[CONTRIBUTING.md](CONTRIBUTING.md)
|