Leo/Arcrun

Files

T

Leo 388c193ae7 docs(registry): seed 10 examples + 5 skills (LI SDD M3.1 + M3.3)

對應 .agents/specs/llm-interface/ Milestone 3.1 + 3.3。

registry/examples/ — 10 個可直接 push 的 workflow 範本：
  starter:    webhook-to-http
  common:     cron-watcher, llm-classify, rag-search-answer, daily-digest
  external:   email-summary (gmail+claude+telegram), pdf-to-blocks,
              github-issue-bot
  advanced:   parallel-fanout (trigger_workflow fan-out),
              error-retry (try_catch+wait pattern)

  每個含：workflow.yaml（可直接 push）+ description.md（解決什麼問題 /
  改成你自己的 / 學到什麼）+ tags.json（搜尋用）

registry/skills/ — 5 個 AI playbook（markdown）：
  build_watcher_workflow            — cron + filter + trigger 模式
  debug_paused_workflow             — claude_api callback paused 怎麼追
  migrate_http_to_trigger_workflow  — 從 self-fetch 換 trigger_workflow
  rag_with_arcrun                   — KBDB + claude_api 組裝 RAG
  add_new_wasm_component            — TinyGo 寫 + 部署全流程

兩者差異：
  examples = 可直接拿來改的 YAML
  skills = 面對 X 問題該怎麼想 + 該用哪個 example

兩者後續：CI 自動同步進 KBDB（type=workflow-example / type=agent-skill），
MCP arcrun_search_examples / arcrun_list_skills 走 KBDB semantic search。
（CI sync 是 M3.4 工作）

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-05-16 16:33:54 +08:00

3.0 KiB

Raw Blame History

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 拿到），可手動：

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）。

3.0 KiB Raw Blame History Unescape Escape