# Copilot 指令(douyin_guaji-main) ## 先从这里入手(入口/主链路) - 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/` 调试输出定位问题。