wangnan0916/debug-mode-skill

Mode Debug

Utilisez cette compétence uniquement après que l'utilisateur a explicitement invoqué debug-mode, $debug-mode, debug mode ou un débogage instrumenté.

Si l'utilisateur n'a pas explicitement donné son accord, déboguez normalement. Mentionnez cette compétence uniquement lorsqu'une instrumentation temporaire d'exécution aiderait matériellement.

Boucle Principale

Exécutez une boucle de débogage basée sur des hypothèses :

1. Lisez le code pertinent, les détails de reproduction et les logs existants.
2. Listez 2 à 5 hypothèses classées avec des identifiants comme H1, H2, et H3. Chaque hypothèse doit prédire ce qu'une sonde d'exécution montrera.
3. Démarrez ou réutilisez le collecteur en boucle locale (Contrat du Collecteur).
4. Ajoutez 3 à 8 sondes ciblées qui distinguent les hypothèses. Utilisez des événements structurés envoyés vers DEBUG_URL + "/log", jamais stdout/stderr. Suivez la Structure des Événements, les Marqueurs de Région et les Aides ci-dessous.
5. Arrêtez-vous au point de contrôle manuel. Envoyez un Modèle de Point de Contrôle. N'analysez pas, ne corrigez pas et ne supprimez pas les sondes jusqu'à ce que l'utilisateur réponde avec A, B, ou C.
6. Après A, inspectez le LOG_FILE imprimé, classez chaque hypothèse comme CONFIRMÉE, REJETÉE, ou NON CONCLUSIVE, et effectuez la plus petite correction uniquement lorsque les logs expliquent la cause racine. Suivez le Résumé des Preuves ci-dessous.
7. Gardez les sondes actives pour une exécution post-correction marquée avec runId: "post-fix".
8. Après que l'utilisateur répond B au point de contrôle post-correction, supprimez toute instrumentation et exécutez les vérifications pertinentes. Suivez la Liste de Nettoyage ci-dessous.

Règles Strictes

• Ne sautez jamais le point de contrôle de reproduction manuelle après avoir ajouté des sondes.
• Ne corrigez jamais par supposition tant que cette compétence est active.
• Ne supprimez jamais les sondes avant que l'utilisateur confirme la vérification post-correction.
• Ne validez jamais les logs de débogage ou l'instrumentation temporaire.
• Ne journalisez jamais de secrets, jetons, cookies, en-têtes d'autorisation, clés API, corps de requête bruts, réponses brutes pouvant contenir des données privées, ou données personnelles inutiles.

Contrat du Collecteur

Le collecteur fourni est intentionnellement petit :

• GET /health vérifie si un collecteur existant est réutilisable.
• POST /log accepte un objet JSON et ajoute une ligne NDJSON de manière asynchrone. Il retourne 200 après validation ; la ligne est écrite en arrière-plan.
• Différentes sessions écrivent dans des fichiers séparés avec des files d'attente indépendantes, donc les écritures peuvent se dérouler en parallèle entre les sessions.
• Les logs sont stockés par défaut sous le répertoire temporaire OS, en dehors de l'espace de travail.
• --ensure affiche DEBUG_URL, SESSION_ID, LOG_DIR, LOG_FILE, et HEALTH_URL.
• Le collecteur crée LOG_FILE sur le premier événement. Ne faites pas de touch, ne pré-créez pas, ne tronquez pas et n'effacez pas après une reproduction.
• Le collecteur est en boucle locale uniquement. Ne le liez pas à 0.0.0.0 ou à toute interface publique.

Démarrez-le ou réutilisez-le avec :

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

Dans les sandbox gérés qui bloquent les écouteurs de port local, demandez l'approbation normale de l'agent lors de la première tentative. Limitez la raison au démarrage ou à la réutilisation de ce collecteur de débogage en boucle locale.

Modèles de Points de Contrôle

Après avoir ajouté des sondes, arrêtez-vous et envoyez ce format avec les détails de session réels :

J'ai ajouté des sondes de mode débogage et le collecteur écrit :

- Session : <session_id>
- Fichier de log : <LOG_FILE>
- Point de terminaison de débogage : <DEBUG_URL>/log

Veuillez reproduire le bug manuellement, puis répondez :

A - Reproduit
B - Corrigé
C - Autre ; décrivez ce qui s'est passé

Pour la vérification post-correction, modifiez uniquement la phrase d'ouverture :

J'ai gardé les sondes de mode débogage actives pour la vérification post-correction et le collecteur écrit :

- Session : <session_id>
- Fichier de log : <LOG_FILE>
- Point de terminaison de débogage : <DEBUG_URL>/log

Veuillez vérifier le bug original manuellement, puis répondez :

A - Reproduit
B - Corrigé
C - Autre ; décrivez ce qui s'est passé

Interprétez les réponses aux points de contrôle comme une petite machine d'état :

• A avant une correction : lisez le log NDJSON, classez les preuves des hypothèses, puis corrigez uniquement une cause confirmée ou ajoutez des sondes plus ciblées.
• A après une correction : le bug est toujours reproduit. Lisez le log post-correction et continuez avec des hypothèses ou des sondes plus ciblées.
• B avant une correction : pas un état terminal. Traitez-le comme une preuve que le bug ne s'est pas reproduit sous instrumentation et demandez des clarifications ou une reproduction plus ciblée.
• B après une correction : supprimez les sondes et exécutez les vérifications finales.
• C à tout moment : traitez le texte de l'utilisateur comme une preuve. Ajustez la reproduction, les hypothèses ou les sondes.

Structure des Événements

Utilisez des événements structurés et à faible volume. Un événement typique ressemble à :

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

Utilisez runId: "pre-fix" avant la correction et runId: "post-fix" pour la vérification. Pour les chemins à haute fréquence, journalisez uniquement lors des changements d'état ou échantillonnez agressivement.

Marqueurs de Région

Encadrez toute instrumentation temporaire pour que le nettoyage soit mécanique :

// #region DEBUG_MODE_PROBE <session_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 <session_id>

Formes de commentaires courantes :

// #region DEBUG_MODE_PROBE <session_id> ...    JavaScript, TypeScript, Java, C#, Go, Rust, C, C++
# #region DEBUG_MODE_PROBE <session_id> ...     Python, Ruby, Shell, YAML
<!-- #region DEBUG_MODE_PROBE <session_id> -->  HTML, Vue, Svelte
/* #region DEBUG_MODE_PROBE <session_id> */     CSS et contextes de bloc de style C
-- #region DEBUG_MODE_PROBE <session_id> ...    SQL, Lua

Aides

Pour JavaScript navigateur ou frontal, utilisez assets/browser-log-helper.js comme modèle helper canonique. Copiez-le dans le module ou script instrumenté, remplacez <session_id> et <DEBUG_URL>, et conservez le nom de fonction debugModeLog.

Pour JavaScript Node.js ou côté serveur, utilisez assets/node-log-helper.js comme modèle helper canonique. Copiez-le dans le module ou script instrumenté, remplacez <session_id> et <DEBUG_URL>, et conservez le nom de fonction debugModeLog.

Pour Python sans dépendances tierces :

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

DEBUG_MODE_URL = "<DEBUG_URL>/log"

def debug_mode_log(event):
    try:
        payload = {"session": "<session_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 <session_id>

Résumé des Preuves

Après une réponse A, résumez les preuves avant de modifier le code :

H1 L'état des paramètres est perdu avant l'appel API
Statut : CONFIRMÉE
Preuve : settings.beforePersist a journalisé enabled=false alors que l'événement UI a journalisé enabled=true.

H2 L'API rejette la valeur
Statut : REJETÉE
Preuve : aucun appel API n'a eu lieu dans cette reproduction.

Action suivante : corrigez le transfert d'état local entre onToggle et saveSettings.

Si chaque hypothèse est REJETÉE ou NON CONCLUSIVE, générez de nouvelles hypothèses à partir d'un sous-système différent et ajoutez des sondes plus ciblées. Ne corrigez pas par intuition.

Dépannage

• Log vide : confirmez que l'application a exécuté le chemin instrumenté, que l'ID de session correspond, et que le point de terminaison inclut /log.
• Requête bloquée par le navigateur : vérifiez le contenu mixte, connect-src CSP, l'isolation d'extension, ou le contexte de script de contenu.
• Problème CORS/preflight : le collecteur gère OPTIONS ; si cela échoue encore, essayez navigator.sendBeacon, un proxy de serveur de développement de même origine, ou une instrumentation côté serveur.
• Hôte rejeté : utilisez 127.0.0.1, localhost, ou ::1 ; ne liez jamais à un réseau local ou des interfaces publiques.
• Le sandbox bloque l'écouteur : réessayez une fois avec l'approbation requise pour ce collecteur en boucle locale. Si l'approbation est refusée, expliquez que la collecte locale est bloquée et revenez en arrière uniquement s'il existe un chemin de sonde sûr basé sur un fichier.
• Trop de logs : remplacez les sondes bruyantes par des sondes de changement d'état plus ciblées.
• Impossible de reproduire : demandez les étapes exactes, l'environnement, les données d'entrée, ou un enregistrement d'écran ; n'inventez pas de correction.

Liste de Nettoyage

Avant de déclarer la tâche terminée :

• Réexécutez la reproduction originale ou la vérification automatisée la plus proche disponible.
• Supprimez chaque paire de région marquée DEBUG_MODE_PROBE <session_id>.
• Recherchez l'ID de session, DEBUG_MODE_PROBE, #region DEBUG_MODE_PROBE, et #endregion DEBUG_MODE_PROBE.
• Supprimez le log NDJSON de session au chemin LOG_FILE imprimé, ou confirmez qu'il doit être conservé comme preuve locale.
• Conservez uniquement la correction du produit et tout test de régression utile.