Arcrun/.agents/specs/arcrun/arcrun.md

arcrun — 進度與待辦

設計細節見 arcrun/README.md（產品說明）和 arcrun/BETA_TEST.md（封測指南）。 這份文件只記錄：目前狀態、還差什麼、封測能不能啟動。

---

一、封測目標場景

封測者是工程師朋友，有自己的網頁，需要後端自動化。目標是他能在 AI 協助下，一次或很少次完成以下完整流程：

1. acr init 取得 api_key
2. acr parts scaffold 查零件格式，AI 幫寫 workflow YAML
3. 若內建零件不足，acr recipe push 增加打外部 API 的 recipe
4. acr creds push 上傳 OAuth token（gmail / google_sheets 等）
5. acr push 部署 workflow，取得 Webhook URL
6. 網頁 POST /webhooks/named/{name}/trigger，結果存 Google Sheets

---

二、場景各步驟驗證狀態

Step 1：acr init → api_key

• acr init Standard 模式完成，api_key 存入 ~/.arcrun/config.yaml
• 已驗證：mode: standard, api_key: ak_... 正確

Step 2：acr parts scaffold → AI 看到零件格式

• acr parts 列出 21 個零件，完全內建，不依賴 registry.arcrun.dev
• acr parts scaffold google_sheets 輸出 spreadsheet_id / range / operation / values 格式與 credentials.yaml 範本
• 已驗證：輸出可直接貼入 YAML

Step 3：acr recipe push → 打外部 API

• acr recipe push 上傳成功，回傳 rec_hash
• workflow 使用 component: rec_xxxxxxxx，acr push 後 trigger 能正確呼叫外部 API
• 已驗證（2026-04-18）：httpbin_post recipe → trigger → httpbin.org/post 回傳正確 ✅

Step 4：acr creds push → 自動注入 token

• POST /credentials API 完成，以 {api_key}:cred:{name} 存入 KV
• Webhook trigger 時 injectCredentials 從 KV 取得 token 自動注入
• /register 現在回傳 encryption_key，acr init 自動存入 config
• acr creds push 從 config 讀 encryption_key，不再需要手動設定環境變數
• 已驗證（2026-04-18）：beta@arcrun.dev 帳號完整流程：init → creds push → trigger → credential 注入成功 ✅

Step 5：acr push → Webhook URL

• acr push workflow.yaml 部署成功，顯示 Webhook URL 和完整 curl 範例
• config 中的 component / 參數在 push 時套入 graph 節點
• 已驗證（2026-04-18）：sheet-test workflow push 成功 ✅

Step 6：網頁 POST → 執行 → 結果到 Google Sheets

• POST /webhooks/named/{name}/trigger -H 'X-Arcrun-API-Key: ...' 觸發執行正常
• google_sheets 零件有實作（append row 到 Sheets API）
• 已驗證（2026-04-18）：trigger sheet-test → 報「缺少 credential」（符合預期，credential 未上傳）✅
• 未驗證：真實 google_oauth token + acr creds push → trigger → Google Sheets 實際寫入
  • 需要真實 OAuth token 才能完整驗證

---

三、封測啟動阻擋項

P0 全部清除才啟動封測。

#	項目	狀態	說明
1	acr parts scaffold 正確輸出	✅ 完成	21 個零件內建清單
2	acr recipe push 端對端	✅ 完成	httpbin_post 驗證通過
3	acr creds push 代碼	✅ 完成	需 ARCRUN_ENCRYPTION_KEY
4	credential 注入端對端	✅ 完成	無 token 時錯誤訊息正確
5	acr push + webhook trigger	✅ 完成	端對端驗證通過
6	acr creds push 實測	✅ 完成	/register 回傳 encryption_key，acr init 自動存入 config（CLI 1.0.9）
7	Google Sheets 真實寫入	⚠️ 部分驗證	credential 注入已驗證；實際 Sheets 寫入需真實 OAuth token
8	第三方服務認證 recipe	✅ 完成	20 個服務（Notion/Slack/GitHub/OpenAI 等），CLI 1.1.0

目前狀況：P0 全部完成。Google Sheets 實際寫入可由封測者用真實 token 驗證，不阻塞啟動。

---

四、封測前 P3（啟動當天）

• 用封測者 email 呼叫 /register，取得 api_key
• 將 ARCRUN_ENCRYPTION_KEY 以安全方式提供給封測者
• 確認聯絡管道

---

五、已知限制（封測期間不修）

1. if_control false branch 不路由（條件 false 時後續節點不執行）
2. 多節點 context 不自動解包（上游輸出 flat merge，下游需從 data.result 取值）
3. 用戶自製邏輯零件（Phase 5）封測後才實作

---

六、實作進度

Phase	內容	狀態
0	Workers 部署、CI/CD、DNS	✅
1	CLI 基礎（init / validate / run / parts）	✅
2	/register、/cypher/execute、21 個零件	✅
3	Service Binding 架構、{{variable}} 插值、ON_FAIL 修正	✅
4	動態 Recipe KV（CRUD）、acr recipe 指令	✅
5	用戶自製邏輯零件（WASM push）	⏸ 封測後
6	Credential 多租戶（{api_key}:cred:{name}）、acr creds push	✅
7	acr parts 內建清單、acr parts scaffold	✅
8	/webhooks/named、acr push 改版、config 套入 graph	✅

CLI 版本

版本	變更
1.1.0	auth recipe 系統：20 個服務預建（Notion/Slack/GitHub/OpenAI/Google SA 等）；acr auth-recipe 指令
1.0.9	/register 回傳 encryption_key；acr init 自動儲存；creds push 不需手動設環境變數
1.0.8	acr push → webhooks/named；config 套入 graph；acr parts 內建清單
1.0.7	acr creds push → POST /credentials
1.0.6	acr recipe push / list / delete
1.0.5	hello.yaml 改 string_ops，--version 修正
1.0.4	config/context 分離
1.0.3	初始發布