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

# Ruta del archivo: scripts/logger_setup.py
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

# Ruta del archivo: scripts/timer.py
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

# Ruta del archivo: scripts/json_logger.py
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

EscenarioMétodo de depuración
La Skill no se activaRevisar la descripción, probar con indicaciones complejas, ejecutar run_loop.py para optimizar
El script muestra ImportErrorEjecute pip install, verifique que el nombre del paquete coincida con el nombre de importación
Error en la ruta del archivoPrimero ejecute ls /mnt/user-data/uploads/ para confirmar el nombre del archivo
Salida ilegibleAl leer el archivo, especifique explícitamente encoding="utf-8"
El orden de ejecución de los pasos es incorrectoEn SKILL.md, use una lista numerada para especificar claramente el orden de los pasos
El resultado está vacíoAñada print en los puntos clave del script para confirmar en qué paso los datos se quedan vacíos
Otras extensiones