Files
douyi_guaji_main/.github/copilot-instructions.md
T

7.3 KiB
Raw Blame History

Copilot 指令(本仓库)

来自 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 描述中说明回退策略。