VianoBugAnalysis/README.md

VianoBugAnalysis

BugAnalysis untersucht gemeldete Softwarefehler anhand von Diagnosepaketen, Sourcecode und lesenden Datenbankabfragen. Ein dauerhaft laufender Worker erstellt Diagnosen und Aufträge für Codingagenten beziehungsweise menschliche Entwickler. Die Weboberfläche bietet Benutzeranmeldung, Betriebsübersicht, Testerantworten, API-Schlüssel und Paketdownloads. Das aktuelle Projektprofil ist für WoW/Vcore ausgelegt. BugAnalysis installiert selbst keine Bugfixes auf dem Spielserver.

Installation auf einem Linux-VPS

Diese Anleitung ist direkt auf der Repository-Startseite lesbar. Sie setzt einen Linux-Server mit systemd und einen SSH-Zugang mit sudo-Rechten voraus. Die Paketbefehle unten gelten für Debian/Ubuntu; auf anderen Distributionen die entsprechenden Pakete installieren. Python 3.11 oder neuer ist erforderlich.

1. Voraussetzungen installieren

sudo apt-get update
sudo apt-get install python3 python3-venv python3-pip git nginx ca-certificates curl
python3 --version

Ist die Python-Version älter als 3.11, zuerst eine unterstützte Python-Version bereitstellen und diese für den Installer verwenden. Datenbankserver und World-Daten werden vom Installer nicht eingerichtet oder importiert. Ein erreichbarer MariaDB-Datenbestand für die Recherche muss separat vorhanden sein, beispielsweise eine isolierte Testdatenbank aus einem Backup.

2. Repository in das vorgesehene Verzeichnis klonen

Der Installer und die systemd-Units erwarten derzeit genau /opt/viano-bug-analysis. Nicht einen beliebigen Ordnernamen verwenden. Git legt den Zielordner an; er muss dafür noch nicht existieren oder leer sein.

sudo git clone https://gitea.viano-software.de/Nico/VianoBugAnalysis /opt/viano-bug-analysis
cd /opt/viano-bug-analysis

Das Klonen mit sudo erzeugt einen root-eigenen Checkout. Der Installer verlangt, dass Programmdateien root gehören und weder für Gruppe noch andere Benutzer schreibbar sind. Bei einem privaten Repository die Git-Anmeldung interaktiv durchführen; keine Zugangsdaten in die URL schreiben.

3. Installationsplan prüfen und installieren

python3 deploy/install.py --dry-run
sudo python3 deploy/install.py

Der erste Befehl zeigt nur den Plan. Der zweite erstellt den Dienstbenutzer buganalysis, die virtuelle Python-Umgebung, Konfigurationsvorlagen und beide systemd-Units. Er startet oder aktiviert noch keinen Dienst und sendet keine LLM-Anfrage. Vorhandene Konfigurationsdateien und Units werden nicht überschrieben.

Verzeichnis	Inhalt
/opt/viano-bug-analysis	Programmcode und .venv; root-verwaltet
/etc/viano-bug-analysis	Konfiguration, geschützte Environment-Dateien und Webnutzerdatei
/var/lib/viano-bug-analysis	Fallakten, Inbox, Outbox, Review und Laufzeitdaten
/srv/viano-bug-analysis/viano-core	Separater Source-Checkout des untersuchten Vcore-Projekts

Der Linux-Dienstbenutzer ist kein Webkonto. Webkonten werden in Schritt 6 gesondert angelegt. Ein Programm zur automatischen Erfassung benötigt später einen Integrationsschlüssel, ebenfalls kein Webpasswort oder Cloud-API-Key.

4. Vcore-Sourcecode und lesenden Datenbankzugang bereitstellen

BugAnalysis benötigt zusätzlich zu seinem eigenen Repository den Sourcecode des untersuchten Projekts. Für Vcore beispielsweise:

sudo git clone --branch master --single-branch https://gitea.viano-software.de/Nico/Viano-Core /srv/viano-bug-analysis/viano-core
sudo git -C /srv/viano-bug-analysis/viano-core rev-parse HEAD

Die Ausgabe des zweiten Befehls ist der vollständige Commit. Der für die Analyse gewünschte Stand muss lokal vorhanden sein und wird in project.toml festgelegt. Der aktuelle Branchkopf ist nur dann passend, wenn genau dieser Stand untersucht werden soll. Der Worker klont oder aktualisiert den Sourcecode nicht automatisch.

Ein DB-Administrator richtet einen Benutzer mit ausschließlich passenden SELECT-Rechten auf die World-Daten ein. Keine Schreibrechte und keinen allgemeinen Administrationszugang verwenden. Für entfernte Datenbanken einen geschützten Netzwerkweg bereitstellen; der aktuelle DB-Provider richtet selbst kein TLS ein. Die vollständige Tabellenfreigabe steht in der Projektvorlage.

5. Konfigurationen und Zugangsdaten eintragen

Die Konfiguration liegt außerhalb des Git-Checkouts. Beispiele öffnen:

sudoedit /etc/viano-bug-analysis/api.toml
sudoedit /etc/viano-bug-analysis/project.toml
sudoedit /etc/viano-bug-analysis/llm.toml
sudoedit /etc/viano-bug-analysis/worker.env

Datei	Beim ersten Einrichten prüfen
api.toml	Projekt-ID, Profilzuordnung und Konfigurationspfade; HTTP-Bindung auf 127.0.0.1:8080 lassen
project.toml	Sourcepfad und vollständigen Commit, DB-Host/Port/Name/Benutzer, Snapshotkennung und Tabellenfreigaben
llm.toml	Anbieter, tatsächlich verfügbares Modell, Cache- und Timeout-Einstellungen; verwendete Schlüssel-Umgebungsvariable
worker.env	Cloud-API-Key und DB-Passwort
worker.toml	Verweis auf api.toml, Polling und Speicherreserve; Vorgaben zunächst übernehmen
investigation.bounded.toml, budget.human-tests.toml	Untersuchungs- und Budgetregeln; Vorgaben zunächst übernehmen
telemetry.toml	Betriebsbeobachtung; Vorgaben zunächst übernehmen

In project.toml die Null-Commit- und CONFIGURE_ME-Platzhalter ersetzen. Die vollständige Vorlage mit Relations-, Enrichment- und Werkzeugregeln beibehalten; die Projektdatei nicht auf DB-Adresse und Sourcepfad zusammenkürzen.

Für mehrere Datenbanken derselben MariaDB-Instanz kann in project.toml ein zusätzlicher Abschnitt ergänzt werden:

[database.additional_databases]
cata_hotfixes = ["*"]
cata_locale = ["*"]

[database].database bleibt beispielsweise cata_world, user kann buganalysis sein. Für den DB-Benutzer müssen entsprechende SELECT-Grants vorliegen. ["*"] erlaubt ausdrücklich alle sichtbaren Tabellen der jeweiligen DB. Alternativ konkrete Tabellennamen auflisten. Nicht konfigurierte Datenbanken bleiben gesperrt. Einzeldatenbank-Konfigurationen bleiben gültig. Vollständige Mehrdatenbank-Vorlage: project.vcore-multidb.example.toml.

Bei Verwendung der gelieferten Gemini-/DB-Vorlagen enthält worker.env:

GEMINI_API_KEY="HIER_DEN_CLOUD_API_KEY_EINTRAGEN"
VIANO_DB_PASSWORD="HIER_DAS_DB_PASSWORT_EINTRAGEN"

Das sind Platzhalter, keine gültigen Zugangsdaten. Keine export-Anweisungen verwenden. Die Datei wird durch systemd geladen und bleibt root-geschützt mit Modus 0600. Secrets nicht ins Repository oder in Shell-Befehlsargumente schreiben.

Wenn Integrationsschlüssel über die Weboberfläche verwaltet werden sollen: Den ausgelieferten [[clients]]-Beispielblock für wow-capture-worker vollständig aus api.toml entfernen. Dazu gehören seine id-, token_env- und projects- Zeilen. Die [[projects]]-Projektdefinition bleibt bestehen. api.env darf dann zunächst nur Kommentare enthalten; ein VBA_INTAKE_TOKEN ist auf der BugAnalysis-Seite nicht erforderlich. Andernfalls erwartet die Startprüfung für den vorhandenen Beispielclient einen manuell konfigurierten Token in api.env.

Details: Projektkonfiguration, Modell-/Cachekonfiguration und Linux-Betrieb.

6. Persönliches Webkonto anlegen

meinname durch den gewünschten Benutzernamen ersetzen. Das Passwort wird verdeckt abgefragt; es gehört nicht in die Befehlszeile.

sudo /opt/viano-bug-analysis/.venv/bin/python -m viano_bug_analysis.api create_user meinname --config /etc/viano-bug-analysis/api.toml --service-group buganalysis

Alle Webnutzer besitzen dieselben Bedienrechte. Nutzer werden ausschließlich per privilegierter Konsole angelegt, geändert oder gelöscht; es gibt keine öffentliche Registrierung. Weitere Befehle: Benutzerkonten.

7. Bereitschaft ohne Modellanfrage prüfen

Die Prüfungen laufen mit den Rechten und Environment-Dateien der späteren Dienste:

sudo systemd-run --wait --pipe --collect \
  --property=User=buganalysis --property=Group=buganalysis \
  --property=EnvironmentFile=/etc/viano-bug-analysis/api.env \
  /opt/viano-bug-analysis/.venv/bin/python -m viano_bug_analysis.deployment check \
  --role api --config /etc/viano-bug-analysis/api.toml

sudo systemd-run --wait --pipe --collect \
  --property=User=buganalysis --property=Group=buganalysis \
  --property=EnvironmentFile=/etc/viano-bug-analysis/worker.env \
  --setenv=GIT_CONFIG_GLOBAL=/etc/viano-bug-analysis/gitconfig \
  /opt/viano-bug-analysis/.venv/bin/python -m viano_bug_analysis.deployment check \
  --role worker --config /etc/viano-bug-analysis/worker.toml

Erwartet wird jeweils READY mit model_requests: 0. Geprüft werden unter anderem Speicher, Schreib-/Leserechte, Webnutzer, Konfiguration, Git-Stand und DB-Schemata. Die Prüfung sendet keine kostenpflichtige Modellanfrage; sie bestätigt deshalb nicht die Gültigkeit des Cloud-Keys oder die Modellverfügbarkeit. Bei NOT_READY zunächst den gemeldeten Fehler beheben.

8. API starten und HTTPS einrichten

sudo systemd-analyze verify /etc/systemd/system/viano-bug-analysis-api.service /etc/systemd/system/viano-bug-analysis-worker.service
sudo systemctl enable --now viano-bug-analysis-api.service
curl --fail http://127.0.0.1:8080/healthz

Der Health-Aufruf auf dem VPS sollte {"status":"OK"} liefern. Die API bleibt an Loopback gebunden. Für die öffentliche Webadresse eine Domain mit passendem DNS-Eintrag und gültigem TLS-Zertifikat bereitstellen. Zertifikatsbeschaffung und Firewallfreigaben an die vorhandene VPS-/Nginx-Einrichtung anpassen.

Auf Debian/Ubuntu kann eine eigene Nginx-Site aus der Vorlage angelegt werden:

sudo cp /etc/viano-bug-analysis/nginx.conf.example /etc/nginx/sites-available/viano-bug-analysis
sudoedit /etc/nginx/sites-available/viano-bug-analysis
sudo ln -s /etc/nginx/sites-available/viano-bug-analysis /etc/nginx/sites-enabled/viano-bug-analysis
sudo nginx -t
sudo systemctl enable --now nginx
sudo systemctl reload nginx

Vor nginx -t alle Beispieldomains und Zertifikatpfade ersetzen; die Zertifikate müssen bereits vorhanden sein. Bei bereits vorhandener Site keinen zweiten Symlink anlegen, sondern die bestehende Einrichtung prüfen. Andere VPS-Sites nicht entfernen. Erst über die fertige HTTPS-Adresse öffentlich anmelden.

Für einen ersten lokalen Zugriff ohne fertige Domain ist ein SSH-Tunnel möglich. Auf deinem eigenen Rechner ausführen, mit deinem SSH-Benutzer und VPS-Host:

ssh -L 8080:127.0.0.1:8080 benutzer@vps-host

Danach lokal http://127.0.0.1:8080/ öffnen, während der Tunnel läuft. Der Port auf dem eigenen Rechner muss frei sein. Für den regulären externen Erfassungsworker weiterhin die öffentliche HTTPS-Adresse einrichten.

9. Erfassungsworker verbinden und Analysebetrieb einschalten

Auf der Weboberfläche mit deinem Konto anmelden. Unter API-Schlüssel einen Schlüssel für den Erfassungsworker und das Projekt viano-core erstellen. Den Schlüssel im Environment des wowdiag-Workers als VBA_INTAKE_TOKEN hinterlegen. Dessen [buganalysis]-Abschnitt mit URL, Projekt und Profil einrichten und bewusst aktivieren. Anleitung und Vorlagen: Erfassungsworker v0.4.

Der Erfassungsworker ist ein eigener Dienst auf dem Erfassungssystem. Er wird nicht durch den BugAnalysis-Installer installiert oder gestartet. Die Datenbank- Zugänge dieser beiden Programme sind ebenfalls voneinander unabhängig.

Anschließend den Analyseworker aktivieren:

sudo systemctl enable --now viano-bug-analysis-worker.service
sudo systemctl status viano-bug-analysis-api.service viano-bug-analysis-worker.service

Ab diesem Zeitpunkt können vorhandene und neue Inbox-Aufträge kostenpflichtige Modellaufrufe auslösen. Mit einem kontrollierten echten Auftrag beginnen. In der Weboberfläche Annahme und Fortschritt verfolgen, gegebenenfalls Testanfragen beantworten und unter Bearbeitete Fälle das Ergebnis herunterladen. Ergebnisse gehen in die Outbox, gescheiterte Analysen ins Review; blockierte Fälle bleiben zur Fortsetzung erhalten. Ein Download bestätigt keine fachliche Übergabe.

10. Betrieb, Sicherung und Updates

sudo journalctl -u viano-bug-analysis-api -u viano-bug-analysis-worker -f
sudo systemctl stop viano-bug-analysis-worker.service

Der Worker beendet beim Stoppen den aktuellen Dispatch kontrolliert. Das kann während einer laufenden Anfrage dauern. Vor Code-/Profiländerungen anhalten; Konfigurationsbindungen laufender Fälle nicht beiläufig ändern.

Mindestens /etc/viano-bug-analysis und /var/lib/viano-bug-analysis gesichert aufbewahren. Dazu zählen die Nutzer-SQLite sowie Integrationsschlüssel-SQLite und deren separate Serverschlüsseldatei unter runtime/integration-secrets. Dieses Verzeichnis ist kein beliebig löschbarer Cache. Für eine einfache konsistente Dateisicherung beide Dienste anhalten. Zugriffe auf Backups mit Secrets schützen.

Für reguläre Codeupdates steht ein Update-Skript bereit:

sudo python3 /opt/viano-bug-analysis/deploy/update.py

Eine Vorschau ohne Netzwerkzugriff oder Änderungen ist mit --dry-run möglich. Das Skript benötigt root und einen sauberen, root-eigenen Checkout mit Tracking-Branch. Es holt den Remote-Stand, prüft Fast-forward, stoppt zuerst den Worker kontrolliert und danach die API, installiert das aktualisierte Paket in die vorhandene venv und startet nur die zuvor aktiven Dienste. Deren Startprüfungen testen die Bereitschaft ohne LLM-Aufruf. Vorher inaktive Dienste werden nicht aktiviert. Auch bei identischem Commit wird das Paket erneut installiert, etwa nach einem vorherigen manuellen Pull. Parallele Updates sind gesperrt. Konfigurationen, Zugangsdaten, Fallakten, Apache, Source-Checkout und Capture-Worker werden nicht verändert. Das Skript erstellt keine Datensicherung und führt keine projektspezifischen Migrationen aus.

Scheitert Installation oder Dienststart, bleiben beide Dienste gestoppt. Es gibt keinen automatischen Rollback von Code oder Daten. Nach Behebung der Ursache das Paket erneut installieren (auch mit diesem Skript möglich) und die gewünschten Dienste ausdrücklich starten. Falls das Skript im bisherigen Checkout noch fehlt, einmal vorab den folgenden Befehl ausführen und danach das Skript starten:

sudo git -C /opt/viano-bug-analysis pull --ff-only

Releasehinweise und geänderte Konfigurations-/Unit-Vorlagen vorher prüfen. Das Updatebeispiel ersetzt keine gezielte Übernahme geänderter systemd-Units mit anschließendem systemctl daemon-reload. Vorlagen werden vom Installer absichtlich nicht über bestehende Konfigurationen kopiert.

Die Einrichtung ist abgeschlossen, wenn Anmeldung, automatischer Auftragseingang, Analyse, Ergebnisdownload, menschliche Rückfrage und Wiederanlauf nach einem Dienst-/Serverneustart geprüft wurden. Die native Linux-/HTTPS-Prüfung erfolgt auf deinem Zielserver; lokale Windows-Entwicklungstests ersetzen sie nicht.

Häufige Probleme bei der Ersteinrichtung

Meldung / Verhalten	Zuerst prüfen
Installer verlangt root-eigenen Checkout	Pfad /opt/viano-bug-analysis, Eigentümer und Schreibrechte des Codes
DEPLOY_MACHINE_CREDENTIALS	Unbenutzten [[clients]]-Beispielblock entfernen oder dessen env-Token korrekt einrichten
LLM_CREDENTIALS	worker.env, Name der Schlüsselvariable in llm.toml und Laden der Datei durch systemd
PROJECT_DATABASE_UNAVAILABLE	DB-Adresse/Port, Netzwerkweg, Passwort und DB-Benutzer
Sourceprüfung schlägt fehl	Lokaler Checkout, tatsächlicher Commit, Leserechte und /etc/viano-bug-analysis/gitconfig
nginx -t meldet fehlendes Zertifikat	Zertifikat bereitstellen und die Beispielpfade im Site-Block ersetzen
Anmeldung funktioniert, aber kein Fall wird analysiert	Analyseworker läuft, Projektbindung stimmt, Auftrag ist tatsächlich angenommen

Dienstfehler über journalctl prüfen. Ein fehlgeschlagener Start wird durch systemd erneut versucht; nach einer Korrektur lässt sich der betreffende Dienst mit sudo systemctl restart DIENSTNAME gezielt neu starten. Dabei den echten Namen viano-bug-analysis-api.service beziehungsweise viano-bug-analysis-worker.service einsetzen.

Weiterführende Anleitungen

• Verwendung und Funktionsweise – auch im Webreiter Benutzeranleitung.
• Projekt-, Source-, DB- und Modellkonfiguration.
• Übergabe-API und Rückgaben.
• Analyseworker.
• Benutzerkonten.
• Integrationsschlüssel.
• Linux-Betrieb im Detail.

Entwicklung und technische Dokumentation

Project-independent foundations for reading, validating and extending ZIP case packages. The authoritative design is docs/architecture.md. The implemented v1 contract is documented in docs/package-format-v1.md. Job state, checkpoints and inbox admission are documented in docs/lifecycle-v1.md. Generic case construction and its input contracts are documented in docs/case-builder-v1.md. Vcore imports for wowdiag/wowsrc are documented in docs/vcore-adapters-v1.md. Authenticated submission of new cases and completed-case feedback is documented in docs/intake-api.md. The HTTP API creates and queues packages; external callers do not need to implement the internal package format. The continuous analysis worker consumes that inbox, routes cases to configured projects and resumes checkpointed analysis after restart. The web console shows active workers, case progress and token charts, with corrections accounted for separately, and accepts new/return submissions. The Linux deployment guide covers systemd services, protected credentials, HTTPS and non-billable readiness checks. The integration key manager lets signed-in users create, reveal and revoke project-scoped machine credentials. The web tab Benutzeranleitung includes the user guide and operator documentation, including project/source/database configuration. After editing bundled documentation, run python scripts/build_user_manual.py.

Requires Python 3.11 or newer.

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[test]"
.\.venv\Scripts\python.exe -m pytest

The lifecycle foundation supports one-pass inbox processing, resumable package checkpoints and a deterministic generic CaseBuilder. An async LLM gateway and CaseInterpreter provide interpretation and bounded initial hypothesis generation, with durable per-hypothesis budget accounting. An LLM-driven investigation controller connects read-only queries, durable evidence and asynchronous test handoffs. Final evaluation produces traceable diagnoses or human review. Confirmed diagnoses can produce policy-bound Change Requests, with final output validation and atomic local outbox/review publication. Operational telemetry observes the APIs and continuous worker.

A bounded single-case command-line trial now connects import, analysis and local delivery with telemetry: first real LLM trial. Use python -m viano_bug_analysis.trial --help. Only its run command makes LLM requests; prepare and check do not contact model services. For a new revision, run --planning-mode joint opts into a single interpretation/ hypothesis call with independent block validation: joint case planning. New joint revisions use v2 source constraints and dependency-aware corrections; frozen v1 cases remain replayable.

The trial enables bounded, durable early model-output corrections with explicit validation feedback: early correction, configured through correction.example.toml.

Expected-behavior resolution and the read-only provider contract: expected-behavior-v1.md.

Configurable LLM transport, failover and durable retries: llm-gateway-v1.md, with example configuration.

Gemini stable case caching, implicit cache measurements and separate token/storage cost accounting: context caching, with native Gemini example. Lossless stable/live partition, versioned aliases and offline measurements: stable case cache.

Causal evidence direction, auditable confidence calibration and current-head validation performance: confidence and local performance.

The first domain LLM phase and its source-reference contracts: case-interpretation-v1.md.

Initial hypotheses, revision-wide creation limits and equal budget allocations: hypothesis-builder-v1.md, with analysis configuration.

Durable investigation budget accounting, configurable costs/rewards and stopping rules: budget-manager-v1.md, with budget configuration.

Case-local asynchronous test requests, confirmed feedback and budget-preserving event-driven resume: async-tests-v1.md. Human test requests can be answered through the web console; external bot adapters are separate integrations.

Read-only packaged source/database queries and the strict tool allowlist: investigation-tools-v1.md.

Shared read-only Git/source/schema and MariaDB research, deterministic case enrichment, bounded investigation prompts and the isolated World test database: project-research-v1.md, with project configuration.

Portable evidence records, provenance, case-wide IDs and novelty-aware budget integration: evidence-store-v1.md.

Resumable, bounded LLM investigation cycles and their controller contracts: investigation-loop-v1.md, with investigation configuration.

Final hypothesis evaluation, traceable diagnoses and controlled human review: diagnosis-builder-v1.md, with diagnosis configuration.

Policy-bound coding requests and validated, resumable local output delivery: change-request-v1.md, with change request configuration.

Opt-in operational logs, safe error chains, metrics, heartbeat/progress and passive queue diagnostics: telemetry-v1.md, with telemetry configuration.

Schlanke Untersuchungsstarts mit gemeinsamer Erstbewertung: Ablauf und Konfiguration.