Journalisation et débogage avancés des Skills

Le débogage de base repose sur print, le débogage avancé repose sur des mécanismes de journalisation systématiques.

Cet article présente comment mettre en place une journalisation structurée pour les scripts Skill, ainsi que des techniques avancées pour localiser les problèmes dans des flux d'exécution complexes.


Remplacer print par logging

printConvient pour un débogage rapide, mais dans les Skills de production, vous devriez passer au moduleloggingde la bibliothèque standard Python.

L’avantage de la journalisation est que vous pouvez contrôler le niveau de sortie — afficher les informations DEBUG pendant le développement, et uniquement WARNING et au-dessus en production.

Exemple

# Chemin du fichier : scripts/logger_setup.py
import logging
import sys
from datetime import datetime

def get_logger(name: str, level: str = "INFO") -> logging.Logger:
    """
Créer un logger structuré

Paramètres :
name: Nom du logger, généralement le nom du module (__name__)
level: Niveau de journalisation, DEBUG / INFO / WARNING / ERROR
    """

    logger = logging.getLogger(name)
    logger.setLevel(getattr(logging, level.upper(), logging.INFO))

    # Éviter d’ajouter des gestionnaires à plusieurs reprises
    if logger.handlers:
        return logger

    # Sortie console : format lisible par l'humain
    console = logging.StreamHandler(sys.stdout)
    console.setFormatter(logging.Formatter(
        "[%(asctime)s] [%(levelname)s] %(name)s - %(message)s",
        datefmt="%H:%M:%S"
    ))
    logger.addHandler(console)

    # Sortie de fichier : écrire dans le fichier journal (facultatif)
    log_file = f"/home/claude/skill_{datetime.now().strftime('%Y%m%d')}.log"
    file_handler = logging.FileHandler(log_file, encoding="utf-8")
    file_handler.setFormatter(logging.Formatter(
        "%(asctime)s [%(levelname)s] %(name)s:%(lineno)d - %(message)s"
    ))
    logger.addHandler(file_handler)

    return logger

# Exemple d'utilisation
if __name__ == "__main__":
    log = get_logger(__name__, level="DEBUG")

    log.debug("Informations de débogage : chemin du fichier = /mnt/user-data/uploads/example.csv")
    log.info("Démarrage du traitement du fichier")
    log.warning("La taille du fichier dépasse 50MB, le traitement peut être lent")
    log.error("Échec de la lecture du fichier : FileNotFoundError")
[10:23:01] [DEBUG]   __main__ - 调试信息:文件路径 = /mnt/user-data/uploads/example.csv
[10:23:01] [INFO]    __main__ - 开始处理文件
[10:23:01] [WARNING] __main__ - 文件大小超过 50MB,处理可能较慢
[10:23:01] [ERROR]   __main__ - 文件读取失败:FileNotFoundError

Suivi du temps d'exécution

Lorsqu'une Skill s'exécute lentement, vous devez identifier les étapes goulot d'étranglement qui consomment du temps.

Exemple

# Chemin du fichier : scripts/timer.py
import time
import functools
import logging

log = logging.getLogger(__name__)

def timeit(func):
    """Décorateur : enregistre automatiquement le temps d'exécution de la fonction"""
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = func(*args, **kwargs)
        elapsed = time.perf_counter() - start
        log.info(f"{func.__name__} a pris {elapsed:.3f} seconds")
        return result
    return wrapper

# Utilisation : ajoutez le décorateur @timeit à la fonction que vous voulez chronométrer
@timeit
def load_csv(file_path: str):
    import pandas as pd
    return pd.read_csv(file_path)

@timeit
def calculate_stats(df):
    return df.describe()

# Vous pouvez aussi utiliser un gestionnaire de contexte pour un chronométrage manuel
class Timer:
    def __init__(self, label: str):
        self.label = label
    def __enter__(self):
        self.start = time.perf_counter()
        return self
    def __exit__(self, *args):
        elapsed = time.perf_counter() - self.start
        log.info(f"{self.label} a pris {elapsed:.3f} seconds")

# Utiliser le gestionnaire de contexte Timer
if __name__ == "__main__":
    with Timer("Lire et nettoyer les données"):
        import pandas as pd
        df = pd.read_csv("/mnt/user-data/uploads/example_data.csv")
        df = df.dropna()
[10:23:05] [INFO] load_csv 耗时 0.342 秒
[10:23:05] [INFO] calculate_stats 耗时 0.018 秒
[10:23:05] [INFO] 读取并清洗数据 耗时 0.361 秒

Journalisation structurée : format de sortie JSON

Lorsque les journaux doivent être analysés par des programmes (plutôt que lus par des humains), le format JSON est plus approprié.

Exemple

# Chemin du fichier : scripts/json_logger.py
import json
import sys
from datetime import datetime

def log_event(level: str, event: str, **context):
    """
Produire des journaux JSON structurés

Paramètres :
level: Niveau de journalisation (info / warning / error)
event: Nom de l'événement
context: paires clé-valeur de contexte supplémentaires
    """

    entry = {
        "timestamp": datetime.now().isoformat(),
        "level": level,
        "event": event,
        **context
    }
    # Utiliser stderr pour la sortie de journalisation afin d'éviter de la mélanger avec la sortie normale du script
    print(json.dumps(entry, ensure_ascii=False), file=sys.stderr)

# Exemple d'utilisation
log_event("info",    "file_loaded",   file="/mnt/user-data/uploads/example.csv", lignes=1024)
log_event("warning", "null_detected", column="score", count=12)
log_event("error",   "parse_failed",  reason="Encoding is not UTF-8")
{"timestamp": "2026-05-18T10:23:05", "level": "info",    "event": "file_loaded",   "file": "/mnt/user-data/uploads/example.csv", "rows": 1024}
{"timestamp": "2026-05-18T10:23:05", "level": "warning", "event": "null_detected", "column": "score", "count": 12}
{"timestamp": "2026-05-18T10:23:05", "level": "error",   "event": "parse_failed",  "reason": "编码不是 UTF-8"}

Débogage de l'exécution des instructions SKILL.md

Lorsque Claude n'exécute pas conformément aux instructions dans SKILL.md, vous pouvez localiser le problème en insérant des « points de contrôle » dans SKILL.md.

## 调试检查点(开发模式,发布前删除)

在执行每个步骤前,先以以下格式输出一行状态确认:

`[STEP N] 开始:{步骤名称},输入:{关键参数}`

示例:
`[STEP 1] 开始:读取文件,输入:/mnt/user-data/uploads/example.csv`
`[STEP 2] 开始:数据清洗,输入:1024 行`

这样可以在出错时快速定位到哪个步骤失败。

Les points de contrôle de débogage sont temporaires. Une fois le débogage terminé, veillez à supprimer ces instructions de SKILL.md, sinon les utilisateurs verront une sortie de débogage redondante lors d'une utilisation normale.


Référence rapide des scénarios de débogage courants

ScénarioMéthode de débogage
Compétence non déclenchéeVérifier la description, tester avec des invites complexes, exécuter run_loop.py pour optimiser
Le script signale ImportErrorExécuter pip install, vérifier si le nom du paquet correspond au nom d'importation
Erreur de chemin de fichierExécutez d'abord ls /mnt/user-data/uploads/ pour confirmer le nom du fichier
Sortie illisibleSpécifier explicitement encoding="utf-8" lors de la lecture des fichiers
Ordre d'exécution incorrect des étapesUtilisez une liste numérotée dans SKILL.md pour clarifier l'ordre des étapes
Résultat videAjoutez des print aux points clés du script pour confirmer à quelle étape les données deviennent vides
Autres extensions