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
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
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
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énario | Méthode de débogage |
|---|---|
| Compétence non déclenchée | Vérifier la description, tester avec des invites complexes, exécuter run_loop.py pour optimiser |
| Le script signale ImportError | Exécuter pip install, vérifier si le nom du paquet correspond au nom d'importation |
| Erreur de chemin de fichier | Exécutez d'abord ls /mnt/user-data/uploads/ pour confirmer le nom du fichier |
| Sortie illisible | Spécifier explicitement encoding="utf-8" lors de la lecture des fichiers |
| Ordre d'exécution incorrect des étapes | Utilisez une liste numérotée dans SKILL.md pour clarifier l'ordre des étapes |
| Résultat vide | Ajoutez des print aux points clés du script pour confirmer à quelle étape les données deviennent vides |