Débogage des points d'arrêt

Le débogueur de Braidrun est un débogueur interactif à points d'arrêt : placez un point d'arrêt sur n'importe quelle étape, inspectez les variables après la pause, poursuivez une fois vos modifications faites, ou avancez pas à pas. L'expérience s'aligne sur le débogage de code ordinaire.

Activer le débogage

Cochez la case dans la fenêtre contextuelle « Exécuter » :

• Activer le débogage — Activez le mode débogage et affichez le panneau de débogage sur la page des détails d'exécution.
• Entrée en pause — Pause automatique avant la première étape
• Pause en cas d'exception — Pause automatique si une étape échoue
• aperçu — Le bouton « Simulation » au bas de la boîte de dialogue ne valide que le plan d'exécution, sans exécution réelle

9 Types de points d'arrêt

Chaque point d'arrêt possède en outre quelques champs facultatifs :

• stepName — Ne s'active que sur l'étape désignée (insensible à la casse) ; s'il est vide, il s'active à toutes les positions de ce type
• condition — Expression conditionnelle : l'interruption n'a réellement lieu que si elle est satisfaite ; sa syntaxe est identique à celle de condition dans un workflow
• once — Se désactive automatiquement après une première activation

Déboguer un sous-workflow

Un point d'arrêt s'applique par défaut à tous les niveaux : un point d'arrêt défini dans le workflow parent s'active aussi lorsque le sous-workflow atteint une étape du même nom.sub_workflow_entry / sub_workflow_exit Ces deux types de points d'arrêt sont rattachés à l'étape parente et s'arrêtent respectivement avant l'entrée dans le sous-workflow et après son retour, ce qui facilite l'examen des inputs transmis et des outputs réécrits.

Lorsqu'un même sous-workflow (par exemple un module du marché) est réutilisé par plusieurs étapes parentes, le moteur de débogage permet d'ajouter à un point d'arrêt un parentPath de filtrage : le point d'arrêt ne s'active que lorsque le sous-workflow est appelé via le chemin de l'étape parente désignée ; l'étape du même nom empruntant d'autres chemins d'appel n'est pas interrompue.

Panneau de débogage

Toutes les commandes de débogage se trouvent dans le panneau de débogage de la page de détails d'exécution ; il n'y a pas de fenêtre de débogueur distincte :

• contrôle exécutif：Boutons Mettre en pause / Poursuivre / Pas à pas, avec affichage en temps réel de la position de pause courante en haut
• Visualisation contextuelle：Variables, sorties d'étape, résumé du résultat d'étape
• Historique des instantanés：Un instantané de contexte est conservé automatiquement à chaque point de contrôle (les 50 derniers au maximum) ; le déplacement sur la frise chronologique permet de revoir les variables à n'importe quelle pause et d'activer un Diff pour comparer les évolutions
• Édition de variables：Double-cliquez sur la valeur de la variable pour la modifier en pause
• Visualisation DAG：Afficher les marqueurs de points d'arrêt et mettre en évidence les pauses directement sur le diagramme DAG
• flux de journaux：Panneau de journal de style terminal en bas de la page des détails d'exécution

Contrôler le débogage via REST

Le panneau de débogage s'appuie sur un ensemble d'endpoints REST, directement appelables lors d'un diagnostic scripté (la même API que celle du panneau) :

Le préfixe est /api/executions/{executionId}. Par exemple :

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

Modifier une variable pendant la pause, puis poursuivre

Scénario typique : une étape en amont a calculé un paramètre manifestement erroné ; une fois l'exécution arrêtée par le point d'arrêt, corrigez directement la variable puis cliquez sur « Poursuivre », et les étapes suivantes s'exécutent avec la nouvelle valeur, ce qui évite de tout recommencer. Dans le panneau, un double-clic sur la valeur d'une variable permet de la modifier ; via REST, on passe par POST /debug/variables, et la modification n'est acceptée que lorsque l'exécution est à l'état de pause.

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

Relancer à partir d'une étape donnée

Une fois l'exécution parvenue à un état final (terminée, échouée ou annulée), il est possible de la relancer depuis une étape : cliquez sur « Relancer depuis cette étape » dans la chronologie d'exécution ou dans le panneau de détails d'étape. Les résultats des étapes antérieures au point de relance sont conservés tels quels, les étapes LLM déjà terminées ne rappellent pas le modèle et n'engendrent donc pas de coûts de token en double.

• Le point de relance doit être une étape ayant réellement été exécutée lors de cette exécution ; relancer depuis la première étape équivaut à une relance intégrale et n'est pas soumis à cette contrainte
• Une exécution encore en cours ne peut pas être relancée ; annulez-la d'abord ou attendez qu'elle se termine
• REST :POST /api/executions/{executionId}/restart-from-step, un stepName laissé vide dans le body signifie une relance depuis le début

Restrictions actuelles

• Faites principalement une pause aux limites des étapes et aux points clés des nœuds composés
• ne s'accroche pas à l'intérieur du flux d'outils/de jetons
• La concurrence de niveau supérieur sera sérialisée lorsque le débogage est activé

Étape suivante

• Planification — Connectez le workflow passé par le débogage à cron/webhook
• Reprise automatique — Après le débogage, décidez quelles étapes sont idempotentes