wangnan0916/runtime-debug-toolkit

Mode Débogage

Démarrez une session uniquement lorsque l'utilisateur actuel invoque $debug-mode, dit "mode débogage", ou demande un débogage instrumenté. Reprenez dès qu'une session de débogage active existe, y compris après les réponses de l'utilisateur ou la compaction du contexte. La session devient active lorsque l'Étape 3 arme le serveur. Elle se termine uniquement après le nettoyage de l'Étape 8 ou un abandon explicite. Si aucune de ces conditions ne s'applique, arrêtez avant analyse, collecte ou instrumentation.

Ce workflow s'appuie sur le workflow frère trace-mode. Il étend les preuves de localisation via la correction, la vérification et le nettoyage. Les scripts frères nécessitent Node.js 24 ou une version ultérieure.

Exécutez cette boucle de preuves :

analyser le code -> hypothétiser -> tracer avec trace-mode -> prouver -> corriger -> vérifier -> nettoyer

Travaillez de manière autonome via l'instrumentation. La première interaction utilisateur planifiée est le point de contrôle de reproduction. La reproduction et la vérification sont des portes.

Invariant des points de contrôle : chaque tentative manuelle de reproduction ou de vérification nécessite un point de contrôle frais. La seule disponibilité des outils sélectionne son chemin : lorsque le request_user_input natif de Codex est listé, vous DEVEZ l'appeler ; sinon, appelez le sélecteur Pi lorsqu'il est listé ; utilisez le modèle en texte brut exact uniquement après qu'aucun chemin interactif ne peut s'exécuter. L'appel d'outil natif est le point de contrôle ; un commentaire ou une réponse finale ne peut pas le remplacer. Une annulation native laisse la porte en attente, et un résultat précédent n'autorise que sa tentative en cours.

1. Analyser le Chemin du Code

Commencez le travail préparatoire dans le dépôt à partir du symptôme rapporté. Lisez les points d'entrée, gestionnaires, transitions d'état, logs existants et modifications récentes pertinents. Cartographiez les chemins candidats depuis le déclencheur de l'utilisateur jusqu'au résultat observé. Rédigez une Fiche de Bug :

• Symptôme et comportement attendu
• Déclencheur, route, commande, entrée ou fixture connu
• Chemin d'exécution candidat et limites contestées
• Environnement, fréquence, modifications et preuves pertinents
• Critère d'acceptation observable

Enregistrez les faits indisponibles comme inconnu. Résolvez les inconnues conséquentes par la lecture du code ou des sondes d'exécution discriminantes.

Terminé lorsque : un chemin candidat relie le déclencheur au symptôme, et chaque branche contestée a une limite de sonde nommée.

2. Construire la Matrice d'Hypothèses

Rédigez deux à cinq hypothèses classées avant d'ajouter des sondes. Ancrez la matrice dans l'analyse du code et les preuves disponibles. Utilisez cette forme :

H1 <cause courte>
Prédiction : <état runtime, chemin ou timing>
Sonner : <noms d'événements et emplacements dans le code>
CONFIRMÉE lorsque : <condition d'enregistrement spécifique>
REJETÉE lorsque : <condition d'enregistrement spécifique>

Une hypothèse sans prédiction concrète nécessite plus de lecture de code. Préférez les sondes qui séparent plusieurs hypothèses.

Terminé lorsque : chaque hypothèse a des conditions falsifiables et une sonde planifiée distinctive.

3. Tracer via le Mode Trace

Lisez la compétence frère trace-mode. Utilisez ses étapes de planification des événements, de démarrage du serveur et d'instrumentation avec la Fiche de Bug. Lisez references/probes.md pour l'extension des événements de débogage. Revenez ici avant son point de contrôle de trace autonome.

Ce workflow est l'appelant. Le workflow trace-mode doit remettre les sondes actives et les cinq valeurs du serveur.

Terminé lorsque : chaque hypothèse a une sonde active et les cinq valeurs du serveur sont connues.

4. Franchir la Porte de Reproduction

Lisez references/checkpoints.md avant de présenter le point de contrôle pré-correction. Exécutez le protocole pré-correction via le chemin de point de contrôle sélectionné ci-dessus. Ensuite, attendez et acheminez son résultat via la table d'état. Chaque nouvelle tentative repasse par cette porte avec un nouvel appel interactif.

Terminé lorsque : un résultat valide A, B ou C a été acheminé par phase.

5. Prouver la Cause

Après le A pré-correction, lisez les enregistrements de session en cours dans LOG_FILE avant de modifier le code du produit. Confirmez que chaque sonde attendue est présente, puis inspectez les enregistrements dans l'ordre du fichier et comparez les valeurs pertinentes avec chaque prédiction d'hypothèse. Classez chaque hypothèse comme CONFIRMÉE, REJETÉE ou NON CONCLUSIVE. Rédigez le rapport de preuves :

H1 <cause courte>
Statut : CONFIRMÉE
Preuves : <événements et valeurs spécifiques>

H2 <cause courte>
Statut : REJETÉE
Preuves : <événements et valeurs spécifiques>

Acceptation : <une phrase observable>
Action suivante : <plus petite correction pour la cause confirmée>

L'absence de sondes attendues bloque la confirmation. Revenez à l'Étape 2 lorsque chaque résultat est rejeté ou non concluant.

Terminé lorsque : les enregistrements de l'exécution en cours confirment une cause explicative, avec un critère d'acceptation observable.

6. Effectuer la Correction Basée sur les Preuves

Apportez la plus petite modification qui adresse la cause confirmée. Gardez chaque sonde active. Changez les événements en runId: "post-fix". Ajoutez un test de régression ciblé lorsque le comportement est automatisable.

Terminé lorsque : chaque modification du produit remonte à la cause, et les preuves post-correction sont prêtes.

7. Franchir la Porte de Vérification

Présentez le point de contrôle post-correction depuis references/checkpoints.md via le chemin sélectionné. Ensuite, attendez et acheminez son résultat via la table d'état. Chaque tentative de vérification ultérieure nécessite un autre appel interactif.

Terminé lorsque : l'utilisateur renvoie le B post-correction pour le critère d'acceptation énoncé.

8. Nettoyer Mécaniquement

Supprimez chaque paire marquée LOG_SERVER_PROBE <session_id>. Recherchez l'ID de session, LOG_SERVER_PROBE et les deux formes de région. Supprimez les helpers copiés et toute instrumentation temporaire. Supprimez LOG_FILE sauf si l'utilisateur demande de conserver les preuves. Laissez le serveur partagé en cours d'exécution sauf si l'utilisateur demande son arrêt. Exécutez les vérifications pertinentes et inspectez le diff final.

Terminé lorsque : les recherches de marqueurs et de sessions retournent zéro correspondance dans le dépôt, les vérifications passent, et seules les modifications du produit subsistent.

Branche Exceptionnelle

Lisez references/troubleshooting.md uniquement lorsque la collecte, la reproduction ou la livraison échoue.