7.3 KiB
Copilot 指令(douyin_guaji-main)
来自 docs/完整技术文档.md 的补充(要点)
- 版本:V4.5(2026-01-18)。本文件为实现细节与验证命令的权威来源,agent 在执行重大改动前请核对文档中的“验证要点”。
- 配置优先级:代码默认 <
config/config.json< 环境变量 < CLI 参数(run_cli.py覆盖最高优先)。 - 截图写入:tmp -> 原子替换(
_safe_replace_file),注意 Windows 文件锁;外部镜像由DISABLE_SCREENSHOT_MIRROR控制。 - OCR:优先 EasyOCR,回退 PaddleOCR;支持延迟初始化(
SKIP_OCR_INIT=1),首次调用按需初始化。 - 日志与时间戳:使用
douyin/logging/douyin_logging.py与unified_logger(毫秒精度),业务日志请用analyser._log_kv(...)。 - 验证脚本:文档提供多个
python -m py_compile与inspect验证示例,建议把常用验证命令做成tools/verify_*.ps1便于 CI/本地复现。
快速运行 & 关键点概览
- CLI 入口:
run_cli.py;主调度器:douyin/core/douyin_fudai.py(核心类fudai_analyse,主流程见run_once_basic())。 - 设备/ADB/OCR 层:
Underlying_Operations.py(优先 EasyOCR,失败回退 PaddleOCR;测试时用SKIP_OCR_INIT=1跳过 OCR 初始化)。 - 配置与路径:以
config/config.json为准,统一使用path_config.py提供的路径函数(不要硬编码assets/、pic/、logs/)。
下面使用简短清单帮助 agent 立即定位常用操作与约定(快速、可执行、可验证)。
先从这里入手(入口/主链路)
- CLI 入口:
run_cli.py;主调度器:douyin/core/douyin_fudai.py的fudai_analyse(fudai_choujiang()-> 循环run_once_basic())。 - 设备/ADB/OCR 兼容层:
Underlying_Operations.py(OCR:优先 EasyOCR,失败回退 PaddleOCR;可用SKIP_OCR_INIT=1跳过初始化)。 - 路径与配置:以
config/config.json为准,统一用path_config.py取路径(不要硬编码./;;assets/、pic/、logs/)。
架构要点(理解模块边界)
- 核心包:
douyin/;主要分层:core/(流程/状态) +stage/(阶段诊断) +handlers/(截图/弹窗/滑动等操作) +fudai/(福袋查找/详情/流程) +reservation/(高价值预约/回退校验) +detection/(像素/模板检测)。 - 分辨率适配以 1080x2400 为基准:坐标/ROI 一般需要走“缩放/偏移”路径(见
fudai_analyse的分辨率字段与相关 helper)。 - 开发以模块化为主:新功能/修复优先落在
douyin/*(业务流程)与operations/*(底层封装);Underlying_Operations.py多为兼容与兜底,避免把新逻辑持续堆进去。
配置加载与覆盖优先级(以 config.json 为核心)
- 真实配置文件:
config/config.json(path_config.get_config_path());GUI/WebGUI 会读写它。 douyin/utils/douyin_config.py:ConfigManager.load_config_from_file()会把配置写回 analyser;命令行传入的needswitch会被保留(命令行优先)。run_cli.py会在创建fudai_analyse()后,用 CLI 参数覆盖部分字段(如min_prize_value_yuan、skip_if_countdown_*、OCR/模板开关等)。
日志与调试图像(排障首选路径)
- 日志初始化:
douyin/logging/douyin_logging.py:configure_logging();统一日志能力在unified_logger.py(traceId/MDC/脱敏)。 - 业务日志优先用
analyser._log_kv(...)(实现见douyin/logging/douyin_logging_wrapper.py):始终 stdout 可被 GUI 捕获,并带阶段分隔。 - 截图/调试图像:
douyin/handlers/douyin_screenshot_manager.py(可异步保存;行为日志写入logs/actions.log,路径用path_config.get_actions_log_path())。 - 排障开关以
config/config.json为准:优先通过debug_captures.*控制调试图像(enabled/keep_days/max_files/async_save/log_on_complete),环境变量只作为性能/临时诊断手段。
状态文件(别改路径/格式)
- 预约队列落盘:
douyin/core/state/reservations.json(见fudai_analyse._reservations_state_path)。 - 高价值直播间等状态:
state/high_value_rooms.json(路径见path_config.get_high_value_rooms_path())。
兼容/遗留机制(默认不用,但别误删)
run_cli.py仍保留 shim +EXTERNAL_DOUYIN_FUDAI_DIR的兼容加载逻辑;本仓库已内置“本地完整版”实现,日常开发以本仓库代码为主。Underlying_Operations.py可能会把pic/screenshot.png镜像到外部目录;如做性能排查可设DISABLE_SCREENSHOT_MIRROR=1。
开发约束(本仓库高频踩坑)
- 代码修改规范(硬性):严格 4 空格缩进(禁用 Tab);
try必须配except/finally,if必须配对else/elif,for/while/def/class块必须完整且缩进正确。 - 修改流程:先理清缩进层级再改;改完做一次语法自检,避免孤立的
except/else/elif、括号/引号不配对、冒号后缺缩进块(详见docs/完整技术文档.md)。 - 当前仓库没有可运行的
pytest测试集;常用验证方式是跑python run_cli.py ...或 GUI/WebGUI,并结合logs/+pic/调试输出定位问题。
模块化要点(新代码必读)
-
把业务逻辑放到
douyin/的合适子包,不要把业务代码塞入Underlying_Operations.py或顶层脚本。举例:douyin/core/:调度与全局运行状态(全局 orchestrator)douyin/handlers/:设备交互、截图、弹窗与滑动douyin/fudai/:福袋查找与参与的业务实现douyin/reservation/:预约队列与回退校验实现douyin/detection/:像素/模板/阈值检测算法实现
-
设计原则:单一职责、清晰 API、低耦合。每个新模块应只负责一类功能并导出明确函数/类(例如
douyin/fudai/my_finder.py导出find_fudai(analyser, device_id))。 -
依赖注入优先:模块应通过参数接收
operation或analyser实例,避免在模块内直接引用全局单例,便于测试和替换实现。 -
避免在模块导入阶段执行重型副作用(例如初始化 OCR、长时间文件 I/O、启动设备连接)。对重型依赖使用延迟导入或在显式的 init()/start() 中加载。
-
配置与路径使用
path_config.py和config/config.json,不要硬编码路径或阈值;新增配置需在config/config.json加入默认值并在模块中读取。 -
日志使用
analyser._log_kv(...)或unified_logger,避免无注释的 print。出错时记录上下文(traceId / run id)。 -
在涉及点击/滑动/截图等行为时,应通过
underlying_operations提供的接口调用,不要在高层模块直接调 adb 命令(底层模块可实现 adb 直接调用,但需注明)。 -
新增检测/模板/handler 请放到相应目录并在模块顶部导出 API,补充
docs/中的简短说明并在tools/提供一个轻量的验证脚本用于手动验证。 -
虽然仓库中没有统一 pytest 测试集,但新增模块应附带小规模验证:可在
tools/下添加 demo 脚本,或通过run_cli.py的参数提供可触发的测试路径。 -
代码风格与质量:4 空格缩进、类型注解优先、合理的异常处理(不要留下孤立的 except/else/elif)、并在 PR 描述中说明回退策略。