wangnan0916/debug-mode-skill

Debug-Modus

Verwenden Sie diesen Skill nur, nachdem der Benutzer explizit debug-mode, $debug-mode, debug mode oder instrumentiertes Debugging aufgerufen hat.

Falls der Benutzer nicht explizit zugestimmt hat, debuggen Sie auf normalem Wege. Erwähnen Sie diesen Skill nur, wenn temporäre Laufzeitinstrumentierung wesentlich zur Problemlösung beitragen würde.

Kernschleife

Führen Sie eine hypothesengesteuerte Debugging-Schleife durch:

1. Lesen Sie den relevanten Code, Reproduktionsdetails und vorhandene Logs.
2. Listen Sie 2–5 priorisierte Hypothesen mit IDs wie H1, H2 und H3 auf. Jede Hypothese muss vorhersagen, was eine Laufzeitsonde zeigen wird.
3. Starten oder verwenden Sie den Loopback-Kollektor (Kollektor-Vertrag).
4. Fügen Sie 3–8 zielgerichtete Sonden hinzu, die die Hypothesen unterscheiden. Verwenden Sie strukturierte Ereignisse, die an DEBUG_URL + "/log" gesendet werden, niemals an stdout/stderr. Beachten Sie die Ereignisstruktur, Bereichsmarkierungen und Helfer unten.
5. Halten Sie am manuellen Prüfpunkt an. Senden Sie eine Prüfpunktvorlage. Analysieren, reparieren oder entfernen Sie die Sonden nicht, bis der Benutzer mit A, B oder C antwortet.
6. Nach A überprüfen Sie die gedruckte LOG_FILE, klassifizieren Sie jede Hypothese als BESTÄTIGT, ABGELEHNT oder UNKLAR und nehmen Sie die kleinste Korrektur nur dann vor, wenn die Logs die Grundursache erklären. Befolgen Sie die Evidenzzusammenfassung unten.
7. Lassen Sie die Sonden für einen nach der Korrektur ausgeführten Lauf mit der Kennzeichnung runId: "post-fix" aktiv.
8. Nachdem der Benutzer mit B auf den Post-Fix-Prüfpunkt geantwortet hat, entfernen Sie die gesamte Instrumentierung und führen Sie die relevanten Prüfungen durch. Befolgen Sie die Bereinigungsliste unten.

Harte Regeln

• Überspringen Sie niemals den manuellen Reproduktionsprüfpunkt nach dem Hinzufügen von Sonden.
• Korrigieren Sie niemals aufgrund von Vermutungen während dieser Fähigkeit.
• Entfernen Sie niemals Sonden, bevor der Benutzer die Post-Fix-Prüfung bestätigt hat.
• Committen Sie niemals Debug-Logs oder temporäre Instrumentierung.
• Protokollieren Sie niemals Geheimnisse, Tokens, Cookies, Autorisierungsheader, API-Schlüssel, rohe Request-Bodies, rohe Antworten, die private Daten enthalten könnten, oder unnötige persönliche Daten.

Kollektor-Vertrag

Der gebündelte Kollektor ist bewusst klein gehalten:

• GET /health prüft, ob ein vorhandener Kollektor wiederverwendet werden kann.
• POST /log akzeptiert ein JSON-Objekt und hängt asynchron eine NDJSON-Zeile an. Es gibt 200 nach der Validierung zurück; die Zeile wird im Hintergrund geschrieben.
• Verschiedene Sitzungen schreiben in separate Dateien mit unabhängigen Warteschlangen, sodass Schreibvorgänge sitzungsübergreifend parallel erfolgen können.
• Logs befinden sich standardmäßig im temporären Systemverzeichnis, außerhalb des Arbeitsbereichs.
• --ensure gibt DEBUG_URL, SESSION_ID, LOG_DIR, LOG_FILE und HEALTH_URL aus.
• Der Kollektor erstellt LOG_FILE beim ersten Ereignis. touch, Vorab-Erstellung, Kürzung oder Löschung nach einer Reproduktion sind nicht erlaubt.
• Der Kollektor ist ausschließlich für Loopback ausgelegt. Binden Sie ihn nicht an 0.0.0.0 oder eine öffentliche Schnittstelle.

Starten oder verwenden Sie ihn erneut mit:

node <skill-dir>/scripts/log-server.mjs --ensure --session <sitzungs_id> --host 127.0.0.1 --port 0

In verwalteten Sandboxen, die lokale Port-Listener blockieren, fordern Sie beim ersten Versuch die normale Zustimmung des Agenten an. Begründen Sie dies mit dem Start oder der Wiederverwendung dieses Loopback-Debug-Kollektors.

Prüfpunktvorlagen

Nach dem Hinzufügen von Sonden halten Sie an und senden Sie diese Struktur mit echten Sitzungsdetails:

Ich habe Debug-Mode-Sonden hinzugefügt und der Kollektor schreibt:

- Sitzung: <sitzungs_id>
- Logdatei: <LOG_FILE>
- Debug-Endpunkt: <DEBUG_URL>/log

Bitte reproduzieren Sie den Fehler manuell und antworten Sie dann:

A - Reproduziert
B - Behoben
C - Sonstiges; beschreiben Sie, was passiert ist

Für die Post-Fix-Überprüfung ändern Sie nur den Eröffnungssatz:

Ich habe Debug-Mode-Sonden für die Post-Fix-Überprüfung aktiviert gelassen und der Kollektor schreibt:

- Sitzung: <sitzungs_id>
- Logdatei: <LOG_FILE>
- Debug-Endpunkt: <DEBUG_URL>/log

Bitte überprüfen Sie den ursprünglichen Fehler manuell und antworten Sie dann:

A - Reproduziert
B - Behoben
C - Sonstiges; beschreiben Sie, was passiert ist

Interpretieren Sie Prüfpunktantworten als kleinen Zustandsautomaten:

• A vor einer Korrektur: Lesen Sie das NDJSON-Log, klassifizieren Sie die Hypothese-Evidenz, korrigieren Sie dann nur eine bestätigte Ursache oder fügen Sie engere Sonden hinzu.
• A nach einer Korrektur: Der Fehler wurde immer noch reproduziert. Lesen Sie das Post-Fix-Log und fahren Sie mit engeren Hypothesen oder Sonden fort.
• B vor einer Korrektur: Kein terminaler Zustand. Behandeln Sie es als Hinweis, dass der Fehler unter Instrumentierung nicht reproduziert wurde, und fragen Sie nach Klärung oder einer engeren Reproduktion.
• B nach einer Korrektur: Entfernen Sie Sonden und führen Sie abschließende Prüfungen durch.
• C jederzeit: Behandeln Sie den Text des Benutzers als Evidenz. Passen Sie die Reproduktion, Hypothesen oder Sonden an.

Ereignisstruktur

Verwenden Sie strukturierte, ereignisarme Ereignisse. Ein typisches Ereignis sieht so aus:

{
  "session": "<sitzungs_id>",
  "runId": "pre-fix",
  "probe": "settings.beforePersist",
  "hypothesis": "H1",
  "file": "src/settings/save.ts",
  "fn": "saveSettings",
  "vars": {
    "enabled": true,
    "userId": "redacted"
  }
}

Verwenden Sie runId: "pre-fix" vor der Korrektur und runId: "post-fix" zur Überprüfung. Protokollieren Sie bei hochfrequenten Pfaden nur bei Zustandsänderungen oder sampeln Sie aggressiv.

Bereichsmarkierungen

Wickeln Sie alle temporären Instrumentierungen ein, damit die Bereinigung mechanisch erfolgen kann:

// #region DEBUG_MODE_PROBE <sitzungs_id> settings-before-persist
debugModeLog({
  probe: "settings.beforePersist",
  hypothesis: "H1",
  file: "src/settings/save.ts",
  fn: "saveSettings",
  vars: { enabled, userId: "redacted" },
});
// #endregion DEBUG_MODE_PROBE <sitzungs_id>

Gängige Kommentarformen:

// #region DEBUG_MODE_PROBE <sitzungs_id> ...    JavaScript, TypeScript, Java, C#, Go, Rust, C, C++
# #region DEBUG_MODE_PROBE <sitzungs_id> ...     Python, Ruby, Shell, YAML
<!-- #region DEBUG_MODE_PROBE <sitzungs_id> -->  HTML, Vue, Svelte
/* #region DEBUG_MODE_PROBE <sitzungs_id> */     CSS und C-artige Blockkontexte
-- #region DEBUG_MODE_PROBE <sitzungs_id> ...    SQL, Lua

Helfer

Für Browser- oder Frontend-JavaScript verwenden Sie assets/browser-log-helper.js als kanonische Helfervorlage. Kopieren Sie sie in das instrumentierte Modul oder Skript, ersetzen Sie <sitzungs_id> und <DEBUG_URL> und behalten Sie den Funktionsnamen debugModeLog.

Für Node.js oder serverseitiges JavaScript verwenden Sie assets/node-log-helper.js als kanonische Helfervorlage. Kopieren Sie sie in das instrumentierte Modul oder Skript, ersetzen Sie <sitzungs_id> und <DEBUG_URL> und behalten Sie den Funktionsnamen debugModeLog.

Für Python ohne Abhängigkeiten von Drittanbietern:

# #region DEBUG_MODE_PROBE <sitzungs_id> debug-log-helper
import json
import urllib.request

DEBUG_MODE_URL = "<DEBUG_URL>/log"

def debug_mode_log(event):
    try:
        payload = {"session": "<sitzungs_id>", **event}
        data = json.dumps(payload).encode("utf-8")
        req = urllib.request.Request(
            DEBUG_MODE_URL,
            data=data,
            headers={"content-type": "application/json"},
            method="POST",
        )
        urllib.request.urlopen(req, timeout=0.5).close()
    except Exception:
        pass
# #endregion DEBUG_MODE_PROBE <sitzungs_id>

Evidenzzusammenfassung

Nach einer A-Antwort zusammenfassen der Evidenz vor der Codebearbeitung:

H1 Der Einstellungsstatus geht vor dem API-Aufruf verloren
Status: BESTÄTIGT
Evidenz: settings.beforePersist protokollierte enabled=false, während das UI-Ereignis enabled=true protokollierte.

H2 API lehnt den Wert ab
Status: ABGELEHNT
Evidenz: In dieser Reproduktion fand kein API-Aufruf statt.

Nächster Schritt: Korrigieren Sie die lokale Zustandsübergabe zwischen onToggle und saveSettings.

Wenn jede Hypothese ABGELEHNT oder UNKLAR ist, generieren Sie neue Hypothesen aus einem anderen Subsystem und fügen Sie engere Sonden hinzu. Patchen Sie nicht aus dem Bauch heraus.

Fehlerbehebung

• Leeres Log: Bestätigen Sie, dass die App den instrumentierten Pfad ausgeführt hat, die Sitzungs-ID übereinstimmt und der Endpunkt /log enthält.
• Vom Browser blockierte Anfrage: Überprüfen Sie Mixed Content, CSP connect-src, Extension-Isolation oder Content-Script-Kontext.
• CORS/Preflight-Problem: Der Kollektor behandelt OPTIONS; falls es immer noch fehlschlägt, versuchen Sie navigator.sendBeacon, einen Same-Origin-Dev-Server-Proxy oder serverseitige Instrumentierung.
• Host abgelehnt: Verwenden Sie 127.0.0.1, localhost oder ::1; binden Sie niemals an LAN- oder öffentliche Schnittstellen.
• Sandbox blockiert Listener: Wiederholen Sie es einmal mit der erforderlichen Zustimmung für diesen Loopback-Kollektor. Falls die Zustimmung verweigert wird, erklären Sie, dass die lokale Sammlung blockiert ist, und greifen Sie nur dann zurück, wenn ein sicherer dateibasierter Sondenpfad existiert.
• Zu viele Logs: Ersetzen Sie verrauschte Sonden durch engere Zustandsänderungssonden.
• Kann nicht reproduzieren: Fragen Sie nach genauen Schritten, Umgebung, Eingabedaten oder einer Bildschirmaufzeichnung; erfinden Sie keine Korrektur.

Bereinigungsliste

Bevor Sie die Aufgabe als erledigt erklären:

• Führen Sie die ursprüngliche Reproduktion oder die nächstgelegene verfügbare automatische Prüfung erneut aus.
• Entfernen Sie jedes gepaarte Region-Marker mit der Bezeichnung DEBUG_MODE_PROBE <sitzungs_id>.
• Suchen Sie nach der Sitzungs-ID, DEBUG_MODE_PROBE, #region DEBUG_MODE_PROBE und #endregion DEBUG_MODE_PROBE.
• Entfernen Sie das Sitzungs-NDJSON-Log unter der gedruckten LOG_FILE oder bestätigen Sie, dass es als lokale Evidenz aufbewahrt werden soll.
• Behalten Sie nur die Produktkorrektur und eventuelle nützliche Regressionstests.