Depuración de puntos de interrupción

El depurador de Braidrun es un depurador interactivo con puntos de interrupción: ponga un punto de interrupción en cualquier paso, tras la pausa inspeccione las variables, corrija y continúe, o avance paso a paso una posición cada vez. La experiencia se alinea con depurar código normal.

Activar la depuración

Marque la casilla en la ventana emergente "Ejecutar":

• Habilitar depuración — Active el modo de depuración y muestre el panel de depuración en la página de detalles de ejecución.
• Entrada pausada — Pausa automáticamente antes del primer paso
• Pausa en caso de excepción — Pausar automáticamente si falla algún paso
• vista previa — El botón «Ensayo» en la parte inferior del cuadro emergente solo valida el plan de ejecución, sin ejecutarlo realmente

9 Tipos de puntos de interrupción

Cada punto de interrupción tiene además algunos campos opcionales:

• stepName — Solo se activa en el paso indicado (no distingue mayúsculas y minúsculas); si se deja vacío, se activa en todas las posiciones de ese tipo
• condition — Expresión de condición; solo interrumpe de verdad cuando se cumple, con la misma sintaxis que la condition del workflow
• once — Se desactiva automáticamente tras activarse una vez

Depurar sub-workflows

Los puntos de interrupción, por defecto, surten efecto en todos los niveles: un punto de interrupción fijado en el workflow padre también se activa cuando el sub-workflow llega a un paso con el mismo nombre.sub_workflow_entry / sub_workflow_exit Estos dos tipos de puntos de interrupción se acoplan al paso padre y se detienen, respectivamente, antes de entrar en el sub-workflow y después de que retorne, para facilitar la inspección de los inputs que entran y los outputs que se escriben de vuelta.

Cuando un mismo sub-workflow (por ejemplo, un módulo del marketplace) es reutilizado por varios pasos padre, el motor de depuración permite añadir al punto de interrupción un filtro de parentPath filtro: el punto de interrupción solo se activa cuando el sub-workflow se invoca por la ruta del paso padre indicado, y los pasos con el mismo nombre en otras rutas de invocación no interrumpen.

Panel de depuración

Los controles de depuración están todos en el panel de depuración de la página de detalle de la ejecución, no hay una ventana de depurador aparte:

• control ejecutivo：Botones de pausar / continuar / paso a paso; arriba se muestra en tiempo real la posición de pausa actual
• Visualización contextual：Variables, salidas de paso, resumen de resultados del paso
• Historial de instantáneas：En cada punto de control se guarda automáticamente una instantánea del contexto (se conservan como máximo las últimas 50); al arrastrar la línea de tiempo se puede revisar las variables de cualquier pausa anterior y activar la comparación Diff de los cambios antes y después
• Edición de variables：Haga doble clic en el valor de la variable para modificarlo mientras está en pausa
• visualización DAG：Muestra marcadores de puntos de interrupción y pausa el resaltado directamente en el diagrama DAG
• flujo de registro：Panel de registro estilo terminal en la parte inferior de la página de detalles de ejecución

Controlar la depuración con REST

Detrás del panel de depuración hay un conjunto de endpoints REST que se pueden llamar directamente al escribir scripts de diagnóstico (la misma interfaz que el panel):

El prefijo es siempre /api/executions/{executionId}. Por ejemplo:

# 给 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>"

Cambiar la variable en pausa y seguir corriendo

Escenario típico: un paso upstream calcula un parámetro claramente incorrecto; tras detenerse en el punto de interrupción, corrija directamente la variable, pulse «Continuar» y los pasos siguientes se ejecutan con el nuevo valor, ahorrándose repetir toda la ronda. En el panel, basta con hacer doble clic en el valor de la variable para editarlo; por REST se usa POST /debug/variables, y solo se acepta la modificación cuando la ejecución está en estado de pausa.

# 暂停态下把变量改对,然后 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"}}'

Reintento desde un paso concreto

Una vez que la ejecución ha llegado a un estado final (completada, fallida o cancelada), se puede reejecutar desde un paso concreto: en la línea de tiempo de la ejecución o en el panel de detalle del paso, pulse «Reejecutar desde este paso». Los resultados de los pasos anteriores al punto de reejecución se conservan tal cual, los pasos de LLM ya completados no vuelven a llamar al modelo, y por tanto no generan un coste de tokens duplicado.

• El punto de reejecución debe ser un paso que se haya ejecutado realmente en esta ejecución; reejecutar desde el primer paso equivale a reejecutar todo, sin esta restricción
• No se puede reejecutar mientras la ejecución sigue en marcha; cancélela primero o espere a que termine
• REST:POST /api/executions/{executionId}/restart-from-step, dejar vacío el stepName del body significa reejecutar desde el principio

Restricciones actuales

• Principalmente pausa en los límites de los pasos y en los puntos clave de los nodos compuestos.
• no se cuelga dentro de la herramienta/flujo de token
• La simultaneidad de nivel superior se serializará cuando la depuración esté habilitada

Siguiente paso

• Programación — Conecte el flujo de trabajo aprobado por depuración a cron/webhook
• Reanudación automática — Después de la depuración, decida qué pasos son idempotentes.