Depuração de pontos de paragem

O depurador de Braidrun é um depurador de ponto de parada interativo: defina um ponto de parada em qualquer passo, inspecione variáveis quando ele pausa, edite e continue, ou um passo para frente um de cada vez. A experiência corresponde à depuração de código normal.

Ativar depuração

Marque a caixa na janela pop-up "Executar":

• Habilitar depuração — Ative o modo de depuração e exiba o painel de depuração na página de detalhes de execução.
• Entrada pausada — Pausar automaticamente antes da primeira etapa
• Pausa na exceção — Pausa automática se algum passo falhar
• visualização — O botão "Executar seco" na parte inferior da janela só valida o plano de execução sem executá- lo

9 Tipos de pontos de paragem

Cada ponto de paragem também tem alguns campos opcionais:

• stepName — Carregue apenas no passo indicado (insensível ao caso); deixe em branco para carregar em cada local desse tipo
• condition — Uma expressão condicional que realmente quebra somente quando satisfeita, com a mesma sintaxe que uma condição de workflow
• once — Auto- desactivar após bater uma vez

Depurando sub- workflows

Os pontos de parada se aplicam a todos os níveis por padrão: um ponto de parada definido em um workflow pai também dispara quando um sub-workflow atinge um passo do mesmo nome.sub_workflow_entry / sub_workflow_exit Esses dois tipos de pontos de interrupção se ligam ao passo pai, pausando antes de entrar no sub-workflow e depois retorna, respectivamente, para facilitar a inspeção das entradas passadas e as saídas gravadas de volta.

Quando o mesmo sub-workflow (por exemplo, um módulo de mercado) é reutilizado por vários passos pai, o motor de depuração permite adicionar um parentPath filtro para um ponto de paragem: ele dispara apenas quando o sub- workflow é chamado através do caminho pai-passo especificado, e passos com o mesmo nome em outros caminhos de chamada não quebram.

O painel de depuração

Todos os controles de depuração estão ao vivo no painel de depuração na página de detalhes da execução — não há janela de depuração separada:

• controle executivo：Pausar / Continuar / Passo botões, com o local atual pausa mostrado ao vivo no topo
• Visualização contextual：Variáveis, saídas de passos e resumos de resultados de passos
• Histórico de imagens：Um instantâneo de contexto é salvo automaticamente em cada checkpoint (até os 50 mais recentes mantidos); arraste a linha do tempo para olhar para trás para as variáveis em qualquer pausa e abra um diff para comparar antes e depois
• Edição de variáveis：Clique duas vezes no valor da variável para modificá-lo durante a pausa
• Visualização DAG：Exibir marcadores de ponto de interrupção e pausar o realce diretamente no diagrama DAG
• fluxo de registros：Painel de log estilo terminal na parte inferior da página de detalhes de execução

Controlando depuração via REST

Atrás do painel de depuração está um conjunto de endpoints REST que você pode chamar diretamente ao programar um diagnóstico (a mesma interface que o painel usa):

O prefixo é /api/executions/{executionId}. Por exemplo:

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

Mudar uma variável enquanto pausada, depois continuar

Um cenário típico: uma etapa upstream computou um parâmetro obviamente errado; uma vez que o ponto de interrupção pausa, você corrige a variável diretamente, clique em "Continuar", e os seguintes passos são executados com o novo valor, salvando uma repetição inteira. No painel, clique duas vezes em um valor variável para editá- lo; via uso REST POST /debug/variables, e as edições só são aceitas enquanto a execução é pausada.

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

Repetir a partir de um passo escolhido

Uma vez que uma execução atinge um estado terminal (completado, falhado ou cancelado), você pode repetir a partir de um dado passo: clique em "Reexecutar a partir desta etapa" na linha do tempo de execução ou no painel de detalhes do passo. Os resultados dos passos antes do ponto de reexecução são mantidos como está, os passos LLM completados não chamam o modelo novamente, e por isso não são incorridas cargas duplicadas.

• O ponto de reprise deve ser um passo que esta execução realmente executou; reprise do primeiro passo é uma reprise completa e não está sujeita a esta restrição
• Você não pode repetir enquanto a execução ainda estiver em execução — cancele-a ou espere que ela termine primeiro
• REST:POST /api/executions/{executionId}/restart-from-step; deixando o stepName vazio no corpo significa uma repetição completa desde o início

Restrições atuais

• Faça uma pausa principalmente nos limites das etapas e nos pontos-chave dos nós compostos
• não fica pendurado dentro do fluxo de ferramentas/tokens
• A simultaneidade de nível superior será serializada quando a depuração estiver habilitada

Próximo passo

• Agendamento — Conecte o workflow aprovado pela depuração ao cron/webhook
• Continuar automaticamente — Após a depuração, decida quais etapas são idempotentes