文件運行斷點調試

斷點調試

9 類中斷點、條件運算式、變數檢視與熱修改 —— 讓自動化流程不再是黑盒。

Braidrun 的偵錯器是互動式中斷點偵錯器：給任意步驟設中斷點，暫停後查看變數、改完再繼續，或者單步一格一格往下走。體驗對齊偵錯普通程式碼。

開啟 debug

在"執行"彈窗裡勾選：

啓用 Debug — 開啟調試模式，執行詳情頁顯示調試面板
入口暫停 — 在第一個步驟前自動暫停
異常時暫停 — 任何步驟失敗時自動暫停
預演 — 彈窗底部的「預演」按鈕，只驗證執行計畫不實際執行

開啟 debug 時，頂層並行會被序列化，方便你逐步排查。正式上線再關掉 debug 即可。偵錯器從 Pro 方案開始提供。

9 種中斷點類型

斷點類型	觸發點
`before_step`	步驟開始執行前
`after_step`	步驟成功結束後
`step_error`	步驟拋錯時
`state_machine_state`	state_machine 進入某個 state 時
`group_chat_round`	group_chat 每一輪發言前
`iteration_item`	iterate_over 每次迭代前
`agent_based_delegation`	agent_based 委派子任務前
`sub_workflow_entry`	sub_workflow 進入子工作流前（在父步驟上觸發）
`sub_workflow_exit`	sub_workflow 子工作流返回、輸出寫回父上下文後

每個中斷點還有幾個可選欄位：

stepName — 只命中指定步驟（不區分大小寫）；留空則命中該類型的所有位置
condition — 條件運算式，滿足時才真的中斷，語法與 workflow 的 condition 一致
once — 命中一次後自動停用

偵錯子工作流

中斷點預設對所有層級生效：在父工作流裡設的中斷點，子工作流執行到同名步驟時同樣會命中。sub_workflow_entry / sub_workflow_exit 這兩類中斷點則掛在父步驟上，分別停在進入子工作流前與它返回後，方便檢查傳入的 inputs 與寫回的 outputs。

同一個子工作流（比如一個市集模組）被多個父步驟重複使用時，偵錯引擎支援給中斷點加 parentPath 過濾：中斷點只在子工作流經由指定父步驟路徑呼叫時命中，其他呼叫路徑下的同名步驟不會中斷。

偵錯面板

偵錯控制都在執行詳情頁的偵錯面板裡，沒有單獨的偵錯器視窗：

執行控制：暫停 / 繼續 / 單步按鈕，頂部即時顯示目前暫停位置
上下文查看：變數、步驟輸出、步驟結果摘要
快照歷史：每過一個檢查點自動留一份上下文快照（最多保留最近 50 份），拖動時間軸可以回看任意一次暫停時的變數，並開啟 Diff 對比前後變化
變量編輯：暫停時雙擊變量值可修改
DAG 可視化：DAG 圖上直接顯示斷點標記和暫停高亮
日誌流：執行詳情頁底部的終端式日誌面板

用 REST 控制偵錯

偵錯面板背後是一組 REST 端點，寫指令碼排查時可以直接呼叫（與面板同一套介面）：

端點	作用
`GET /debug/state`	偵錯狀態：是否暫停、中斷點列表、目前暫停點
`GET /debug/context`	目前變數、步驟輸出與結果摘要
`POST /debug/pause`	請求暫停，在下一個檢查點生效
`POST /debug/continue`	繼續，跑到下一個中斷點
`POST /debug/step`	單步：只前進到下一個檢查點
`PUT /debug/breakpoints`	整組替換中斷點（執行中可隨時改）
`PUT /debug/break-on-error`	執行中開關「異常時暫停」
`GET /debug/snapshots`	快照歷史，也可按序號取單份
`POST /debug/variables`	暫停態下修改變數

前綴都是 /api/executions/{executionId}。例如：

bash

# 给 fetch_data 步骤加断点,再加一个"出错即停"的一次性断点
curl -X PUT https://braidrun.com/api/executions/<execution-id>/debug/breakpoints \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "breakpoints": [
      {"point": "before_step", "stepName": "fetch_data"},
      {"point": "step_error", "once": true}
    ]
  }'

# 暂停 / 单步 / 继续
curl -X POST https://braidrun.com/api/executions/<execution-id>/debug/pause \
  -H "Authorization: Bearer <token>"
curl -X POST https://braidrun.com/api/executions/<execution-id>/debug/step \
  -H "Authorization: Bearer <token>"
curl -X POST https://braidrun.com/api/executions/<execution-id>/debug/continue \
  -H "Authorization: Bearer <token>"

暫停時改變數，接著跑

典型場景：上游步驟算出了一個明顯不對的參數，中斷點停下來後直接把變數改對，再點「繼續」，後面的步驟就按新值執行，省掉整輪重來。面板裡雙擊變數值即可編輯；REST 走 POST /debug/variables，只有執行處於暫停態時才接受修改。

bash

# 暂停态下把变量改对,然后 continue
curl -X POST https://braidrun.com/api/executions/<execution-id>/debug/variables \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"variables": {"target_country": "US"}}'

從指定步驟重跑

執行到達終態後（完成、失敗或取消），可以從某個步驟重跑：在執行時間軸或步驟詳情面板裡點「從此步驟重跑」。重跑點之前的步驟結果原樣保留，已完成的 LLM 步驟不會重新呼叫模型，也就不產生重複的 token 費用。

重跑點必須是這次執行實際執行過的步驟；從第一步重跑等於整體重跑，不受此限制
執行還在執行時不能重跑，先取消或等它結束
REST:POST /api/executions/{executionId}/restart-from-step，body 裡的 stepName 留空表示從頭重跑

中斷點排查 + 改變數 + 從出錯步驟重跑，配合起來就是長工作流的省錢調法：前面幾十個步驟的結果留著，只為出錯的那一段付費。

當前限制

主要在步驟邊界與複合節點關鍵點暫停
不在 tool / token 流內部掛起
開啟 debug 時頂層併發會被串行化

下一步

調度 — 把 debug 通過的 workflow 接上 cron / webhook
自動續跑 — debug 之後決定哪些步驟是 idempotent