文档运行断点调试

断点调试

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