Skills Registro y Depuración Avanzados
La depuración básica usa print; la depuración avanzada usa un mecanismo de registro sistemático.
Este artículo explica cómo crear registros estructurados para scripts de Skill y técnicas avanzadas para localizar problemas en flujos de ejecución complejos.
Usar logging en lugar de print
printAdecuado para depuración rápida, pero en una Skill de producción se debe usar la biblioteca estándar de Pythonloggingmódulo.
La ventaja de logging es que permite controlar el nivel de salida: durante el desarrollo se muestra información DEBUG, y en producción solo se muestran WARNING y superiores.
Ejemplo
import logging
import sys
from datetime import datetime
def get_logger(name: str, level: str = "INFO") -> logging.Logger:
"""
Crear un registrador de logs estructurado
Parámetros:
name: Nombre del registrador, normalmente el nombre del módulo (__name__)
level: Nivel de registro, DEBUG / INFO / WARNING / ERROR
"""
logger = logging.getLogger(name)
logger.setLevel(getattr(logging, level.upper(), logging.INFO))
# Evitar agregar handlers duplicados
if logger.handlers:
return logger
# Salida a consola: formato legible para humanos
console = logging.StreamHandler(sys.stdout)
console.setFormatter(logging.Formatter(
"[%(asctime)s] [%(levelname)s] %(name)s - %(message)s",
datefmt="%H:%M:%S"
))
logger.addHandler(console)
# Salida a archivo: escribir en un archivo de registro (opcional)
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
# Ejemplo de uso
if __name__ == "__main__":
log = get_logger(__name__, level="DEBUG")
log.debug("Información de depuración: ruta de archivo = /mnt/user-data/uploads/ejemplo.csv")
log.info("Comenzando a procesar el archivo")
log.warning("El tamaño del archivo supera los 50 MB, el procesamiento puede ser lento")
log.error("Error al leer el archivo: FileNotFoundError")
[10:23:01] [DEBUG] __main__ - 调试信息:文件路径 = /mnt/user-data/uploads/ejemplo.csv [10:23:01] [INFO] __main__ - 开始处理文件 [10:23:01] [WARNING] __main__ - 文件大小超过 50MB,处理可能较慢 [10:23:01] [ERROR] __main__ - 文件读取失败:FileNotFoundError
Rastreo del tiempo de ejecución
Cuando una Skill se ejecuta lentamente, es necesario identificar los pasos que son cuellos de botella en tiempo.
Ejemplo
import time
import functools
import logging
log = logging.getLogger(__name__)
def timeit(func):
"""Decorador: registra automáticamente el tiempo de ejecución de la función"""
@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__} tardó {elapsed:.3f} segundos")
return result
return wrapper
# Uso: agregue el decorador @timeit a la función que desea cronometrar
@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()
# También puede usar un administrador de contexto para cronometrar manualmente
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} tardó {elapsed:.3f} segundos")
# Usar el administrador de contexto Timer
if __name__ == "__main__":
with Timer("Leer y limpiar los datos"):
import pandas as pd
df = pd.read_csv("/mnt/user-data/uploads/ejemplo_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 秒
Registro estructurado: salida en formato JSON
Cuando los registros deben ser analizados por programas (en lugar de leídos por humanos), el formato JSON es más adecuado.
Ejemplo
import json
import sys
from datetime import datetime
def log_event(level: str, event: str, **context):
"""
Emitir registros JSON estructurados
Parámetros:
level: Nivel de registro (info / warning / error)
event: Nombre del evento
context: Pares clave-valor de contexto adicionales
"""
entry = {
"timestamp": datetime.now().isoformat(),
"level": level,
"event": event,
**context
}
# Usar stderr para emitir los registros, evitando mezclarlos con la salida normal del script
print(json.dumps(entry, ensure_ascii=False), file=sys.stderr)
# Ejemplo de uso
log_event("info", "file_loaded", file="/mnt/user-data/uploads/ejemplo.csv", rows=1024)
log_event("warning", "null_detected", column="score", count=12)
log_event("error", "parse_failed", reason="La codificación no es UTF-8")
{"timestamp": "2026-05-18T10:23:05", "level": "info", "event": "file_loaded", "file": "/mnt/user-data/uploads/ejemplo.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"}
Depurar la ejecución de instrucciones de SKILL.md
Cuando Claude no sigue las instrucciones de SKILL.md, se puede localizar el problema insertando «puntos de control» en SKILL.md.
## 调试检查点(开发模式,发布前删除)
在执行每个步骤前,先以以下格式输出一行状态确认:
`[STEP N] 开始:{步骤名称},输入:{关键参数}`
示例:
`[STEP 1] 开始:读取文件,输入:/mnt/user-data/uploads/ejemplo.csv`
`[STEP 2] 开始:数据清洗,输入:1024 行`
这样可以在出错时快速定位到哪个步骤失败。
Los puntos de control de depuración son temporales. Después de depurar, asegúrese de eliminar estas instrucciones de SKILL.md; de lo contrario, los usuarios verán salidas de depuración innecesarias durante el uso normal.
Referencia rápida de escenarios comunes de depuración
| Escenario | Método de depuración |
|---|---|
| La Skill no se activa | Revisar la descripción, probar con indicaciones complejas, ejecutar run_loop.py para optimizar |
| El script muestra ImportError | Ejecute pip install, verifique que el nombre del paquete coincida con el nombre de importación |
| Error en la ruta del archivo | Primero ejecute ls /mnt/user-data/uploads/ para confirmar el nombre del archivo |
| Salida ilegible | Al leer el archivo, especifique explícitamente encoding="utf-8" |
| El orden de ejecución de los pasos es incorrecto | En SKILL.md, use una lista numerada para especificar claramente el orden de los pasos |
| El resultado está vacío | Añada print en los puntos clave del script para confirmar en qué paso los datos se quedan vacíos |