Workflows ausführen

Das Ausführen eines Workflows in CodeCourier erzeugt eine Ausführungsinstanz (einen "Run"), die die Pipeline-Schritte sequenziell verarbeitet. Jeder Run hat seinen eigenen Prompt, eigene Konfigurations-Overrides und seinen eigenen Ausführungszustand. Diese Anleitung beschreibt, wie Sie Runs starten, was während der Ausführung passiert und wie Sie sie überwachen und verwalten.

Einen Run starten

Run-Ausführungsablauf

Der Workflow-Orchestrator (ein Trigger.dev-Hintergrund-Task) verwaltet den gesamten Lebenszyklus des Runs:

1. Run-Initialisierung

Der Orchestrator liest die Workflow-Blaupause, löst Persona- Referenzen auf und erstellt den Ausführungsplan. Er zerlegt die Pipeline-Schritte in Execution Blocks (einzelne Schritte und Loops) und bereitet die Sandbox- Konfiguration vor.

2. Schritt-Ausführung

Für jeden Schritt in der Pipeline tut der Orchestrator:

1. Erstellt einen Run-Schritt-Datensatz in der runSteps-Tabelle mit der Rolle, der Iterations- Nummer, der Persona-Referenz und dem Status des Schritts.
2. Erstellt eine E2B-Sandbox aus der konfigurierten Vorlage. Die Sandbox wird mit dem Git-Repo des Projekts, Umgebungs- Variablen, Skills und Learnings eingerichtet.
3. Sendet den entsprechenden Step-Task (designer-step, checker-step, optimizer-step usw.) an Trigger.dev.
4. Der Step-Task führt den KI-Agenten innerhalb der Sandbox mit Prompt und Anweisungen des Schritts aus. Die Ausgabe streamt zurück zur Sandbox-Nachrichten-Tabelle.
5. Protokolliert Token-Verbrauch und Kostendaten für den Schritt.
6. Aktualisiert den Status des Run-Schritts auf completed oder failed.

3. Iteration-Block-Behandlung

Erreicht der Orchestrator einen Iteration Block(eine Gruppe aufeinanderfolgender Schritte mit einer loopId), führt er die Schritte des Blocks in Folge aus und prüft dann das Urteil:

• Erzeugt der Checker-Schritt ein positives Urteil, verlässt der Block die Schleife und die Ausführung fährt mit dem nächsten Block fort.
• Erzeugt der Checker-Schritt ein negatives Urteil, läuft der Block ab seinem ersten Schritt erneut. Das Feedback des Checkers wird in den Prompt des Designers in der nächsten Iteration eingebaut.
• Werden die loopMaxIterations des Blocks ohne positives Urteil erreicht, wird der Block beendet und der Run als failed markiert.

Schritte außerhalb eines Iteration Block werden genau einmal ausgeführt. Checker außerhalb eines Blocks geben weiterhin ein Urteil ab, lösen aber keinen automatischen Retry aus.

4. Run-Abschluss

Wenn alle Execution Blocks verarbeitet wurden:

1. Der Run-Status wird auf completed aktualisiert.
2. Der Zeitstempel completedAt wird gesetzt.
3. Ein Pull-Request wird erstellt, wenn der Run Git-Änderungen erzeugt hat.
4. Learning-Extraktion wird für die Sandboxes des Runs angestoßen.
5. Projektzähler werden aktualisiert.
6. Benachrichtigungen werden versendet (falls konfiguriert).

Run-Zustände

Jeder Run befindet sich in einem von sieben Zuständen:

• scheduled - Der Run wurde durch den Scheduler wiederkehrender Aufgaben eingereiht und wartet auf seinen geplanten Auslösezeitpunkt. Dies ist ein Vor-Ausführungs-Zustand, der pending vorangeht. Geplante Runs tragen einen scheduledFor- Zeitstempel, eine timezone, ein recurrencePatternund eine recurringTaskId, die auf die wiederkehrende Aufgabe verweist, die ihn erzeugt hat.
• pending - Der Run wurde erstellt, aber der Orchestrator hat die Verarbeitung noch nicht gestartet.
• running - Der Orchestrator führt aktiv Schritte aus. Das Feld currentIterationverfolgt den Fortschritt.
• paused - Der Run wurde vorübergehend ausgesetzt. Dies kann passieren, wenn ein Benutzereingriff erforderlich ist.
• completed - Alle Schritte sind erfolgreich abgeschlossen.
• failed - Ein Schritt ist auf einen nicht behebbaren Fehler gestoßen. Das Feld error enthält die Fehlermeldung.
• cancelled - Der Run wurde manuell vom Nutzer abgebrochen.

Einen Run überwachen

Run-Detailansicht

Die Run-Detailseite bietet einen umfassenden Überblick über die Ausführung:

• Status und Fortschritt - Aktueller Zustand, Iterations- Anzahl und vergangene Zeit.
• Schritt-Zeitleiste - Eine visuelle Zeitleiste, die jeden Run-Schritt, dessen Rolle, Status und Dauer zeigt. Sie können auf einen Schritt klicken, um dessen Sandbox-Ausgabe zu sehen.
• Sandbox-Nachrichten - Die gestreamte Terminal-Ausgabe jeder Sandbox, die die Arbeit des KI-Agenten in Echtzeit zeigt.
• Urteile - Für Checker-Schritte werden das Pass/Fail-Urteil und der Feedback-Text angezeigt.
• PR-Status - Wurde ein Pull-Request erstellt, werden seine URL und sein Status angezeigt.

Run-Listenansicht

Die Runs-Seite zeigt eine paginierte Liste aller Runs des Projekts. Jede Zeile zeigt den Run-Namen, Status, Quelle (Workflow, Sprint oder Sandbox), Erstellzeit und Prompt-Vorschau. Sie können Runs filtern und sortieren und Bulk-Aktionen verwenden, um mehrere Runs gleichzeitig zu löschen.

Run-Quellen

Runs werden aus mehreren Quellen erstellt, verfolgt durch das Feld source:

• workflow - Manuell von einer Workflow-Blaupause auf der Workflows-Seite ausgelöst.
• issue - Von einer Work Chain im Rahmen einer Issue-Session-Ausführung erstellt.
• sandbox - Aus einem eigenständigen Sandbox-Launch erstellt.
• merge_agent - Vom Merge-Agent für die PR-Verwaltung erstellt.
• sprint - Vom Sprint-Chain- Orchestrator im Rahmen einer Batch-Sprint-Ausführung erstellt.
• scheduled - Vom Scheduler für wiederkehrende Aufgaben in konfigurierter Frequenz (täglich, wöchentlich usw.) erstellt.

Fehlerbehandlung

Schritt-Fehler

Wenn ein einzelner Schritt fehlschlägt, wird der Fehler im Run-Schritt- Datensatz protokolliert. Abhängig vom Fehlertyp:

• Fehler bei der Sandbox-Erstellung - E2B konnte die VM nicht bereitstellen. Das bedeutet meist, dass der E2B-API-Schlüssel ungültig ist oder die Vorlage nicht existiert.
• Agenten-Absturz - Der KI-CLI-Prozess wurde unerwartet beendet. Die Fehlerausgabe wird in den Sandbox-Nachrichten erfasst.
• Timeout - Die Sandbox hat das konfigurierte Timeout überschritten. Die vor dem Timeout geleistete Arbeit bleibt erhalten, sofern committet.
• API-Fehler - Der KI-Anbieter hat einen Fehler zurückgegeben (Rate- Limit, ungültiger Schlüssel, Serverfehler).

Run-Wiederherstellung

CodeCourier unterstützt derzeit nicht, einen fehlgeschlagenen Run vom Fehlerpunkt aus fortzusetzen. Schlägt ein Run fehl, können Sie einen neuen Run mit demselben Prompt starten. Der neue Run startet von vorne, aber wenn der vorherige Run Commits in den Branch gepusht hat, baut der neue Run dort auf, wo der Code stehengeblieben ist.

Nach dem aktuellen Turn stoppen

Zusätzlich zum sofortigen Abbruch können Sie das Flag stopAfterCurrentTurn für einen laufenden Workflow setzen. Dies ist ein geordneter Stopp, der es dem aktuell laufenden Agenten-Turn erlaubt, abzuschließen, bevor der Run angehalten wird. Es ist nützlich, wenn Sie Teilergebnisse prüfen möchten, ohne die bereits in Bearbeitung befindliche Arbeit zu verlieren.

Wenn stopAfterCurrentTurn gesetzt ist:

1. Der Orchestrator schließt den aktuellen Agenten-Turn ab (die KI beendet ihre aktuelle Antwort, Tool-Nutzung und alle Datei-Commits).
2. Statt zur nächsten Iteration oder zum nächsten Schritt überzugehen, wechselt der Run in den Zustand paused.
3. Code-Änderungen, die während des letzten Turns committet wurden, bleiben auf dem Branch erhalten.

Sie können dieses Flag von der Run-Detailseite über die Schaltfläche "Nach Turn stoppen" setzen, die verfügbar ist, solange sich der Run im Zustandrunning befindet. Dies ist gegenüber einem harten Abbruch zu bevorzugen, wenn Sie einen sauberen Stoppunkt statt eines abrupten Halts wünschen.

CI-Checks-Verfolgung

Nachdem ein Run einen Pull-Request erzeugt, verfolgt CodeCourier den Status der CI-Checks für diesen PR. Das Objekt ciChecks im Run-Datensatz spiegelt den aktuellen Status aus der Checks-API von GitHub wider:

ciChecks: {
  status: "passing" | "failing" | "pending",  // Aggregate CI status
  checks: Array<{
    name: string,       // Check name (e.g., "Build", "Tests", "Lint")
    status: string,     // Individual check status
    url: string,        // Link to the check run on GitHub
  }>,
  checkedAt: number,    // Unix timestamp of the last status poll
}

Wenn die CI-Checks im PR eines Runs fehlschlagen, wechselt der PR-Status des Runs zu blocked_on_ci. Dieser Status ist von den anderen PR-Zuständen verschieden und zeigt an, dass der PR existiert und offen ist, aber erst gemergt werden kann, wenn die CI erfolgreich durchläuft.

PR-Statuswerte

Das Feld prStatus in einem Run verfolgt den gesamten Lebenszyklus des zugehörigen Pull-Requests:

• creating - Die Anfrage zur PR-Erstellung wurde abgesetzt, aber noch nicht abgeschlossen.
• created - Der PR ist offen und wartet auf Review. CI-Checks können laufen.
• blocked_on_ci - Der PR ist offen, aber die CI-Checks scheitern. Das Objekt ciChecksenthält Details, welche Checks fehlgeschlagen sind.
• merged - Der PR wurde in den Ziel-Branch gemergt.
• failed - Der Versuch der PR-Erstellung ist fehlgeschlagen (z. B. GitHub-API-Fehler, Authentifizierungsfehler). Das Feld prError enthält die Fehlermeldung.
• skipped - Der Run hat keine Code-Änderungen erzeugt, daher wurde kein PR erstellt.

Qualitäts-Scores

Enthält der Workflow einen Evaluator-Schritt, verfolgt der Run-Datensatz einen gesamten qualityScore (den Composite-Score aller Evaluator-Schritte). Einzelne Run-Schritt-Datensätze tragen die vollständige qualityScores-Aufschlüsselung:

// On the run record:
qualityScore: number,   // Composite score (0-100) from all evaluator steps

// On individual runStep records (type: "evaluator"):
qualityScores: {
  correctness: number,      // 0-100
  typeSafety: number,       // 0-100
  codeStyle: number,        // 0-100
  testCoverage: number,     // 0-100
  completeness: number,     // 0-100
  composite: number,        // Weighted average of all five dimensions
  thresholdResult: boolean, // Whether composite meets the configured threshold
}

Qualitäts-Scores sind in der Schritt-Zeitleiste der Run-Detailansicht und im Monitoring-Dashboard sichtbar. Runs mit niedrigen Qualitäts-Scores oder einem fehlschlagenden thresholdResult werden visuell hervorgehoben, sodass sie in der Run-Liste auffallen.

Einen Run abbrechen

Sie können einen laufenden Workflow über die Run-Detailseite abbrechen. Der Abbruch:

1. Setzt den Run-Status auf cancelled.
2. Versucht, alle aktiven Sandboxes des Runs zu beenden.
3. Stoppt den Orchestrator daran, weitere Schritte zu verarbeiten.

Der Abbruch erfolgt nach bestem Bemühen - befindet sich ein Schritt mitten in der Ausführung, kann die Sandbox weiterlaufen, bis der Kill-Befehl wirkt. Möchten Sie einen saubereren Stopp, verwenden Sie stattdessen das Flag stopAfterCurrentTurn(siehe oben).

Run-Metadaten

Jeder Run-Datensatz enthält Metadaten, die für Verfolgung und Analyse nützlich sind:

{
  status: "running",              // Current state (includes "scheduled")
  prompt: "...",                  // The task description
  source: "workflow",             // How the run was created (workflow|sprint|sandbox|scheduled|...)
  currentIteration: 2,           // Current iteration inside an Iteration Block (or 1 when no block is active)
  config: { ... },               // Sandbox configuration
  githubRepoUrl: "...",          // Git repository
  branchName: "feat/...",        // Working branch
  prUrl: "...",                  // Pull request URL (after completion)
  prStatus: "created",           // PR lifecycle state (includes "blocked_on_ci")
  startedAt: 1712345678,         // Execution start timestamp
  completedAt: null,             // Null until finished
  cliVersion: "1.2.3",          // CLI tool version used
  qualityScore: 87,              // Composite quality score from evaluator steps
  stopAfterCurrentTurn: false,   // Graceful stop flag
  ciChecks: {                    // CI check status for the run's PR
    status: "passing",
    checks: [...],
    checkedAt: 1712345900,
  },
  // Scheduled run fields (only when source = "scheduled"):
  scheduledFor: 1712340000,      // Intended fire time
  timezone: "America/New_York",  // Timezone from recurring task
  recurrencePattern: "daily",    // Frequency (daily|weekly|...)
  recurringTaskId: "...",        // Reference to the recurring task
}