[10:23:01] [DEBUG] __main__ - 调试信息：文件路径 = /mnt/user-data/uploads/runoob.csv [10:23:01] [INFO] __main__ - 开始处理文件 [10:23:01] [WARNING] __main__ - 文件大小超过 50MB，处理可能较慢 [10:23:01] [ERROR] __main__ - 文件读取失败：FileNotFoundError

执行时间追踪

当 Skill 执行较慢时，需要找出耗时的瓶颈步骤。

实例

# 文件路径：scripts/timer.py
import time
import functools
import logging

log = logging.getLogger(__name__)

def timeit(func):
"""装饰器：自动记录函数执行时间"""
@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__} 耗时 {elapsed:.3f} 秒")
return result
return wrapper

# 使用方式：在需要计时的函数上加 @timeit 装饰器
@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()

# 也可以用上下文管理器手动计时
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} 耗时 {elapsed:.3f} 秒")

# 使用 Timer 上下文管理器
if __name__ == "__main__":
with Timer("读取并清洗数据"):
import pandas as pd
df = pd.read_csv("/mnt/user-data/uploads/runoob_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 秒

结构化日志：输出 JSON 格式

当日志需要被程序解析（而非人工阅读）时，JSON 格式更合适。

实例

# 文件路径：scripts/json_logger.py
import json
import sys
from datetime import datetime

def log_event(level: str, event: str, **context):
"""
输出结构化 JSON 日志

参数：
level: 日志级别（info / warning / error）
event: 事件名称
context: 附加的上下文键值对
"""
entry = {
"timestamp": datetime.now().isoformat(),
"level": level,
"event": event,
**context
}
# 使用 stderr 输出日志，避免与脚本的正常输出混合
print(json.dumps(entry, ensure_ascii=False), file=sys.stderr)

# 使用示例
log_event("info", "file_loaded", file="/mnt/user-data/uploads/runoob.csv", rows=1024)
log_event("warning", "null_detected", column="score", count=12)
log_event("error", "parse_failed", reason="编码不是 UTF-8")

{"timestamp": "2026-05-18T10:23:05", "level": "info", "event": "file_loaded", "file": "/mnt/user-data/uploads/runoob.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"}

调试 SKILL.md 的指令执行

当 Claude 没有按照 SKILL.md 的指令执行时，可以通过在 SKILL.md 中插入"检查点"来定位问题。

## 调试检查点（开发模式，发布前删除） 在执行每个步骤前，先以以下格式输出一行状态确认： `[STEP N] 开始：{步骤名称}，输入：{关键参数}` 示例： `[STEP 1] 开始：读取文件，输入：/mnt/user-data/uploads/runoob.csv` `[STEP 2] 开始：数据清洗，输入：1024 行` 这样可以在出错时快速定位到哪个步骤失败。

调试检查点是临时的。调试完成后，务必从 SKILL.md 中删除这些指令，否则正式使用时用户会看到多余的调试输出。

常见调试场景速查

场景	调试方法
Skill 未触发	检查 description、使用复杂提示词测试、运行 run_loop.py 优化
脚本报 ImportError	运行 pip install，检查包名与 import 名称是否匹配
文件路径报错	先 ls /mnt/user-data/uploads/ 确认文件名
输出乱码	在文件读取时显式指定 encoding="utf-8"
步骤执行顺序不对	在 SKILL.md 中用编号列表明确步骤顺序
结果为空	在脚本关键节点加 print，确认数据在哪一步变空