# 参数使用跟踪模块说明 简要说明如何使用新添加的 `douyin.utils.param_usage_tracker` 模块来记录参数调用位置。 1) 直接记录单个参数位置 ```python from douyin.utils.param_usage_tracker import track_param def some_fn(): cfg_value = 42 track_param("important_threshold", cfg_value) # ... 业务逻辑 ... ``` 调用 `track_param` 会把一条记录追加到 `state/param_usage.json`,包含时间戳、调用文件、行号、函数名和参数的 repr。文件为逐行 JSON(NDJSON)。 2) 用装饰器自动记录函数调用参数 ```python from douyin.utils.param_usage_tracker import track_call @track_call() def process(item, flag=False): # 每次调用时,会把 func 名、定义位置、调用位置与参数记录到 state/param_usage.json pass process(1, flag=True) ``` 3) 读取记录 可以在调试脚本或 REPL 中使用 `read_entries()` 来读取并解析记录文件: ```python from douyin.utils.param_usage_tracker import read_entries entries = read_entries(limit=200) for e in entries: print(e) ``` 注意:为了兼容并发与减少文件读写冲突,记录以逐行 JSON 追加方式保存(NDJSON)。如需转换为 JSON 数组,可用脚本读取所有行并写入新的 JSON 文件。 启用全局跟踪(可选) 如果你想在程序运行期间自动记录仓库内所有函数的调用位置与参数,可以在启动前设置环境变量 `PARAM_TRACK_ALL=1`: ```bash PARAM_TRACK_ALL=1 python run_cli.py --help ``` 在 Windows PowerShell 中: ```powershell $env:PARAM_TRACK_ALL = '1' python run_cli.py --help ``` 注意:全局跟踪使用 `sys.settrace` 实现,会对性能产生显著影响,建议仅用于短时调试或在受控环境下使用。跟踪记录默认写入 `state/param_usage.json`(逐行 JSON)。 性能与范围控制建议: - 在仅需跟踪少数模块时,优先使用 `@track_call()` 装饰器或在关键位置调用 `track_param(...)`,以降低运行开销。 - 若启用全局跟踪,请在完成诊断后关闭(退出进程)以避免长期性能下降。 查看与转换记录示例: ```python from douyin.utils.param_usage_tracker import read_entries entries = read_entries(limit=500) for e in entries: print(e) # 将 NDJSON 转为 JSON 数组 with open('state/param_usage.json','r',encoding='utf-8') as f: lines = [json.loads(l) for l in f if l.strip()] with open('state/param_usage_array.json','w',encoding='utf-8') as f: json.dump(lines, f, ensure_ascii=False, indent=2) ``` 快速查看工具: 仓库中包括一个独立工具 `tools/param_usage_tool.py`,可以作为独立脚本使用来查看记录或静态扫描代码: 示例: ```bash python tools/param_usage_tool.py show --limit 200 python tools/param_usage_tool.py show --param important_threshold python tools/param_usage_tool.py tail python tools/param_usage_tool.py scan track_param ``` 该工具不依赖运行时跟踪器,可独立拿来分析 `state/param_usage.json` 或查找代码中 `track_param`/`track_call` 的调用位置。