138 lines
7.1 KiB
Markdown
138 lines
7.1 KiB
Markdown
# Bereich: Kanban-Engine (kartenbasierte Themenverarbeitung)
|
|
beschreibung: Verteilt einen Themen-Run als Kanban-Board über mehrere Stages und zieht Karten worker-gesteuert durch die Verarbeitung.
|
|
|
|
## Feature: Themen-Run starten und überwachen [kern]
|
|
beschreibung: Initialisiert pro Topic den Laufzeit-Zustand, fährt Worker pro Stage hoch und meldet den Live-Fortschritt der Karten im Fluss.
|
|
|
|
### Kann für ein Topic einen Lauf starten, Worker hochfahren und live registrieren
|
|
einheiten: backend/kanban.py::run_flow
|
|
|
|
### Kann den Laufzeit-Zustand pro Topic (aktive Worker, Producer, Wachsignal) führen
|
|
einheiten: backend/kanban.py::Flow
|
|
|
|
### Kann sekündlich die Gesamtzahl der Karten im Fluss als deutschen Statustext melden
|
|
einheiten: backend/kanban.py::_progress
|
|
|
|
## Feature: Board und Stages modellieren [kern]
|
|
beschreibung: Bildet die Spalten eines Kanban-Boards mit Verarbeitung und Verhaltens-Flags ab und verknüpft Vorgänger-Stages automatisch.
|
|
|
|
### Kann eine Kanban-Spalte mit zugeordneter Verarbeitung und Verhaltens-Flags (Serial, Drain, Barrier, Gate) beschreiben
|
|
einheiten: backend/kanban.py::Stage
|
|
|
|
### Kann Vorgänger-Spalten automatisch verketten, sodass Barrier-Worker ihre Quellen kennen
|
|
einheiten: backend/kanban.py::chain_stages
|
|
|
|
## Feature: Karten worker-gesteuert abarbeiten [kern]
|
|
beschreibung: Pullt Karten aus der Queue der eigenen Stage, hält mehrere Pakete gleichzeitig und wartet reaktiv auf neue Arbeit.
|
|
|
|
### Kann Karten pullen, mehrere Pakete gleichzeitig halten und beim Stopp alle laufenden Tasks sauber abbrechen
|
|
einheiten: backend/kanban.py::_worker
|
|
|
|
### Kann reaktiv auf neue Arbeit warten, statt dauerhaft zu pollen
|
|
einheiten: backend/kanban.py::_sleep_wake
|
|
|
|
### Kann Ruhe über aktive Worker und Queue-Bestand zuverlässig erkennen und zum Beenden auflösen
|
|
einheiten: backend/kanban.py::quiescent
|
|
|
|
## Feature: Fehler im Karten-Lauf behandeln [kern]
|
|
beschreibung: Wiederholt fehlgeschlagene Karten mit exponentiellem Backoff und verschiebt erschöpfte Karten in die Dead-Letter-Stage.
|
|
|
|
### Kann fehlgeschlagene Karten mit Backoff wiederholen oder als Dead-Letter ablegen, ohne bereits weitergerückte Karten zu bestrafen
|
|
einheiten: backend/kanban.py::_fail_package
|
|
|
|
# Bereich: Pipeline-Steuerung (Guide-Laufzeitverwaltung)
|
|
beschreibung: Orchestriert parallele Agent-Aufrufe für einen Guide, verwaltet Stornierung und Fortschritt und stellt Helfer für Prompt-Bau sowie Fehlerformatierung bereit.
|
|
|
|
## Feature: Guide-Abbruch handhaben [kern]
|
|
beschreibung: Markiert einen Guide als abgebrochen, beendet laufende Agent-Slots und gibt die Sperre für einen Neustart wieder frei.
|
|
|
|
### Kann einen laufenden Guide abbrechen, zugehörige Agent-Slots stoppen und den Datensatz als fehlgeschlagen markieren
|
|
einheiten: backend/pipeline.py::cancel_guide
|
|
|
|
### Kann den Stornierungsstatus eines Guides abfragen
|
|
einheiten: backend/pipeline.py::is_guide_cancelled
|
|
|
|
### Kann nach einem Abbruch die Sperre lösen, damit der Guide neu gestartet werden kann
|
|
einheiten: backend/pipeline.py::clear_guide_cancelled
|
|
|
|
## Feature: Live-Fortschritt und Statusmeldungen [kern]
|
|
beschreibung: Schreibt Fortschritt, Schrittnummer und Fehler persistiert und meldet nebenläufige Jobs mit Live-Zähler an einen Reporter.
|
|
|
|
### Kann Fortschritt, Schrittnummer und Fehlermeldung im Guide-Datensatz persistieren
|
|
einheiten: backend/pipeline.py::_set_progress, backend/pipeline.py::_set_step, backend/pipeline.py::_fail
|
|
|
|
### Kann nebenläufige Jobs mit Live-Zähler an einen Reporter melden und auch bei Ausnahmen weiterzählen
|
|
einheiten: backend/pipeline.py::_gather_progress
|
|
|
|
### Kann Info-Meldungen mit Topic-Präfix einheitlich loggen
|
|
einheiten: backend/pipeline.py::_log
|
|
|
|
## Feature: Parallele Agent-Slots orchestrieren [kern]
|
|
beschreibung: Startet mehrere Agent-Slots parallel, sammelt bis zum Quorum gültige Ergebnisse und reagiert auf Stornierung und Infrastrukturfehler.
|
|
|
|
### Kann mehrere Agent-Slots parallel starten und auf eine konfigurierbare Quorum-Anzahl gültiger Ergebnisse warten, mit Hedging, Grace-Periode und Infrastruktur-Retries
|
|
einheiten: backend/pipeline.py::_race
|
|
|
|
### Kann Pipeline-Parameter einmal bündeln und durch alle Pipeline-Glieder reichen
|
|
einheiten: backend/pipeline.py::GenContext
|
|
|
|
## Feature: Fehler klassifizieren und formatieren [rand]
|
|
beschreibung: Erkennt Infrastruktur- von inhaltlichen Fehlern und baut kompakte Fehlertexte für Anzeige und Vergleich.
|
|
|
|
### Kann Infrastruktur- von inhaltlichen Fehlern anhand einer Markerliste unterscheiden
|
|
einheiten: backend/pipeline.py::_is_infra
|
|
|
|
### Kann Agent-Fehler aus Returncode und Ausgaben zu einer kompakten Meldung formatieren
|
|
einheiten: backend/pipeline.py::_claude_error
|
|
|
|
### Kann aus einer Liste von Slot-Ergebnissen den ersten verwertbaren Fehler auswählen und melden
|
|
einheiten: backend/pipeline.py::_gather_error
|
|
|
|
## Feature: Prompt-Bau und Schemavalidierung [rand]
|
|
beschreibung: Stellt Helfer bereit, um Prompts aus Vorlagen aufzubauen, Timeouts zu berechnen und Agent-Antworten zu validieren.
|
|
|
|
### Kann Prompt-Vorlagen aus dem Templates-Verzeichnis laden und mit Argumenten ausfüllen
|
|
einheiten: backend/pipeline.py::_prompt
|
|
|
|
### Kann zusätzliche Nutzeranweisungen als klar markierten Block an einen Prompt anhängen
|
|
einheiten: backend/pipeline.py::_extra
|
|
|
|
### Kann die Timeout-Dauer eines Schritts als Basis plus skalierten Zuschlag pro Eintrag berechnen
|
|
einheiten: backend/pipeline.py::_timeout
|
|
|
|
### Kann die Probleme-Liste einer Agent-Antwort bereinigen oder leer zurückgeben
|
|
einheiten: backend/pipeline.py::_problems_schema
|
|
|
|
# Bereich: Provider-Konfiguration
|
|
beschreibung: Lädt Umgebung und Provider-Defaults, wählt pro Rolle den effektiven Provider samt Modell und überschreibt Tuning-Werte zur Startzeit.
|
|
|
|
## Feature: Umgebung und Defaults laden [kern]
|
|
beschreibung: Lädt eine .env-Datei und stellt den Default-Provider als Pflicht-Voraussetzung für den Start sicher.
|
|
|
|
### Kann eine .env-Datei laden und damit Umgebungsvariablen setzen, auch über bereits gesetzte Werte hinweg
|
|
einheiten: backend/config.py::_load_env
|
|
|
|
### Kann das System ohne konfigurierten Default-Provider gar nicht starten
|
|
einheiten: backend/config.py::DEFAULT_PROVIDER
|
|
|
|
## Feature: Provider-Stacks und Rollen-Routing [kern]
|
|
beschreibung: Stellt mehrere unabhängige Provider-Stacks bereit und routet Agent-Rollen optional auf alternative Provider um.
|
|
|
|
### Kann mehrere unabhängige Provider-Stacks (Cloud-Auth, API-Key, lokal) mit Modellen und Authentifizierung bereitstellen
|
|
einheiten: backend/config.py::PROVIDERS
|
|
|
|
### Kann die vier Agent-Rollen prozessweit auf alternative Provider umleiten
|
|
einheiten: backend/config.py::ROLE_ROUTING
|
|
|
|
### Kann für eine Rolle das effektive (Provider, Modell)-Paar unter Berücksichtigung von Overrides und "provider:model"-Syntax liefern
|
|
einheiten: backend/config.py::resolve_role
|
|
|
|
## Feature: Schritt-Timeouts und Tuning-Overrides [rand]
|
|
beschreibung: Definiert pro Agent-Schritt eine Timeout-Paarung und erlaubt numerische Tuning-Overrides per JSON zur Startzeit.
|
|
|
|
### Kann pro Agent-Schritt ein Timeout-Paar (Basis, Pro-Eintrag) zentral definieren
|
|
einheiten: backend/config.py::TIMEOUTS
|
|
|
|
### Kann numerische Tuning-Konstanten aus einer JSON-Umgebungsvariablen zur Startzeit überschreiben
|
|
einheiten: backend/config.py::_apply_param_overrides
|