Debuggen von Haltepunkten

Der Debugger von Braidrun ist ein interaktiver Breakpoint-Debugger: Setzen Sie an einem beliebigen Schritt einen Breakpoint, prüfen Sie nach dem Pausieren die Variablen, fahren Sie nach der Bearbeitung fort oder gehen Sie Schritt für Schritt vorwärts. Das Erlebnis entspricht dem Debuggen von normalem Code.

Aktivieren Sie das Debuggen

Aktivieren Sie das Kontrollkästchen im Popup-Fenster „Ausführen“:

• Aktivieren Sie Debug — Aktivieren Sie den Debugging-Modus und zeigen Sie das Debugging-Panel auf der Seite mit den Ausführungsdetails an.
• Der Eingang blieb stehen — Vor dem ersten Schritt automatisch pausieren
• Pause bei Ausnahme — Automatische Pause, wenn ein Schritt fehlschlägt
• Vorschau — Die Schaltfläche „Probelauf“ am Fuß des Dialogs validiert nur den Ausführungsplan, ohne tatsächlich auszuführen

9 Breakpoint-Typen

Jeder Breakpoint hat zudem einige optionale Felder:

• stepName — Trifft nur einen angegebenen Schritt (Groß-/Kleinschreibung ignorierend); bleibt es leer, werden alle Positionen dieses Typs getroffen
• condition — Bedingungsausdruck; erst bei Erfüllung wird tatsächlich unterbrochen, die Syntax entspricht der condition des workflow
• once — Nach einmaligem Treffer automatisch deaktiviert

Sub-workflow debuggen

Breakpoints wirken standardmäßig auf allen Ebenen: Ein im übergeordneten Workflow gesetzter Breakpoint wird auch getroffen, wenn der Sub-Workflow einen gleichnamigen Schritt erreicht.sub_workflow_entry / sub_workflow_exit Diese beiden Breakpoint-Typen hingegen hängen am übergeordneten Schritt und halten jeweils vor dem Eintritt in den Sub-Workflow und nach seiner Rückkehr an, um die übergebenen inputs und die zurückgeschriebenen outputs zu prüfen.

Wird derselbe Sub-Workflow (etwa ein Marktplatzmodul) von mehreren übergeordneten Schritten wiederverwendet, unterstützt die Debug-Engine, dem Breakpoint ein parentPath -Filter hinzuzufügen: Der Breakpoint wird nur getroffen, wenn der Sub-Workflow über den angegebenen übergeordneten Schrittpfad aufgerufen wird; ein gleichnamiger Schritt auf einem anderen Aufrufpfad wird nicht unterbrochen.

Debug-panel

Alle Debug-Steuerungen befinden sich im Debug-Panel der Ausführungsdetailseite; es gibt kein separates Debugger-Fenster:

• exekutive Kontrolle：Schaltflächen Pausieren / Fortsetzen / Einzelschritt; oben wird die aktuelle Pauseposition in Echtzeit angezeigt
• Kontextuelle Betrachtung：Variablen, Schrittausgaben, Zusammenfassung des Schrittergebnisses
• Snapshot-Verlauf：Bei jedem Checkpoint wird automatisch ein Kontext-Snapshot hinterlegt (höchstens die letzten 50 werden behalten); durch Ziehen der Zeitachse lassen sich die Variablen jeder Pause zurückverfolgen und per Diff die Änderungen davor und danach vergleichen
• Variablenbearbeitung：Doppelklicken Sie auf den Variablenwert, um ihn während der Pause zu ändern
• DAG-Visualisierung：Zeigen Sie Haltepunktmarkierungen an und unterbrechen Sie die Hervorhebung direkt im DAG-Diagramm
• Log-Stream：Protokollfenster im Terminal-Stil unten auf der Seite mit den Ausführungsdetails

Debugging per REST steuern

Hinter dem Debug-Panel steht eine Reihe von REST-Endpunkten, die sich bei der Skript-basierten Fehlersuche direkt aufrufen lassen (dieselbe Schnittstelle wie das Panel):

Das Präfix ist jeweils /api/executions/{executionId}. Zum Beispiel:

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

Beim Pausieren Variablen ändern und dann weiterlaufen

Typisches Szenario: Ein vorgelagerter Schritt hat einen offensichtlich falschen Parameter berechnet; nachdem der Breakpoint angehalten hat, korrigieren Sie die Variable direkt und klicken auf „Fortsetzen“, woraufhin die folgenden Schritte mit dem neuen Wert ausgeführt werden und ein kompletter Neustart entfällt. Im Panel bearbeiten Sie den Variablenwert per Doppelklick; über REST läuft es über POST /debug/variables; eine Änderung wird nur akzeptiert, wenn sich die Ausführung im pausierten Zustand befindet.

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

Neustart ab einem bestimmten Schritt

Nachdem die Ausführung einen Endzustand erreicht hat (abgeschlossen, fehlgeschlagen oder abgebrochen), lässt sie sich ab einem bestimmten Schritt erneut ausführen: Klicken Sie in der Ausführungszeitachse oder im Schrittdetail-Panel auf „Ab diesem Schritt erneut ausführen“. Die Ergebnisse der Schritte vor dem Wiederholungspunkt bleiben unverändert erhalten, bereits abgeschlossene LLM-Schritte rufen das Modell nicht erneut auf und verursachen somit keine doppelten Token-Kosten.

• Der Wiederholungspunkt muss ein in dieser Ausführung tatsächlich durchlaufener Schritt sein; ein Neustart ab dem ersten Schritt entspricht einer vollständigen Wiederholung und unterliegt dieser Einschränkung nicht
• Während die Ausführung noch läuft, ist keine Wiederholung möglich; brechen Sie sie zuerst ab oder warten Sie, bis sie endet
• REST:POST /api/executions/{executionId}/restart-from-step; ein leeres stepName im body bedeutet eine Wiederholung von Anfang an

Aktuelle Einschränkungen

• Halten Sie hauptsächlich an Schrittgrenzen und Schlüsselpunkten zusammengesetzter Knoten an
• hängt nicht im Tool-/Token-Stream
• Die Parallelität der obersten Ebene wird serialisiert, wenn das Debuggen aktiviert ist

Nächster Schritt

• Terminplanung — Verbinden Sie den Debug-Pass-Workflow mit cron/webhook
• Automatische Fortsetzung — Entscheiden Sie nach dem Debuggen, welche Schritte idempotent sind