feat: add landing page + builtins Worker + BETA_TEST guide + README

- landing/: Next.js 15 app for arcrun.dev (dashboard, integrations, API docs, login). Deploys via Cloudflare Pages — CI scan skips this via pages_build_output_dir marker. - builtins/: minimal Hono Worker at arcrun-builtins (/init for one-shot component registry seeding). initComponents logic is flagged stale in src/index.ts for future rewrite. - BETA_TEST.md: pre-launch validation playbook. - README.md: updated to match current arcrun.dev / acr CLI flow. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-04-20 17:52:41 +08:00
parent 13b01328c1
commit 4516cdee4b
34 changed files with 5203 additions and 23 deletions
@@ -0,0 +1,286 @@
+# 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"}'
+```