A. docs/ 根目录下 5 篇过期/迁移类文档归档到 docs/archive/ - LOGGING_IMPROVEMENTS.md (日志系统迭代报告,与 archive/日志系统优化说明.md 重复) - OCR性能分析报告.md (历史性能分析) - 统一截图和分数记录说明.md (重构方案,已合并到代码) - AI_PROJECT_SUMMARY.md (提到的 Underlying_Operations.py / path_config.py 路径已与 main 重构后不一致) - param_usage.md (模块使用说明,零引用,模块本身有 docstring) B. docs/optimization/ 整目录归档为 docs/archive/optimization/(7 篇) - ADB_EXECOUT_OPTIMIZATION / OCR_PERFORMANCE_OPTIMIZATION - SCREENSHOT_PERFORMANCE_DIAGNOSIS / SCREENSHOT_VERIFICATION_GUIDE - STREAMING_SCREENSHOT_DISABLED / STREAMING_SCREENSHOT_COMPLETELY_DISABLED - optimize_file_replace 全部是优化报告 / 已禁用功能记录,属于历史迭代而非活文档 C. docs/README.md 重写为按主题分组的索引,明确"活文档 vs 归档"边界 保留为活文档: - 日志系统规范文档.md(被 3 处引用) - 日志轮转功能说明.md(描述当前在用的轮转策略) - 截图服务日志说明.md(描述当前服务行为) - 完整技术文档.md / 流程图.md / 预约系统详细流程.md / 高价值房间重访功能说明.md 回归:纯文档归档不影响代码;140 .py 全量编译通过; test_filter_logging / check_web_gui_config_sync 通过。 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
97 lines
3.0 KiB
Markdown
97 lines
3.0 KiB
Markdown
# 参数使用跟踪模块说明
|
||
|
||
简要说明如何使用新添加的 `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` 的调用位置。
|