uncle6me-web
922a57fe34
Self-hosted 開源：WASM 零件 + recipe + cypher-executor，跑在你自己的 Cloudflare。 此為重建的乾淨歷史起點（移除曾誤 commit 的 GCP SA 金鑰，舊歷史保留在 richblack/arcrun 與本地 backup 分支）。含： - acr init --self-hosted installer（建 KV/R2 + codeload 拉預編譯 wasm + wrangler deploy + seed recipe） - recipe push 把關（資料外流提醒 + 打通檢查） - 19 個正當零件預編譯 wasm（claude_api/km_writer/kbdb_upsert_block 排除：違反 DECISIONS §1） - CLI / cypher-executor / registry / 完整 SDD Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
82 lines
3.0 KiB
Markdown
82 lines
3.0 KiB
Markdown
# Skill: Debug Paused Workflow
|
||
|
||
## 何時用這個 skill
|
||
|
||
- 你 `arcrun_run_workflow(...)` 得到 error 含「workflow paused at node X waiting for task task_XXX」
|
||
- 用戶說「workflow 跑了卻沒結果」/「等很久」
|
||
- 看到 `error_code: paused_awaiting_resume`
|
||
|
||
## 重要觀念：paused **不是錯誤**
|
||
|
||
某些零件設計為 async：發起任務 → 立刻回 paused → 等外部 callback POST `/workflows/resume` → cypher-executor 接續執行。
|
||
|
||
典型 paused 零件：
|
||
- `claude_api` — 打 mira daemon，daemon 跑 Claude（30-60 秒）→ 回 callback
|
||
- `http_request_async`（未來會有）— 發 webhook 後等回應
|
||
- 任何用 `pending: true, task_id: X` 模式的零件
|
||
|
||
paused 的 workflow **正在跑**，只是 cypher-executor 不浪費 CPU 等它，把 state 持久化到 KV 等 callback。
|
||
|
||
## Debug 流程
|
||
|
||
### Step 1：確認是不是真 paused（不是 fail）
|
||
|
||
```
|
||
arcrun_list_paused_executions(api_key=ak_xxx, limit=20)
|
||
```
|
||
|
||
看回傳的 paused 陣列：
|
||
- 找你的 workflow 名稱
|
||
- 看 `expires_at`（距離 24h TTL 還多久）
|
||
- 拿 `task_id` 進下一步
|
||
|
||
### Step 2：看 paused state 細節
|
||
|
||
```
|
||
arcrun_get_execution_trace(api_key=ak_xxx, task_id=task_XXX)
|
||
```
|
||
|
||
回傳 `paused_pending_result` 含外部任務 id（如 mira daemon 的 task_id），`paused_node_id` 告訴你卡在哪。
|
||
|
||
### Step 3：判斷卡住原因
|
||
|
||
| 觀察 | 原因 | 解 |
|
||
|---|---|---|
|
||
| `expires_at` 已過 | 24h 沒 callback，state 已 GC | 重 trigger workflow |
|
||
| paused_node 是 `claude_api` 且 mira daemon 503 | daemon 掛了 | `ssh cto && systemctl status cloud-cto` |
|
||
| paused_node 是 `claude_api` 且 daemon 正常 | callback 還沒回 | 等 30-90 秒 |
|
||
| `paused_pending_result` 沒 `task_id` | 零件實作 bug | 看零件源碼 |
|
||
| `paused_pending_result.callback_url` 錯 | 部署 URL 設錯 | 看零件 env config |
|
||
|
||
### Step 4：手動 resume（救急用）
|
||
|
||
若已知 callback 結果（從外部 log / 直接打外部 API 拿到），可手動：
|
||
|
||
```bash
|
||
curl -X POST https://cypher.arcrun.dev/workflows/resume \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"task_id": "task_XXX",
|
||
"result": { ... 模擬 callback 應該回的東西 ... }
|
||
}'
|
||
```
|
||
|
||
cypher-executor 找出對應 paused state 接續執行。
|
||
|
||
### Step 5：避免再卡住
|
||
|
||
部署 watcher / async 流程時：
|
||
- 設合理 timeout（claude_api 預設 30s，重 prompt 可拉到 60-90s）
|
||
- 處理 daemon 健康檢查（monitor 加 alert）
|
||
- 別在 high-load 時段同時 trigger 太多 paused workflow（KV write 量爆）
|
||
|
||
## paused 跟 fail 的差異速查
|
||
|
||
| 狀態 | success 欄 | error 含 | 該做 |
|
||
|---|---|---|---|
|
||
| **成功完成** | true | — | 看 data 結果 |
|
||
| **paused** | false（但其實算成功） | "workflow paused at node X" | 等 callback / get_execution_trace |
|
||
| **真錯** | false | 各種 error 訊息（非 paused） | 看 trace 第一個 failed node |
|
||
|
||
`trigger_workflow` 內建零件已把 paused 視為 status='paused_awaiting_resume' 而非 fail（commit 5216242）。
|