Communitygithub.com

sethjuarez/auditaur

Auditaur Debug-Workflow für Tauri-Apps – Diagnose und Steuerung von Tauri-Anwendungen.

Was ist auditaur?

Dieser Skill beschreibt den vollständigen Debug-Workflow für Tauri-Anwendungen mit dem Tool Auditaur. Auditaur beobachtet die App, ersetzt aber nicht deren normalen Entwicklungsbefehl. Der Skill erklärt, wie man Auditaur startet, den Bereitschaftsstatus prüft, die App über die Tauri-native Drive-Bridge steuert, Telemetriedaten (Logs, IPC, Events, Traces) abruft und Drills mit menschlichen Freigabeschritten (Human Gates) durchführt. Besonders nützlich ist Auditaur für Entwickler und KI-Agenten, die Tauri-Apps automatisieren oder debuggen müssen – es unterstützt maschinenlesbare JSON-Ausgaben und kann über MCP, Canvas-Erweiterungen oder Terminaleingaben angesteuert werden.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add sethjuarez/auditaur

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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:

BenutzerphraseAgenteninterpretation
"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.

SzenarioBevorzugter Modus
Menschliches lokales DebuggenAn die bereits laufende App anhängen
IDE/Debugger/Tauri-Dev-Workflow läuft bereitsAnhängen
Agent benötigt eine End-to-End-ValidierungsausführungWrapper
Dogfood- oder CI-ähnlicher lokaler Smoke-LaufWrapper

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-bridge verwenden; wenn mehrere Sitzungen übereinstimmen, mit --session-id, --instance-id, --pid, --latest oder --active eindeutig machen.
  • JSON-Ausgabekontamination: debug run --json von einer aktuellen Auditaur-CLI verwenden; untergeordnete Startausgabe sollte nicht in JSON-Zeilen erscheinen.

Validierungsschleife

Für Änderungen mit hohem Vertrauen:

  1. Führe die relevanten Tests/Builds aus.
  2. Starte oder hänge mit auditaur debug an.
  3. Führe den konfigurierten auditaur drill aus; wenn er ein Human Gate veröffentlicht, zeige es über den Canvas/MCP/Terminal-Antwortpfad an, anstatt die manuelle Aktion zu ersetzen.
  4. Steuere einen repräsentativen UI-Pfad über die Tauri-native Bridge, wenn UI-Abdeckung benötigt wird.
  5. Überprüfe debug status --require-frontend, wenn Frontend-Telemetrie wichtig ist.
  6. Untersuche timeline und explain.
  7. Räume gestartete App-Prozesse und temporäre Telemetrieverzeichnisse auf.

Verwandte Skills