Arcrun/README.md

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

npm i -g arcrun

1. 初始化

acr init

互動式問答：

• Cloudflare Account ID
• USER_KV Namespace ID（在 CF Dashboard 建立一個 KV）
• CF API Token（只需 KV Edit 權限）
• Email（取得 arcrun.dev API Key）

2. 設定 Credential

建立 credentials.yaml（已自動加入 .gitignore）：

# credentials.yaml — 不要提交至 git！
gmail_token: "ya29.your-google-oauth-token"
telegram_bot_token: "1234567890:ABCxxx"

上傳加密 credential 至你的 CF KV：

acr creds push credentials.yaml

3. 部署 Workflow

建立 newsletter_subscribe.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}}"

部署：

acr push newsletter_subscribe.yaml

4. 執行

acr run newsletter_subscribe --input email=user@example.com timestamp=2026-01-01

---

快速開始 — Self-hosted 模式

自行部署所有 Worker 到你的 Cloudflare 帳號。

# 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 範本：

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。

# 提交零件至公眾 registry（審核通過後對所有人開放）
acr parts publish ./my-component/

---

License

MIT