Arcrun/BETA_TEST.md

arcrun 封測指南

感謝你參與 arcrun 的封測。

arcrun 是一個讓 AI 和人都能直接讀寫、執行的 workflow 工具。 你的任務是測試核心功能，並記錄任何不符合預期的地方。

---

環境安裝（5 分鐘）

npm install -g arcrun
acr --version   # 應顯示 1.1.0 或以上

---

模式選擇

arcrun 有兩種使用模式：

Local 模式（不需要帳號，快速試用）

mkdir my-workflows && cd my-workflows
acr init --local

建立 ~/.arcrun/config.yaml（local 模式）和一個 hello.yaml 範例。

acr validate hello.yaml --offline
acr run hello --input input="Hello, arcrun!"

預期看到："result": "HELLO, ARCRUN!"

Standard 模式（需要 API Key，支援 Webhook 部署）

acr init

互動式設定，輸入 email 後自動取得 API Key，存入 ~/.arcrun/config.yaml。

---

零件清單

執行以下指令查看所有可用零件：

acr parts

取得單一零件的 config 範本：

acr parts scaffold string_ops
acr parts scaffold http_request
acr parts scaffold gmail   # 含 credentials.yaml 範本

---

可用零件（21 個，不需要帳號）

字串操作 — string_ops

config:
  my_node:
    component: string_ops
    operation: upper   # upper / lower / trim / length / replace / split / join

數字運算 — number_ops

config:
  my_node:
    component: number_ops
    operation: add
    b: 10   # 加上 10

支援：add / sub / mul / div / round / floor / ceil / abs

HTTP 請求 — http_request

config:
  my_node:
    component: http_request
    method: GET   # GET / POST / PUT / DELETE

acr run notify --input url="https://httpbin.org/get"

其他零件

if_control     條件分支（ON_SUCCESS / ON_FAIL 路由）
switch         多分支條件
foreach_control 迭代陣列
filter         過濾陣列
set            設定固定值到 context
array_ops      陣列操作（push / pop / slice）
date_ops       日期操作（now / format / diff）
validate_json  驗證 JSON Schema
ai_transform_compile / ai_transform_run   AI 自然語言轉換

---

動態參數 {{variable}}

config 裡的字串欄位支援 {{variable}}，從 --input 取值：

# flexible.yaml
name: flexible
flow:
  - "input >> ON_SUCCESS >> process"
config:
  process:
    component: string_ops
    operation: "{{op}}"

acr run flexible --input input="hello" --input op=upper   # → HELLO
acr run flexible --input input="HELLO" --input op=lower   # → hello

---

錯誤路由（ON_FAIL）

# safe-fetch.yaml
name: safe-fetch
flow:
  - "input >> ON_SUCCESS >> fetch"
  - "fetch >> ON_FAIL >> fallback"
config:
  fetch:
    component: http_request
    method: GET
  fallback:
    component: string_ops
    operation: upper

# 故意讓 fetch 失敗，觸發 fallback
acr run safe-fetch \
  --input url="https://invalid.domain.xyz" \
  --input input="fallback triggered"

---

中文語意

flow 支援中文關係詞：

flow:
  - "輸入 >> 完成後 >> 轉換"
  - "轉換 >> 失敗時 >> 錯誤處理"

---

Webhook 部署（Standard 模式）

讓外部網頁或服務能觸發你的 workflow：

# 部署 workflow
acr push my-workflow.yaml

輸出範例：

✓ "my-workflow" 已部署

  Webhook URL：https://cypher.arcrun.dev/webhooks/named/my-workflow/trigger
  需帶 Header：X-Arcrun-API-Key: ak_...

  curl 觸發範例：
  curl -X POST https://cypher.arcrun.dev/webhooks/named/my-workflow/trigger \
    -H 'X-Arcrun-API-Key: ak_your-key' \
    -H 'Content-Type: application/json' \
    -d '{"message": "hello"}'

---

API Recipe（整合外部服務）

不需要 deploy Worker，只要上傳 recipe YAML：

acr recipe push my-recipe.yaml
acr recipe list
acr recipe delete rec_xxxxxxxx

Recipe 上傳後會得到 rec_xxxxxxxx hash，可直接在 workflow config 的 component 欄位使用。

---

Credential 管理（Standard 模式）

需要帶 token 的零件（gmail、telegram、notion 等）可以提前上傳 credential，執行 workflow 時自動注入。

加密金鑰在 acr init 時已自動取得並存入 ~/.arcrun/config.yaml，不需要手動設定。

步驟一：查看某服務需要哪些 credential

acr auth-recipe scaffold notion    # 輸出 credentials.yaml 範本 + workflow 使用範例
acr auth-recipe list               # 列出所有支援的服務（20 個）

步驟二：建立 credentials.yaml（參考 scaffold 的輸出）：

# 範例：Notion
notion_token: "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# 範例：Telegram Bot
telegram_bot_token: "123456789:your-bot-token"

步驟三：上傳：

acr creds push credentials.yaml

上傳後執行 workflow 時，tokens 自動注入，不需要在 --input 手動帶。

支援的第三方服務（20 個）

acr auth-recipe list

輸出：Notion、Slack、GitHub、OpenAI、Anthropic、Airtable、Discord、Stripe、Twilio、SendGrid、HubSpot、Linear、Shopify、Resend、Supabase、Typeform、Jira、Google Sheets（Service Account）、Gmail（Service Account）、Google Drive（Service Account）

---

回饋格式

請把你的觀察記錄在 FEEDBACK.md，格式不限，但希望包含：

1. 成功的地方 — 哪些功能符合預期？
2. 失敗的地方 — 錯誤訊息是什麼？步驟是？
3. 困惑的地方 — 不知道怎麼用、文件不清楚的地方
4. 想要的功能 — 你覺得少了什麼

---

已知限制

• number_ops 的數字參數（a、b）若從 --input 帶入為字串，需要零件自行做型別轉換（目前已支援）
• ON_FAIL 觸發時，fallback 節點收到的 context 包含上游的錯誤物件（{success: false, ...}）
• 多節點串連時，context 為 flat merge，上游的 data.result 會直接合併到頂層
• if_control 條件為 false 時，不執行任何下游節點（沒有明確的 else 分支）

---

有問題？

遇到任何問題直接問。你的 API Key 是確定性的，只要用同一個 email 呼叫 /register 就能拿回來：

curl -X POST https://cypher.arcrun.dev/register \
  -H "Content-Type: application/json" \
  -d '{"email":"your@email.com"}'