210 lines
12 KiB
Markdown
210 lines
12 KiB
Markdown
# Dauerhafter Analyseworker
|
|
|
|
Der Worker verbindet die Übergabe-API mit dem vorhandenen Analyseablauf. Er nimmt
|
|
Pakete aus derselben Inbox auf, wählt die serverseitige Projektkonfiguration und
|
|
bearbeitet aktive Fälle bis zu Outbox oder Review. Er erstellt keine Patches,
|
|
führt keine Builds aus und verändert keine Projekt-Datenbank.
|
|
|
|
## Konfiguration
|
|
|
|
`config/worker.example.toml` verweist auf die Konfiguration der Übergabe-API.
|
|
API und Worker müssen denselben Workspace und Projektkatalog verwenden. Der
|
|
Worker benötigt die API-Clienttokens nicht, wohl aber die in seiner LLM-Konfiguration
|
|
genannten Provider-Zugangsdaten. Beide Prozesse dürfen getrennt laufen.
|
|
|
|
Für jedes freigegebene Projekt werden die Analysekonfigurationen in der
|
|
API-Konfiguration hinterlegt:
|
|
|
|
```toml
|
|
[[projects]]
|
|
id = "viano-core"
|
|
type = "wow"
|
|
profile = "vcore"
|
|
adapter = "vcore"
|
|
planning_mode = "joint"
|
|
[projects.settings]
|
|
project_config = "project.local.toml"
|
|
llm_config = "llm.early-review.local.toml"
|
|
investigation_config = "investigation.bounded.toml"
|
|
```
|
|
|
|
Die Pfade sind relativ zur API-Konfigurationsdatei. `llm_config` ist erforderlich.
|
|
Weitere optionale Einstellungen: `analysis_config`, `budget_config`,
|
|
`diagnosis_config`, `change_request_config`, `correction_config`. Ohne explizite
|
|
Datei gelten deren bestehende Standardwerte. Für den aktuellen Vcore-Betrieb die
|
|
erprobte `investigation.bounded.toml` verwenden; ältere ausführliche Promptmodi
|
|
können an der unveränderten 20.000-Zeichen-Grenze scheitern.
|
|
|
|
`planning_mode` ist je Projekt `joint` (Standard) oder `separate`. Die Profilbindung
|
|
einer Akte muss vollständig zum Katalog passen: `project.id`, `type`, `profile`.
|
|
Alte manuelle Pakete ohne `project.id` werden nicht automatisch zugeordnet.
|
|
Andere Projektadapter bleiben ein eigener Ausbauschritt.
|
|
|
|
## Start und Prüfung
|
|
|
|
```powershell
|
|
.\.venv\Scripts\python.exe -m viano_bug_analysis.worker check --config config/worker.local.toml
|
|
.\.venv\Scripts\python.exe -m viano_bug_analysis.worker run --config config/worker.local.toml
|
|
```
|
|
|
|
`check` lädt Konfiguration und prüft die Anwesenheit der LLM-Zugangsdaten. Es sendet
|
|
keine Modellanfrage und ist kein Erreichbarkeitstest für API, Datenbank oder
|
|
Repository. `run` verarbeitet angenommene Aufträge und kann deshalb kostenpflichtige
|
|
LLM-Aufrufe auslösen. Der reine Start ohne anstehende Fälle führt keine Modellaufrufe
|
|
aus. `run --once` führt genau einen Scheduler-Durchgang aus, nicht einen vollständigen
|
|
Buglauf. Auch dieser Modus kann LLM-Aufrufe auslösen.
|
|
|
|
API zusätzlich in einem zweiten Prozess starten:
|
|
|
|
```powershell
|
|
.\.venv\Scripts\python.exe -m viano_bug_analysis.api serve --config config/api.local.toml
|
|
```
|
|
|
|
Für diese Entwicklung wurden die zuvor nicht vorhandenen lokalen Dateien
|
|
`config/api.local.toml` und `config/worker.local.toml` mit dem Vcore-Profil vorbereitet.
|
|
Sie sind nicht versioniert und enthalten keine Zugangsschlüssel. Vorhandene lokale
|
|
Konfigurationen werden bei späteren Änderungen nicht automatisch überschrieben.
|
|
|
|
## Scheduling und Wiederanlauf
|
|
|
|
- Pro Durchgang erhält jeder berechtigte aktive Fall einen Dispatch. Danach
|
|
darf der nächste Fall arbeiten. Gibt es Fortschritt, folgt der nächste Durchgang
|
|
unmittelbar; nur im Leerlauf oder bei Wartefällen greift das Pollintervall.
|
|
- Der Dienst läuft als einzelner Analyseprozess. Eine OS-Dateisperre verhindert
|
|
einen zweiten Worker im selben Workspace. Die Fall-Lease ist mit dem manuellen
|
|
Trialbefehl geteilt. API-Veröffentlichungen verwenden weiterhin die kurzen
|
|
Checkpoint-/Inbox-Sperren; während einer Modellanfrage bleibt die API benutzbar.
|
|
- Paketmanifest und Checkpoints bleiben maßgeblich. Es wird nur die neueste
|
|
Generation pro Fall geprüft, nicht jede historische Generation erneut geöffnet.
|
|
- Bei Neustart werden verwaltete aktive Fälle und noch nicht übernommene Uploads
|
|
wiedergefunden. PREPARED-Veröffentlichungen der API werden vor der Verarbeitung
|
|
abgeschlossen. Rückläufer starten die bereits eröffnete neue Analyse-Revision;
|
|
alte Interpretation und Hypothesen werden nicht als neue Ergebnisse behandelt.
|
|
- Bestehende LLM-Operationskennungen bleiben stabil. Der Dienst ändert keine
|
|
Versuchskennungen, Budgets, Iterationsgrenzen oder Korrekturregeln, um einen
|
|
blockierten Fall weiterzutreiben.
|
|
- `RETRY_PENDING`/`DEFERRED` beachten die gespeicherte Wartezeit. Ein unerwarteter
|
|
Konfigurations-/Vorbereitungsfehler erhält einen lokalen Cooldown; andere Fälle
|
|
werden weiterbearbeitet. Eine ausdrücklich zurückgegebene `ERROR`-Antwort oder
|
|
unerwartete Exception während eines Dispatch erzeugt `ATTENTION`, statt dieselbe
|
|
Fehlantwort endlos abzuspielen oder möglicherweise erneut Modellkosten auszulösen.
|
|
- BLOCKED bleibt BLOCKED, wenn eine menschliche Testerantwort benötigt wird,
|
|
automatische Wiederholung untersagt ist, Modellvalidierung gescheitert ist oder
|
|
die LLM-Wiederholungen ausgeschöpft sind. Explizit freigegebene, fällige technische
|
|
Wiederholungen dürfen über den vorhandenen Resume-Checkpoint fortgesetzt werden.
|
|
- Outbox-/Review-Veröffentlichung wird nach Erfolg nicht ständig wiederholt. Nach
|
|
einem Absturz zwischen Paketabschluss und Veröffentlichung kann der bestehende
|
|
Outputvalidator die fehlende Veröffentlichung idempotent nachholen.
|
|
|
|
Ein Prozessabbruch während einer externen Modellanfrage kann deren bereits
|
|
berechnete Kosten nicht zurücknehmen. Ist die Antwort vor dem Checkpoint verloren
|
|
gegangen, lässt sich eine erneute Anfrage nicht grundsätzlich ausschließen. Der
|
|
Worker verspricht keine Exactly-once-Ausführung beim externen Anbieter.
|
|
|
|
## Betrieb und Fehlerbehandlung
|
|
|
|
```powershell
|
|
.\.venv\Scripts\python.exe -m viano_bug_analysis.worker status --config config/worker.local.toml
|
|
```
|
|
|
|
`runtime/worker/status.json` enthält den letzten Dienstzustand und gegebenenfalls
|
|
den bearbeiteten Fall. Es ist ein Snapshot, kein Beweis für einen noch lebenden
|
|
Prozess. Die bestehende Telemetrie liefert ergänzend Heartbeat, Phasen, Laufzeiten
|
|
und Modellverbrauch. `runtime/worker/cases/` enthält kleine lokale
|
|
Schedulingquittungen mit Status, Fehlercode, Wartezeit und Konfigurationshashes.
|
|
Keine Prompts, Antworten oder Geheimnisse werden diesen Quittungen hinzugefügt.
|
|
Die Statusantwort der Übergabe-API enthält für einen zugeordneten Fall zusätzlich
|
|
den letzten Workerstatus.
|
|
|
|
Die Akte bleibt vollständig transportabel. Die lokalen Quittungen sind keine
|
|
fachliche Beweisquelle und keine verteilte Jobdatenbank. Bei ihrer vollständigen
|
|
Entfernung müssen reine Scheduler-Cooldowns/Attention-Markierungen gegebenenfalls
|
|
neu erkannt werden; fachliche Sperren und LLM-Operationshistorie bleiben im Paket.
|
|
|
|
Konfigurationsdateien werden über ihre Hashes vor dem ersten Dispatch gebunden.
|
|
Eine geänderte Konfiguration wird nicht unbemerkt auf dieselbe aktive Revision
|
|
angewendet. Neue Profileinstellungen benötigen einen Worker-Neustart; laufende
|
|
Revisionen mit abweichender Bindung gehen auf `ATTENTION/WORKER_CONFIG_CHANGED`.
|
|
Auch abhängige Profil-/Relationsdateien nicht während einer Untersuchung ändern.
|
|
Eine allgemeine Migration laufender Modelloperationen auf neue Policies ist noch
|
|
kein Bestandteil dieses Dienstes.
|
|
|
|
Nach Behebung eines lokalen Schedulingfehlers kann der Betreiber den **gestoppten**
|
|
Worker freigeben:
|
|
|
|
```powershell
|
|
.\.venv\Scripts\python.exe -m viano_bug_analysis.worker retry --config config/worker.local.toml --case-id BUG-000020 --package-id api-PAKETIDENTITAET
|
|
```
|
|
|
|
Dies entfernt die lokale Warte-/Attention-Markierung, aber setzt keine LLM-Operation
|
|
oder fachliche Budgets zurück. Für einen fälligen `RESEARCH_UNAVAILABLE`-Fall
|
|
bestätigt der Befehl zusätzlich die Reparatur des Research-Dienstes und setzt dessen
|
|
Resume-Checkpoint fort. Andere BLOCKED-Gründe, ausstehende menschliche Rückmeldungen
|
|
und abweichende Konfigurationsbindungen werden damit nicht umgangen.
|
|
|
|
Bei zu wenig freiem Speicher pausiert der Worker mit `STORAGE_LOW`, ohne Akten zu
|
|
löschen oder Untersuchungsbudgets zu verbrauchen. Die konfigurierbare
|
|
`min_free_bytes`-Reserve ersetzt keine Speicherüberwachung oder Retention. Die
|
|
20-GB-Vorgabe für Entwicklungs-/Testdaten bleibt davon unabhängig. Der Worker
|
|
löscht keine Paketgenerationen und keine Inhalte erhaltener Akten.
|
|
|
|
Die [Web-Betriebssteuerung](web-console.md#betriebssteuerung) kann neue Fälle je
|
|
Projekt pausieren, während begonnene Analysen abschließen. Freigabeaufträge werden
|
|
dauerhaft gespeichert und zwischen Dispatches unter derselben Fall-Lease geprüft.
|
|
Damit ist für Web-Freigaben kein Worker-Stopp nötig. CLI-Freigaben benötigen
|
|
weiterhin den gestoppten Dienst. Alle fachlichen Retry- und Budgetregeln gelten
|
|
für beide Wege; ein veralteter Webauftrag entsperrt keinen neueren Paketstand.
|
|
|
|
Ctrl+C bzw. SIGTERM fordert einen geordneten Stopp an. Der laufende Dispatch darf
|
|
noch abschließen; erst danach wird die Prozess-Lease freigegeben. Ein Dispatch
|
|
kann mehrere interne Schritte/Modellanfragen enthalten und entsprechend dauern.
|
|
Bei hartem Beenden greift beim nächsten Start der Checkpoint-Wiederanlauf.
|
|
|
|
## Freigabe nach einer technischen Korrektur
|
|
|
|
Bei `ENTITY_RESOLUTION_INVALID_RESPONSES` bietet die aktuelle Fallansicht die
|
|
Aktion **Einen Reparaturversuch freigeben**. Vorher die technische Ursache beheben
|
|
und im Pflichtfeld kurz dokumentieren (keine Secrets). Die Freigabe wird über den
|
|
authentifizierten Betreiberzugang mit CSRF-Schutz vorgemerkt. Maschinenclients
|
|
dürfen sie nicht auslösen. Der Worker prüft Zustand, Projektbindung und aktuelle
|
|
Paketgeneration erneut. Doppelte oder veraltete Aufträge gewähren keinen weiteren Versuch.
|
|
|
|
Jede Freigabe erlaubt genau einen zusätzlichen Antwortversuch in der betroffenen
|
|
Namensauflösungsstufe (Suchplan oder Bewertung), ohne die bisherigen Versuche zu
|
|
löschen. Eine gültige Reparatur kann anschließend den regulären Ablauf fortsetzen.
|
|
Scheitert sie, bleibt der Fall erneut gesperrt. Weitere Versuche benötigen eine neue
|
|
ausdrückliche Freigabe. Akteur, Begründung, betroffener Antwort-Hash und Code-Hash
|
|
werden dauerhaft als Checkpoint in der Fallakte gespeichert. Revision, gültiger
|
|
Suchplan, Recherchebelege und Untersuchungsbudgets werden nicht zurückgesetzt.
|
|
Die Freigabe selbst führt keine Modellanfrage aus; die anschließende Bearbeitung
|
|
kann reguläre LLM-Kosten verursachen.
|
|
|
|
Alternativ bei gestopptem Worker als root unter Linux:
|
|
|
|
```sh
|
|
/opt/viano-bug-analysis/.venv/bin/python -m viano_bug_analysis.worker repair --config /etc/viano-bug-analysis/worker.toml --case-id BUG-000021 --package-id api-PAKETIDENTITAET --reason "Technische Korrektur installiert; Namensbewertung gezielt reparieren"
|
|
```
|
|
|
|
Danach den Worker wieder starten. Der CLI-Befehl benötigt keinen Cloud-Schlüssel,
|
|
weil er nur eine Freigabe protokolliert. Die vorhandene Projektkonfiguration muss
|
|
unverändert gebunden sein. Diese Freigabe ist derzeit bewusst auf ausgeschöpfte
|
|
Namensauflösung beschränkt. Sie umgeht weder menschliche Rückfragen noch
|
|
fachliche Budgetgrenzen und öffnet keine erfolgreich abgeschlossenen Fälle oder
|
|
`FAILED_TO_ANALYZE`-Revisionen. Für andere Fehlergründe bleiben die jeweiligen
|
|
Retry- beziehungsweise Review-Verfahren maßgeblich.
|
|
|
|
Für einen Server ist die Vorlage `deploy/viano-bug-analysis-worker.service`
|
|
vorbereitet. Sie wird nicht automatisch installiert oder gestartet. Dienstbenutzer,
|
|
Pfade, Zugangsdaten und gemeinsame Workspace-Berechtigungen müssen zum Zielserver
|
|
passen. Der Worker startet weder die lokale Testdatenbank noch einen Repository-
|
|
Synchronisationsdienst. Diese Abhängigkeiten werden separat betrieben.
|
|
|
|
## Lokale Tests
|
|
|
|
Worker-, Übergabe- und Wiederanlauftests verwenden künstliche Daten und lokale
|
|
Provideradapter; es werden keine kostenpflichtigen Modellanfragen ausgeführt:
|
|
|
|
```powershell
|
|
.\.venv\Scripts\python.exe -m pytest tests/test_worker.py tests/profiles/vcore/test_worker_intake.py tests/profiles/vcore/test_intake_api.py -q
|
|
```
|