Auditaur Debug-Workflow
Verwende Auditaur als erste diagnostische Oberfläche für das Debuggen von Tauri-Apps. Bevorzuge maschinenlesbares JSON, wenn du als Agent agierst. Das kanonische mentale Modell ist: Auditaur beobachtet die App; es ersetzt nicht den normalen Entwicklungsbefehl der App.
Befehlszuordnung
Übersetze häufige Benutzerphrasen in den entsprechenden Auditaur-Workflow:
| Benutzerphrase | Agenteninterpretation |
|---|---|
| "beobachte die App" | An die bereits laufende App anhängen und Bereitschaft überwachen. |
| "starte mit Auditaur" / "Auditaur starte die App" | auditaur start ausführen, wenn .auditaur/config.json existiert; andernfalls das normale App-Kommando unter Auditaur-Beobachtung mit debug run -- <normal command> starten. |
| "debugge die App mit Auditaur" | Zuerst Bereitschaft prüfen, dann Logs/Zeitachse/Spuren/IPC untersuchen. |
| "steuere die App" / "klicke in der App" | Die Tauri-native Drive-Bridge voraussetzen, dann auditaur drive verwenden. |
| "führe einen Drill aus" / "rauche die App an" | auditaur drill für den konfigurierten Standard-Drill ausführen, oder auditaur drill <name> für einen benannten Drill. |
| "manuelle Freigabe" / "menschliche Kontrolle" / "OAuth-Zustimmung" | Ein Drill-Skript-Gate verwenden, sodass die App-Sitzung fixiert bleibt, während der Mensch die Aktion abschließt. |
Erhalte den normalen Startbefehl der App. Bevorzuge den einfachen, im Repo konfigurierten Ablauf, wenn verfügbar:
auditaur start
auditaur drill
auditaur inspect
auditaur stop
Diese Befehle lesen .auditaur/config.json und teilen standardmäßig .auditaur/session.json, sodass Agenten keine benutzerdefinierten Wrapper für Bereitschaftsabfragen, Sitzungs-IDs, Datenbankpfade oder Prozessbereinigung benötigen.
Verwende auditaur start --json, wenn ein Agent maschinenlesbare Startausgabe benötigt. Es gibt ein einzelnes finales JSON-Objekt mit der genauen App-Sitzung, dem Prozess, den Selektoren, dem Sitzungsdateipfad und allen generierten benannten Ports aus. auditaur stop stoppt den aufgezeichneten Prozessbaum und entfernt die Sitzungsdatei nach der Bereinigung, sodass nachfolgende Befehle keine tote Sitzung ansteuern.
Bereitschaft zuerst
Bevor Logs gelesen oder die UI gesteuert wird, feststellen, was bereit ist:
auditaur debug --app <app-name> --json status
Bei einer laufenden App warten, bis die Kern-Telemetrie bereit ist:
auditaur debug --app <app-name> --active --json watch --until-ready --timeout-seconds 120
Wenn die Aufgabe Frontend-Telemetrie erfordert, --require-frontend hinzufügen. Wenn die Aufgabe WebView-Selektoraktionen erfordert, die Auditaur-In-App-Drive-Bridge verwenden: initAuditaur({ driveBridge: true }) in genau einem Debug/Test-WebView pro Auditaur-Sitzung aktivieren und --require-drive-bridge zu Bereitschaftsüberwachungen hinzufügen.
npm run tauri dev
auditaur debug --app <app-name> --active --require-frontend --json watch --until-ready --timeout-seconds 120
Unter Windows PowerShell:
npm run tauri dev
auditaur debug --app <app-name> --active --require-frontend --json watch --until-ready --timeout-seconds 120
Auditaur Drive verwendet die Tauri-native In-App-Drive-Bridge. Die App muss explizit initAuditaur({ driveBridge: true }) in genau einem Debug/Test-WebView pro Auditaur-Sitzung aktivieren. Dann sendet auditaur drive begrenzte Anfragen durch diese Bridge.
Die App starten
Standardmäßig den Anhängemodus bevorzugen: Lass den Entwickler, die IDE, den Tauri-Entwicklungsserver oder ein vorhandenes Terminal den App-Start übernehmen und verwende dann auditaur debug watch, um die Bereitschaft zu beobachten. Dies bewahrt die normale Umgebung des Benutzers, den Debugger, Hot Reload und die Terminalausgabe.
Den Wrapper-Modus nur verwenden, wenn der Agent oder ein Smoke-Skript einen wiederholbaren Lauf besitzen muss. Der Wrapper-Modus sollte die App trotzdem über ihren normalen Befehl starten; Auditaur beobachtet diesen Prozess, anstatt das App-Start-System zu ersetzen.
| Szenario | Bevorzugter Modus |
|---|---|
| Menschliches lokales Debuggen | An die bereits laufende App anhängen |
| IDE/Debugger/Tauri-Dev-Workflow läuft bereits | Anhängen |
| Agent benötigt eine End-to-End-Validierungsausführung | Wrapper |
| Dogfood- oder CI-ähnlicher lokaler Smoke-Lauf | Wrapper |
Wenn der Agent die App starten soll, den vorhandenen Befehl umschließen:
auditaur start
auditaur start verwendet .auditaur/config.json, meldet Bereitschaft, schreibt .auditaur/session.json und lässt die App nach Erreichen der Bereitschaft absichtlich laufen. Wenn die Konfiguration benannte Ports deklariert, reserviert start zufällige lokale Ports, erweitert {{port:name}}-Platzhalter im Befehl, setzt konfigurierte Port-Umgebungsvariablen und zeichnet die gewählten Ports in der Sitzungsdatei und der JSON-Ausgabe auf. Wenn noch keine Konfiguration existiert, die untergeordnete Form verwenden:
auditaur debug --app <app-name> --require-frontend --json run --timeout-seconds 180 --write-session .auditaur/session.json -- npm run tauri dev
debug run meldet Bereitschaft und lässt die App nach Erreichen der Bereitschaft absichtlich laufen. Wenn --app angegeben ist, ignoriert es übereinstimmende Erkennungsdatensätze, die vor dem Start existierten, wartet auf die neue Auditaur-Sitzung und fixiert die Bereitschaft auf genau diese Sitzung/Datenbank/PID. Verwende --write-session <path> für agenteneigene Starts, damit nachfolgende Befehle sessionId, instanceId, pid, databasePath und die generierten Selektor-Argumentarrays lesen können, anstatt mit --active oder --latest zu raten. Räume den gestarteten App-Prozess mit auditaur stop auf, wenn die Validierung abgeschlossen ist.
Bereitschaft interpretieren
Das stages-Array inspizieren:
app_discovery: Auditaur-Erkennungsdatei existiert.heartbeat: App-Heartbeat ist aktuell.telemetry_database: SQLite-Datenbank existiert und Schema validiert.session: Eine Sitzungszeile ist abfragbar.window: Tauri-Fenster-Telemetrie existiert.backend_telemetry: Backend/Plugin-Logs, Spans oder Fensterzeilen existieren.frontend_telemetry: Frontend-Logs/Fehler/IPC/Events existieren; nur erforderlich mit--require-frontend.drive_bridge: Tauri-native In-App-Drive-Bridge-Status existiert und hat einen aktuellen Heartbeat; nur erforderlich mit--require-drive-bridge.cdp_endpoint: Legacy-Browser-Debug-Endpoint-Bereitschaft; nur geprüft, wenn explizit angefordert.
Wenn die Bereitschaft false ist, den Stufenmeldungen und hints folgen, anstatt aus der Terminalausgabe zu raten.
Das WebView steuern
Die Tauri-native Drive-Bridge inspizieren, bevor die App verändert wird:
auditaur drive --app <app-name> --active --json inspect
Wenn eine Zielauswahl benötigt wird, das Bridge-Ziel verwenden:
auditaur drive --app <app-name> --active --json click --target auditaur-bridge --selector '<css>'
Nach Möglichkeit zuerst schreibgeschützte Aktionen verwenden:
auditaur drive --app <app-name> --active --json exists --selector '<css>'
auditaur drive --app <app-name> --active --json text --selector '<css>'
auditaur drive --app <app-name> --active --json snapshot --selector body --output failure.json
auditaur drive --app <app-name> --active --json screenshot --selector body --output failure.png --snapshot-output failure.json
Snapshot-Artefakte vor dem Teilen überprüfen; sie können DOM-Text, URLs oder andere sensible Inhalte enthalten.
Für Texteingaben fill verwenden, wenn ein direkter DOM-Wertsetzer plus input/change-Events ausreicht. type verwenden, wenn ein frameworkgesteuertes Input oder Textarea eine fokussierte Texteinfügung benötigt:
auditaur drive --app <app-name> --active --json type --selector 'textarea' --value 'hello' --visible-only
--visible-only (oder --visible) bei Selektoraktionen (wait, exists, text, click, fill, type, hover, select, check und uncheck) bevorzugen, wenn Modalitäten, Overlays oder Vollbild-Shells validiert werden, die doppeltes verstecktes DOM hinterlassen.
Wenn drive inspect bridge.status als inaktiv meldet, driveBridge im Frontend aktivieren. Sobald aktiv, wait, exists, text, click, fill, type, press, hover, select, check, uncheck, evaluate, snapshot und screenshot über die Tauri-native Bridge verwenden. Bridge-Screenshots versuchen zuerst die native WebView-Aufnahme (screenshotBackend=tauri_native_webview_snapshot) für überlagerungsfreie WebView-Pixel; Selektor-Screenshots beschneiden dieses WebView-Bild und melden screenshotScope=selector plus selectorRect. Falls die WebView-Aufnahme fehlschlägt, fällt Auditaur auf die native Fensteraufnahme (screenshotBackend=tauri_native_window_xcap) und dann auf das DOM-Text-Zusammenfassungs-PNG (screenshotBackend=bridge_dom_summary_canvas) mit Fehlermetadaten zurück. evaluate führt beliebiges JavaScript im WebView aus, daher die Bridge auf Entwicklungs-/Testsitzungen beschränken. Falls die Bridge inaktiv ist, die Auditaur-Telemetrie (timeline, ipc, traces, explain) für die Wahrheit verwenden und nur mit der Accessibility-Automatisierung kombinieren, wenn manuelle UI-Eingaben simuliert werden müssen.
Legacy-Kompatibilität: --cdp-port kann in älteren Befehlen vorkommen, aber auditaur drive ignoriert es. Verwende positive Formulierungen für Drive-Befehle: Sage, dass sie die Tauri-native Drive-Bridge verwenden.
Telemetrie inspizieren
Nach der Bereitschaft strukturierte Lese-Befehle verwenden:
auditaur apps --json
auditaur sessions --json
auditaur logs --json
auditaur errors --json
auditaur ipc --json
auditaur events --json
auditaur traces --json
auditaur timeline --json
auditaur explain --json
--session <id>, --db <path>, --active, --latest, --pid oder --instance-id bevorzugen, wenn es veraltete oder mehrere Sitzungen gibt.
Menschliche Freigaben in Drills
Verwende Drill-Human-Gates für Workflows, die echte menschliche Aktionen erfordern, während die gleiche fixierte App-Sitzung erhalten bleibt: OAuth/Device-Code-Freigabe, OS-Berechtigungsaufforderungen, Installationserweiterungen, externe Browser-Übergaben, Kamera/Mikrofon-Berechtigungen, Hardware-Sicherheitsschlüssel oder jeden Ablauf, bei dem ein Agent pausieren sollte, anstatt vertrauenssensitive Eingaben zu simulieren.
Gates in einem Drill-Skript hinzufügen und den Drill mit --script <path> ausführen:
{
"gates": [
{
"name": "GitHub-Anmeldung genehmigen",
"instructions": "Schließe die GitHub-Device-Code-Genehmigung in der App oder im Browser ab und kehre dann hierher zurück.",
"selector": "#status-card",
"expectText": "Angemeldet",
"manualContinue": true,
"timeoutMs": 300000,
"choices": [
{ "id": "done", "label": "Erledigt", "outcome": "continue" },
{ "id": "blocked", "label": "Blockiert", "outcome": "fail" }
]
}
]
}
Human Gates laufen, nachdem Auditaur die neue App-Sitzung erzeugt und fixiert und die Bereitschaft erreicht hat, aber vor der Sammlung von Selektor/Text/Fehler/IPC/Explain-Beweisen. Die App nicht neu starten oder zu einer anderen Sitzung während des Gates wechseln; der Punkt ist, dass Beweise vor und nach dem Gate an derselben Sitzung/Datenbank/PID hängen bleiben. Gates können nur per Selektor überwachte Wartezeiten, manuelle Fortsetzungen, Auswahlen mit continue/retry/skip/fail/abort-Ergebnissen, Eingaben und Zwischenablagehinweise sein. Sensitive Eingaben und Zwischenablagewerte werden in Drill-Berichten standardmäßig geschwärzt, aber lokale temporäre Gate-Antwort-JSONs können kurzzeitig rohe Eingabewerte enthalten, bis der Drill sie verbraucht und entfernt.
Wenn ein Gate eine manuelle Antwort erfordert, veröffentlicht Auditaur auch eine sitzungslokale Anfrage neben der fixierten Sitzungsdatenbank. Agenten können diese über MCP auflisten und beantworten:
auditaur mcp
Verwende list_pending_human_gates, um ausstehende Gates zu finden, und respond_human_gate mit der requestId, optionaler choiceId, optionalen inputs und einem klaren responder-Wert. Starte den MCP-Server mit demselben Auditaur-Datenverzeichnis wie der Drill, damit er die sitzungslokalen Anfragedateien sehen kann. Wenn die Copilot-Canvas-Erweiterung mit auditaur init extension installiert ist, öffne den auditaur-human-gate-Canvas für das ausstehende Gate, damit der Benutzer eine Aktionskarte erhält und eine Antwort klicken kann. Terminal-ENTER/Auswahl-Eingabe bleibt die Fallback-Lösung, wenn kein MCP- oder Canvas-Client verfügbar ist.
Häufige Fehlermuster
- Keine Erkennungsdatei: Die App wird noch kompiliert, wurde nicht gestartet oder das Auditaur-Plugin ist nicht registriert.
- Datenbank nicht lesbar/Schema ungültig: Die App wurde teilweise initialisiert oder das Datenverzeichnis ist falsch.
- Keine Frontend-Telemetrie: Die Frontend-API wurde nicht initialisiert, es wurde keine Frontend-Aktion ausgelöst oder der Export ist in der UI fehlgeschlagen.
- Drive-Bridge inaktiv: Aktiviere
initAuditaur({ driveBridge: true })in genau einem Debug/Test-WebView, ansonsten Telemetrie plus Accessibility-Fallback verwenden. - Ausstehendes Human Gate: Es nicht mit synthetischem App-Zustand umgehen. Die Gate-Anweisungen dem Benutzer anzeigen, über den Canvas/MCP/Terminal-Pfad antworten, dann die Beweissammlung auf derselben fixierten Sitzung fortsetzen.
- Ziel-Mehrdeutigkeit:
--target auditaur-bridgeverwenden; wenn mehrere Sitzungen übereinstimmen, mit--session-id,--instance-id,--pid,--latestoder--activeeindeutig machen. - JSON-Ausgabekontamination:
debug run --jsonvon einer aktuellen Auditaur-CLI verwenden; untergeordnete Startausgabe sollte nicht in JSON-Zeilen erscheinen.
Validierungsschleife
Für Änderungen mit hohem Vertrauen:
- Führe die relevanten Tests/Builds aus.
- Starte oder hänge mit
auditaur debugan. - Führe den konfigurierten
auditaur drillaus; wenn er ein Human Gate veröffentlicht, zeige es über den Canvas/MCP/Terminal-Antwortpfad an, anstatt die manuelle Aktion zu ersetzen. - Steuere einen repräsentativen UI-Pfad über die Tauri-native Bridge, wenn UI-Abdeckung benötigt wird.
- Überprüfe
debug status --require-frontend, wenn Frontend-Telemetrie wichtig ist. - Untersuche
timelineundexplain. - Räume gestartete App-Prozesse und temporäre Telemetrieverzeichnisse auf.