Arcrun/BETA_TEST.md

# arcrun 封測指南

感謝你參與 arcrun 的封測。

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

---

## 環境安裝（5 分鐘）

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

---

## 模式選擇

arcrun 有兩種使用模式：

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

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

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

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

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

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

```bash
acr init
```

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

---

## 零件清單

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

```bash
acr parts
```

取得單一零件的 config 範本：

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

---

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

### 字串操作 — `string_ops`

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

### 數字運算 — `number_ops`

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

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

### HTTP 請求 — `http_request`

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

```bash
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` 取值：

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

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

---

## 錯誤路由（ON_FAIL）

```yaml
# 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
```

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

---

## 中文語意

flow 支援中文關係詞：

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

---

## Webhook 部署（Standard 模式）

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

```bash
# 部署 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：

```bash
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**

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

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

```yaml
# 範例：Notion
notion_token: "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

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

**步驟三：上傳**：
```bash
acr creds push credentials.yaml
```

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

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

```bash
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` 就能拿回來：

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