feat(arcrun): implement arcrun MVP — open-source AI workflow engine
Phase 1-5 complete per .agents/specs/u6u-core-mvp/: **Phase 1 — Cherry-pick & cleanup** - Create arcrun/ from cypher-executor, credentials, builtins, registry - Remove 9 InkStone Service Bindings (KBDB, REGISTRY, CLINIC_*, AICEO, MINI_ME) - Rewrite component-loader: 3-layer (builtin → WASM_BUCKET R2 → error) - Remove autoPublishMissing.ts, proxy.ts (AICEO), execution-logger.ts (KBDB) - Clean all KV namespace IDs and InkStone internal URLs from config files **Phase 2 — contract.yaml completeness** - Add credentials_required to gmail, google_sheets, telegram, line_notify - Add config_example to all 21 components with annotated field descriptions **Phase 3 — Credential injection** - Add credential-injector.ts: AES-GCM decrypt from CREDENTIALS_KV - Integrate into GraphExecutor before WASM execution - Structured errors with repair instructions when credential missing **Phase 4 — CLI (acr)** - cli/package.json: arcrun package, bin: acr, deps: commander/js-yaml/chalk/ora - 8 commands: init, creds push, push, run, validate, parts, list, logs - Standard mode: writes directly to user's CF KV via CF REST API - acr init: interactive setup with arcrun.dev API Key registration **Phase 5 — Open source release prep** - README.md: 5-minute quickstart, component table, workflow YAML syntax - CONTRIBUTING.md: TinyGo dev env, component scaffolding, submission flow - Security audit: no InkStone internal URLs/IDs in committed files - .gitignore: exclude credentials.yaml, .wrangler, *.wasm https://claude.ai/code/session_01BnCdSLVH8tUed9VrrPavgT
This commit is contained in:
Claude
@@ -0,0 +1,234 @@
|
||||
# arcrun
|
||||
|
||||
**AI Workflow Execution Engine** — 以 WASM 零件為基礎的 Cloudflare Workers 工作流平台。
|
||||
|
||||
定義一個 workflow，串接 Gmail、Telegram、Google Sheets 等服務，無需伺服器，直接跑在 Cloudflare Edge。
|
||||
|
||||
---
|
||||
|
||||
## 專案定位
|
||||
|
||||
| 層級 | 內容 | 存取 |
|
||||
|------|------|------|
|
||||
| **開源核心** | cypher-executor、21 個 WASM 零件、credentials Worker、CLI（acr） | MIT License |
|
||||
| **Hosted SaaS** | 一行指令取得 API Key，使用 arcrun.dev 的執行引擎與公眾零件庫，credential 永遠在你自己的 CF KV | 免費 |
|
||||
| **InkStone 付費** | KBDB 向量搜尋、Graph 查詢、Persona SDK、MatchGPT | 付費方案 |
|
||||
|
||||
**你的 credential 和 workflow 永遠在你自己的 Cloudflare KV，arcrun.dev 不儲存它們。**
|
||||
|
||||
---
|
||||
|
||||
## 快速開始 — Standard 模式（推薦，零部署）
|
||||
|
||||
只需在 Cloudflare 建立一個 KV namespace，其餘由 arcrun.dev 處理。
|
||||
|
||||
### 安裝 CLI
|
||||
|
||||
```bash
|
||||
npm i -g arcrun
|
||||
```
|
||||
|
||||
### 1. 初始化
|
||||
|
||||
```bash
|
||||
acr init
|
||||
```
|
||||
|
||||
互動式問答：
|
||||
- Cloudflare Account ID
|
||||
- USER_KV Namespace ID（在 [CF Dashboard](https://dash.cloudflare.com) 建立一個 KV）
|
||||
- CF API Token（只需 KV Edit 權限）
|
||||
- Email（取得 arcrun.dev API Key）
|
||||
|
||||
### 2. 設定 Credential
|
||||
|
||||
建立 `credentials.yaml`（已自動加入 `.gitignore`）：
|
||||
|
||||
```yaml
|
||||
# credentials.yaml — 不要提交至 git！
|
||||
gmail_token: "ya29.your-google-oauth-token"
|
||||
telegram_bot_token: "1234567890:ABCxxx"
|
||||
```
|
||||
|
||||
上傳加密 credential 至你的 CF KV：
|
||||
|
||||
```bash
|
||||
acr creds push credentials.yaml
|
||||
```
|
||||
|
||||
### 3. 部署 Workflow
|
||||
|
||||
建立 `newsletter_subscribe.yaml`：
|
||||
|
||||
```yaml
|
||||
name: newsletter_subscribe
|
||||
description: 訂閱電子報，發感謝信並記錄到 GSheets
|
||||
|
||||
flow:
|
||||
- "input >> 完成後 >> send_thanks"
|
||||
- "input >> 完成後 >> save_to_sheet"
|
||||
- "send_thanks >> 完成後 >> output"
|
||||
- "send_thanks >> 失敗時 >> notify_error"
|
||||
- "save_to_sheet >> 完成後 >> output"
|
||||
|
||||
config:
|
||||
send_thanks:
|
||||
to: "{{input.email}}"
|
||||
subject: "感謝訂閱！"
|
||||
body: "歡迎加入！"
|
||||
# access_token 由 credentials.yaml 的 gmail_token 自動注入
|
||||
|
||||
save_to_sheet:
|
||||
action: write
|
||||
spreadsheet_id: "your-sheet-id"
|
||||
range: "訂閱者!A:B"
|
||||
values: [["{{input.email}}", "{{input.timestamp}}"]]
|
||||
|
||||
notify_error:
|
||||
chat_id: "your-telegram-chat-id"
|
||||
text: "發信失敗：{{input.email}}"
|
||||
```
|
||||
|
||||
部署：
|
||||
|
||||
```bash
|
||||
acr push newsletter_subscribe.yaml
|
||||
```
|
||||
|
||||
### 4. 執行
|
||||
|
||||
```bash
|
||||
acr run newsletter_subscribe --input email=user@example.com timestamp=2026-01-01
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 快速開始 — Self-hosted 模式
|
||||
|
||||
自行部署所有 Worker 到你的 Cloudflare 帳號。
|
||||
|
||||
```bash
|
||||
# 1. 部署 cypher-executor
|
||||
cd cypher-executor
|
||||
wrangler deploy
|
||||
|
||||
# 2. 部署 credentials Worker
|
||||
cd ../credentials
|
||||
wrangler deploy
|
||||
|
||||
# 3. 初始化 CLI（Self-hosted 模式）
|
||||
acr init --self-hosted
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workflow YAML 語法
|
||||
|
||||
### 三元組格式
|
||||
|
||||
```
|
||||
"A >> 關係詞 >> B"
|
||||
```
|
||||
|
||||
### 合法關係詞
|
||||
|
||||
| 關係詞 | 英文別名 | 說明 |
|
||||
|--------|----------|------|
|
||||
| `完成後` | `ON_SUCCESS` | 上游成功後執行 |
|
||||
| `失敗時` | `ON_FAIL` | 上游失敗時執行 |
|
||||
| `對每個` | `FOREACH` | 迭代執行 |
|
||||
| `條件滿足時` | `IF` | 條件分支 |
|
||||
| `ON_CLICK` | — | 前端點擊觸發 |
|
||||
| `CALLS_SUBFLOW` | — | 呼叫子 workflow |
|
||||
|
||||
> `PIPE` 已棄用，請改用 `完成後` 或 `ON_SUCCESS`。
|
||||
|
||||
---
|
||||
|
||||
## 零件列表（21 個）
|
||||
|
||||
### 整合類（需要 Credential）
|
||||
|
||||
| 零件 | 說明 | 所需 Credential |
|
||||
|------|------|-----------------|
|
||||
| `gmail` | Gmail 發信 | `gmail_token`（Google OAuth） |
|
||||
| `google_sheets` | Google Sheets 讀寫 | `google_oauth`（Google OAuth） |
|
||||
| `telegram` | Telegram Bot 發訊息 | `telegram_bot_token` |
|
||||
| `line_notify` | LINE Notify 發訊息 | `line_token` |
|
||||
| `http_request` | HTTP 請求（手動設 headers） | — |
|
||||
|
||||
### 控制流
|
||||
|
||||
| 零件 | 說明 |
|
||||
|------|------|
|
||||
| `if_control` | 條件判斷 |
|
||||
| `foreach_control` | 迴圈執行 |
|
||||
| `try_catch` | 錯誤處理 |
|
||||
| `switch` | 多路路由 |
|
||||
| `wait` | 延遲等待 |
|
||||
|
||||
### 資料處理
|
||||
|
||||
| 零件 | 說明 |
|
||||
|------|------|
|
||||
| `set` | 設定/賦值 |
|
||||
| `filter` | 陣列過濾 |
|
||||
| `merge` | 合併物件 |
|
||||
| `string_ops` | 字串操作 |
|
||||
| `number_ops` | 數字運算 |
|
||||
| `array_ops` | 陣列操作 |
|
||||
| `date_ops` | 日期操作 |
|
||||
|
||||
### AI 類
|
||||
|
||||
| 零件 | 說明 |
|
||||
|------|------|
|
||||
| `ai_transform_compile` | AI 轉換規則編譯（Workers AI） |
|
||||
| `ai_transform_run` | AI 轉換執行 |
|
||||
|
||||
### 其他
|
||||
|
||||
| 零件 | 說明 |
|
||||
|------|------|
|
||||
| `validate_json` | JSON Schema 驗證 |
|
||||
| `cron` | Cron 排程觸發 |
|
||||
|
||||
取得任一零件的 config 範本：
|
||||
|
||||
```bash
|
||||
acr parts scaffold gmail
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CLI 指令
|
||||
|
||||
```
|
||||
acr init 互動式初始化設定
|
||||
acr creds push [file] 上傳加密 credentials 至 CF KV
|
||||
acr push <workflow.yaml> 部署 workflow
|
||||
acr run <name> [--input] 執行 workflow
|
||||
acr validate <workflow.yaml> 執行前驗證
|
||||
acr parts 列出所有零件（含統計）
|
||||
acr parts scaffold <comp> 取得 config 範本
|
||||
acr parts publish <dir> 提交零件至公眾庫
|
||||
acr list 列出已部署的 workflow
|
||||
acr logs <name> 查看執行記錄
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 貢獻零件
|
||||
|
||||
詳見 [CONTRIBUTING.md](CONTRIBUTING.md)。
|
||||
|
||||
```bash
|
||||
# 提交零件至公眾 registry（審核通過後對所有人開放）
|
||||
acr parts publish ./my-component/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
Reference in New Issue
Block a user