Files
douyin_guaji-main/docs/完整技术文档.md
CodexandClaude Opus 4.7 941bbc2475 docs: 命令行示例与核显说明改新路径
- docs/完整技术文档.md:7 处 'python run_cli.py …' 命令统一改为
  'python bin/run_cli.py …',与重构后入口位置对齐(头部小贴士那
  一行的示例字符串保留作为对照说明)
- docs/核显GPU加速说明.md:'修改 Underlying_Operations.py' 改为
  'douyin/core/underlying_operations.py'

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-21 13:35:19 +08:00

294 KiB
Raw Permalink Blame History

抖音福袋挂机 — 完整技术文档(重构)

版本: V4.5 最后更新: 2026-01-18 目标读者: 开发者、维护者、运维与 AI 助手

说明:本文件为项目主要技术文档的重构版,聚焦“快速上手、配置规范、关键模块地图、运行与排障、验证清单”。文档同时给出可执行的诊断/采样命令,便于自动化采集与 CI 校验。

⚠️ 路径迁移说明(2026-05 之后阅读本文档时请对照)

本文档主体撰写于项目大重构之前,正文里仍出现大量旧路径。重构后实际位置如下(旧 → 新):

文档里写的(旧) 当前实际位置(新)
Underlying_Operations.py douyin/core/underlying_operations.py
path_config.py douyin/core/path_config.py
run_cli.py bin/run_cli.py
gui_app.py bin/gui_app.py(launcher)/ gui/gui_app.py(实现)
webgui_launcher.py bin/webgui_launcher.py(launcher)/ gui/webgui_launcher.py(实现)
manage_logs.py bin/manage_logs.py
unified_logger.py douyin/logging/unified_logger.py
version.py douyin/core/version.py
from Underlying_Operations import … from douyin.core.underlying_operations import …
from path_config import … from douyin.core.path_config import …

入口脚本现在统一放在 bin/ 下,根目录已不再保留 launcher 转发。文档里所有 python run_cli.py … 示例命令请改读为 python bin/run_cli.py …,其他入口同理。

-- 变更记录

  • 2026-01-18: V4.5 — 修复预约更新后的循环问题,添加强制切换标志防止在同一直播间反复检测。
  • 2026-01-18: V4.4 — 修复并行OCR重试导致日志/重试噪音,参与失败自动切换直播间;购物红包像素+OCR复查(非直播间也OCR复查);并行OCR完成后写盘映射表以提升回退校验一致性;预约回退纠偏(方向提示)与二次回退改进;GUI映射表自适应列与新增购物红包阈值配置(GUI暴露)。
  • 2026-01-16: V4.3 — 修复GUI回退配置逻辑分离问题,完善预约二次回退机制。
  • 2026-01-16: V4.2 — 优化任务数量传递逻辑,统一日志时间戳格式,添加警告日志追踪。
  • 2026-01-07: V4.1 — 删除所有预约抢占逻辑,包括配置项、代码实现和相关文档。
  • 2026-01-03: V4.0 — 重构文档结构,补充快速上手、配置优先级、截图/OCR/日志说明、故障排查与验证清单。

最近修复与配置变更(2026-01-16)

本小节记录最近完成的若干修复与功能开关,便于开发与运维快速验证和回滚。

2026-01-18: V4.4 — 重要修复与新增说明 ✅

  • 修复并行OCR重试/日志噪音:修复 douyin/fudai/core/fudai_attend.py 中无限重试导致的重复日志(已添加 click_times 计数与短延时),避免 OCR 缓存复用的过度重试。
  • 连续参与失败自动切换直播间:douyin/core/douyin_fudai.py::_handle_in_fudai_detail 当 _consecutive_attend_failures 超过阈值时会关闭详情并在 needswitch 启用时上滑切换直播间并重置计数器。
  • 购物红包像素命中时的 OCR 复查:当像素检测到购物红包背景且不在直播间时,新增 步骤2.5[购物红包OCR复查](douyin/stage/douyin_stage.py),以 OCR 决定是否判定为 SHOPPING_REDPACKET_POPUP,降低误判率。
  • 购物红包阈值配置与 GUI 暴露:新增配置项 shopping_redpacket_red_ratio_threshold(默认 0.15)并在 gui/gui_app.py 的「像素检测阈值」中暴露为 购物红包背景红色占比阈值。
  • 映射表并行OCR写盘:并行 OCR 完成后会将运行时 analyser._room_pos_to_title_map 写入状态(调用 _dump_room_pos_map_to_state),保证预约回退时使用最新映射(见 douyin/fudai/douyin_fudai_core.py 和 douyin/reservation/douyin_reservation_handler.py)。
  • 预约回退纠偏与二次回退修复:当映射表显示已在目标位置但校验失败时,记录方向提示 _seek_direction_hint 并在 seek_reservation_room 中执行一次纠偏滑动(上/下),避免二次回退未触发滑动导致定位失败。
  • GUI 映射表改进:gui/gui_app.py 中映射表现在可垂直扩展(pack(fill=BOTH, expand=True))、自动根据内容自适应列宽,并在刷新后触发列自适应。
    • 新增 UI 交互:为避免列过窄导致文字被挤在一起,GUI 新增“显示原始标题”复选框(默认隐藏 title_raw 列)可释放列宽;同时支持双击行弹出详情窗口查看完整文本(适用于被截断的 任务列表 / 福袋内容 等字段)。
  • 取消 SwipeHandler 中的早返回:修复 douyin/handlers/douyin_swipe_handler.py 中对 has_fudai 的早返回逻辑,确保在有福袋信息时仍然允许上滑切换直播间(避免写盘后被误拦截)。

验证要点(运行时观察):

  • 日志:出现 "连续参与失败次数过多,跳过此福袋" 后会有 "切换直播间" 或 "单间模式不切换" 的记录;参与失败计数会重置。
  • 购物红包检测:像素命中但未进入直播间时会有 步骤2.5[购物红包OCR复查] 的日志;OCR 匹配到关键词(如"购物红包"、"邀你抢")会返回 SHOPPING_REDPACKET_POPUP。
  • 映射表:并行 OCR 完成后场景下应能在 douyin/core/state/room_pos_map.json 中看到新写入或更新的项(可通过 GUI 映射表看到)。

快速验证命令(仓库根目录,PowerShell / Python):

# 语法检查(关注新增/修改的文件)
python -m py_compile douyin/fudai/core/fudai_attend.py \
    douyin/core/douyin_fudai.py \
    douyin/stage/douyin_stage.py \
    douyin/detection/douyin_pixel.py \
    douyin/other/douyin_popups.py \
    douyin/reservation/douyin_reservation_handler.py \
    douyin/handlers/douyin_swipe_handler.py \
    gui/gui_app.py

# 检查 detect_redpacket_popup_background 签名
python - <<'PY'
import inspect
from douyin.detection import douyin_pixel
print('signature:', inspect.signature(douyin_pixel.detect_redpacket_popup_background))
PY

# 检查配置项是否可读
python - <<'PY'
from douyin.utils.douyin_config import ConfigManager
class Dummy: pass
d = Dummy()
ConfigManager.load_config_from_file(d)
print('shopping_redpacket_red_ratio_threshold=', getattr(d, 'shopping_redpacket_red_ratio_threshold', None))
PY

# 检查 GUI 中是否有相应变量与控件
python - <<'PY'
import inspect, gui.gui_app as g
s = inspect.getsource(g)
print('gui control exists:', 'shopping_redpacket_red_ratio_threshold_var' in s)
PY

# 检查并行OCR写盘相关调用
python - <<'PY'
import inspect
import douyin.fudai.douyin_fudai_core as core
print('_dump_room_pos_map_to_state call present:', '_dump_room_pos_map_to_state' in inspect.getsource(core))
PY

如果需要,我可以把这些验证步骤做成独立脚本并加入 tools/ 供 CI / 本地复现调用。

2026-01-18: V4.5 — 预约更新循环修复 ✅

  • 修复预约更新后的循环问题:当福袋已被预约过时,douyin/fudai/douyin_fudai_core.py 的 basic_join_decision 函数会更新预约信息,但之前未设置强制切换标志,导致程序在同一直播间反复检测和参与,形成循环。
  • 强制切换标志机制:更新预约后设置 analyser._just_recorded_reservation = True,并返回 False 触发切换;douyin/core/douyin_fudai.py 的 run_once_basic 检查该标志并强制调用 swipe_up_to_next_live。
  • 关闭详情页:更新预约后添加关闭详情页逻辑,避免停留在详情页。

验证要点(运行时观察):

  • 日志:更新预约后应有 "切换直播间" 记录,无反复 [福袋查找] 循环;有 "已关闭详情(更新预约后)" 日志。
  • 行为:预约更新后立即切换到下一个直播间,避免卡在同一房间。

快速验证命令(仓库根目录,PowerShell):

# 语法检查
python -m py_compile douyin/fudai/douyin_fudai_core.py
python -m py_compile douyin/core/douyin_fudai.py

# 检查标志设置
python - <<'PY'
import inspect
import douyin.fudai.douyin_fudai_core as core
source = inspect.getsource(core.basic_join_decision)
print('_just_recorded_reservation set in update branch:', 'analyser._just_recorded_reservation = True' in source and 'return False' in source)
PY

# 检查标志检查
python - <<'PY'
import inspect
import douyin.core.douyin_fudai as main
source = inspect.getsource(main.run_once_basic)
print('flag check and swipe:', '_just_recorded_reservation' in source and 'swipe_up_to_next_live' in source)
PY

如果需要,我可以把这些验证步骤做成独立脚本并加入 tools/ 供 CI / 本地复现调用。

  • 概要:修复GUI中滑动重置回退方式与返回键回退的配置逻辑分离问题;完善预约系统中回退校验失败后的二次回退机制,确保能根据映射表重新定位目标直播间;优化滑动重置回退过程中的延迟,从2秒减少到0.1秒以加快回退速度;修复映射表中福袋信息记录缺失问题,确保福袋内容和详情能正确记录到映射表中;新增映射表重复直播间标题检测和去重功能,自动删除重复记录并标记去重信息。

    • GUI回退配置逻辑分离:

      • gui/gui_app.py:修复保存配置逻辑,独立处理reset_after_swipes_action和enable_back_on_misses配置;重新组织UI布局,按功能分组显示相关配置。
      • 滑动重置配置组:reset_after_swipes_enabled、reset_after_swipes、reset_after_swipes_action。
      • 返回键回退配置组:enable_back_on_misses、fudai_exit_after_misses。
    • 预约二次回退机制完善:

      • douyin/reservation/douyin_reservation_logic.py:修复回退校验失败后的二次回退逻辑,添加位置重新查找机制;确保二次回退成功时正确设置锁定期和待处理标志。
      • douyin/reservation/douyin_reservation_handler.py:seek_reservation_room函数优化,确保位置差为0时仍能正确处理。
    • 滑动回退延迟优化:

      • douyin/handlers/douyin_swipe_handler.py:优化滑动重置回退过程中的延迟,从每次回退间的2秒延迟减少到0.1秒;显著加快回退到第一个直播间的速度。
    • 映射表福袋信息记录修复:

      • douyin/fudai/douyin_fudai_core.py:修复映射表中福袋信息记录缺失问题,在记录映射表前确保_current_fudai_content和_last_fudai_detail_tuple属性已被正确设置。
      • douyin/fudai/core/fudai_detail_orchestrator.py(旧位置:fudai_detail_modules/fudai_detail_reader.py,2026-05 合并到 core/):优化福袋详情识别完成后映射表记录时机,将并行映射表记录从OCR开始前移动到福袋详情识别完成后,确保福袋内容和详情信息完整记录到映射表。
    • 预约锁定期保护机制:

      • douyin/core/douyin_fudai.py:修复预约福袋参与成功后锁定期被提前清除的问题,实现依次参与保护机制;参与成功后检查是否还有其他预约,如果有则设置10秒保护期,确保预约福袋依次参与不被其他预约打断;如果没有其他预约则正常清除锁定期。
  • 验证要点(运行时观察):

    • GUI中滑动重置回退方式与返回键回退配置完全独立,不再相互影响。
    • 预约回退校验失败时,会先重新查找目标直播间位置,然后执行二次回退。
    • 二次回退成功时会正确设置锁定期,避免重复处理同一预约。
    • 日志中显示"重新查找目标直播间位置成功"和"第二次回退成功"的相关信息。
    • 滑动重置回退过程显著加快,每次回退间的延迟从2秒减少到0.1秒。
    • 映射表中正确记录了福袋内容和详情信息,日志显示"has_fudai": true 和相应的福袋内容;在福袋详情识别完成后立即记录,确保信息完整性。
    • 预约福袋参与成功后,如果还有其他预约,会设置10秒保护期确保依次参与;如果没有其他预约,则正常清除锁定期;日志显示"[预约] 参与成功,设置保护期确保依次参与"或"[预约] 参与成功,清除锁定期(无其他预约)"。
  • 快速验证命令(仓库根目录,PowerShell):

# 语法检查
python -m py_compile gui/gui_app.py
python -m py_compile douyin/reservation/douyin_reservation_logic.py
python -m py_compile douyin/reservation/douyin_reservation_handler.py

# GUI配置验证
python -c "import gui.gui_app; print('GUI配置逻辑正常')"

# 预约逻辑验证
python -c "from douyin.reservation import douyin_reservation_logic; print('预约逻辑正常')"

# 配置独立性验证
python -c "
import json
config = json.load(open('config/config.json'))
print('reset_after_swipes_action:', config.get('reset_after_swipes_action', 'MISSING'))
print('enable_back_on_misses:', config.get('enable_back_on_misses', 'MISSING'))
print('配置项独立存在')
"

# 滑动处理器验证
python -c "
from douyin.handlers import douyin_swipe_handler
handler = douyin_swipe_handler.SwipeHandler()
print('滑动处理器初始化正常')

# 检查回退延迟是否已优化
import inspect
source = inspect.getsource(handler.maybe_reset_after_swipes)
if 'analyser.operation.delay(0.1)' in source and 'analyser.operation.delay(2)' not in source.split('#')[0]:
    print('回退延迟优化验证通过:延迟已从2秒减少到0.1秒')
else:
    print('回退延迟优化验证失败:延迟未正确修改')
"

# 映射表福袋信息记录验证
python -c "
from douyin.fudai.core import fudai_detail_orchestrator as fudai_detail_reader
import inspect
source = inspect.getsource(fudai_detail_reader.read_fudai_detail_once)
if 'analyser._current_fudai_content = content' in source and 'analyser._last_fudai_detail_tuple = detail_tuple' in source and '在福袋详情识别完成后记录映射表' in source:
    print('映射表福袋信息记录验证通过:在福袋详情识别完成后正确设置福袋属性并记录映射表')
else:
    print('映射表福袋信息记录验证失败:福袋属性设置或记录时机未正确修改')
"

# 预约锁定期保护验证
python -c "
with open('douyin/core/douyin_fudai.py', 'r', encoding='utf-8') as f:
    content = f.read()
if 'has_other_reservations' in content and '设置保护期确保依次参与' in content and 'protection_seconds=10' in content:
    print('预约锁定期保护验证通过:参与成功后正确设置保护期')
else:
    print('预约锁定期保护验证失败:保护期逻辑未正确实现')
"

如果需要,我可以把这些验证步骤写成一键脚本 tools/verify_recent_fixes.sh / tools/verify_recent_fixes.ps1 以便 CI 调用。

  • 概要:优化福袋详情页任务计数检测,避免重复阶段诊断;统一日志时间戳格式为毫秒精度;增加任务计数未获取时的警告日志;修复截图复用逻辑,确保在详情页关闭前复用截图。

    • 任务计数检测优化:
      • douyin/stage/douyin_stage.py:限制任务计数仅在触发原因 "find_and_open_fudai_detail_click_verification" 时设置,避免重复诊断。
      • douyin/fudai/douyin_fudai_core.py:删除备用阶段检测逻辑,默认任务计数为 0,增加警告日志。
      • douyin/fudai/core/fudai_detail_orchestrator.py(旧位置:fudai_detail_modules/fudai_detail_reader.py):默认任务计数为 0,增强警告日志输出。
    • 日志时间戳统一:
      • douyin/logging/douyin_logging.py:新增 MillisecondFormatter 类。
      • douyin/logging/unified_logger.py:为 UnifiedFormatter 添加 formatTime 方法。
      • douyin/logging/action_logger.py:更新为使用 MillisecondFormatter。
    • 截图复用优化:
      • 确保在福袋详情页关闭前复用截图,避免不必要的重复截图。
  • 验证要点(运行时观察):

    • 日志时间戳统一为毫秒精度格式(如 2026-01-16 01:34:52.333)。
    • 福袋详情页不再出现重复阶段诊断。
    • 任务计数未获取时输出 WARNING 级别日志,包含原因和建议。
    • 截图在详情页关闭前得到复用。
  • 快速验证命令(仓库根目录,PowerShell):

# 语法检查
python -m py_compile douyin/stage/douyin_stage.py
python -m py_compile douyin/fudai/douyin_fudai_core.py
python -m py_compile douyin/fudai/core/fudai_detail_orchestrator.py

# 运行短会话验证
python bin/run_cli.py --wait-minutes 0 --device-id <ADB_ID>

# 检查日志格式
Get-Content logs/actions.log -Tail 10 | Select-String "\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}"

如果需要,我可以把这些验证步骤写成一键脚本 tools/verify_fudai_disable.sh / tools/verify_fudai_disable.ps1 以便 CI 调用。

快速步骤(3 分钟上手)

  1. 克隆仓库并进入目录

  2. 建议在 Windows PowerShell 中运行(示例):

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements-minimal.txt
  1. 运行主流程(单设备示例):
python bin/run_cli.py --device-id <ADB_ID> --needswitch
  1. 调试单次循环:
python bin/run_cli.py --device-id <ADB_ID> --wait-minutes 0

说明:如需快速禁用 OCR 启动耗时,可设置环境变量 SKIP_OCR_INIT=1。

文档结构(建议阅读顺序)

  • 快速上手(本节)
  • 配置与覆盖优先级(重要)
  • 截图/OCR/日志与状态文件(实现细节 + 开关)
  • 核心模块地图(文件 + 关键符号)
  • 运行流程概览(简要调用链)
  • 故障排查与采样操作(可执行命令)
  • 验证清单与 CI 建议
  • FAQ

配置加载与覆盖优先级

生效顺序(从低到高):

  1. 代码内默认值(常量/类属性)
  2. config/config.json(通过 path_config.get_config_path() 获取)
  3. 环境变量(例如 SKIP_OCR_INIT, DISABLE_SCREENSHOT_MIRROR)
  4. 命令行参数(bin/run_cli.py 解析,优先级最高,运行时覆盖实例属性)

示例:通过命令行临时指定设备优先于 config/config.json 中的默认设备。

实现建议与样例:

  • 在 douyin/utils/douyin_config.py 中实现 load_config_from_file(path) 返回 dict,主流程使用该 dict 初始化分析器并在 bin/run_cli.py 中用命令行覆盖字段。
  • 推荐在 config/config.json 中采用明确分组,例如:
{
  "device": { "default_device": "emulator-5554" },
  "logging": { "level": "INFO", "file_path": "logs/unified.log" },
  "debug_captures": { "enabled": false, "max_files": 100 }
}
  • 命令行覆盖示例(bin/run_cli.py 中解析后合并):
# pseudo
config = load_config()
if args.device_id:
    config['device']['default_device'] = args.device_id

错误处理与回退策略:当 config/config.json 不存在或字段缺失时:

  • 使用代码内默认值并在日志中写 warning;
  • 在关键字段(如 device、ocr_engine)缺失时中断并提示用户。

关联文件:config/config.json,douyin/utils/douyin_config.py,douyin/core/path_config.py,bin/run_cli.py。

截图 / OCR / 日志 / 状态(实现细节与故障采样)

  1. 截图(实现要点)
  • 优先方式:adb exec-out screencap -p(单次 adb 调用,速度最快)。
  • 回退方式:adb shell screencap -p /sdcard/screen.png + adb pull(兼容性但更慢)。
  • 写入策略:先写入临时文件(例如 screenshot.png.tmp),再通过原子替换或安全复制覆盖 pic/screenshot.png,以避免并发读取到半写入文件。见 underlying_operations.get_screenshot() 的实现。
  • Windows 文件锁与镜像:_safe_replace_file() 包含多重回退(os.replace → shutil.copy2 → 分块复制),并可通过环境变量 DISABLE_SCREENSHOT_MIRROR=1 禁用将截图镜像到外部目录(EXTERNAL_DOUYIN_FUDAI_DIR)。
  1. OCR(策略与初始化)
  • 优先引擎:EasyOCR(速度与准确性通常最佳);回退:PaddleOCR。实现位于 underlying_operations.analyse_pic_word()。
  • 延迟初始化:支持 SKIP_OCR_INIT=1(跳过启动时初始化),首次调用时会在 _ensure_ocr() 进行按需初始化。
  • 回退与容错:若 OCR 未能初始化或识别失败,函数返回空字符串,上层代码需对空结果做容错与重试。建议生产环境安装 easyocr 并允许启动时初始化以减少首次延迟。
  1. 日志(配置点与建议)
  • 日志初始化:douyin/logging/douyin_logging.py::configure_logging(),业务封装见 douyin/logging/douyin_logging_wrapper.py。
  • 关键字段(建议在文档或 config.json 中说明):
    • logging.level、logging.file_path、logging.rotation.max_bytes、logging.rotation.backup_count。
    • debug_captures:enabled、keep_days、max_files、auto_cleanup 用于调试图片的保存与清理。
  • 建议:生产默认禁用大量 debug captures,CI/调试时开启并限制 max_files。日志需包含 traceId/device_id/stage 字段以便聚合分析。

常见日志/截图故障与排查命令:

  • 截图失败(设备无法连接或 adb 权限问题):
adb devices
adb -s <ADB_ID> shell screencap -p /sdcard/test.png && adb -s <ADB_ID> pull /sdcard/test.png .\
  • 截图文件被占用/半写入(Windows 文件锁问题):检查进程并清理临时文件:
Get-Process | Where-Object { $_.Path -like '*python*' }
Remove-Item pic\screenshot.png.tmp -Force -ErrorAction SilentlyContinue
  • OCR 未初始化或识别异常:
from douyin.core.underlying_operations import underlying_operations
op = underlying_operations()
op._ensure_ocr()
print(op.analyse_pic_word('pic/screenshot.png'))
  1. 状态文件(预约)
  • 持久化路径:通过 path_config.get_reservations_path() 返回 state/reservations.json。
  • 行为说明:当前实现“首次运行清空内存预约以避免历史污染,后续运行使用内存队列并在变更时写回文件以供外部查看”。若需保留历史,可添加 --preserve-reservations 启动开关或修改加载逻辑。
  1. 故障采样与自动化收集(建议步骤)
  • 已提供:tools/scan_coords.py(扫描仓库中疑似硬编码坐标/ROI,输出 tools/coords_report.csv)。

推荐采样流程(避免自动大量归档):

  1. 在短时间窗口运行主流程以生成调试图片和日志(注意 debug_captures.enabled):
python bin/run_cli.py --device-id <ADB_ID> --wait-minutes 1
  1. 基于日志时间戳筛选 pic/ 下的候选图片(示例:按文件修改时间):
Get-ChildItem -Recurse pic\*.png | Where-Object { $_.LastWriteTime -gt (Get-Date).AddHours(-1) }
  1. 根据识别结果或文件名(包含 ocr、digits、预处理 等关键词)手动或用小脚本筛选出低置信度或异常样本,复制到团队约定目录(例如 tools/samples/)。

  2. 生成小型清单(CSV)记录样本来源与日志行号,便于人工复核。

注:避免一次性将大量样本提交到仓库,建议只保留小样本或使用内部 artifact 存储。

快速检查命令:

# 扫描仓库硬编码坐标
python tools/scan_coords.py

# 查看前200条样例(生成的文件较大时使用)
powershell -Command "Get-Content tools/coords_report.csv -TotalCount 200 | Out-File -Encoding utf8 tools/coords_report_head.csv"

验证清单(可纳入 CI)

最小验证覆盖:

  • 语法检查(所有 Python 文件):
python -m py_compile $(git ls-files "**/*.py")
  • 关键文件存在性检查:确保 bin/run_cli.py、douyin/core/underlying_operations.py、config/config.json、douyin/core/path_config.py 存在并可被导入。

示例 CI 脚本片段:

python -m py_compile $(git ls-files "**/*.py") || exit 1
python - <<'PY'
from douyin.core.path_config import get_reservations_path
import os
print('reservations path', get_reservations_path())
assert os.path.isdir(os.path.dirname(get_reservations_path()))
PY

AI 集成指南(供代码助手/分析器使用)

目标:为自动化助手或 LLM 提供结构化入口与可观测点,便于自动查询、故障定位与代码导航。

  • 项目意图(一句话):自动化在抖音直播中查找并参与“福袋”活动的流程化机器人,包含截图、像素/模板检测、OCR、决策与预约管理。

  • 关键入口(按优先级):

    • bin/run_cli.py:CLI 入口,生成 fudai_analyse 实例并开始主循环;适合触发最小可运行示例。
    • douyin/core/douyin_fudai.py::fudai_choujiang():主循环调度;查看运行状态与错误堆栈。
    • douyin/core/underlying_operations.py:底层设备接口(截图、裁剪、OCR)— 对外数据采集点。
  • 可调用的“程序式”API(Python)示例:

from douyin.core.underlying_operations import underlying_operations
op = underlying_operations()
# 获取当前截图路径
img = op.get_screenshot('<ADB_ID>')
# 对单张图运行 OCR
text = op.analyse_pic_word(img)
  • 关键文件与含义速查表(便于 LLM 快速定位实现细节):

    • douyin/core/path_config.py:统一路径(logs/pic/state)——用于定位运行数据。
    • douyin/logging/douyin_logging_wrapper.py:业务日志封装——搜索 traceId 与 stage。
  • 可观测数据(建议供 AI 检索):

    • 截图目录:pic/(按时间戳与文件名可映射运行步骤)。
    • 行为日志:logs/actions.log(操作事件序列)。
    • 统一日志:logs/unified_*.log(错误堆栈、traceId)。
    • 工具产物:tools/coords_report.csv(硬编码坐标候选)。
  • 配置/状态快速定位:

    • 运行时配置:config/config.json(AI 可读取以模拟运行参数)。
    • 状态文件:state/reservations.json(预约队列快照)。
  • 推荐的自动分析任务(便于 LLM 自动执行或生成报告):

    1. 检查最近 logs/unified_*.log 中的 ERROR/WARN,提取 traceId 与相关文件路径。
    2. 对应 traceId 检索 pic/ 中同时间窗口的截图,生成 OCR 对比表(识别结果 vs 预期)。
    3. 从 tools/coords_report.csv 筛选出现频率高的文件/行,给出重构建议(提取到 path_config 或使用缩放函数)。
  • 示例 LLM 提示模板(短):

"给定 traceId:XYZ,请从 logs/unified_*.log 中提取错误堆栈,定位触发点对应的源码文件与行数,并生成 3 条可能的修复建议(每条含修改位置与简要代码片段)。"

  • 采集数据权限与安全:自动化助手读取日志与截图即可完成大部分分析;若需要访问远程设备或私有数据,请确保遵守隐私与访问控制策略,避免将敏感截图提交到远端模型。

此节旨在让 AI 快速找到“能运行的代码路径”与“可用于证据收集的文件”,从而降低人工解释成本并提高定位效率。

完成以上更新后,可考虑把常用查询脚本(例如从日志到截图的映射器)加入 tools/ 以便自动执行。

  1. 参考实现与文件链接
  • 截图与裁剪:underlying_operations.get_screenshot()、underlying_operations.cut_pic()。
  • OCR:underlying_operations.analyse_pic_word()、underlying_operations.analyse_pic_digits()。
  • 日志:douyin/logging/douyin_logging.py、douyin/logging/douyin_logging_wrapper.py。
  • 路径与状态:douyin/core/path_config.py、state/reservations.json。

以上补充将帮助运维快速定位截图/OCR/日志相关问题并提供明确采样路径供后续模型/规则优化使用。

核心模块地图(快捷索引)

  • bin/run_cli.py:入口,解析命令行并创建 fudai_analyse。

  • douyin/core/douyin_fudai.py:主分析器/主循环(fudai_choujiang、run_once_basic)。

  • douyin/core/underlying_operations.py:底层设备/截图/OCR/文件操作。

  • douyin/detection/douyin_pixel.py:像素检测与并行检测实现。

  • douyin/fudai/douyin_fudai_core.py:福袋核心逻辑。

    • get_fudai_contain:获取福袋的内容和倒计时(从 fudai_analyse.get_fudai_contain 抽离)。调用位置:douyin/fudai/core/fudai_attend.py、douyin/fudai/core/fudai_detail_orchestrator.py(旧位置:fudai_detail_modules/fudai_detail_reader.py,已合并到 core/)。具体行号会随重构变化,以代码当前状态为准。
    • basic_join_decision:基础版参与决策,根据配置筛选福袋,满足条件则尝试参与抽奖或记录高价值预约。调用位置:douyin/core/douyin_fudai.py 第3127行和第3721行。
    • attend_choujiang:点击参与抽奖。调用位置:douyin/core/douyin_fudai.py 第2892行,douyin/core/fudai_modules/fudai_main_logic.py 第223行,以及文件内多处。
    • check_lucky_draw_result:判定福袋抽奖的结果(简化)。统一只检测开奖结果按钮区域(使用 HelperFunctions.check_lottery_result_by_ocr),不再对弹窗文字或其它区域进行OCR识别。返回:1='我知道了', 2='立即领取奖品', False=未识别。调用位置:文件内第3913行。
    • check_have_reward_notice_confirm:判断是否有领奖的二次确认提醒。调用位置:文件内第3937行。
    • get_reward:中奖后领奖然后返回。调用位置:无外部调用。
  • douyin/utils/douyin_utils.py:通用工具函数。

    • normalize_countdown_text:对福袋倒计时类 OCR 文本做标准化,抽离自 douyin_fudai.py,方便复用与单元测试。调用位置:douyin/utils/douyin_text_utils.py 第12行和第56行。
    • extract_prize_value_yuan:从 OCR 文本中抽取奖品价值金额(元),抽离自 douyin_fudai.py。调用位置:douyin/fudai/core/fudai_detail_reader.py 第16行和第1174行,douyin/fudai/douyin_fudai_core.py 第11行和第1965行,douyin/utils/douyin_text_utils.py 第12行和第65行。
  • douyin/stage/douyin_stage.py:阶段诊断逻辑。

    • diagnose_stage_from_current_screen:完整抽離自 douyin_fudai.fudai_analyse._diagnose_stage_from_current_screen。日志輸出已從 print 改為 _log_kv,方便結構化查看。当前模式:优先使用像素检测,OCR检测已暂时关闭用于测试像素检测精准度。注意:此函数复杂度较高,包含多个检测步骤和条件分支,这是设计上的权衡。调用位置:douyin/core/douyin_flow_control.py 第393行,douyin/reservation/douyin_reservation_logic.py 第812行和第846行,douyin/stage/douyin_stage_handler.py 第44行。

最近修改要点(2026-01-18):

  • douyin/fudai/core/fudai_attend.py:修复并行OCR重试导致的无限重试日志,增加重试计数 click_times 及短延时。

  • douyin/core/douyin_fudai.py:在 _handle_in_fudai_detail 中增加连续参与失败阈值逻辑,超过阈值可关闭详情并切换直播间(若 needswitch 为 True)。

  • douyin/stage/douyin_stage.py:购物红包像素命中时新增 OCR 复查(步骤2.5),即使不在直播间也强制 OCR 进行二次确认。

  • douyin/detection/douyin_pixel.py:detect_redpacket_popup_background 支持可配置阈值 red_ratio_threshold(默认0.15),并由配置项读取。

  • gui/gui_app.py:映射表 UI 改进(可扩展/自动列宽)并新增 购物红包背景红色占比阈值 的 GUI 控件,配置键 shopping_redpacket_red_ratio_threshold (默认 0.15)。

  • douyin/fudai/douyin_fudai_core.py:并行OCR完成后写盘映射表(调用 _dump_room_pos_map_to_state)。

  • douyin/reservation/douyin_reservation_logic.py & douyin/reservation/douyin_reservation_handler.py:在映射表定位失败时记录 _seek_direction_hint 并在二次回退时执行纠偏滑动以修正定位偏差。

  • douyin/handlers/douyin_swipe_handler.py:删除对 has_fudai 的早期返回,允许在有福袋信息时继续上滑以切换直播间。

  • douyin/stage/douyin_stage.py:阶段诊断入口(diagnose_stage_from_current_screen)。

  • douyin/reservation/douyin_reservation_logic.py:预约加载与回退处理。

  • douyin/core/path_config.py:统一路径获取,避免硬编码。

在文档中引用这些文件并包含小示例会帮助维护者快速定位实现点。

GUI — 映射表组件(gui/components/mapping_table.py)

概述:该组件在 GUI 中以标签页形式展示运行时的房间-位置映射(来源 douyin/core/state/room_pos_map.json),供人工核验与调试。

  • 入口函数:create_mapping_tab(root: tk.Tk, notebook: ttk.Notebook, cfg: dict) -> ttk.Frame

    • 调用位置:gui/gui_app.py 在创建 Notebook 页时直接 import 并挂载(参见 create_mapping_tab(...) 的使用)。
  • 数据源:优先读取项目根下或 douyin/core/state/room_pos_map.json;若不存在会尝试 douyin/state/room_pos_map.json 与若干备份路径;同时读取 reservations.json 以标记已预约项。

  • 显示与交互要点:

    • 使用 Canvas + 内嵌 inner_frame 的卡片式布局渲染每条记录;每个字段独占一行(标题/原始标题/更新时间/已预约/有福袋/价值/参与人数/份数/倒计时/按钮/任务列表/福袋内容),满足“每一个内容换一行”的需求。
    • 为了更合理使用横向空间,组件根据 canvas 宽度自动计算列数(默认最多 3 列),并把卡片以 grid 网格方式分列显示;每列计算独立的 wraplength 以保证文字在列内换行。
    • 控件:自动刷新开关(默认 5s)、手动刷新按钮、显示原始标题开关、搜索框 + 回车触发、清除按钮、复制选中条目按钮与状态提示。
    • 鼠标交互:卡片支持单击选中(高亮)、双击弹出详情窗口、键入搜索过滤;Canvas 区域绑定鼠标滚轮(enter/leave 动态绑定),支持 Windows/macOS/Linux 的滚轮和 X11 Button-4/5。
  • 样式与可配置点:

    • 字体:基础为等宽字体(Consolas),当前实现较紧凑的尺寸(base 10 / title 12 / meta 9 / body 10),可在组件内部调整。
    • 颜色/间距:卡片背景、hover 背景与选中背景有明确区分;卡片间距与分隔线已调整为更紧凑的视觉。
  • 实现细节(注意点):

    • 组件会在刷新前保存当前的 canvas.yview(),刷新完后尝试恢复到之前位置,避免刷新回到顶部的问题。
    • 旧实现中曾使用 Text 区索引定位(mapping_text),当前实现已移除该依赖,事件均基于卡片索引与 last_selected_entry 管理。若你在调试中看到与 mapping_text 相关的 trace,请清理缓存/重启 GUI。
    • 为避免过窄列导致被挤在一起,组件提供“显示原始标题”开关,开启后会增加行数但释放列宽以避免截断。
  • 调试 / 验证步骤:

    1. 在项目根运行 GUI:
      python gui\gui_app.py
      
    2. 打开“运行时映射表”页,验证:每字段是否独占一行、卡片列数是否随窗口宽度变化、滚动条与滚轮是否正常、双击详情与复制按钮是否工作。
    3. 若需要查看源文件:douyin/core/state/room_pos_map.json(包含 timestamp 字段,可用于同步更新时间)。
  • 已知限制与后续优化:

    • 当前列数上限为 3(实现中可调),在极宽窗口下可以适当增加列数或使用自适应列宽策略;
    • 卡片圆角/阴影等更高级视觉需要额外绘制或使用第三方皮肤(如 ttkbootstrap),可作为后续优化项;
    • UI 国际化与主题适配(浅色/深色)尚未全面支持,建议在统一主题体系下再做统一调整。

运行流程概览(精简)

  1. bin/run_cli.py -> 创建 fudai_analyse -> load_config() -> fudai_choujiang()
  2. fudai_choujiang() 循环调用 run_once_basic()
  3. run_once_basic() 流程要点:
    • 处理等待开奖 / 预约回退
    • 获取截图(operation.get_screenshot())
    • 阶段诊断(像素/模板/OCR 回退)
    • 根据阶段执行(直播间查找福袋 / 详情页解析 / 结果处理)

故障排查与采样(可直接运行的命令)

  1. 验证截图是否可用:
python -c "from douyin.core.underlying_operations import underlying_operations; op=underlying_operations(); print(op.get_screenshot('<DEVICE_ID>'))"
  1. 快速语法检查(仓库级):
python -m py_compile $(git ls-files "**/*.py")
  1. 采集 OCR 失败样本(手动或自定义脚本):
# 伪命令示例:运行一段短时日志以产生调试图片
python bin/run_cli.py --device-id <ADB_ID> --wait-minutes 1
# 手动或团队自定义脚本筛选 pic/ 下的失败图片并复制到约定目录(例如 tools/samples/)

预约(state/reservations.json)行为说明

  • 预约持久化路径:state/reservations.json(通过 path_config.get_reservations_path() 获取)。
  • 启动策略(当前实现):
    • 第一次运行时清空内存预约并可清空文件(避免使用旧历史);后续运行使用内存队列并在变更时写回文件以便外部查看。
    • 文档中应明确“第一次运行语义”以免运维误解。

分辨率与坐标适配(基准与缩放)

  • 基准分辨率:1080x2400(所有坐标与ROI以此为基准)。
  • 缩放公式(示例): 若基准点为 (x0,y0),设备分辨率为 (W,H),则实际坐标 x = int(x0 * W / 1080),y = int(y0 * H / 2400)。

建议:在文档中加入 2 个常用坐标示例与验证截图(放置于 docs/images/)。

验证清单(可纳入 CI)

  1. python -m py_compile 全仓库通过。
  2. 关键路径存在检查:bin/run_cli.py、douyin/core/underlying_operations.py、config/config.json、douyin/core/path_config.py。
  3. path_config.get_reservations_path() 返回文件夹存在性检查。

示例 CI 命令片段:

python -m py_compile $(git ls-files "**/*.py") || exit 1
python - <<'PY'
from douyin.core.path_config import get_reservations_path
import os
print('reservations path', get_reservations_path())
assert os.path.isdir(os.path.dirname(get_reservations_path()))
PY

FAQ(快速)

  • Q: 如何跳过 OCR 初始化以加速冷启动?
    • A: 设置环境变量 SKIP_OCR_INIT=1。
  • Q: 截图镜像到外部目录导致性能问题怎么办?
    • A: 设置 DISABLE_SCREENSHOT_MIRROR=1。
  • Q: 日志在哪查看?
    • A: 参见 douyin/logging/douyin_logging.py 配置的 file_path(默认 logs/unified.log)。

下一步建议(可选交付)

  1. 在 docs/images/ 添加 2 个运行时截图(基准 1080x2400),用于快速视觉检查。
  2. 将“硬编码坐标扫描”脚本放入 tools/ 并在 CI 中运行,生成 tools/coords_report.csv。 如果你确认,我会:
  3. 将本文的验证清单脚本加入 .github/workflows/(可选)。

映射表(Runtime room_pos_map)

  • 目的:在运行期间维护“房间位置 -> 标题”映射,供 GUI 展示、预约回退与高价值房间匹配使用。
  • 导出文件:douyin/core/state/room_pos_map.json(主)、room_pos_map.csv、room_pos_map.md(供人工查看)。
  • 文件格式:JSON 包含字段 _meta(生成时间 generated_ts、版本信息等)以及键值对 "<pos>": {"title":"...","title_raw":"..."}。导出实现见 douyin/reservation/douyin_reservation_handler.py。
  • 生命周期:每次启动实例会删除先前导出的文件(确保“仅本次运行”语义);运行中会按需写入临时文件再原子替换,避免部分写入导致 GUI 读取异常。
  • 行为影响:外部工具或 GUI 只能看到当前运行生成的数据;若需要保留历史请手动备份或修改导出路径。

实现细节(映射导出与结构)

  • 导出实现:函数 _dump_room_pos_map_to_state(analyser) 位于 douyin/reservation/douyin_reservation_handler.py,会把 analyser._room_pos_to_title_map 过滤后序列化为 JSON,并同时导出 CSV 与 Markdown 供人工查看。JSON 写入采用先写入 .tmp 再用 os.replace/os.rename 原子替换的策略。

V4.4 更新:在并行 OCR 完成后(并行 OCR 线程池完成映射收集时),系统会立即调用 _dump_room_pos_map_to_state 将最新映射写盘(见 douyin/fudai/douyin_fudai_core.py 中的触发点),以确保预约回退/定位逻辑能及时使用最新映射数据,减少校验失败导致的误回退。

  • JSON 结构示例:

    { "0": ["房间标题 A", "房间标题原文A"], "1": ["房间标题 B", ""], "_meta": {"source":".../douyin/core/state/room_pos_map.json","generated_ts":1670000000,"run_id":"20260107123456"} }

  • 导出规则:只保留非空条目(title 或 title_raw 非空),_meta 仅写入 JSON(CSV/MD 不包含 _meta)。CSV 第一行为 pos,title,title_raw,Markdown 为简单表格带顶部注释 <!-- source: ... -->。

  • 查找/写入时机:ReservationHandler.record_room_title_and_pos() 在首次进入/切换直播间后会调用,只有在 record_room_title_mapping_enabled 为 True 时才执行,写入发生于首次记录或标题变更时。

  • 页面位置:映射表由 gui/gui_app.py 提供(TreeView),从导出文件读取并呈现(优先读取 JSON,然后 CSV/MD 作为回退)。GUI 已更新为允许映射表垂直扩展(fill=BOTH, expand=True)并在窗口大小变化或刷新后自动调整列宽以适配内容,改善可读性。

  • UI 元素:列 位置 / 标题 / 原始标题;支持 手动刷新 按钮与 2s 自动刷新(可在 GUI 中关闭)。

  • 异常场景:首次运行或导出尚未生成时,GUI 显示“未找到 room_pos_map.json”;建议使用手动刷新或等待自动刷新完成。

  • 兼容说明:GUI 读取的是磁盘导出,因此在高并发写入与读取场景下可能会短暂看到旧数据或空表,导出采用 tmp->replace 的写法以降低此类问题。

阶段诊断去重与跳过逻辑

  • 目标:避免在打开福袋详情后对同一详情重复执行阶段诊断(减少截图/OCR/ADB 调用),仅保留打开详情时的一次诊断作为可信来源。
  • 触发与跳过:点击“参与”或进入某些快速路径时,代码会设置 analyser._skip_stage_diagnosis_and_find_fudai = True,下一个循环会跳过阶段诊断并直接查找福袋。相关实现见 douyin/fudai/core/fudai_attend.py 与 douyin/core/douyin_fudai.py。
  • 实现要点:首个打开详情时应调用一次 shot_and_diagnose / _diagnose_stage_from_current_screen() 并将结果缓存(写入 analyser._last_diag_*),随后在恢复/回退分支中使用缓存结果而不是重新诊断。文档应说明哪些分支会主动跳过诊断以及失败回退策略(例如第一次诊断失败时会尝试重新诊断)。
  • 可回归问题:在少数路径上此前的快速修补可能留下了 try/except 或异常处理的结构问题,见“已知问题”节。

实现细节(阶段诊断缓存与跳过标志)

  • 缓存字段:fudai_analyse 实例维护 ._last_diag_stage、._last_diag_seen、._last_diag_ts 三个字段,首次截图+诊断后由 _diagnose_stage_from_current_screen() 或 shot_and_diagnose() 更新。代码位置:douyin/core/douyin_fudai.py 初始化与多处调用。
  • 跳过标志:点击“参与”路径在 douyin/fudai/core/fudai_attend.py 会设置 analyser._skip_stage_diagnosis_and_find_fudai = True,表示下一次主循环应跳过阶段诊断并直接执行“查找/参与福袋”的快速路径。该标志用于减少在详情页关闭时的重复截图/诊断。
  • 使用语义:当 _skip_stage_diagnosis_and_find_fudai 为 True 时,主循环或相关恢复函数会直接使用缓存的 ._last_diag_*(若可用)或直接进入福袋查找流程;若缓存不可用或首次诊断失败,代码会回退为正常的截屏+诊断流程。
  • 诊断节流/缓存:项目在多个诊断/检测模块使用短时缓存以减少重复计算,例如 douyin/detection/douyin_detection.py 使用 _detection_cache_ttl(默认 2.0 秒)来节流像素/模板检测;统一日志格式化器 unified_logger.UnifiedFormatter 对 MDC 查询使用 _mdc_cache_ttl(默认 0.1 秒)以减少频繁 MDC 访问。在文档中应标注这些默认值并提示可通过实例属性修改。

查找匹配算法(映射匹配逻辑)

  • 在 ReservationHandler.find_room_pos_by_title() 中实现匹配:
    • 先对目标标题与映射中标题做规范化(尝试调用 douyin.other.douyin_high_value_room._normalize_room_title(),失败则做 strip())。
    • 匹配规则优先级:完全相等 -> 子串匹配(得分 0.8) -> difflib 相似度(ratio)。
    • 接受阈值:只有 match_score >= 0.6 的候选才会被考虑为匹配;完全相等得分为 1.0。
    • 成功匹配后会通过 analyser._log_kv() 写入 found_pos 与 match_score 供排障使用。

快速排障示例(映射与诊断)

  • 检查映射文件是否存在与内容:
Get-Content douyin\core\state\room_pos_map.json -Raw | ConvertFrom-Json
  • 日志中查看匹配信息(示例行):

    [2026-01-15 12:00:00] [INFO] 预约 - [预约] _find_room_pos_by_title:在映射表中找到匹配位置 found_pos=3 match_score=0.812

  • 若诊断跳过导致问题,可强制重新诊断的最小操作:在运行时清理 analyser._skip_stage_diagnosis_and_find_fudai 或重启实例以清除运行缓存(详见已知问题节)。

滑动 / 导航 与 映射记录

  • 触发点:上滑/下滑切换直播间、重置/回退后、手动跳转后会调用记录函数将当前房间标题与位置写入运行时映射(实现见 douyin/handlers/douyin_swipe_handler.py 与 analyser._record_room_title_and_pos())。
  • 位置计数语义:位置为当前在播放列表中的索引(上滑为+1,下滑为-1),重置时归零。文档需说明如何将索引映射到实际 UI 行为。
  • 行为影响:滑动/导航记录确保在预约回退时更高的匹配准确度;若记录被跳过或失败会影响回退命中率,应在排障步骤中检查导出文件与日志。

已知问题与 TODO

  • douyin/fudai/core/fudai_attend.py:最近为避免重复诊断做了多处修改,文件中仍存在需要人工复核的 try/except 嵌套与缩进问题,请在合并/部署前检查语法与异常覆盖范围。
  • TTL 缓存:对 _diagnose_stage_from_current_screen() 周边加入了短 TTL(用于性能缓解),为临时措施;文档应标注该缓存为可调整参数并记录默认值与位置。
  • 调试日志路径:某些调试写入(get_debug_log_path())采用 append 模式,可能需要定期轮转/清理;建议文档列出路径并给出清理建议。
  • 诊断跳过边界:在点击参与后直接跳过诊断的逻辑在极端失败情况下可能导致使用过期或缺失的诊断结果,文档应列出故障排查步骤(强制触发重新诊断的方法)。

如果你确认,我会:

  1. 备份当前文档为 docs/完整技术文档.md.bak(可选)
  2. 将以上内容写入 docs/完整技术文档.md
  3. 更新任务清单(TODO)并开始下一项(补充快速开始示例截图与 coords 扫描脚本)。
run_once_basic(recursion_depth=0)
  ↓
  [检查1] 预约回退处理(直接参与标志已移除)
  └─> 如需回退则在回退流程中直接处理参与逻辑(不再使用 `_reservation_back_direct_attend` 或 `_force_attend_after_reservation_back` 标志)
  ↓
  [检查2] 等待开奖状态 (_waiting_for_lottery_result)
    ├─> 是 → 检查开奖结果 → return
    └─> 否 → 继续
    ↓
[检查3] 30分钟超时检查
    ├─> 超时 → _return_to_recommend_and_reenter_live() → return
    └─> 未超时 → 继续
    ↓
[步骤1] 加载预约数据
    └─> douyin_reservation_logic.load_reservations_from_state(analyser)
        └─> 读取 state/reservations.json
        └─> 更新 analyser.reservations
    ↓
[步骤2] 处理预约回退窗口
    └─> douyin_reservation_logic.process_reservation_attend_window(analyser, ...)
        ├─> 检查距离开奖时间
        ├─> 如果 ≤ high_value_fudai_join_ahead_seconds
        │   ├─> 触发回退 → _seek_reservation_room() → swipe_down_back_from_live() → return
        └─> 未触发 → 继续
    ↓
[步骤3] 获取截图
    └─> analyser.operation.get_screenshot(device_id)
        └─> ADB命令: adb -s {device_id} exec-out screencap -p
        └─> 保存到 pic/screenshot.png
    ↓
[步骤4] 阶段诊断
    └─> diagnose_stage_from_current_screen(analyser)
        ├─> 步骤0: 检测直播间(优先级最高)
        │   ├─> _check_in_live_room_by_pixel() - 像素检测
        │   ├─> _check_in_live_room_by_icon() - 模板匹配
        │   └─> _check_in_live_room_by_ocr() - OCR回退
        ├─> 步骤1: 并行像素检测
        │   └─> read_pixel_stage_state_from_screenshot()
        │       ├─> detect_shopping_redpacket_background()
        │       ├─> detect_coupon_background()
        │       ├─> detect_attend_button_red_area()
        │       ├─> detect_fansclub_join_red_area()
        │       ├─> detect_fudai_detail_page()
        │       └─> detect_lucky_draw_result_popup()
        └─> 返回阶段结果 (IN_LIVE_ROOM, FUDai_DETAIL, FUDai_RESULT, 等)
    ↓
[步骤5] 根据阶段执行逻辑
    ├─> IN_LIVE_ROOM → _handle_live_room_has_or_not_fudai()
    ├─> FUDai_DETAIL → _handle_in_fudai_detail()
    ├─> FUDai_RESULT → _handle_lottery_result()
    ├─> COUPON_POPUP → _check_coupon_popup() → 关闭弹窗
    ├─> SHOPPING_REDPACKET_POPUP → _check_shopping_redpacket_popup() → 关闭弹窗
    └─> 其他 → 导航到直播间

关键函数说明:

  • run_once_basic(): 单次循环的核心函数,包含所有检查和处理逻辑
  • diagnose_stage_from_current_screen(): 综合诊断当前页面阶段
  • process_reservation_attend_window(): 处理预约回退窗口

3.3 直播间处理流程 (_handle_live_room_has_or_not_fudai)

_handle_live_room_has_or_not_fudai()
    ↓
find_and_open_fudai_detail(analyser, room_pos_ref)
    ├─> analyser.operation.get_screenshot(device_id)
    ├─> 查找福袋图标
    │   ├─> 像素检测 (优先)
    │   │   └─> detect_fudai_icon_by_pixel()
    │   └─> 模板匹配 (可选,如果启用 fudai_template_match_enabled)
    │       └─> template_match_fudai_icon()
    ├─> 如果找到福袋图标
    │   ├─> analyser.operation.click(device_id, x, y)
    │   └─> 智能等待详情页打开
    │       ├─> 最小等待 (fudai_detail_initial_wait_seconds, 默认0.8秒)
    │       ├─> 循环检测详情页是否打开
    │       │   ├─> diagnose_stage_from_current_screen(analyser)
    │       │   └─> 如果检测到 FUDai_DETAIL → 成功
    │       └─> 最大等待 (fudai_click_wait_seconds, 默认1.7秒)
    └─> 如果未找到福袋图标
        └─> 返回 False
    ↓
[结果判断]
    ├─> 成功打开 → _handle_in_fudai_detail()
    └─> 未找到福袋 → handle_no_fudai_situation(analyser, ...)
        ├─> process_reservation_attend_window(analyser, ...)
        │   └─> 如果触发预约回退 → return True
        └─> 如果未触发预约回退,且 needswitch=true
            └─> swipe_up_to_next_live()
                └─> analyser.operation.swipe(device_id, x1, y1, x2, y2, duration_ms)
                └─> _swipe_times += 1
                └─> _maybe_reset_after_swipes() [检查是否需要重置]

关键函数说明:

  • find_and_open_fudai_detail(): 查找并打开福袋详情页
  • handle_no_fudai_situation(): 处理未找到福袋的情况(预约回退或切换直播间)

3.4 福袋详情处理流程 (_handle_in_fudai_detail)

_handle_in_fudai_detail()
    ↓
[步骤1] 读取福袋信息
    └─> get_fudai_contain(analyser, renwu=2)
        ├─> 并行OCR (ThreadPoolExecutor, 6个线程)
        │   ├─> ocr_task_list() - 任务列表 OCR
        │   │   └─> 识别区域: (200, 600, 880, 900)
        │   ├─> ocr_content() - 福袋内容 OCR
        │   │   └─> 识别区域: (200, 600, 880, 900)
        │   ├─> ocr_countdown_mm() - 倒计时分钟 OCR
        │   │   └─> 识别区域: (390, 1140, 480, 1290)
        │   ├─> ocr_countdown_ss() - 倒计时秒 OCR
        │   │   └─> 识别区域: (480, 1140, 570, 1290)
        │   ├─> ocr_value() - 价值 OCR
        │   │   └─> 识别区域: (200, 1400, 880, 1600)
        │   └─> ocr_button() - 按钮状态 OCR
        │       └─> 识别区域: (306, 2030, 780, 2110)
        │       └─> 存储到 analyser._fudai_button_status, analyser._fudai_button_text
        │       └─> 记录识别时间 analyser._fudai_button_ocr_time
        ├─> 解析倒计时 (normalize_countdown_text)
        │   └─> 如果整体识别失败,使用分割识别结果 (mm + ss)
        ├─> 解析价值 (extract_prize_value_yuan)
        │   └─> 从OCR文本中提取数字(元)
        └─> 解析参与人数
            └─> 从任务列表OCR结果中提取
        ↓
        返回: (content, countdown_text, participants, task_count, prize_value_yuan)
    ↓
[步骤2] 数据验证
    └─> fudai_detail_validator.validate_fudai_detail(analyser, detail)
        ├─> 验证倒计时格式
        ├─> 验证价值范围
        └─> 验证参与人数
    ↓
[步骤3] 筛选判断
    └─> basic_join_decision(analyser, detail)
        ├─> 价值筛选: prize_value_yuan >= min_prize_value_yuan
        ├─> 参与人数筛选: min_participants <= participants <= max_participants
        ├─> 倒计时筛选: countdown >= skip_if_countdown_lt_seconds
        ├─> 关键词筛选:
        │   ├─> contains_want: 必须包含的关键词(任意一个匹配即可)
        │   └─> contains_not_want: 不能包含的关键词(任意一个匹配即跳过)
        └─> 高价值预约:
            └─> 如果价值 ≥ high_value_fudai_threshold_yuan
                └─> 记录到 state/reservations.json
                └─> 包含: room_title, lottery_time_ts, prize_value_yuan, fudai_x
    ↓
[步骤4] 根据筛选结果
    ├─> 通过筛选 → attend_choujiang(analyser)
    │   ├─> 识别按钮状态
    │   │   ├─> 优先使用并行OCR结果(5秒内有效)
    │   │   │   ├─> 检查 analyser._fudai_button_text 和 analyser._fudai_button_status
    │   │   │   └─> 检查 analyser._fudai_button_ocr_time 是否在5秒内
    │   │   └─> 如果不可用,重新识别按钮
    │   │       ├─> 裁剪按钮区域 (analyser.cut_pic)
    │   │       ├─> 图像预处理 (preprocess_for_ocr)
    │   │       └─> OCR识别(模式0和模式1)
    │   ├─> 根据按钮状态执行操作:
    │   │   ├─> "已参与" → 设置 _waiting_for_lottery_result = True
    │   │   │   └─> 计算 _lottery_result_expected_ts = 当前时间 + 倒计时秒数
    │   │   │   └─> 更新 _last_successful_attend_ts = 当前时间
    │   │   ├─> "需要加入粉丝团" → 加入粉丝团
    │   │   │   └─> 点击粉丝团加入按钮
    │   │   │   └─> 如果失败且 fansclub_fail_action="switch" → 切换直播间
    │   │   ├─> "需要评论" → 发送评论
    │   │   │   └─> 点击评论输入框
    │   │   │   └─> 输入评论内容(使用ADB键盘)
    │   │   │   └─> 点击发送按钮
    │   │   └─> "可以参与" → 点击参与按钮
    │   │       └─> analyser.operation.click(device_id, x, y)
    │   │       └─> 更新 _last_successful_attend_ts = 当前时间
    │   └─> 最多重试2次
    └─> 未通过筛选 → 关闭详情页 → 切换直播间 (如果 needswitch=true)
        └─> 点击返回按钮
        └─> swipe_up_to_next_live()

关键函数说明:

  • get_fudai_contain(): 并行OCR获取福袋完整信息
  • basic_join_decision(): 根据配置筛选福袋
  • attend_choujiang(): 点击参与抽奖,处理各种前置条件

4. 关键函数详细说明

4.1 入口函数

run_cli.py::main(argv: list[str]) -> int

  • 文件位置: bin/run_cli.py
  • 作用: 命令行入口函数,解析参数并启动主程序
  • 参数:
    • argv: 命令行参数列表
  • 返回值: 退出码 (0=成功, 其他=失败)
  • 调用位置: 命令行直接调用(if __name__ == "__main__")
  • 主要逻辑:
    1. 确保ADB在PATH中 (ensure_adb_in_path())
    2. 解析命令行参数 (parse_args(argv))
    3. 配置输出编码(UTF-8,实时刷新)
    4. 创建 fudai_analyse 对象
    5. 设置配置覆盖(从命令行参数)
    6. 调用 fudai_choujiang() 启动主循环

代码示例:

def main(argv: list[str]) -> int:
    ensure_adb_in_path()
    args = parse_args(argv)
    
    # 配置输出编码
    sys.stdout.reconfigure(encoding="utf-8", line_buffering=True)
    
    analyser = fudai_analyse()
    
    # 从命令行参数设置配置
    if args.device_id:
        analyser.device_id = args.device_id
    if args.needswitch is not None:
        analyser.needswitch = args.needswitch
    
    # 启动主循环
    analyser.fudai_choujiang(
        device_id=args.device_id or "",
        y_pianyi=int(args.y_pianyi or 0),
        needswitch=args.needswitch,
        wait_minutes=int(args.wait_minutes or 0)
    )
    
    return 0

fudai_analyse.fudai_choujiang(device_id, y_pianyi, needswitch, wait_minutes)

  • 文件位置: douyin/core/fudai_modules/fudai_main_logic.py (MainLogicMixin)
  • 作用: 主循环入口,初始化并启动无限循环
  • 参数:
    • device_id: str: 设备ID(如果为空,会自动选择设备)
    • y_pianyi: int: Y轴偏移,用于调整点击坐标
    • needswitch: bool: 是否允许切换直播间
    • wait_minutes: int: 运行时长(分钟,0表示无限)
  • 返回值: None
  • 调用位置: run_cli.py::main(), GUI启动
  • 主要逻辑:
    1. 设置设备ID和分辨率
      • 如果 device_id 为空,调用 operation.select_device() 选择设备
      • 获取设备分辨率 (operation.get_device_resolution())
    2. 加载配置 (load_config())
      • 从 config/config.json 读取配置
      • 更新 self.needswitch 等属性
    3. 初始化运行状态
      • 设置 _run_start_ts = time.time()
      • 初始化 _last_successful_attend_ts
    4. 进入无限循环调用 run_once_basic()
      • 如果 wait_minutes > 0,检查运行时间是否超过限制
      • 每次循环后延迟0.1秒(避免CPU占用过高)

代码示例:

def fudai_choujiang(self, device_id: str = "", y_pianyi: int = 0, 
                    needswitch: bool = False, wait_minutes: int = 15) -> None:
    # 设置设备ID
    if not device_id:
        device_id = self.operation.select_device()
    self.device_id = device_id
    
    # 设置Y偏移和分辨率
    self.y_pianyi = y_pianyi
    self.resolution_ratio_x, self.resolution_ratio_y = \
        self.operation.get_device_resolution(device_id)
    
    # 加载配置
    self.load_config()
    if needswitch is not None:
        self.needswitch = needswitch
    
    # 初始化运行状态
    self._run_start_ts = time.time()
    self._last_successful_attend_ts = self._run_start_ts
    
    # 进入无限循环
    while True:
        if wait_minutes > 0:
            if time.time() - self._run_start_ts > wait_minutes * 60:
                break
        
        self.run_once_basic()
        time.sleep(0.1)

4.2 主循环函数

fudai_analyse.run_once_basic(recursion_depth: int = 0) -> None

  • 文件位置: douyin/core/douyin_fudai.py(实际实现位置)

  • 作用: 单次循环执行,包含所有核心逻辑

  • 参数: 无(recursion_depth 参数已移除)

  • 返回值: None

  • 调用位置: fudai_choujiang() 循环调用

  • 主要逻辑(按执行顺序):

    0. 检查等待开奖状态 (_waiting_for_lottery_result)

    • 如果为 True,执行以下逻辑:
      1. 等待开奖时间检查:
        • 计算剩余秒数:remain_seconds = max(0, future_ts - current_ts + 6.0)(加上6秒延迟修正)
        • 开奖检测开始时间:check_start_ts = future_ts + 1.0(开奖时间+1秒缓冲)
        • 超时时间:timeout_ts = future_ts + 10.0(超过开奖时间10秒清除等待标志)
      2. 超时处理:
        • 如果 current_ts >= timeout_ts,清除等待标志,继续执行其他操作
      3. 开奖结果检测:
        • 如果 current_ts >= check_start_ts,开始检测开奖结果:
          • 直接点击模式: 直接点击"我知道了"按钮(坐标532, 1322,最多点击10次,每次间隔1秒)
          • 每次点击后通过阶段诊断检查是否还在开奖结果弹窗(FUDai_RESULT)
          • 如果弹窗已关闭,停止点击
          • 如果直接点击失败,回退到OCR识别方式
          • 如果OCR识别到结果,调用 _handle_lottery_result_by_ocr() 处理
          • 清除等待标志,切换直播间(如果允许)
      4. 等待中:
        • 如果还未到开奖时间,短暂等待(min(2.0, remain_seconds))后返回

    0.1. 检查30分钟超时 (_no_attend_timeout_minutes)

    • 如果距离 _last_successful_attend_ts 超过 _no_attend_timeout_minutes 分钟(默认30分钟):
      • 调用 _return_to_recommend_and_reenter_live() 返回推荐页面并重新进入直播间
      • 重置最后成功参与时间(避免立即再次触发)
      • 返回,不执行后续逻辑
    • 如果从未成功参与过,检查运行时间:
      • 如果运行时间超过30分钟,同样触发超时处理

    0.2. 处理预约回退窗口(如果启用高价值预约)

    1. 第一次运行处理:
      • 如果是第一次运行(_first_run_once_basic = True),清空预约队列,不加载状态文件
      • 同时清空状态文件,确保外部查看时也是空的
      • 标记已运行过(_first_run_once_basic = False)
    2. 预约回退检查:
    • 如果启用高价值预约且预约队列不为空,调用 process_reservation_attend_window() 检查是否需要回退
    • 如果触发回退,回退流程会决定是否立即参与(不再设置运行时标志 _reservation_back_direct_attend)

    1. 预约回退处理(直接参与标志已移除) - 如果回退流程决定立即参与,会在回退内部直接处理参与逻辑并返回;否则按常规流程继续

    2. 获取截图并执行阶段诊断

    • 调用 operation.get_screenshot() 获取截图
    • 调用 _diagnose_stage_from_current_screen() 执行阶段诊断
    • 根据诊断结果执行相应的处理逻辑

    3. 根据阶段执行相应逻辑

    • FUDai_DETAIL: 调用 _handle_in_fudai_detail() 处理福袋详情
    • LIVE_ROOM: 调用 _handle_live_room_has_or_not_fudai() 处理直播间
    • FUDai_RESULT: 调用 _handle_lottery_result() 处理开奖结果
    • 其他阶段:执行相应的处理逻辑(导航到直播间等)

    4. 桌面检测和自救机制(阶段诊断后)

    • 检测是否意外返回桌面(不在抖音前台)
    • 如果检测到不在抖音前台,尝试恢复:
      • 点击桌面图标(坐标:desktop_icon_x, desktop_icon_y 或默认 153, 260)
      • 点击直播按钮(坐标:yanghao_fallback_live_x, yanghao_fallback_live_y)
      • 点击进入直播间(坐标:yanghao_fallback_enter_live_x, yanghao_fallback_enter_live_y,点击2次)
      • 自救完成后,递归调用 run_once_basic() 重新执行主流程

代码示例:

def run_once_basic(self) -> None:
    start_time = time.time()
    
    # 0. 检查等待开奖状态
    if getattr(self, "_waiting_for_lottery_result", False):
        # 等待开奖时间检查
            remain_seconds = max(0, future_ts - current_ts + 6.0)
            check_start_ts = future_ts + 1.0
            timeout_ts = future_ts + 10.0
            
            if current_ts >= timeout_ts:
                self._waiting_for_lottery_result = False
            elif current_ts >= check_start_ts:
                # 直接点击"我知道了"按钮或OCR识别
                # ...
            else:
                # 等待中
                wait_s = min(2.0, remain_seconds)
                self.operation.delay(wait_s)
                return
    
    # 0.1. 检查30分钟超时
    if self._last_successful_attend_ts > 0:
        elapsed_minutes = (time.time() - self._last_successful_attend_ts) / 60.0
        if elapsed_minutes >= self._no_attend_timeout_minutes:
            self._return_to_recommend_and_reenter_live()
            self._last_successful_attend_ts = time.time()
            return
    
    # 0.2. 处理预约回退窗口
    if is_first_run:
        # 清空预约队列和状态文件
        self.reservations = []
        write_reservations_state(...)
        self._first_run_once_basic = False
    
    if queue_full:
        # 回退到最早开奖的预约直播间等待
        handle_queue_full_wait_at_earliest(...)
        return
    
    if process_reservation_attend_window(...):
      # 回退触发:在回退逻辑中直接处理立即参与行为(已移除 `_reservation_back_direct_attend` 标志)
      # 例如:回退完成后会在回退流程中决定是否立即参与,并设置相应的锁定期/待处理状态
      pass
    
    # 1. 预约回退处理(直接参与标志已移除)
    # 如果回退流程决定需要立即参与,则在回退流程内部直接调用参与处理逻辑;
    # 否则按常规流程继续执行阶段诊断与详情处理。
    
    # 2. 检查跳过阶段诊断标志
    if self._skip_stage_diagnosis_and_find_fudai:
        self._skip_stage_diagnosis_and_find_fudai = False
        self._handle_live_room_has_or_not_fudai()
        return
    
    # 3. 获取截图并执行阶段诊断
    if not self.operation.get_screenshot(self.device_id):
        return
    
    stage, seen = self._diagnose_stage_from_current_screen()
    self._last_diag_stage = stage
    self._last_diag_seen = seen
    self._last_diag_ts = time.time()
    
    # 4. 桌面检测和自救机制
    top_pkg = self.operation.get_top_package(self.device_id)
    if top_pkg and not is_douyin_pkg(top_pkg):
        # 尝试恢复
        self.click(self.desktop_icon_x, self.desktop_icon_y)
        # ... 其他恢复操作
        self.run_once_basic()  # 递归调用
        return
    
    # 5. 根据阶段执行相应逻辑
    if stage == "FUDai_DETAIL":
        self._handle_in_fudai_detail()
    elif stage == "LIVE_ROOM":
        self._handle_live_room_has_or_not_fudai()
    elif stage == "FUDai_RESULT":
        self._handle_lottery_result()
    # ... 其他阶段处理

4.3 阶段诊断函数

douyin_stage.diagnose_stage_from_current_screen(analyser) -> Tuple[str, str]

  • 文件位置: douyin/stage/douyin_stage.py

  • 作用: 综合诊断当前页面阶段,使用多种检测方法确保准确性

  • 参数:

    • analyser: 分析器对象
  • 返回值: Tuple[str, str] - (阶段字符串, 识别结果描述)

    • IN_LIVE_ROOM: 直播间
    • FUDai_DETAIL: 福袋详情页
    • FUDai_RESULT: 抽奖结果页
    • RECOMMEND_PAGE: 推荐页
    • COUPON_POPUP: 优惠券弹窗
    • SHOPPING_REDPACKET_POPUP: 购物红包弹窗
    • 等其他阶段
  • 调用位置: run_once_basic() 中调用

  • 主要逻辑:

    1. 步骤0: 检测直播间(优先级最高)

      • 像素检测 (detect_live_room_icons_by_pixel)
        • 检测直播间特征像素(点赞、收藏、评论图标区域)
        • 返回置信度分数(0.0-1.0)
        • 如果置信度 ≥ live_room_match_threshold(默认0.8),判定为直播间
      • 模板匹配 (_check_in_live_room_by_icon)
        • 使用OpenCV模板匹配检测直播间图标
        • 匹配多个模板(assets/like.png, assets/fav.png, assets/xin.png等)
        • 如果匹配度 ≥ live_room_match_threshold,判定为直播间
      • OCR回退 (_check_in_live_room_by_ocr)
        • 如果前两种方法都失败,使用OCR识别直播间标题
        • 识别区域:屏幕顶部标题区域
        • 如果识别到直播间特征文字,判定为直播间
    2. 步骤1: 并行像素检测

      • 调用 read_pixel_stage_state_from_screenshot() 并行检测多个区域
      • 检测项目:
        • shopping_redpacket_background: 购物红包背景
        • coupon_background: 优惠券背景
        • attend_button_red_region: 参与按钮红色区域
        • fansclub_join_red_region: 粉丝团加入红色区域
        • fudai_detail_page: 福袋详情页
        • lottery_result_popup: 抽奖结果弹窗
    3. 综合判断返回阶段

      • 根据像素检测结果,按优先级判断阶段
      • 优先级:FUDai_RESULT > FUDai_DETAIL > COUPON_POPUP > SHOPPING_REDPACKET_POPUP > IN_LIVE_ROOM

注:如果像素检测命中购物红包背景且当前不在直播间,系统会执行额外的 OCR 复查(参见代码中的“步骤2.5[购物红包OCR复查]”),以核验文本关键字(如“购物红包”、“邀你抢”等)。该复查在像素命中但未判定为直播间时强制触发,用以降低像素误判导致的误操作。像素阈值可通过配置项 shopping_redpacket_red_ratio_threshold(默认 0.15)调整,并可在 GUI 的“像素检测阈值”中修改。

配置参数:

  • stage_diag_max_time: 最大诊断时间(秒,默认10.0)
  • stage_diag_max_step_time: 单步最大耗时(秒,默认2.0)
  • live_room_match_threshold: 直播间检测阈值(0.0-1.0,默认0.8)
  • stage_diag_verbose: 是否输出详细日志(bool,默认False)

代码示例:

def diagnose_stage_from_current_screen(analyser):
    # 步骤0: 检测直播间
    in_live_room, confidence = detect_live_room_icons_by_pixel(pic_rgb)
    if in_live_room and confidence >= pixel_threshold:
        return "IN_LIVE_ROOM", "直播间(像素检测)"
    
    # 如果像素检测失败,尝试模板匹配
    in_live_room, score = _check_in_live_room_by_icon(analyser)
    if in_live_room and score >= template_threshold:
        return "IN_LIVE_ROOM", f"直播间(模板匹配,分数={score})"
    
    # 步骤1: 并行像素检测
    pixel_state = read_pixel_stage_state_from_screenshot(...)
    
    # 综合判断
    if pixel_state["lottery_result_popup"]:
        return "FUDai_RESULT", "抽奖结果页"
    if pixel_state["fudai_detail_page"]:
        return "FUDai_DETAIL", "福袋详情页"
    # ... 其他判断

douyin_pixel.read_pixel_stage_state_from_screenshot(pic_path, ...) -> dict

  • 文件位置: douyin/detection/douyin_pixel.py
  • 作用: 并行像素检测,检测多个区域的特征,用于阶段诊断
  • 参数:
    • pic_path: str: 截图路径
    • resolution_ratio_x: int: 分辨率X(默认1080)
    • resolution_ratio_y: int: 分辨率Y(默认2400)
    • y_pianyi: int: Y轴偏移(默认0)
    • lucky_draw_red_ratio_threshold: float: 抽奖结果弹窗红色比例阈值(默认0.8)
    • fudai_template_threshold: float: 福袋模板匹配阈值(默认0.7)
    • return_details: bool: 是否返回详细信息(默认False)
    • analyser: Any: 分析器对象(可选)
  • 返回值: dict[str, bool] 或 tuple[dict[str, bool], dict[str, dict]](如果 return_details=True)
    • shopping_redpacket_background: bool: 购物红包背景
    • coupon_background: bool: 优惠券背景
    • attend_button_red_region: bool: 参与按钮红色区域
    • fansclub_join_red_region: bool: 粉丝团加入红色区域
    • fudai_detail_page: bool: 福袋详情页
    • lottery_result_popup: bool: 抽奖结果弹窗
  • 调用位置: diagnose_stage_from_current_screen() 中调用
  • 检测方法:
    • 在指定区域采样像素,统计符合特征的颜色比例
    • 使用 ThreadPoolExecutor 并行执行多个检测任务
    • 每个检测函数独立采样像素并计算比例

检测原理:

  1. 读取截图并转换为RGB格式
  2. 根据基准分辨率(1080x2400)和实际分辨率缩放坐标
  3. 在指定区域采样像素(通常每5像素采样一次)
  4. 统计符合特征颜色的像素比例
  5. 如果比例 ≥ 阈值,判定为检测到该特征

代码示例:

def read_pixel_stage_state_from_screenshot(
    pic_path: str,
    resolution_ratio_x: int = 1080,
    resolution_ratio_y: int = 2400,
    y_pianyi: int = 0,
    lucky_draw_red_ratio_threshold: float = 0.8,
    fudai_template_threshold: float = 0.7,
    return_details: bool = False,
    analyser: Any = None
) -> dict[str, bool]:
    pic_rgb = _safe_open_screenshot_rgb(pic_path)
    if pic_rgb is None:
        return {}
    
    # 并行执行多个检测任务
    with ThreadPoolExecutor(max_workers=6) as executor:
        future_shopping = executor.submit(
            detect_shopping_redpacket_background, pic_rgb, ...
        )
        future_coupon = executor.submit(
            detect_coupon_background, pic_rgb, ...
        )
        # ... 其他检测任务
        
        results = {
            "shopping_redpacket_background": future_shopping.result(),
            "coupon_background": future_coupon.result(),
            # ... 其他结果
        }
    
    return results

4.4 福袋查找函数

douyin_flow_control.find_and_open_fudai_detail(analyser, room_pos_ref) -> bool

  • 作用: 查找并打开福袋详情页

  • 参数:

    • analyser: Any: 分析器对象
    • room_pos_ref: List[int]: 直播间位置引用(列表,用于更新位置)
  • 返回值: bool - True=成功打开, False=未找到

  • 调用位置: _handle_live_room_has_or_not_fudai() 中调用

  • 主要逻辑:

    1. 检查等待开奖状态

      • 如果 _waiting_for_lottery_result = True,直接返回 False(避免重复打开)
    2. 获取截图

      • 调用 analyser.operation.get_screenshot(device_id) 获取最新截图
    3. 查找福袋图标

      • 像素检测(优先)
        • 调用 check_have_fudai_with_ready_screenshot() 检测福袋图标
        • 在配置的最大等待时间内重复检测(fudai_icon_max_wait_seconds,默认8.5秒)
        • 重试间隔:fudai_icon_retry_delay_seconds(默认0.1秒)
      • 模板匹配(可选)
        • 如果启用 fudai_template_match_enabled,使用OpenCV模板匹配
        • 匹配模板:assets/fudai.png
        • 匹配阈值:fudai_template_match_threshold(默认0.7)
    4. 点击福袋图标

      • 如果找到福袋图标,调用 analyser.operation.click(device_id, x, y) 点击
    5. 智能等待详情页打开

      • 最小等待时间: fudai_detail_initial_wait_seconds(默认0.8秒)
      • 循环检测详情页是否打开
        • 每次等待 fudai_detail_verified_wait_seconds(默认0.2秒)
        • 调用 diagnose_stage_from_current_screen() 检测阶段
        • 如果检测到 FUDai_DETAIL,判定为成功打开
      • 最大等待时间: fudai_click_wait_seconds(默认1.7秒)
      • 如果超时仍未打开,返回 False

配置参数:

  • fudai_find_max_attempts: 最大尝试次数(默认99999)
  • fudai_icon_retry_delay_seconds: 重试间隔(秒,默认0.1)
  • fudai_icon_max_wait_seconds: 最大等待时间(秒,默认8.5)
  • fudai_click_wait_seconds: 点击后等待时间(秒,默认1.7)
  • fudai_detail_initial_wait_seconds: 详情页初始等待时间(秒,默认0.8)
  • fudai_detail_verified_wait_seconds: 详情页验证等待时间(秒,默认0.2)
  • fudai_template_match_enabled: 是否启用模板匹配(bool,默认False)
  • fudai_template_match_threshold: 模板匹配阈值(默认0.7)

代码示例:

def find_and_open_fudai_detail(analyser: Any, room_pos_ref: List[int]) -> bool:
    # 检查等待开奖状态
    if getattr(analyser, "_waiting_for_lottery_result", False):
        return False
    
    # 在最大等待时间内重复检测福袋图标
    max_wait_seconds = getattr(analyser, "fudai_icon_max_wait_seconds", 8.5)
    start_time = time.time()
    x = False
    
    while (time.time() - start_time) < max_wait_seconds:
        x = check_have_fudai_with_ready_screenshot(analyser, screenshot_ready=False)
        if x:
            break
        time.sleep(getattr(analyser, "fudai_icon_retry_delay_seconds", 0.1))
    
    if not x:
        return False
    
    # 点击福袋图标
    analyser.operation.click(analyser.device_id, x, analyser.y_pianyi + 2000)
    
    # 智能等待详情页打开
    initial_wait = getattr(analyser, "fudai_detail_initial_wait_seconds", 0.8)
    time.sleep(initial_wait)
    
    max_wait = getattr(analyser, "fudai_click_wait_seconds", 1.7)
    verified_wait = getattr(analyser, "fudai_detail_verified_wait_seconds", 0.2)
    start_time = time.time()
    
    while (time.time() - start_time) < max_wait:
        stage, _ = diagnose_stage_from_current_screen(analyser)
        if stage == "FUDai_DETAIL":
            return True
        time.sleep(verified_wait)
    
    return False

douyin_flow_control.handle_no_fudai_situation(analyser, ...) -> bool

  • 作用: 处理未找到福袋的情况,包括预约回退和切换直播间

  • 参数:

    • analyser: Any: 分析器对象
    • x: int: 福袋X坐标(未使用,保留兼容性)
    • swipe_times: int: 滑动次数(未使用,保留兼容性)
    • wait_times_ref: List[int]: 等待次数引用(未使用)
    • needswitch: bool: 是否允许切换直播间
    • reservation_focus_until_ts: float: 预约聚焦时间戳
    • reservations: list: 预约列表
    • room_pos: int: 当前直播间位置
    • post_switch_delay_s: float: 切换后延迟(秒)
    • swipe_up_switch_callback: Callable: 上滑切换回调函数
    • swipe_down_back_callback: Callable: 下滑回退回调函数
    • seek_reservation_room_callback: Callable: 查找预约直播间回调函数
    • sort_reservations_callback: Callable: 排序预约回调函数
    • write_state_callback: Callable: 写入状态回调函数
    • reservation_focus_until_ts_ref: List[float]: 预约聚焦时间戳引用
    • reset_to_list_after_reservations_ref: List[bool]: 重置到列表标志引用
    • swipe_times_ref: List[int]: 滑动次数引用
  • 返回值: bool - True=已处理预约回退, False=未处理

  • 调用位置: _handle_live_room_has_or_not_fudai() 中调用

  • 主要逻辑:

    1. 处理预约回退窗口

      • 调用 process_reservation_attend_window() 检查是否需要回退到预约直播间
      • 如果触发预约回退,返回 True
    2. 切换直播间(如果未触发预约回退)

      • 如果 needswitch = True,调用 swipe_up_switch_callback() 上滑切换直播间
      • 等待 post_switch_delay_s 秒
      • 更新滑动次数计数器

代码示例:

def handle_no_fudai_situation(
    analyser: Any,
    x: int,
    swipe_times: int,
    wait_times_ref: List[int],
    needswitch: bool,
    reservation_focus_until_ts: float,
    reservations: list,
    room_pos: int,
    post_switch_delay_s: float,
    swipe_up_switch_callback,
    swipe_down_back_callback,
    seek_reservation_room_callback,
    sort_reservations_callback,
    write_state_callback,
    back_to_list_callback,
    into_list_callback,
    reservation_focus_until_ts_ref: List[float],
    reset_to_list_after_reservations_ref: List[bool],
    swipe_times_ref: List[int]
) -> bool:
    # 处理预约回退窗口
    if process_reservation_attend_window(
        analyser,
        reservations,
        room_pos,
        reservation_focus_until_ts_ref,
        reservation_after_action_pending_ref,
        reservation_back_swipe_delay_s,
        swipe_down_back_callback,
        seek_reservation_room_callback,
        sort_reservations_callback,
        write_state_callback
    ):
        return True  # 已触发预约回退
    
    # 如果未触发预约回退,且允许切换直播间
    if needswitch:
        swipe_up_switch_callback()
        time.sleep(post_switch_delay_s)
        swipe_times_ref[0] += 1
    
    return False

4.5 福袋详情处理函数

douyin_fudai_core.get_fudai_contain(analyser, renwu: int = 2) -> Tuple

  • 作用: 获取福袋的完整信息(内容、倒计时、价值、参与人数),使用并行OCR提高效率

  • 参数:

    • analyser: Any: 分析器对象
    • renwu: int: 任务数量(用于验证,默认2)
  • 返回值: Tuple[str, str, int, int, float]

    • content: str: 福袋内容文本
    • countdown_text: str: 倒计时文本(格式:mm:ss)
    • participants: int: 参与人数
    • task_count: int: 任务数量
    • prize_value_yuan: float: 奖品价值(元)
  • 调用位置: _handle_in_fudai_detail() 中调用

  • 主要逻辑:

    1. 并行OCR识别(使用 ThreadPoolExecutor,6个线程)

      • ocr_task_list(): 任务列表OCR
        • 识别区域: (200, 600, 880, 900)
        • 用于提取参与人数和任务数量
      • ocr_content(): 福袋内容OCR
        • 识别区域: (200, 600, 880, 900)
        • 识别福袋内容描述
      • ocr_countdown_mm(): 倒计时分钟OCR
        • 识别区域: (390, 1140, 480, 1290) (倒计时区域的前30%)
        • 识别分钟数字
      • ocr_countdown_ss(): 倒计时秒OCR
        • 识别区域: (480, 1140, 570, 1290) (倒计时区域的中间30%)
        • 识别秒数字
      • ocr_value(): 价值OCR
        • 识别区域: (200, 1400, 880, 1600)
        • 识别奖品价值(元)
      • ocr_button(): 按钮状态OCR
        • 识别区域: (306, 2030, 780, 2110)
        • 识别参与按钮状态("已参与"、"需要加入粉丝团"、"需要评论"、"可以参与"等)
        • 特殊处理:
          • 识别结果存储在 analyser._fudai_button_status 和 analyser._fudai_button_text
          • 记录识别时间 analyser._fudai_button_ocr_time(用于判断是否可复用,5秒内有效)
    2. 解析倒计时

      • 优先使用整体识别结果(normalize_countdown_text)
      • 如果整体识别失败,使用分割识别结果(分钟 + 秒)
      • 支持多种格式:mm:ss、mm分ss秒、mm:ss后开奖 等
    3. 解析价值

      • 使用 extract_prize_value_yuan 从OCR文本中提取数字(元)
      • 支持格式:200元、¥200、价值200元 等
    4. 解析参与人数

      • 从任务列表OCR结果中提取参与人数
      • 支持格式:已有1234人参与、参与人数:1234 等
    5. 返回完整信息

代码示例:

def get_fudai_contain(analyser, renwu: int = 2) -> Tuple[str, str, int, int, float]:
    # 并行OCR识别(6个线程)
    with ThreadPoolExecutor(max_workers=6) as executor:
        future_task_list = executor.submit(ocr_task_list)
        future_content = executor.submit(ocr_content)
        future_countdown_mm = executor.submit(ocr_countdown_mm)
        future_countdown_ss = executor.submit(ocr_countdown_ss)
        future_value = executor.submit(ocr_value)
        future_button = executor.submit(ocr_button)
        
        # 等待所有任务完成
        task_list_raw = future_task_list.result()
        fudai_content_raw = future_content.result()
        countdown_mm_raw = future_countdown_mm.result()
        countdown_ss_raw = future_countdown_ss.result()
        value_raw = future_value.result()
        button_text_raw = future_button.result()
    
    # 解析倒计时
    countdown_text = normalize_countdown_text(
        countdown_mm_raw, countdown_ss_raw
    )
    
    # 解析价值
    prize_value_yuan = extract_prize_value_yuan(value_raw)
    
    # 解析参与人数
    participants = extract_participants(task_list_raw)
    
    return (fudai_content_raw, countdown_text, participants, renwu, prize_value_yuan)

douyin_fudai_core.basic_join_decision(analyser: Any, detail: Tuple) -> bool

  • 作用: 基础版参与决策,根据配置筛选福袋

  • 参数:

    • analyser: Any: 分析器对象
    • detail: Tuple: 福袋详情元组 (content, countdown_text, participants, task_count, prize_value_yuan, countdown_tuple)
  • 返回值: bool - True=已参与或已处理, False=未参与

  • 调用位置: _handle_in_fudai_detail() 中调用

  • 筛选逻辑:

    1. 价值筛选

      • 如果 min_prize_value_yuan > 0,检查 prize_value_yuan >= min_prize_value_yuan
      • 如果价值低于阈值,返回 False(不参与)
    2. 参与人数筛选

      • 如果 min_participants > 0,检查 participants >= min_participants
      • 如果 max_participants > 0,检查 participants <= max_participants
      • 如果不在范围内,返回 False
    3. 倒计时筛选

      • 如果 skip_if_countdown_lt_seconds > 0,检查 countdown >= skip_if_countdown_lt_seconds
      • 如果倒计时小于阈值,返回 False(避免参与即将开奖的福袋)
      • 如果 skip_if_countdown_gt_seconds > 0,检查 countdown <= skip_if_countdown_gt_seconds
      • 如果倒计时大于阈值,返回 False(避免参与等待时间过长的福袋)
    4. 关键词筛选

      • contains_want: 必须包含的关键词列表(任意一个匹配即可)
        • 如果列表不为空,且内容中不包含任何关键词,返回 False
      • contains_not_want: 不能包含的关键词列表(任意一个匹配即跳过)
        • 如果内容中包含任何关键词,返回 False
    5. 高价值预约

      • 如果价值 ≥ high_value_fudai_threshold_yuan,记录到 state/reservations.json
      • 预约信息包含:
        • room_title: 直播间标题
        • lottery_time_ts: 开奖时间戳(当前时间 + 倒计时秒数)
        • prize_value_yuan: 奖品价值
        • fudai_x: 福袋X坐标
        • reserved_at_ts: 预约时间戳

配置参数:

  • min_prize_value_yuan: 最低奖品价值(元,默认200.0)
  • min_participants: 最少参与人数(默认0,表示不启用)
  • max_participants: 最多参与人数(默认0,表示不启用)
  • skip_if_countdown_lt_seconds: 倒计时小于该秒数时不参与(默认5)
  • skip_if_countdown_gt_seconds: 倒计时大于该秒数时不参与(默认120)
  • contains_want: 必须包含的关键词列表(默认[])
  • contains_not_want: 不能包含的关键词列表(默认["首饰盒", "袜子"])
  • high_value_fudai_threshold_yuan: 高价值福袋阈值(元,默认500.0)

代码示例:

def basic_join_decision(analyser: Any, detail: Tuple) -> bool:
    content, countdown_text, participants, task_count, prize_value_yuan, countdown_tuple = detail
    countdown = countdown_tuple[0] * 60 + countdown_tuple[1] if countdown_tuple else 0
    
    # 价值筛选
    min_prize = analyser.config.get("min_prize_value_yuan", 200.0)
    if min_prize > 0 and prize_value_yuan < min_prize:
        return False
    
    # 参与人数筛选
    min_participants = analyser.config.get("min_participants", 0)
    max_participants = analyser.config.get("max_participants", 0)
    if min_participants > 0 and participants < min_participants:
        return False
    if max_participants > 0 and participants > max_participants:
        return False
    
    # 倒计时筛选
    skip_lt = analyser.config.get("skip_if_countdown_lt_seconds", 5)
    if skip_lt > 0 and countdown < skip_lt:
        return False
    skip_gt = analyser.config.get("skip_if_countdown_gt_seconds", 120)
    if skip_gt > 0 and countdown > skip_gt:
        return False
    
    # 关键词筛选
    contains_want = analyser.config.get("contains_want", [])
    if contains_want and not any(kw in content for kw in contains_want):
        return False
    
    contains_not_want = analyser.config.get("contains_not_want", [])
    if contains_not_want and any(kw in content for kw in contains_not_want):
        return False
    
    # 高价值预约
    threshold = analyser.config.get("high_value_fudai_threshold_yuan", 500.0)
    if prize_value_yuan >= threshold:
        # 记录预约
        reservation = {
            "room_title": analyser._current_room_title or "",
            "lottery_time_ts": time.time() + countdown,
            "prize_value_yuan": prize_value_yuan,
            "fudai_x": analyser._current_fudai_x or 540,
            "reserved_at_ts": time.time()
        }
        # 写入 state/reservations.json
        # ...
    
    return True  # 通过筛选

douyin_fudai_core.attend_choujiang(analyser) -> bool

  • 文件位置: douyin/fudai/core/fudai_attend.py

  • 作用: 点击参与抽奖,根据按钮状态执行相应操作

  • 参数:

    • analyser: Any: 分析器对象
  • 返回值: bool - True=参与成功, False=参与失败

  • 调用位置: basic_join_decision() 中调用(如果通过筛选)

  • 主要逻辑:

    1. 识别按钮状态

      • 优先使用并行OCR结果(5秒内有效)
        • 检查 analyser._fudai_button_text 和 analyser._fudai_button_status
        • 检查 analyser._fudai_button_ocr_time 是否在5秒内
        • 如果可用,直接使用,避免重复识别
      • 如果不可用,重新识别按钮
        • 裁剪按钮区域 (analyser.cut_pic(306, 2030, 780, 2110, "", "参与按钮"))
        • 图像预处理 (preprocess_for_ocr)
        • OCR识别(模式0和模式1,如果模式0识别失败)
    2. 根据按钮状态执行操作:

      • "已参与" → 设置 _waiting_for_lottery_result = True
        • 计算 _lottery_result_expected_ts = 当前时间 + 倒计时秒数
        • 更新 _last_successful_attend_ts = 当前时间
        • 返回 True
      • "需要加入粉丝团" → 加入粉丝团
        • 点击粉丝团加入按钮
        • 如果失败且 fansclub_fail_action="switch" → 切换直播间
        • 如果 fansclub_fail_action="stay" → 停留等待
      • "需要评论" → 发送评论
        • 点击评论输入框
        • 输入评论内容(使用ADB键盘)
        • 点击发送按钮
      • "可以参与" → 点击参与按钮
        • analyser.operation.click(device_id, x, y)
        • 更新 _last_successful_attend_ts = 当前时间
        • 返回 True
    3. 最多重试2次

      • 如果第一次操作失败,重试一次
      • 如果两次都失败,返回 False

配置参数:

  • auto_join_fansclub: 是否自动加入粉丝团(bool,默认True)
  • fansclub_fail_action: 加入粉丝团失败后的动作("switch"=切换直播间, "stay"=停留,默认"switch")

代码示例:

def attend_choujiang(analyser) -> bool:
    click_times = 0
    while click_times < 2:
        # 优先使用并行OCR结果
        attend_button_text = None
        button_status = getattr(analyser, "_fudai_button_status", None)
        button_text = getattr(analyser, "_fudai_button_text", "")
        
        if button_text and button_status:
            button_ocr_time = getattr(analyser, "_fudai_button_ocr_time", 0)
            if time.time() - button_ocr_time < 5.0:
                attend_button_text = button_text
        
        # 如果不可用,重新识别
        if not attend_button_text:
            analyser.cut_pic(306, 2030, 780, 2110, "", "参与按钮")
            use_name = preprocess_for_ocr(analyser, "参与按钮")
            attend_button_text = analyser.operation.analyse_pic_word(use_name, 0)
            if not attend_button_text:
                attend_button_text = analyser.operation.analyse_pic_word(use_name, 1)
        
        # 根据按钮状态执行操作
        if "参与成功" in attend_button_text or "已参与" in attend_button_text:
            analyser._waiting_for_lottery_result = True
            analyser._lottery_result_expected_ts = time.time() + countdown_seconds
            analyser._last_successful_attend_ts = time.time()
            return True
        
        elif "加入粉丝团" in attend_button_text or "粉丝团" in attend_button_text:
            # 加入粉丝团
            if analyser.config.get("auto_join_fansclub", True):
                if join_fansclub(analyser):
                    continue  # 重试参与
                else:
                    if analyser.config.get("fansclub_fail_action") == "switch":
                        return False  # 切换直播间
        
        elif "评论" in attend_button_text:
            # 发送评论
            send_comment(analyser)
            continue  # 重试参与
        
        elif "参与抽奖" in attend_button_text or "参与" in attend_button_text:
            # 点击参与按钮
            analyser.operation.click(analyser.device_id, 540, 2070)
            analyser._last_successful_attend_ts = time.time()
            return True
        
        click_times += 1
    
    return False

4.6 预约相关函数

douyin_reservation_logic.load_reservations_from_state(analyser) -> list

  • 文件位置: douyin/reservation/douyin_reservation_logic.py

  • 作用: 从状态文件加载预约数据

  • 参数:

    • analyser: Any: 分析器对象
  • 返回值: list[dict] - 预约列表

  • 调用位置: run_once_basic() 中调用

  • 文件路径: state/reservations.json (通过 path_config.get_reservations_path() 获取)

  • 主要逻辑:

    1. 读取 state/reservations.json 文件
    2. 解析JSON数据
    3. 过滤已过期的预约(lottery_time_ts < 当前时间)
    4. 更新 analyser.reservations 属性
    5. 返回预约列表

预约数据格式:

[
  {
    "room_title": "直播间标题",
    "lottery_time_ts": 1234567890.0,
    "prize_value_yuan": 500.0,
    "fudai_x": 540,
    "reserved_at_ts": 1234567890.0
  }
]

代码示例:

def load_reservations_from_state(analyser) -> list:
    import json
    from douyin.core import path_config
    
    reservations_path = path_config.get_reservations_path()
    if not os.path.exists(reservations_path):
        return []
    
    try:
        with open(reservations_path, "r", encoding="utf-8") as f:
            reservations = json.load(f)
        
        # 过滤已过期的预约
        current_time = time.time()
        reservations = [
            r for r in reservations
            if r.get("lottery_time_ts", 0) > current_time
        ]
        
        # 更新 analyser 属性
        analyser.reservations = reservations
        
        return reservations
    except Exception as e:
        analyser._log_kv("错误", "加载预约数据失败", error=str(e))
        return []

douyin_reservation_logic.process_reservation_attend_window(analyser, ...) -> bool

  • 文件位置: douyin/reservation/douyin_reservation_logic.py

  • 作用: 处理预约回退窗口,检查是否需要回退到预约直播间

  • 参数:

    • analyser: Any: 分析器对象
    • reservations: list: 预约列表
    • room_pos: int: 当前直播间位置
    • reservation_focus_until_ts_ref: List[float]: 预约聚焦时间戳引用
    • reservation_after_action_pending_ref: List[bool]: 预约后动作待处理标志引用
    • reservation_back_swipe_delay_s: float: 回退滑动延迟(秒)
    • swipe_down_back_callback: Callable: 下滑回退回调函数
    • seek_reservation_room_callback: Callable: 查找预约直播间回调函数
    • sort_reservations_callback: Callable: 排序预约回调函数
    • write_state_callback: Callable: 写入状态回调函数
  • 返回值: bool - True=已触发回退, False=未触发

  • 调用位置: run_once_basic() 和 handle_no_fudai_situation() 中调用

  • 主要逻辑:

    1. 检查预约队列是否已满

      • 如果预约数量 ≥ high_value_fudai_max_reservations,跳过处理
    2. 遍历预约列表,计算距离开奖时间

      • 对预约列表按开奖时间排序(sort_reservations_callback)
      • 计算每个预约距离开奖时间:remaining_seconds = lottery_time_ts - 当前时间
    3. 如果距离开奖时间 ≤ high_value_fudai_join_ahead_seconds,触发回退

      • 调用 seek_reservation_room_callback 查找目标直播间
      • 调用 swipe_down_back_callback 回退到目标直播间
      • 设置 reservation_focus_until_ts = lottery_time_ts + 60(聚焦到开奖后60秒)
      • 设置 reservation_back_direct_attend = True(标记需要直接参与)
    4. 验证是否在目标直播间(可选)

      • 如果启用 reservation_back_verify_enabled,验证是否在目标直播间
      • 通过OCR识别直播间标题,与预约的 room_title 比较

配置参数:

  • high_value_fudai_join_ahead_seconds: 提前参与秒数(默认120)
  • high_value_fudai_max_reservations: 最大预约数量(默认9999)
  • reservation_back_verify_enabled: 是否启用回退验证(bool,默认True)
  • reservation_back_swipe_delay: 回退滑动延迟(秒,默认0.1)

代码示例:

def process_reservation_attend_window(
    analyser: Any,
    reservations: list,
    room_pos: int,
    reservation_focus_until_ts_ref: List[float],
    reservation_after_action_pending_ref: List[bool],
    reservation_back_swipe_delay_s: float,
    swipe_down_back_callback: Callable,
    seek_reservation_room_callback: Callable,
    sort_reservations_callback: Callable,
    write_state_callback: Callable
) -> bool:
    # 检查预约队列是否已满
    max_reservations = analyser.config.get("high_value_fudai_max_reservations", 9999)
    if len(reservations) >= max_reservations:
        return False
    
    # 排序预约列表
    sorted_reservations = sort_reservations_callback(reservations)
    
    # 遍历预约列表
    current_time = time.time()
    ahead_seconds = analyser.config.get("high_value_fudai_join_ahead_seconds", 120)
    
    for item in sorted_reservations:
        lottery_time_ts = item.get("lottery_time_ts", 0)
        remaining_seconds = lottery_time_ts - current_time
        
        # 如果距离开奖时间 ≤ 提前参与秒数,触发回退
        if 0 < remaining_seconds <= ahead_seconds:
            # 查找目标直播间
            if seek_reservation_room_callback(item):
                # 回退到目标直播间
                swipe_down_back_callback()
                time.sleep(reservation_back_swipe_delay_s)
                
                # 设置聚焦时间戳
                reservation_focus_until_ts_ref[0] = lottery_time_ts + 60
                
                # 验证是否在目标直播间(可选)
                if analyser.config.get("reservation_back_verify_enabled", True):
                    verify_reservation_room(analyser, item)
                
                return True
    
    return False

4.7 预约处理函数详解

4.7.1 ReservationHandler.find_room_pos_by_title(analyser, target_title: str, target_title_raw: str = "") -> Optional[int]

  • 文件位置: douyin/reservation/douyin_reservation_handler.py
  • 作用: 根据直播间标题在运行时映射表中查找对应的位置
  • 参数:
    • analyser: Any: 分析器对象
    • target_title: str: 目标标题(规范化后)
    • target_title_raw: str: 目标原始标题
  • 返回值: Optional[int] - 如果找到匹配的位置,返回位置值;否则返回 None
  • 调用位置: 预约回退时查找目标直播间
  • 实现细节:
    1. 规范化标题: 使用 _normalize_room_title() 规范化目标标题和记录的标题
    2. 匹配算法:
      • 完全匹配: 如果规范化后的标题完全相同,匹配分数 = 1.0
      • 子串匹配: 如果一个是另一个的子串,匹配分数 = 0.8
      • 相似度匹配: 使用 difflib.SequenceMatcher 计算相似度(0.0~1.0)
    3. 选择最佳匹配: 选择匹配分数 >= 0.6 且最高的位置
    4. 返回结果: 如果找到匹配,返回位置值;否则返回 None

代码示例:

# 查找目标直播间位置
target_pos = ReservationHandler.find_room_pos_by_title(
    analyser,
    target_title="直播间标题",
    target_title_raw="直播间标题(原始)"
)
if target_pos is not None:
    print(f"找到目标直播间,位置: {target_pos}")
else:
    print("未找到目标直播间")

4.7.2 ReservationHandler.record_room_title_and_pos(analyser) -> None

  • 文件位置: douyin/reservation/douyin_reservation_handler.py
  • 作用: 记录当前直播间的标题和位置到运行时映射表
  • 参数:
    • analyser: Any: 分析器对象
  • 返回值: 无
  • 调用位置: 进入直播间后调用
  • 实现细节:
    1. 获取当前直播间位置: room_pos = analyser.room_pos
    2. 读取直播间标题: 调用 read_live_room_title_core() 获取标题(规范化和原始)
    3. 更新映射表: 将 (room_title, room_title_raw) 存储到 analyser._room_pos_to_title_map[room_pos]
    4. 更新分析器属性: 更新 analyser.current_room_title 和 analyser.current_room_title_raw

代码示例:

# 记录当前直播间标题和位置
ReservationHandler.record_room_title_and_pos(analyser)
# 映射表现在包含: {room_pos: (room_title, room_title_raw)}

4.7.3 ReservationHandler.seek_reservation_room(analyser, item: Dict[str, Any]) -> bool

  • 文件位置: douyin/reservation/douyin_reservation_handler.py
  • 作用: 根据预约记录里的 pos_seen 与当前 room_pos 进行回退,靠近目标直播间
  • 参数:
    • analyser: Any: 分析器对象
    • item: Dict[str, Any]: 预约记录字典
  • 返回值: bool - 是否成功回退到目标直播间
  • 调用位置: 预约回退时调用
  • 实现细节:
    1. 计算位置差: pos_diff = target_pos - cur_pos
    2. 判断方向:
      • pos_diff < 0: 目标在上方,需要向上回退(减少 room_pos)
      • pos_diff > 0: 目标在下方,需要向下切换(增加 room_pos)
      • pos_diff == 0: 已在目标位置,跳过回退
    3. 计算回退次数:
      • 向上回退: back_times = min(abs(pos_diff), max_back)
      • 向下切换: forward_times = min(pos_diff, max_back)
    4. 执行回退:
      • 向上回退: 调用 swipe_down_back_from_live() N次
      • 向下切换: 调用 swipe_up_to_next_live() N次
      • 每次滑动后延迟 reservation_back_swipe_delay 秒
    5. 设置标志: 回退过程中设置 _skip_record_title_during_seek = True,避免重复记录标题
    6. 返回结果: 回退完成后返回 True(校验将在 process_reservation_attend_window 中统一进行)

配置参数:

  • high_value_fudai_max_swipe_back: 最大回退次数(默认60,最大100)
  • reservation_back_swipe_delay: 回退滑动延迟(秒,默认0.3)

代码示例:

# 回退到目标直播间
item = {
    "pos_seen": 5,  # 目标位置
    "room_title": "目标直播间",
    "lottery_time_ts": 1704067200.0
}
success = ReservationHandler.seek_reservation_room(analyser, item)
if success:
    print("成功回退到目标直播间")

4.7.4 ReservationHandler.handle_reservation_direct_attend(analyser) -> None

  • 文件位置: douyin/reservation/douyin_reservation_handler.py
  • 作用: 预约回退后直接参与,跳过OCR识别,使用按钮检测进行决策
  • 参数:
    • analyser: Any: 分析器对象
  • 返回值: 无
  • 调用位置: run_once_basic() 中回退处理会直接触发参与逻辑(不再依赖 _reservation_back_direct_attend 标志)
  • 主要流程:
    1. 检查预约队列: 如果预约队列为空,回退到正常流程(调用 _handle_in_fudai_detail())
    2. 检查福袋是否过期:
      • 获取预约的 future_ts(开奖时间戳,从 first_reservation.get("future_ts") 获取)
      • 计算过期阈值: expired_threshold = future_ts + poll_before_seconds
      • 如果当前时间 > 过期阈值,清除标志并退出
      • 调用 cleanup_expired_reservations() 从预约队列中移除过期预约
    3. 步骤1: 直接查找福袋图标并点击
      • 调用 find_and_open_fudai_detail() 查找并打开福袋详情
      • 如果未找到,回退到正常流程(调用 _handle_in_fudai_detail())
      • 等待详情页加载(0.5秒,减少延迟)
    4. 步骤2: 调用按钮检测进行决策
      • 获取截图(operation.get_screenshot())
      • 读取截图文件(path_config.get_screenshot_path())
      • 调用 detect_attend_button_red_area() 检测参与按钮(返回 (has_button, button_info) 元组)
      • 如果未检测到按钮,回退到正常流程
    5. 步骤3: 点击参与按钮
      • 计算参与按钮坐标(基于截图优化坐标:OCR区域(306,2030)-(780,2110),区域中心(543, 2070))
      • 根据设备分辨率缩放坐标: attend_x = int(543 * rx / 1080), attend_y = int(2070 * ry / 2400)
      • 点击参与按钮(operation.click(device_id, attend_x, attend_y))
      • 等待点击后的响应(0.8秒,减少延迟)
    6. 步骤4: 点击福袋图标验证参与状态(详细验证逻辑)
      • 再次查找并点击福袋图标:
        • 调用 find_and_open_fudai_detail() 再次查找福袋图标
        • 如果未找到,可能已参与成功(记录日志,继续执行)
      • 如果找到福袋图标:
        • 等待详情页加载(0.5秒)
        • 获取截图并检测按钮状态
        • 调用 detect_attend_button_red_area() 再次检测参与按钮
        • 如果仍检测到按钮,可能参与失败,回退到正常流程
        • 如果未检测到按钮,说明参与成功
    7. 步骤5: 参与成功,设置开奖等待状态并从预约队列中移除
      • 设置开奖等待状态:
        • 计算剩余秒数: remain_seconds = max(0, future_ts - current_time)
        • 如果 remain_seconds > 0,设置 _waiting_for_lottery_result = True
        • 设置 _lottery_result_expected_ts = future_ts - 13.0(提前13秒检查开奖结果)
      • 设置锁定期:
        • 计算锁定期: reservation_focus_until_ts = future_ts + max(0.0, poll_before)
        • 防止过早切换直播间
      • 从预约队列中移除已参与的预约:
        • 遍历预约队列,匹配 future_ts(允许5秒误差: abs(res_future_ts - future_ts) <= 5.0)
        • 移除匹配的预约,保留不匹配的预约
        • 记录移除日志
      • 清除标志:
      • 清除相关运行时标志(已移除,不再使用)
      • 清除 reservation_after_action_pending = False

配置参数:

  • high_value_fudai_poll_before_seconds: 开奖前轮询时间(秒,默认10.0)

关键实现细节:

  • 参与按钮坐标: 基于OCR区域中心点计算,坐标为 (543, 2070)(基准分辨率1080x2400)
  • 验证机制: 通过再次检测按钮状态验证参与是否成功
  • 预约匹配: 通过 future_ts 匹配预约(允许5秒误差),确保准确移除已参与的预约
  • 错误处理: 所有步骤都有异常处理,出错时回退到正常流程(_handle_in_fudai_detail())

代码示例:

# 预约回退后直接参与
if analyser._reservation_back_direct_attend:
    ReservationHandler.handle_reservation_direct_attend(analyser)
    analyser._reservation_back_direct_attend = False
    return

4.7.5 预约验证机制

预约回退后需要进行验证,确保在正确的直播间。验证机制包括:

  1. 标题匹配验证:

    • 使用 find_room_pos_by_title() 查找目标直播间位置
    • 如果找到匹配的位置,验证成功
  2. 位置验证:

    • 检查当前 room_pos 是否等于目标 pos_seen
    • 如果相等,验证成功
  3. 福袋详情验证(可选):

    • 打开福袋详情页
    • 验证福袋价值是否匹配
    • 验证倒计时是否合理

验证失败处理:

  • 如果验证失败,记录警告日志
  • 继续执行流程(不中断)
  • 如果多次验证失败,可能需要重新查找目标直播间

4.7.6 douyin_reservation_verify.match_reservation(item, detail) -> Tuple[bool, str, Dict]

  • 文件位置: douyin/reservation/douyin_reservation_verify.py
  • 作用: 校验回退后的福袋详情是否匹配预约记录
  • 参数:
    • item: Dict[str, Any]: 预约项字典,包含 prize_value_yuan, future_ts, content 等
    • detail: Tuple: 福袋详情元组 (content, time_text, participants, copies, prize_value_yuan, countdown_tuple)
  • 返回值: (is_match, reason, debug_dict) - 是否匹配、原因、调试信息
  • 调用位置: 预约回退验证时调用
  • 主要逻辑:
    1. 提取预约和实际福袋信息:
      • 从预约项提取: expected_value, expected_future, expected_content
      • 从详情元组提取: actual_value, actual_future, actual_content
    2. 检查是否为"观看X分钟"类任务:
      • 使用正则表达式检测: (?:观看|看)(?:直播)?\s*(?:\d+|[\u4e00-\u9fff]+)\s*分钟
      • 如果是观看任务,返回 (False, "watch_task_detected", ...)
    3. 验证 future_ts:
      • 如果 expected_future <= 0 或 actual_future <= 0,返回 (False, "future_missing", ...)
    4. 价值或内容匹配(二选一命中即可):
      • 价值匹配: abs(expected_value - actual_value) <= max(50.0, expected_value * 0.25)
      • 内容匹配: expected_content in actual_content 或 actual_content in expected_content
      • 如果价值或内容都不匹配,返回 (False, "content_or_value_mismatch", ...)
    5. future_ts 精确匹配:
      • 计算 future_diff = abs(expected_future - actual_future)
      • 如果 future_diff <= 180,返回 (True, "ok", ...)
      • 如果 future_diff > 180 但 future_diff <= 1200 且价值+内容都匹配,返回 (True, "future_mismatch_relaxed", ...)
      • 否则返回 (False, "future_mismatch", ...)

代码示例:

item = {
    "prize_value_yuan": 500.0,
    "future_ts": 1704067200.0,
    "content": "测试福袋"
}
detail = ("测试福袋", "01:30", 100, 10, 500.0, (1704067000.0, 1704067200.0))
is_match, reason, debug = match_reservation(item, detail)

4.7.7 douyin_reservation_verify.validate_back_to_reservation(analyser, item, quick=False, max_checks=3) -> Tuple[bool, Optional[Tuple]]

  • 文件位置: douyin/reservation/douyin_reservation_verify.py
  • 作用: 回退后校验直播间标题,确保在正确的直播间
  • 参数:
    • analyser: Any: 分析器对象
    • item: Dict[str, Any]: 预约项字典
    • quick: bool: 是否快速模式(减少检查次数)
    • max_checks: int: 最大检查次数(未使用,保留兼容性)
  • 返回值: (is_valid, None) - 如果校验通过返回 True,否则返回 False
  • 调用位置: 预约回退后验证时调用
  • 主要逻辑:
    1. 检查是否启用验证:
      • 如果 reservation_back_verify_enabled = False,直接返回 True
    2. 规范化预期标题:
      • 使用 _normalize_room_title() 规范化预约的 room_title
      • 去除空格、特殊字符、无关词("点赞"、"关注"等)
    3. 运行时映射表验证:
      • 从 _room_pos_to_title_map 获取目标位置的记录标题
      • 如果映射表中的标题与预期标题匹配,增强验证信心
    4. 读取当前直播间标题:
      • 调用 read_live_room_title_core() 读取当前直播间标题
      • 计算相似度: difflib.SequenceMatcher(None, expected_title, current_title).ratio()
    5. 标题匹配判断:
      • 如果 expected_title in current_title 或 current_title in expected_title 或 ratio >= 0.45,验证通过
      • 如果标题不匹配(ratio < 0.45),尝试根据映射表找到正确位置并回退
    6. 自动回退到正确位置:
      • 调用 _find_room_pos_by_title() 在映射表中查找正确位置
      • 如果找到,更新 item["pos_seen"] 并调用 _seek_reservation_room() 回退
      • 重新读取标题验证,如果匹配则返回 True

配置参数:

  • reservation_back_verify_enabled: 是否启用回退验证(bool,默认True)

5. 底层操作函数

底层操作函数封装在 douyin/core/underlying_operations.py 的 underlying_operations 类中,提供设备控制、截图、OCR、图像处理等基础功能。

5.1 设备操作函数

underlying_operations.select_device() -> str | bool

  • 文件位置: douyin/core/underlying_operations.py
  • 作用: 选择需要连接的Android设备
  • 参数: 无
  • 返回值:
    • str: 设备ID(单设备或多设备选择后)
    • False: 无设备连接
  • 调用位置: bin/run_cli.py 的 main() 函数中调用
  • 实现细节:
    • 执行 adb devices 命令获取设备列表
    • 使用正则表达式提取设备ID(支持IP地址和序列号)
    • 单设备:直接返回设备ID
    • 多设备:显示设备列表,用户选择后返回
    • 无设备:返回 False 并提示检查连接

代码示例:

operation = underlying_operations()
device_id = operation.select_device()
if not device_id:
    print("未检测到设备")
    return

underlying_operations.get_device_resolution(device_id: str) -> Tuple[int, int]

  • 文件位置: douyin/core/underlying_operations.py
  • 作用: 获取Android设备的分辨率
  • 参数:
    • device_id: str: 设备ID
  • 返回值: Tuple[int, int] - (宽度, 高度)
  • 调用位置: fudai_analyse.__init__() 中调用,用于初始化分辨率
  • 实现细节:
    • 执行 adb shell wm size 命令
    • 使用正则表达式提取物理分辨率(格式:Physical size: WIDTHxHEIGHT)
    • 返回宽度和高度

代码示例:

width, height = operation.get_device_resolution(device_id)
analyser.resolution_ratio_x = width
analyser.resolution_ratio_y = height

underlying_operations.click(device_id: str, x: int, y: int) -> None

  • 文件位置: douyin/core/underlying_operations.py
  • 作用: 在设备屏幕上点击指定坐标
  • 参数:
    • device_id: str: 设备ID
    • x: int: X坐标
    • y: int: Y坐标
  • 返回值: 无
  • 调用位置: 所有需要点击的地方(福袋图标、参与按钮、返回键等)
  • 实现细节:
    • 执行 adb shell input tap x y 命令
    • 支持坐标缩放(根据设备分辨率自动调整)

代码示例:

operation.click(device_id, 540, 1200)  # 点击屏幕中心

underlying_operations.click_back(device_id: str) -> None

  • 文件位置: douyin/core/underlying_operations.py
  • 作用: 点击Android返回键(KEYCODE_BACK)
  • 参数:
    • device_id: str: 设备ID
  • 返回值: 无
  • 调用位置: 返回操作、退出详情页等场景
  • 实现细节:
    • 执行 adb shell input keyevent 4 命令(4 = KEYCODE_BACK)

underlying_operations.click_confirm(device_id: str) -> None

  • 文件位置: douyin/core/underlying_operations.py
  • 作用: 点击确认键(KEYCODE_ENTER)
  • 参数:
    • device_id: str: 设备ID
  • 返回值: 无
  • 调用位置: 确认操作场景
  • 实现细节:
    • 执行 adb shell input keyevent 66 命令(66 = KEYCODE_ENTER)

5.2 截图操作函数

underlying_operations.get_screenshot(device_id: str, path: str = "pic") -> bool

  • 文件位置: douyin/core/underlying_operations.py

  • 作用: 获取设备屏幕截图并保存到本地

  • 参数:

    • device_id: str: 设备ID
    • path: str: 保存路径(默认"pic")
  • 返回值: bool - 成功返回 True,失败返回 False

  • 调用位置: 所有需要截图的地方(阶段诊断、OCR识别、像素检测等)

  • 实现细节:

    • 优先方法: 使用 adb exec-out screencap -p 直接输出到文件(只需1次adb调用,不在手机端落盘)
    • 回退方法1: 使用 adb shell screencap -p /sdcard/DCIM/screenshot.png + adb pull(2次adb调用)
    • 回退方法2: 使用 screenshot1.png 覆盖 screenshot.png
    • 文件安全: 先写入临时文件(screenshot.png.tmp),再原子替换,避免并发读取到半写入文件
    • Windows兼容: 使用 _safe_replace_file() 处理Windows文件锁定问题
    • 镜像功能: 自动镜像截图到外部工作树(如果配置了 EXTERNAL_DOUYIN_FUDAI_DIR)
    • 文件验证: 检查文件大小(至少1KB),避免0字节/损坏文件

    实现细节补充(重要):

    • 临时文件 + 原子替换: 截图先写入临时文件(例如 screenshot.png.tmp),完成后通过原子替换或安全复制覆盖目标 screenshot.png,以避免并发读取到半写入文件。
    • Windows 文件锁容错: 使用 _safe_replace_file() 做两段回退(os.replace -> shutil.copy2 -> 手动分块复制),确保在文件被占用时也能尽快恢复截图文件,避免阻塞主流程。
    • 优先策略: 优先使用 adb exec-out screencap -p(单次 adb 调用、速度最快)。若失败回退到 adb shell screencap + adb pull 或其它降级路径。
    • 外部镜像: 若设定 EXTERNAL_DOUYIN_FUDAI_DIR,会尝试把 screenshot.png 镜像一份到外部工作树,便于其它工具/工作树读取。为避免性能损耗,可通过 DISABLE_SCREENSHOT_MIRROR=1 禁用该镜像逻辑。
    • 性能/可靠性权衡: 镜像和原子替换会带来额外 IO,生产运行可选择禁用镜像且减少调试图像以提升稳定性。

代码示例:

if operation.get_screenshot(device_id):
    # 截图成功,继续处理
    pass
else:
    # 截图失败,记录错误
    logger.error("截图失败")

underlying_operations.save_reward_pic(device_id: str) -> None

  • 文件位置: douyin/core/underlying_operations.py
  • 作用: 保存中奖截图(带时间戳)
  • 参数:
    • device_id: str: 设备ID
  • 返回值: 无
  • 调用位置: fudai_result_checker.get_reward() 中调用
  • 实现细节:
    • 生成带时间戳的文件名(格式:YYYY-MM-DD-HH-MM-SS.png)
    • 优先使用 exec-out 方法,失败则回退到 shell screencap + pull
    • 保存失败不打断主流程(仅打印警告)

5.3 图像处理函数

underlying_operations.cut_pic(left_up: Tuple[int, int] = (0, 63), right_down: Tuple[int, int] = (1080, 1620), target: str = "", name: str = "") -> bool

  • 文件位置: douyin/core/underlying_operations.py
  • 作用: 裁剪图片,获取指定区域的子图片(用于OCR识别)
  • 参数:
    • left_up: Tuple[int, int]: 左上角坐标(默认(0, 63))
    • right_down: Tuple[int, int]: 右下角坐标(默认(1080, 1620))
    • target: str: 目标目录(空字符串表示使用默认路径)
    • name: str: 裁剪后的图片名称(不含扩展名,空字符串表示使用"cut")
  • 返回值: bool - 成功返回 True,失败返回 False
  • 调用位置: 所有需要OCR识别的地方(福袋内容、倒计时、价值、参与人数等)
  • 实现细节:
    • 重试机制: 最多重试3次,每次延迟递增(0.1s, 0.2s, 0.3s)
    • 文件验证: 检查源文件是否存在、文件大小(至少100字节)、图片完整性
    • 坐标验证: 验证裁剪坐标有效性(不能超出图片范围,left < right, top < bottom)
    • 路径管理: 使用 _find_pic_path() 查找/创建图片路径(支持分类目录)
    • 坐标缓存: 存储裁剪坐标到 _ocr_coords_cache,供OCR使用
    • 调试图像: 自动保存调试图像(完整截图+区域标注)
    • 错误处理: 捕获所有异常,最后一次尝试失败则返回 False 并记录错误

代码示例:

# 裁剪福袋内容区域
if operation.cut_pic(
    left_up=(100, 200),
    right_down=(980, 400),
    name="福袋内容"
):
    # 裁剪成功,继续OCR识别
    text = operation.analyse_pic_word("福袋内容")
else:
    # 裁剪失败
    logger.error("裁剪福袋内容区域失败")

5.4 OCR识别函数

underlying_operations.analyse_pic_word(picname: str, change_color: int = 0, pic_path: Optional[str] = None) -> str

  • 文件位置: douyin/core/underlying_operations.py

  • 作用: 对指定图片运行OCR识别,返回拼接后的文本结果

  • 参数:

    • picname: str: 图片名称(不含扩展名,如"福袋内容")
    • change_color: int: 颜色转换模式(0=不转换,1=转换为黑白,2=其他)
    • pic_path: Optional[str]: 图片路径(可选,默认使用 _find_pic_path() 查找)
  • 返回值: str - OCR识别结果(所有文本行拼接后的字符串)

  • 调用位置: 所有需要OCR识别的地方(福袋内容、倒计时、价值、参与人数、按钮文本等)

  • 实现细节:

    • OCR引擎: 优先使用EasyOCR,失败则回退到PaddleOCR
    • 延迟初始化: OCR引擎在首次使用时初始化(_ensure_ocr())
    • 图片加载: 使用PIL加载图片,支持多种格式(PNG、JPEG等)
    • 颜色转换: 根据 change_color 参数进行颜色转换(提高识别率)
    • 文本提取: 使用 extract_ocr_content() 提取文本(去除置信度信息)
    • 坐标缓存: 如果存在坐标缓存,传递给OCR引擎(提高识别精度)
    • 错误处理: 捕获所有异常,返回空字符串并记录错误

    OCR 初始化与回退策略(实现细节):

    • 延迟初始化: 类在构造时会根据 SKIP_OCR_INIT 环境变量决定是否立即初始化 OCR。若未设置 SKIP_OCR_INIT,构造函数会尝试优先初始化 EasyOCR;若失败回退到 PaddleOCR;两者都失败则保留 ocr=None,按需延迟初始化(通过 _ensure_ocr() 在首次 OCR 请求时再尝试加载)。
    • 优先级: EasyOCR 为首选(通常更快),PaddleOCR 为回退。若系统缺少依赖,会打印提示并继续运行(不会阻塞主流程)。
    • 环境变量影响:
      • SKIP_OCR_INIT=1:跳过启动时 OCR 初始化(用于快速启动或仅需截图调试的场景)。
      • DISABLE_MODEL_SOURCE_CHECK=True:在 PaddleOCR 导入时抑制模型源连通性检查(避免国内网络阻塞)。
    • 输出与静默化: 初始化过程会尽量静默(重定向 stdout/stderr),仅在需要时打印简短提示,减少启动噪音。
    • 回退行为: 当 analyse_pic_word 被调用且 ocr is None,会在内部调用 _ensure_ocr() 进行延迟初始化;初始化仍然可能失败,函数会捕获异常并返回空串,上层需要对空结果做容错处理。

    小结/建议:

    • 若频繁做大量 OCR 识别(生产运行),建议在环境中预装 easyocr 并允许启动时初始化以减少首次延迟;调试或仅需截图时可设置 SKIP_OCR_INIT=1 来缩短启动时间。

代码示例:

# 识别福袋内容
content = operation.analyse_pic_word("福袋内容")
if content:
    print(f"福袋内容: {content}")
else:
    print("OCR识别失败")

underlying_operations.analyse_pic_digits(picname: str, change_color: int = 1, pic_path: Optional[str] = None) -> str

  • 文件位置: douyin/core/underlying_operations.py
  • 作用: 对指定图片运行OCR识别,专门用于识别数字(倒计时、价值、参与人数等)
  • 参数:
    • picname: str: 图片名称(不含扩展名,如"倒计时")
    • change_color: int: 颜色转换模式(默认1=转换为黑白,提高数字识别率)
    • pic_path: Optional[str]: 图片路径(可选)
  • 返回值: str - OCR识别结果(数字字符串)
  • 调用位置: 识别倒计时、价值、参与人数等数字信息
  • 实现细节:
    • 与 analyse_pic_word() 类似,但默认使用黑白转换(change_color=1)
    • 专门优化数字识别(去除非数字字符,保留数字、小数点、冒号等)

代码示例:

# 识别倒计时
countdown_text = operation.analyse_pic_digits("倒计时")
# 可能返回: "05:30" 或 "5:30"

underlying_operations.extract_ocr_content(content: List, return_confidence: bool = False) -> str | Tuple[str, float]

  • 文件位置: douyin/core/underlying_operations.py
  • 作用: 从OCR结果中提取文本内容(去除坐标、置信度等信息)
  • 参数:
    • content: List: OCR原始结果(EasyOCR或PaddleOCR格式)
    • return_confidence: bool: 是否返回平均置信度(默认 False)
  • 返回值:
    • str: 提取的文本(如果 return_confidence=False)
    • Tuple[str, float]: (文本, 平均置信度)(如果 return_confidence=True)
  • 调用位置: analyse_pic_word() 和 analyse_pic_digits() 内部调用
  • 实现细节:
    • EasyOCR格式: [[[坐标], 文本, 置信度], ...] → 提取文本和置信度
    • PaddleOCR格式: [[[坐标], [文本, 置信度]], ...] → 提取文本和置信度
    • 文本拼接: 将所有文本行用空格拼接
    • 置信度计算: 计算所有文本的平均置信度(如果 return_confidence=True)

5.5 滑动操作函数

underlying_operations.swipe(device_id: str, x1: int, y1: int, x2: int, y2: int, duration_ms: int = 600) -> None

  • 文件位置: douyin/core/underlying_operations.py
  • 作用: 在设备屏幕上执行滑动操作(从起点滑动到终点)
  • 参数:
    • device_id: str: 设备ID
    • x1: int: 起点X坐标
    • y1: int: 起点Y坐标
    • x2: int: 终点X坐标
    • y2: int: 终点Y坐标
    • duration_ms: int: 滑动持续时间(毫秒,默认600ms)
  • 返回值: 无
  • 调用位置: 所有需要滑动的地方(切换直播间、返回推荐页、滑动列表等)
  • 实现细节:
    • 优先方法: 使用 adb shell input swipe x1 y1 x2 y2 duration_ms(最简单,兼容性好)
    • 回退方法1: 使用 sendevent 模拟触摸事件(更精确,但需要root权限)
    • 回退方法2: 使用 uiautomator(Android 4.3+)
    • 回退方法3: 使用改进的 sendevent(支持非root设备)
    • 坐标缩放: 根据设备分辨率自动调整坐标

代码示例:

# 向上滑动(切换直播间)
operation.swipe(device_id, 540, 1800, 540, 800, duration_ms=600)

5.6 工具函数

underlying_operations.delay(seconds: float = 1.0) -> None

  • 文件位置: douyin/core/underlying_operations.py
  • 作用: 延迟指定秒数
  • 参数:
    • seconds: float: 延迟秒数(默认1.0秒)
  • 返回值: 无
  • 调用位置: 所有需要等待的地方(页面加载、操作后等待等)

underlying_operations.random_delay(min_seconds: float = 1.0, max_seconds: float = 100.0) -> None

  • 文件位置: douyin/core/underlying_operations.py
  • 作用: 随机延迟指定范围内的秒数(模拟人工操作)
  • 参数:
    • min_seconds: float: 最小延迟秒数(默认1.0秒)
    • max_seconds: float: 最大延迟秒数(默认100.0秒)
  • 返回值: 无
  • 调用位置: 需要模拟人工操作的场景

underlying_operations.check_countdown(last_time: str = "") -> Optional[int]

  • 文件位置: douyin/core/underlying_operations.py
  • 作用: 检查倒计时文本,转换为剩余秒数
  • 参数:
    • last_time: str: 倒计时文本(格式:mm:ss 或 m:ss 或 ss)
  • 返回值: Optional[int] - 剩余秒数,解析失败返回 None
  • 调用位置: douyin_fudai_core.ocr_countdown_mm() 和 ocr_countdown_ss() 中调用
  • 实现细节:
    • 支持多种格式:mm:ss、m:ss、ss、m分s秒 等
    • 使用正则表达式提取分钟和秒数
    • 计算总秒数 = 分钟 × 60 + 秒数

代码示例:

countdown_text = "05:30"
remaining_seconds = operation.check_countdown(countdown_text)
# 返回: 330 (5分30秒 = 330秒)

underlying_operations.get_current_hour() -> int

  • 文件位置: douyin/core/underlying_operations.py
  • 作用: 获取当前时间的小时数(0-23)
  • 参数: 无
  • 返回值: int - 当前小时数(0-23)
  • 调用位置: 静音时段检查等场景

6. 核心类和数据结构详解

6.1 核心类:fudai_analyse

fudai_analyse 是项目的核心调度类,采用Mixin模式组合多个功能模块。

类定义

class fudai_analyse(
    NavigationMixin,        # 导航功能
    StageDetectionMixin,    # 阶段检测
    PopupHandlerMixin,      # 弹窗处理
    LotteryResultMixin,     # 抽奖结果
    RoomUtilsMixin,         # 直播间工具
    MainLogicMixin,         # 主逻辑
):
    """福袋抽奖相关操作类(本地模块化实现,保留原有属性与入口)。"""

核心属性

设备与分辨率
  • device_id: str - 设备ID(需要在运行时设置)
  • y_pianyi: int - Y轴偏移量(用于坐标调整)
  • resolution_ratio_x: int - 屏幕宽度(默认1080)
  • resolution_ratio_y: int - 屏幕高度(默认2400)
运行配置
  • operation: underlying_operations - 底层操作对象
  • config_path: str - 配置文件路径
  • config: dict - 配置字典(从 config.json 加载)
日志相关
  • _run_id: str - 运行ID(格式:YYYYMMDDHHMMSS)
  • _log_seq: int - 日志序列号
  • _log_kv: Callable - 日志记录函数(增强版本)
  • _last_log_tag: str - 上一个日志标签(用于检测阶段变化)
  • _std_logger: logging.Logger - 标准日志器
状态管理
  • _swipe_times: int - 滑动次数计数器(用于滑动次数重置功能)
  • _last_diag_stage: str - 上次诊断的阶段(如"IN_LIVE_ROOM")
  • _last_diag_seen: str - 上次诊断看到的标识(如直播间标题)
  • _last_diag_ts: float - 上次诊断的时间戳
  • _last_successful_attend_ts: float - 最后一次成功参与福袋的时间戳(用于30分钟超时检查)
  • _no_attend_timeout_minutes: float - 无参与超时时间(默认30分钟)
  • _run_start_ts: float - 运行开始时间戳
  • last_fudai_x: int - 上次检测到的福袋图标X坐标(用于优化搜索)
福袋筛选配置
  • contains_not_want: List[str] - 不想要的福袋内容关键词列表
  • contains_want: List[str] - 想要的福袋内容关键词列表
  • min_prize_value_yuan: float - 最小奖品价值(元)
  • min_participants: int - 最小参与人数
  • max_participants: int - 最大参与人数
  • skip_if_countdown_gt_seconds: int - 倒计时大于该秒数则跳过(默认900秒)
  • skip_if_countdown_lt_seconds: int - 倒计时小于该秒数则不参与(默认0秒)
福袋查找配置
  • fudai_icon_retry_delay_seconds: float - 福袋图标重试延迟(默认0.6秒)
  • fudai_icon_max_wait_seconds: float - 福袋图标最大等待时间(默认5.0秒)
  • fudai_click_wait_seconds: float - 点击福袋图标后等待详情页加载的时间(默认2.0秒)
  • fudai_finder_optimized_enabled: bool - 是否启用优化查找器(默认 True)
  • fudai_click_verify_enabled: bool - 点击后是否验证成功打开详情页(默认 True)
  • fudai_find_max_retries: int - 最大重试次数(默认3次)
其他配置
  • switch_room_wait_after_stage_diag_seconds: float - 切换直播间后等待阶段诊断的时间(默认7.0秒)
  • swipe_duration_ms: int - 滑动持续时间(毫秒,默认600ms)
  • screenshot_diagnose_min_interval_seconds: float - 截图诊断最小间隔(默认8.0秒)
  • no_fudai_watchdog_enabled: bool - 是否启用无福袋看门狗(默认 False)
预约相关
  • _forced_reservation_detail: Optional[dict] - 强制预约详情(用于测试)
  • _forced_reservation_fudai_x: Optional[int] - 强制预约福袋X坐标(用于测试)
等待开奖相关
  • _waiting_for_lottery_result: bool - 是否正在等待开奖结果
  • _lottery_result_room_pos: Optional[dict] - 等待开奖的直播间位置信息

核心方法

初始化方法
  • __init__() -> None - 初始化所有属性,加载配置,初始化日志系统
主流程方法
  • fudai_choujiang() -> None - 主循环入口(无限循环或单次运行)
  • run_once_basic() -> bool - 单次循环执行(返回 True 表示继续,False 表示退出)
配置加载
  • load_config() -> None - 从 config.json 加载配置并更新属性
阶段诊断
  • _diagnose_stage_from_current_screen() -> str - 阶段诊断入口(调用 douyin_stage.diagnose_stage_from_current_screen())
后台任务
  • background_tick() -> None - 后台tick函数(在等待循环期间执行轻量后台任务,如处理弹窗)

6.2 Mixin类详细说明

6.2.1 NavigationMixin(导航功能混入类)

文件位置: douyin/core/fudai_modules/fudai_navigation.py

职责: 提供导航、点击、滑动等基础交互功能

主要方法:

  1. click(x: int, y: int) -> None

    • 作用: 点击指定坐标(兼容原版接口)
    • 参数:
      • x: int - X坐标
      • y: int - Y坐标
    • 实现: 转发到底层 operation.click()
    • 调用位置: 所有需要点击的地方
  2. load_config() -> None

    • 作用: 从 config.json 加载配置
    • 实现: 调用 douyin_config.ConfigManager.load_config_from_file()
    • 调用位置: fudai_analyse.__init__() 中调用
  3. cut_pic(x1: int, y1: int, x2: int, y2: int, name: str = "", desc: str = "", y_pianyi: int = 0) -> None

    • 作用: 截取指定区域的图片(兼容原版接口)
    • 参数:
      • x1, y1: int - 左上角坐标
      • x2, y2: int - 右下角坐标
      • name: str - 图片名称(不含扩展名)
      • desc: str - 描述信息
      • y_pianyi: int - Y轴偏移量
    • 实现: 调用 douyin_screenshot_handler.ScreenshotHandler.cut_pic()
    • 调用位置: OCR识别前裁剪图片区域
  4. _scale_from_base(base_x: int, base_y: int) -> tuple[int, int]

    • 作用: 根据当前设备分辨率,从基准分辨率(1080x2400)缩放到实际分辨率
    • 参数:
      • base_x, base_y: int - 基准坐标(基于1080x2400)
    • 返回值: (scaled_x, scaled_y) - 缩放后的坐标
    • 调用位置: 所有需要坐标缩放的地方
  5. _save_step_screenshot(label: str) -> None

    • 作用: 保存步骤截图用于调试(带时间戳)
    • 参数: label: str - 步骤标签
    • 调用位置: 关键步骤执行后保存调试截图
  6. swipe_up_to_next_live() -> None

    • 作用: 上滑切换直播间
    • 注意: 如果处于预约锁定期内,则不允许上划离开预约直播间
    • 实现: 调用 douyin_swipe_handler.SwipeHandler.swipe_up_to_next_live()
    • 调用位置: 切换直播间时调用
  7. _return_to_recommend_and_reenter_live() -> None

    • 作用: 返回推荐页面并重新进入直播间
    • 实现: 通过多次点击返回键返回到推荐页面,然后点击关注标签并进入直播间
    • 调用位置: 30分钟超时、滑动次数重置等场景
  8. swipe_down_back_from_live() -> None

    • 作用: 上划回退到上一个直播间(供预约/无福袋逻辑使用)
    • 实现: 调用 douyin_swipe_handler.SwipeHandler.swipe_down_back_from_live()
    • 调用位置: 预约回退、无福袋回退等场景
  9. _maybe_reset_after_swipes() -> int

    • 作用: 达到切换阈值后,在当前直播间页面回退到第一个直播间
    • 返回值: int - 重置后的滑动次数(通常为0)
    • 实现: 调用 douyin_swipe_handler.SwipeHandler.maybe_reset_after_swipes()
    • 调用位置: 滑动次数达到阈值时调用

6.2.2 StageDetectionMixin(阶段检测混入类)

文件位置: douyin/core/fudai_modules/fudai_stage_detection.py

职责: 提供屏幕阶段诊断、像素状态检测等功能

主要方法:

  1. _diagnose_stage_from_current_screen() -> Tuple[str, str]

    • 作用: 封装到子模块的阶段诊断入口
    • 返回值: (stage, seen) - (阶段字符串, 看到的标识)
    • 实现: 调用 douyin_stage_handler.StageHandler.diagnose_stage_from_current_screen()
    • 调用位置: run_once_basic() 中调用
  2. _read_pixel_stage_state(return_details: bool = False) -> dict | tuple[dict, dict]

    • 作用: 读取像素阶段状态(用于阶段诊断)
    • 参数:
      • return_details: bool - 是否返回每个检测步骤的详细信息(包括分数)
    • 返回值:
      • dict - 检测结果(return_details=False时)
      • tuple[dict, dict] - (检测结果, 详细信息)(return_details=True时)
    • 实现: 调用 douyin_helpers.HelperFunctions.read_pixel_stage_state()
    • 调用位置: 阶段诊断时调用
  3. _check_in_live_room_by_icon() -> Tuple[bool, float]

    • 作用: 通过模板匹配检测是否在直播间
    • 返回值: (is_in_live_room, confidence) - (是否在直播间, 置信度)
    • 实现: 使用OpenCV模板匹配检测直播间图标
    • 调用位置: 阶段诊断时调用

6.2.3 PopupHandlerMixin(弹窗处理混入类)

文件位置: douyin/core/fudai_modules/fudai_popup_handler.py

职责: 提供各种弹窗的检测和处理功能

主要方法:

  1. _check_coupon_popup() -> bool

    • 作用: 检测购物券/新客专享券等底部营销弹窗
    • 返回值: bool - 是否检测到弹窗
    • 注意: 仅在详情链路外的"看门狗"中使用
    • 实现: 调用 douyin_popup_handler.PopupHandler.check_coupon_popup()
    • 调用位置: 后台tick函数中调用
  2. _check_shopping_redpacket_popup() -> bool

    • 作用: 检测购物红包中央弹窗
    • 返回值: bool - 是否检测到弹窗
    • 实现: 调用 douyin_popup_handler.PopupHandler.check_shopping_redpacket_popup()
    • 调用位置: 后台tick函数中调用
  3. _shot_and_diagnose(operation_type: str, description: str, device_id: str | None = None, force_screenshot: bool = False) -> None

    • 作用: 统一截图并诊断方法
    • 参数:
      • operation_type: str - 操作类型(如"开奖诊断"、"详情识别"等)
      • description: str - 操作描述
      • device_id: str | None - 设备ID,如果为None则使用self.device_id
      • force_screenshot: bool - 是否强制截图(忽略缓存)
    • 实现: 调用 douyin_helpers.HelperFunctions.shot_and_diagnose()
    • 调用位置: 需要截图并诊断的场景

6.2.4 LotteryResultMixin(抽奖结果混入类)

文件位置: douyin/core/fudai_modules/fudai_lottery_result.py

职责: 提供开奖结果的OCR识别和处理功能

主要方法:

  1. _check_lottery_result_by_ocr() -> Optional[str]

    • 作用: 通过OCR识别开奖结果按钮区域,返回识别到的文本类型
    • 返回值:
      • "我知道了" - 未中奖
      • "立即领取奖品" - 中奖
      • None - 识别失败
    • 实现: 调用 douyin_helpers.HelperFunctions.check_lottery_result_by_ocr()
    • 调用位置: 检查开奖结果时调用
  2. _handle_lottery_result_by_ocr(result_type: str) -> None

    • 作用: 根据OCR识别结果处理开奖结果
    • 参数: result_type: str - "我知道了" 或 "立即领取奖品"
    • 实现: 调用 douyin_helpers.HelperFunctions.handle_lottery_result_by_ocr()
    • 调用位置: 处理开奖结果时调用

6.2.5 RoomUtilsMixin(直播间工具混入类)

文件位置: douyin/core/fudai_modules/fudai_room_utils.py

职责: 提供房间定位、记录等工具功能

主要方法:

  1. _find_room_pos_by_title(target_title: str, target_title_raw: str = "") -> int | None

    • 作用: 根据直播间标题在运行时映射表中查找对应的位置
    • 参数:
      • target_title: str - 目标直播间标题(规范化后)
      • target_title_raw: str - 目标直播间标题(原始)
    • 返回值: int | None - 如果找到匹配的位置,返回位置值;否则返回None
    • 实现: 调用 douyin_reservation_handler.ReservationHandler.find_room_pos_by_title()
    • 调用位置: 预约回退时查找目标直播间
  2. _record_room_title_and_pos() -> None

    • 作用: 记录当前直播间的标题和位置到运行时映射表
    • 用途: 用于预约回退校验时验证位置信息
    • 实现: 调用 douyin_reservation_handler.ReservationHandler.record_room_title_and_pos()
    • 调用位置: 进入直播间后调用
  3. _seek_reservation_room(item: dict[str, Any]) -> bool

    • 作用: 根据预约记录里的 pos_seen 与当前 room_pos 进行回退,靠近目标直播间
    • 参数: item: dict - 预约记录
    • 返回值: bool - 是否成功找到目标直播间
    • 说明:
      • 使用 high_value_fudai_max_swipe_back 约束最大回退次数
      • 如果启用了回退校验,会进行详细校验(直播间名、福袋详情匹配)
    • 实现: 调用 douyin_reservation_handler.ReservationHandler.seek_reservation_room()
    • 调用位置: 预约回退时调用

6.2.6 MainLogicMixin(主逻辑混入类)

文件位置: douyin/core/fudai_modules/fudai_main_logic.py

职责: 提供主要的业务逻辑和流程控制

主要方法:

  1. _enhanced_log_kv(*args, **fields) -> None

    • 作用: 增强版日志记录,自动添加时间戳、设备ID等通用字段
    • 实现: 调用 douyin_logging_wrapper.LoggingWrapper.enhanced_log_kv()
    • 调用位置: 所有需要记录日志的地方
  2. _log_step_time(step_name: str, start_time: float) -> None

    • 作用: 记录步骤耗时(带格式化)
    • 参数:
      • step_name: str - 步骤名称
      • start_time: float - 开始时间戳
    • 调用位置: 性能分析时调用
  3. fudai_choujiang(device_id: str = "", y_pianyi: int = 0, needswitch: bool = False, wait_minutes: int = 15) -> None

    • 作用: 主循环入口(兼容原版接口)
    • 参数:
      • device_id: str - 设备ID
      • y_pianyi: int - Y轴偏移量
      • needswitch: bool - 是否允许切换直播间
      • wait_minutes: int - 每次循环等待时间(分钟)
    • 实现: 设置设备ID和配置,然后循环调用 run_once_basic()
    • 调用位置: bin/run_cli.py 的 main() 函数中调用

6.2.7 BaseFudaiMixin(基础混入类)

文件位置: douyin/core/fudai_modules/base_interface.py

职责: 提供通用功能,所有Mixin类的基类

主要方法:

  1. _safe_log(*args, **fields) -> None

    • 作用: 安全的日志记录,避免依赖主类的日志方法
    • 实现: 尝试调用主类的 _enhanced_log_kv(),失败则使用 print()
    • 调用位置: Mixin类内部需要记录日志时调用
  2. _safe_operation_call(operation_name: str, *args, **kwargs) -> Any

    • 作用: 安全的操作调用,避免依赖未定义的属性
    • 参数:
      • operation_name: str - 操作名称
      • *args, **kwargs - 传递给操作的参数
    • 返回值: 操作结果,失败返回 None
    • 调用位置: Mixin类内部需要调用操作时使用

6.3 数据结构

预约数据结构

预约数据存储在 state/reservations.json 文件中,格式如下:

[
  {
    "room_title": "直播间标题",
    "room_pos": {
      "x": 540,
      "y": 1200,
      "title": "直播间标题"
    },
    "lottery_time_ts": 1704067200.0,
    "prize_value_yuan": 500.0,
    "fudai_x": 900
  },
  ...
]

字段说明:

  • room_title: str - 直播间标题(用于匹配)
  • room_pos: dict - 直播间位置信息
    • x: int - X坐标
    • y: int - Y坐标
    • title: str - 直播间标题
  • lottery_time_ts: float - 开奖时间戳(Unix时间戳)
  • prize_value_yuan: float - 奖品价值(元)
  • fudai_x: int - 福袋图标X坐标(可选)

阶段类型枚举

阶段类型定义在 douyin/stage/douyin_stage.py 中:

IN_LIVE_ROOM = "IN_LIVE_ROOM"          # 直播间
RECOMMEND_PAGE = "RECOMMEND_PAGE"      # 推荐页
FOLLOW_LIST = "FOLLOW_LIST"            # 关注列表
LIVE_LIST = "LIVE_LIST"                 # 直播列表
FUDai_DETAIL = "FUDai_DETAIL"          # 福袋详情页
FUDai_RESULT = "FUDai_RESULT"          # 抽奖结果页
FANSCLUB_JOIN = "FANSCLUB_JOIN"        # 粉丝团加入页
LIVE_CLOSED = "LIVE_CLOSED"            # 直播已结束
UNKNOWN = "UNKNOWN"                     # 未知阶段

福袋详情数据结构

福袋详情在代码中通常使用元组或字典表示:

# 元组格式(get_fudai_contain返回值)
(
    content: str,              # 福袋内容文本
    countdown_text: str,       # 倒计时文本(格式:mm:ss)
    participants: int,         # 参与人数
    task_count: int,          # 任务数量
    prize_value_yuan: float   # 奖品价值(元)
)

# 字典格式(用于传递)
{
    "content": "福袋内容",
    "countdown_text": "05:30",
    "participants": 1000,
    "task_count": 2,
    "prize_value_yuan": 500.0
}

直播间位置数据结构

{
    "x": 540,           # X坐标
    "y": 1200,          # Y坐标
    "title": "直播间标题"  # 直播间标题(用于匹配)
}

7. 配置系统详解

7.1 配置文件位置

配置文件位于 config/config.json,路径通过 path_config.get_config_path() 获取。

7.1.1 douyin/core/path_config.py 用法

  • 使用 path_config.get_config_path() 获取配置文件的绝对路径;
  • 常用路径获取函数:
    • path_config.get_screenshot_path():当前截图 pic/screenshot.png;
    • path_config.get_reservations_path():预约状态文件路径;
    • path_config.get_logs_dir() / get_log_file_path():日志目录与统一日志文件;
    • path_config.get_cut_pic_path(name):获取裁剪图片用于 OCR 的路径。
  • 在代码中不要硬编码 pic/、logs/、state/ 等路径,统一通过 path_config 获取以保证兼容不同工作目录。

7.1.2 配置加载与覆盖优先级

配置项的生效顺序(从低到高优先级):

  1. 代码中内置的默认值(类属性或常量);
  2. config/config.json(通过 path_config.get_config_path() 指定的文件);
  3. 环境变量(仅少数开关被代码显式读取,如 SKIP_OCR_INIT, EXTERNAL_DOUYIN_FUDAI_DIR, DISABLE_MODEL_SOURCE_CHECK, DISABLE_SCREENSHOT_MIRROR 等);
  4. 命令行参数(bin/run_cli.py 中解析的参数,会在创建 fudai_analyse 实例后覆盖运行时属性——命令行优先级最高)。

说明:实际运行时 fudai_analyse.__init__() 会加载 config.json(若存在),随后 bin/run_cli.py 会将命令行参数按需覆盖分析器属性;因此临时调试请优先使用命令行参数,长期配置请写入 config/config.json。

7.2 配置项详解

7.2.1 基础运行配置

{
  "needswitch": true,                    // 是否允许切换直播间
  "infinite_loop_enabled": true,         // 是否启用无限循环
  "wait_minutes": 5                      // 每次循环等待时间(分钟)
}
  • needswitch: 控制是否允许自动切换直播间寻找更多福袋
    • true: 允许切换(多间模式)
    • false: 不允许切换(单间模式)
  • infinite_loop_enabled: 控制主循环是否无限运行
    • true: 无限循环
    • false: 单次运行后退出
  • wait_minutes: 每次循环结束后的等待时间(分钟)

7.2.2 福袋筛选配置

{
  "min_prize_value_yuan": 200.0,         // 最小奖品价值(元)
  "min_participants": 0,                 // 最小参与人数(0=不限制)
  "max_participants": 0,                 // 最大参与人数(0=不限制)
  "skip_if_countdown_gt_seconds": 120,  // 倒计时大于该秒数则跳过
  "skip_if_countdown_lt_seconds": 5,     // 倒计时小于该秒数则不参与
  "contains_want": [],                  // 想要的福袋内容关键词列表
  "contains_not_want": [                 // 不想要的福袋内容关键词列表
    "首饰盒",
    "袜子"
  ]
}
  • min_prize_value_yuan: 只参与价值大于等于该值的福袋
  • min_participants: 只参与参与人数大于等于该值的福袋(0=不限制)
  • max_participants: 只参与参与人数小于等于该值的福袋(0=不限制)
  • skip_if_countdown_gt_seconds: 倒计时大于该秒数则跳过(避免等待时间过长)
  • skip_if_countdown_lt_seconds: 倒计时小于该秒数则不参与(避免来不及参与)
  • contains_want: 福袋内容必须包含这些关键词之一(空列表=不限制)
  • contains_not_want: 福袋内容不能包含这些关键词(空列表=不限制)

7.2.3 高价值福袋预约配置

{
  "high_value_fudai_enabled": true,                    // 是否启用高价值福袋预约
  "high_value_fudai_threshold_yuan": 500.0,            // 高价值福袋阈值(元)
  "high_value_fudai_join_ahead_seconds": 120,          // 提前参与秒数(开奖前N秒回退参与)
  "high_value_fudai_max_swipe_back": 50,                // 最大回退滑动次数
  "high_value_fudai_max_reservations": 9999,           // 最大预约数量
  "high_value_fudai_after_action": "continue",         // 预约后的动作(continue/switch)
  "high_value_room_revisit_enabled": true,              // 是否启用高价值直播间重访
  "high_value_room_revisit_only_current_run": true,     // 是否仅在当前运行中重访
  "reservation_back_verify_enabled": true,              // 是否验证预约回退
  "reservation_back_swipe_delay": 0.1                   // 预约回退滑动延迟(秒)
}
  • high_value_fudai_enabled: 是否启用高价值福袋预约功能
  • high_value_fudai_threshold_yuan: 价值大于等于该值的福袋会被预约
  • high_value_fudai_join_ahead_seconds: 开奖前N秒自动回退到目标直播间参与
  • high_value_fudai_max_swipe_back: 回退时最多滑动N次(防止无限滑动)
  • high_value_fudai_max_reservations: 最多同时记录N个预约(超过后丢弃最晚开奖的)
  • high_value_fudai_after_action: 预约后的动作
    • "continue": 继续当前流程
    • "switch": 切换直播间
  • high_value_room_revisit_enabled: 是否启用高价值直播间重访(记录高价值直播间,后续自动重访)
  • high_value_room_revisit_only_current_run: 是否仅在当前运行中重访(重启后不保留)
  • reservation_back_verify_enabled: 是否验证预约回退(回退后验证是否在目标直播间)
  • reservation_back_swipe_delay: 预约回退滑动后的延迟(秒)

7.2.4 福袋查找配置

{
  "fudai_find_max_attempts": 99999,                    // 最大尝试次数(已废弃,保留仅为兼容性)
  "fudai_icon_retry_delay_seconds": 0.1,              // 福袋图标重试延迟(秒)
  "fudai_icon_max_wait_seconds": 8.5,                 // 福袋图标最大等待时间(秒)
  "fudai_click_wait_seconds": 1.7,                    // 点击福袋图标后等待详情页加载的时间(秒)
  "fudai_detail_initial_wait_seconds": 0.8,           // 福袋详情页初始等待时间(秒)
  "fudai_detail_verified_wait_seconds": 0.2,           // 福袋详情页验证后等待时间(秒)
  "fudai_detail_retry_delay_seconds": 0.5,             // 福袋详情页重试延迟(秒)
  "fudai_detail_save_debug_images": false              // 是否保存调试图像
}
  • fudai_icon_retry_delay_seconds: 每次重试查找福袋图标之间的延迟
  • fudai_icon_max_wait_seconds: 最多等待N秒查找福袋图标(超时后放弃)
  • fudai_click_wait_seconds: 点击福袋图标后等待详情页加载的时间
  • fudai_detail_initial_wait_seconds: 进入福袋详情页后的初始等待时间(等待页面稳定)
  • fudai_detail_verified_wait_seconds: 验证详情页加载成功后的等待时间
  • fudai_detail_retry_delay_seconds: 详情页加载失败后的重试延迟
  • fudai_detail_save_debug_images: 是否保存调试图像(用于调试OCR识别问题)

7.2.5 滑动和导航配置

{
  "reset_after_swipes_enabled": true,                 // 是否启用滑动次数重置
  "reset_after_swipes": 50,                           // 滑动N次后重置到推荐页
  "reset_after_swipes_action": "swipe",               // 滑动重置后的回退方式(swipe/back)
  "enable_back_on_misses": true,                      // 是否在连续无福袋时启用返回键回退
  "fudai_exit_after_misses": 10,                      // 连续无福袋N次后返回推荐页
  "swipe_duration_ms": 600,                           // 滑动持续时间(毫秒)
  "switch_room_wait_after_stage_diag_seconds": 4.0    // 切换直播间后等待阶段诊断的时间(秒)
}
  • reset_after_swipes_enabled: 是否启用滑动次数重置功能
  • reset_after_swipes: 滑动N次后自动返回推荐页(防止无限滑动)
  • reset_after_swipes_action: 滑动重置后的回退方式
    • "swipe": 使用滑动方式返回推荐页
    • "back": 使用返回键返回推荐页
  • enable_back_on_misses: 是否在连续无福袋时启用返回键回退(独立于滑动重置配置)
  • fudai_exit_after_misses: 连续无福袋N次后返回推荐页(仅当 enable_back_on_misses 为 true 时生效)
  • swipe_duration_ms: 滑动持续时间(毫秒,值越大滑动越慢)
  • switch_room_wait_after_stage_diag_seconds: 切换直播间后等待阶段诊断的时间(确保页面稳定)

7.2.6 粉丝团配置

{
  "auto_join_fansclub": true,                         // 是否自动加入粉丝团
  "fansclub_fail_action": "switch"                    // 加入粉丝团失败后的动作(switch/continue)
}
  • auto_join_fansclub: 是否自动加入粉丝团(如果需要)
  • fansclub_fail_action: 加入粉丝团失败后的动作
    • "switch": 切换直播间
    • "continue": 继续当前流程

7.2.7 超时配置

{
  "no_attend_timeout_minutes": 30.0                   // 无参与超时时间(分钟)
}
  • no_attend_timeout_minutes: 如果N分钟内没有成功参与任何福袋,则返回推荐页(防止卡在无福袋的直播间)

7.2.8 静音时段配置

{
  "fudai_quiet_hours_enabled": true,                 // 是否启用静音时段
  "fudai_quiet_start_hour": 2,                        // 静音时段开始时间(小时,0-23)
  "fudai_quiet_end_hour": 9                           // 静音时段结束时间(小时,0-23)
}
  • fudai_quiet_hours_enabled: 是否启用静音时段(在指定时间段内不参与福袋)
  • fudai_quiet_start_hour: 静音时段开始时间(小时,0-23)
  • fudai_quiet_end_hour: 静音时段结束时间(小时,0-23)

7.2.9 检测阈值配置

{
  "stage_diag_max_time": 5.0,                          // 阶段诊断最大时间(秒)
  "stage_diag_max_step_time": 2.0,                     // 阶段诊断单步最大时间(秒)
  "live_room_match_threshold": 0.6,                    // 直播间模板匹配阈值(0.0-1.0)
  "fudai_template_match_enabled": false,               // 是否启用福袋模板匹配
  "fudai_template_match_threshold": 0.7,              // 福袋模板匹配阈值(0.0-1.0)
  "lucky_draw_red_ratio_threshold": 0.8,               // 开奖页面红色占比阈值(0.0-1.0)
  "attend_button_red_ratio_threshold": 0.25,          // 参与按钮红色占比阈值(0.0-1.0)
  "fansclub_join_red_ratio_threshold": 0.25,           // 粉丝团加入按钮红色占比阈值(0.0-1.0)
  "shopping_redpacket_red_ratio_threshold": 0.15,      // 购物红包背景红色占比阈值(0.0-1.0,默认0.15)
  "coupon_template_match_threshold": 0.4,              // 优惠券弹窗模板匹配阈值(0.0-1.0)
  "fudai_detail_template_threshold": 0.54              // 福袋详情页模板匹配阈值(0.0-1.0)
}
  • stage_diag_max_time: 阶段诊断总最大时间(超时后返回UNKNOWN)
  • stage_diag_max_step_time: 阶段诊断单步最大时间(超时后跳过该步骤)
  • live_room_match_threshold: 直播间模板匹配阈值(值越大越严格)
  • fudai_template_match_enabled: 是否启用福袋模板匹配(用于查找福袋图标)
  • fudai_template_match_threshold: 福袋模板匹配阈值
  • lucky_draw_red_ratio_threshold: 开奖页面红色占比阈值(用于检测开奖结果页面)
  • attend_button_red_ratio_threshold: 参与按钮红色占比阈值(用于检测按钮状态)
  • fansclub_join_red_ratio_threshold: 粉丝团加入按钮红色占比阈值
  • shopping_redpacket_red_ratio_threshold: 购物红包背景红色占比阈值(用于 detect_redpacket_popup_background,默认0.15)
  • coupon_template_match_threshold: 优惠券弹窗模板匹配阈值
  • fudai_detail_template_threshold: 福袋详情页模板匹配阈值

7.2.10 OCR配置

{
  "enable_ocr_mode1": false                            // 是否启用OCR模式1(已废弃,保留仅为兼容性)
}

7.2.11 日志配置

{
  "logging": {
    "level": "DEBUG",                                  // 日志级别(DEBUG/INFO/WARNING/ERROR)
    "file_path": "logs/unified.log",                   // 日志文件路径
    "keep_days": 30,                                   // 日志保留天数
    "use_dated_logs": true,                            // 是否使用按日期分割的日志文件
    "rotation": {
      "enabled": true,                                 // 是否启用日志轮转
      "max_bytes": 10485760,                           // 单个日志文件最大大小(字节)
      "backup_count": 5,                              // 保留的备份文件数量
      "when": "midnight",                             // 轮转时间(midnight/daily/hourly)
      "interval": 1                                    // 轮转间隔
    },
    "beautify_output": true,                           // 是否美化输出
    "show_timestamps": true,                           // 是否显示时间戳
    "show_execution_times": true,                      // 是否显示执行时间
    "debug_detail_level": "detailed",                  // 调试详细级别
    "error_detail_level": "full",                      // 错误详细级别
    "action_log_format": "detailed",                   // 操作日志格式
    "color_output": true,                              // 是否启用彩色输出
    "max_log_lines_display": 1000,                    // 最大显示日志行数
    "auto_scroll_logs": true,                          // 是否自动滚动日志
    "performance_tracking": {
      "enabled": true,                                // 是否启用性能跟踪
      "track_function_calls": true,                   // 是否跟踪函数调用
      "track_database_queries": false,                 // 是否跟踪数据库查询
      "slow_operation_threshold_ms": 100               // 慢操作阈值(毫秒)
    },
    "error_logging": {
      "capture_stack_traces": true,                   // 是否捕获堆栈跟踪
      "include_context": true,                        // 是否包含上下文
      "max_error_logs": 1000,                         // 最大错误日志数量
      "error_categories": [                           // 错误类别列表
        "ocr",
        "network",
        "validation",
        "system",
        "user_action"
      ]
    }
  }
}

7.2.12 调试配置

{
  "debug_captures": {
    "enabled": true,                                   // 是否启用调试捕获
    "keep_days": 3,                                   // 调试文件保留天数
    "max_files": 2000,                                // 最大调试文件数量
    "auto_cleanup": true                              // 是否自动清理
  },
  "reservation_test_mode": false                      // 是否启用预约测试模式
}

7.3 配置加载流程

  1. 初始化时加载: fudai_analyse.__init__() → load_config()
  2. 配置文件路径: 通过 path_config.get_config_path() 获取
  3. 配置更新: 从JSON文件读取配置,更新类的所有相关属性
  4. 默认值: 如果配置项不存在,使用类属性中的默认值

7.4 配置验证

配置加载后,会进行基本验证:

  • 检查必需配置项是否存在
  • 验证数值范围(如阈值必须在0.0-1.0之间)
  • 验证枚举值(如 fansclub_fail_action 必须是 "switch" 或 "continue")

8. 状态管理机制详解

8.1 状态管理概述

项目使用多种状态标志来跟踪运行状态,确保流程的正确执行和异常恢复。状态主要分为以下几类:

  1. 运行状态标志:控制主流程的执行
  2. 预约状态:管理高价值福袋预约
  3. 等待开奖状态:跟踪正在等待开奖的福袋
  4. 超时保护状态:防止脚本卡死
  5. 阶段诊断状态:记录当前页面阶段

8.2 运行状态标志

8.2.1 预约回退直接参与标志

-- 属性名: _reservation_back_direct_attend: 已移除(不再作为运行时属性使用)

  • 作用: 标记预约回退后是否直接参与(跳过阶段诊断和福袋查找)
  • 设置时机: 预约回退成功后设置为 True
  • 清除时机: 参与完成后清除
  • 使用位置: run_once_basic() 开头检查

代码示例:

# 在 run_once_basic() 中
if self._reservation_back_direct_attend:
    # 直接参与,跳过阶段诊断
    self._handle_reservation_direct_attend()
    self._reservation_back_direct_attend = False
    return

8.2.2 等待开奖状态

  • 属性名: _waiting_for_lottery_result: bool
  • 作用: 标记是否正在等待某个福袋的开奖结果
  • 设置时机: 参与福袋后,如果倒计时较长,设置为 True
  • 清除时机: 检查到开奖结果后清除
  • 使用位置: run_once_basic() 中检查

代码示例:

# 在 run_once_basic() 中
if self._waiting_for_lottery_result:
  # 检查开奖结果
  if time.time() >= self._lottery_result_expected_ts:
    self._handle_lottery_result()
    self._waiting_for_lottery_result = False
    return

8.2.3 跳过阶段诊断标志

  • 属性名: _skip_stage_diagnosis_and_find_fudai: bool
  • 作用: 标记是否跳过阶段诊断和福袋查找(直接进入详情页处理)
  • 设置时机:
    • 点击参与抽奖按钮后(attend_choujiang() 中设置)
    • 预约回退后,如果确定在目标直播间
  • 清除时机: 处理完成后清除
  • 使用位置: run_once_basic() 中检查
  • 使用场景:
    • 点击参与按钮后,详情页会自动关闭,下次循环直接查找福袋,跳过阶段检测
    • 预约回退后,如果确定在目标直播间,跳过阶段检测直接查找福袋

8.2.4 福袋详情验证标志

  • 属性名: _fudai_detail_verified: bool
  • 作用: 标记是否已验证过福袋详情页(用于避免重复查找福袋)
  • 设置时机: 验证福袋详情页成功后设置为 True
  • 清除时机: 处理完成后清除
  • 使用位置: _handle_live_room_has_or_not_fudai() 中检查
  • 使用场景: 如果已验证过详情页,直接调用 _handle_in_fudai_detail(),不查找福袋

8.2.5 刚刚切换直播间标志

  • 属性名: _just_switched_room: bool
  • 作用: 标记是否刚刚切换了直播间(用于优化阶段诊断)
  • 设置时机: 切换直播间后设置为 True
  • 清除时机: 阶段诊断完成后清除
  • 使用位置: 阶段诊断时,如果刚切换,增加等待时间

8.2.6 第一次运行标志

  • 属性名: _first_run_once_basic: bool
  • 作用: 标记是否是第一次运行 run_once_basic()
  • 设置时机: 初始化时设置为 True
  • 清除时机: 第一次运行后设置为 False
  • 使用位置: run_once_basic() 中检查
  • 使用场景: 第一次运行时清空预约队列和状态文件,确保每次启动时队列为空

8.2.7 队列满等待标志

  • 属性名: queue_full_waiting_at_earliest: bool
  • 作用: 标记是否在队列满等待状态(回退到最早开奖的预约直播间等待)
  • 设置时机: 队列满时,回退到最早开奖的预约直播间后设置为 True
  • 清除时机:
    • 所有预约完成后清除
    • 预约回退后清除
  • 使用位置: run_once_basic() 中检查
  • 使用场景: 队列满时,回退到最早开奖的预约直播间等待,避免继续添加预约

8.3 预约状态管理

8.3.1 预约队列

  • 属性名: reservations: List[Dict[str, Any]]
  • 作用: 存储高价值福袋预约列表
  • 数据结构: 见 6.2 数据结构 - 预约数据结构
  • 初始化时机:
    • 第一次运行: 清空预约队列,不加载状态文件(_first_run_once_basic = True)
    • 非第一次运行: 保持当前预约队列,不从状态文件加载
  • 保存时机:
    • 添加预约时
    • 清理过期预约时
    • 预约回退时
    • 队列裁剪时
    • 写入状态文件供外部查看

重要变更:

  • 不再从状态文件加载: 每次启动时预约队列为空,不加载之前保存的预约
  • 第一次运行清空: 如果是第一次运行,强制清空预约队列和状态文件
  • 状态文件仅用于外部查看: 状态文件主要用于外部查看预约状态,程序内部不依赖状态文件加载

8.3.2 预约状态文件

  • 文件路径: state/reservations.json
  • 格式: JSON对象,包含 reservations 数组和其他元数据
  • 持久化: 每次修改预约队列后自动保存(供外部查看)
  • 加载策略:
    • 不再自动加载: 程序启动时不从状态文件加载预约数据
    • 仅用于外部查看: 状态文件主要用于外部工具查看预约状态
    • 第一次运行清空: 第一次运行时清空状态文件

代码示例:

# 加载预约数据
def load_reservations_from_state(analyser):
    try:
        with open(analyser._reservations_state_path, 'r', encoding='utf-8') as f:
            data = json.load(f)
            analyser.reservations = data.get('reservations', [])
    except FileNotFoundError:
        analyser.reservations = []
    except Exception as e:
        logger.error(f"加载预约数据失败: {e}")
        analyser.reservations = []

# 保存预约数据
def save_reservations_to_state(analyser):
    try:
        data = {
            'reservations': analyser.reservations,
            'updated_at': time.time()
        }
        with open(analyser._reservations_state_path, 'w', encoding='utf-8') as f:
            json.dump(data, f, ensure_ascii=False, indent=2)
    except Exception as e:
        logger.error(f"保存预约数据失败: {e}")

8.3.3 预约队列管理

队列排序规则:

  1. 主排序键: lottery_time_ts(开奖时间戳,升序)
  2. 次排序键: prize_value_yuan(奖品价值,降序)
  3. 第三排序键: created_ts(创建时间戳,升序)

队列裁剪:

  • 当队列长度超过 high_value_fudai_max_reservations 时
  • 保留优先级最高的N个预约(按排序规则)
  • 丢弃优先级最低的预约

过期清理:

  • 每次处理预约窗口时检查
  • 如果 lottery_time_ts <= 当前时间,则清理该预约

8.4 等待开奖状态管理

8.4.1 等待开奖标志

  • 属性名: _waiting_for_lottery_result: bool
  • 关联属性:
    • _lottery_result_expected_ts: float - 预期开奖时间戳
    • _lottery_result_room_pos: Optional[Dict] - 等待开奖的直播间位置信息

8.4.2 等待开奖流程

  1. 设置等待状态: 参与福袋后,如果倒计时较长(> 30秒),设置等待状态
  2. 等待期间: 继续运行主循环,但跳过福袋查找和参与
  3. 检查开奖结果: 到达预期开奖时间后,检查开奖结果
  4. 清除等待状态: 处理完开奖结果后清除

代码示例:

# 参与福袋后设置等待状态
if countdown_seconds > 30:
    self._waiting_for_lottery_result = True
    self._lottery_result_expected_ts = time.time() + countdown_seconds
    self._lottery_result_room_pos = room_pos
    logger.info(f"设置等待开奖状态,预期开奖时间: {self._lottery_result_expected_ts}")

8.5 超时保护机制

8.5.1 30分钟无参与超时

  • 属性名: _last_successful_attend_ts: float
  • 配置项: no_attend_timeout_minutes: float(默认30.0分钟)
  • 作用: 如果N分钟内没有成功参与任何福袋,返回推荐页面(防止卡在无福袋的直播间)

检查逻辑:

# 在 run_once_basic() 中
current_time = time.time()
timeout_seconds = self._no_attend_timeout_minutes * 60

# 检查是否超时
if self._last_successful_attend_ts > 0:
    elapsed = current_time - self._last_successful_attend_ts
    if elapsed > timeout_seconds:
        logger.warning(f"30分钟无参与超时,返回推荐页面")
        self._return_to_recommend_and_reenter_live()
        return
else:
    # 从未成功参与,检查运行时间
    elapsed = current_time - self._run_start_ts
    if elapsed > timeout_seconds:
        logger.warning(f"运行{timeout_seconds}秒未成功参与,返回推荐页面")
        self._return_to_recommend_and_reenter_live()
        return

8.5.2 滑动次数重置

  • 属性名: _swipe_times: int
  • 配置项: reset_after_swipes: int(默认50次)
  • 作用: 滑动N次后自动返回推荐页面(防止无限滑动)

检查逻辑:

# 在 _maybe_reset_after_swipes() 中
if self.config.get("reset_after_swipes_enabled", True):
    max_swipes = self.config.get("reset_after_swipes", 50)
    if self._swipe_times >= max_swipes:
        logger.info(f"滑动次数达到{max_swipes}次,返回推荐页面")
        self._return_to_recommend_and_reenter_live()
        self._swipe_times = 0
        return True
return False

8.6 阶段诊断状态

8.6.1 上次诊断信息

  • 属性名:
    • _last_diag_stage: str - 上次诊断的阶段
    • _last_diag_seen: str - 上次诊断看到的标识(如直播间标题)
    • _last_diag_ts: float - 上次诊断的时间戳

8.6.2 阶段诊断优化

  • 最小间隔: screenshot_diagnose_min_interval_seconds(默认8.0秒)
  • 作用: 避免频繁截图和诊断,提高效率

代码示例:

# 在 diagnose_stage_from_current_screen() 中
current_time = time.time()
min_interval = analyser.screenshot_diagnose_min_interval_seconds

# 如果距离上次诊断时间太短,且阶段未变化,直接返回上次结果
if (analyser._last_diag_ts > 0 and 
    current_time - analyser._last_diag_ts < min_interval and
    analyser._last_diag_stage != "UNKNOWN"):
    return analyser._last_diag_stage

8.7 状态持久化

8.7.1 预约状态持久化

  • 文件: state/reservations.json
  • 时机: 每次修改预约队列后自动保存
  • 格式: JSON格式,包含预约列表和更新时间戳

8.7.2 运行时状态

  • 内存状态: 大部分状态标志存储在内存中(重启后丢失)
  • 持久化状态: 只有预约数据持久化到文件
  • 恢复机制: 程序启动时自动加载预约数据

9. 错误处理和异常情况

9.1 错误处理策略

项目采用多层错误处理策略,确保程序在遇到异常时能够优雅降级或恢复:

  1. 底层操作错误处理:捕获ADB命令失败、文件操作失败等
  2. OCR识别错误处理:处理OCR失败、识别结果为空等
  3. 阶段诊断错误处理:处理诊断超时、识别失败等
  4. 流程控制错误处理:处理流程异常、状态不一致等

9.2 常见错误和恢复机制

9.2.1 截图失败

错误原因:

  • ADB连接断开
  • 设备锁屏
  • 设备无响应
  • 文件系统错误

处理机制:

def get_screenshot(self, device_id, path="pic"):
    # 优先方法:exec-out(1次adb调用)
    try:
        with open(tmp_file, "wb") as f:
            subprocess.run(
                [adb, "-s", device_id, "exec-out", "screencap", "-p"],
                stdout=f,
                stderr=subprocess.DEVNULL,
                check=True,
            )
        # 验证文件有效性
        if _valid_png(tmp_file):
            _safe_replace_file(tmp_file, out_file)
            return True
    except Exception:
        pass
    
    # 回退方法1:shell screencap + pull(2次adb调用)
    try:
        # ... 回退逻辑
    except Exception:
        pass
    
    # 回退方法2:使用screenshot1.png
    try:
        # ... 回退逻辑
    except Exception:
        return False  # 所有方法都失败

恢复策略:

  • 重试机制(最多2次)
  • 多种方法回退
  • 返回 False 让上层处理

9.2.2 OCR识别失败

错误原因:

  • 图片质量差
  • 文字区域裁剪错误
  • OCR引擎初始化失败
  • 识别结果为空

处理机制:

def analyse_pic_word(self, picname, change_color=0, pic_path=None):
    try:
        # 确保OCR已初始化
        self._ensure_ocr()
        if self.ocr is None:
            logger.error("OCR引擎未初始化")
            return ""
        
        # 加载图片
        pic_path = pic_path or self._find_pic_path(picname, for_reading=True)
        if not pic_path or not os.path.exists(pic_path):
            logger.error(f"图片文件不存在: {picname}")
            return ""
        
        # 执行OCR
        img = Image.open(pic_path)
        # ... OCR处理
        
        # 提取文本
        text = self.extract_ocr_content(result)
        return text if text else ""
    except Exception as e:
        logger.error(f"OCR识别失败: {e}")
        return ""  # 返回空字符串,让上层处理

恢复策略:

  • 返回空字符串,让上层判断
  • 上层可以重试或跳过该步骤
  • 记录错误日志

9.2.3 阶段诊断超时

错误原因:

  • 截图失败
  • OCR识别超时
  • 像素检测超时
  • 设备响应慢

处理机制:

def diagnose_stage_from_current_screen(analyser):
    max_time = analyser.config.get("stage_diag_max_time", 5.0)
    start_time = time.time()
    
    try:
        # 步骤0: 检测直播间(优先级最高)
        if time.time() - start_time > max_time:
            return "UNKNOWN"
        
        # 步骤1: 并行像素检测
        if time.time() - start_time > max_time:
            return "UNKNOWN"
        
        # ... 其他步骤
        
    except Exception as e:
        logger.error(f"阶段诊断异常: {e}")
        return "UNKNOWN"
    
    return "UNKNOWN"  # 默认返回未知阶段

恢复策略:

  • 设置超时时间(stage_diag_max_time)
  • 超时后返回 UNKNOWN
  • 上层根据 UNKNOWN 执行默认逻辑(导航到直播间)

9.2.4 福袋查找失败

错误原因:

  • 福袋图标未出现
  • 像素检测失败
  • 模板匹配失败
  • 超时

处理机制:

def find_fudai_icon(analyser):
    max_wait = analyser.fudai_icon_max_wait_seconds
    start_time = time.time()
    
    while time.time() - start_time < max_wait:
        try:
            # 获取截图
            if not analyser.operation.get_screenshot(analyser.device_id):
                time.sleep(analyser.fudai_icon_retry_delay_seconds)
                continue
            
            # 查找福袋图标
            result = _find_fudai_icon_internal(analyser)
            if result:
                return result
            
            # 等待后重试
            time.sleep(analyser.fudai_icon_retry_delay_seconds)
        except Exception as e:
            logger.error(f"查找福袋图标异常: {e}")
            time.sleep(analyser.fudai_icon_retry_delay_seconds)
    
    # 超时返回None
    logger.warning(f"查找福袋图标超时({max_wait}秒)")
    return None

恢复策略:

  • 设置最大等待时间(fudai_icon_max_wait_seconds)
  • 超时后返回 None
  • 上层根据 None 执行默认逻辑(切换直播间或返回)

9.2.5 福袋详情页加载失败

错误原因:

  • 点击福袋图标后页面未加载
  • 详情页元素未出现
  • 超时

处理机制:

def _handle_in_fudai_detail(self):
    # 等待详情页加载
    initial_wait = self.config.get("fudai_detail_initial_wait_seconds", 0.8)
    time.sleep(initial_wait)
    
    # 验证详情页是否加载成功
    if self.fudai_click_verify_enabled:
        max_retries = self.fudai_find_max_retries
        for i in range(max_retries):
            try:
                if not self.operation.get_screenshot(self.device_id):
                    continue
                
                # 检测详情页
                stage = diagnose_stage_from_current_screen(self)
                if stage == "FUDai_DETAIL":
                    break  # 加载成功
                
                # 等待后重试
                time.sleep(self.config.get("fudai_detail_retry_delay_seconds", 0.5))
            except Exception as e:
                logger.error(f"验证详情页加载异常: {e}")
        
        # 如果仍然失败,记录警告但继续处理
        if stage != "FUDai_DETAIL":
            logger.warning("福袋详情页加载验证失败,但继续处理")

恢复策略:

  • 重试机制(最多N次)
  • 验证失败后记录警告但继续处理
  • 如果OCR识别失败,返回空值让上层处理

9.2.6 预约回退失败

错误原因:

  • 找不到目标直播间
  • 滑动次数超限
  • 直播间已关闭
  • 标题匹配失败

处理机制:

def process_reservation_attend_window(analyser, ...):
    try:
        # 查找目标直播间
        if not seek_reservation_room_callback(item):
            logger.warning(f"找不到预约直播间: {item.get('room_title')}")
            return False
        
        # 回退到目标直播间
        swipe_down_back_callback()
        time.sleep(reservation_back_swipe_delay_s)
        
        # 验证是否在目标直播间
        if analyser.config.get("reservation_back_verify_enabled", True):
            if not verify_reservation_room(analyser, item):
                logger.warning("预约回退验证失败")
                return False
        
        return True
    except Exception as e:
        logger.error(f"预约回退异常: {e}")
        return False

恢复策略:

  • 验证失败后返回 False
  • 上层可以重试或跳过该预约
  • 记录错误日志

9.3 异常情况处理

9.3.1 设备断开连接

检测: ADB命令执行失败 处理:

  • 记录错误日志
  • 返回错误状态
  • 上层可以重试或退出

9.3.2 直播间关闭

检测: 阶段诊断返回 LIVE_CLOSED 处理:

  • 切换到下一个直播间
  • 或返回推荐页面

9.3.3 网络异常

检测: OCR初始化失败、网络请求超时 处理:

  • 使用本地OCR引擎(PaddleOCR)
  • 重试机制
  • 降级处理

9.3.4 状态不一致

检测: 阶段诊断结果与预期不符 处理:

  • 重新诊断
  • 导航到正确页面
  • 重置相关状态

9.4 错误日志记录

所有错误都会记录到日志系统:

# 统一日志记录
logger.error(f"错误描述: {error}", exc_info=True)

# 带上下文的错误记录
logger.error(
    f"OCR识别失败: {picname}",
    extra={
        "picname": picname,
        "pic_path": pic_path,
        "error": str(e)
    }
)

10. 代码示例

10.1 完整运行示例

# run_cli.py
from douyin.core.douyin_fudai import fudai_analyse
from douyin.core.underlying_operations import underlying_operations

# 初始化
operation = underlying_operations()
device_id = operation.select_device()
if not device_id:
    print("未检测到设备")
    exit(1)

# 创建分析器
analyser = fudai_analyse()
analyser.device_id = device_id

# 获取设备分辨率
width, height = operation.get_device_resolution(device_id)
analyser.resolution_ratio_x = width
analyser.resolution_ratio_y = height

# 加载配置
analyser.load_config()

# 开始主循环
analyser.fudai_choujiang()

10.2 阶段诊断示例

# 获取截图
if not analyser.operation.get_screenshot(analyser.device_id):
    logger.error("截图失败")
    return

# 阶段诊断
stage = diagnose_stage_from_current_screen(analyser)
logger.info(f"当前阶段: {stage}")

# 根据阶段执行逻辑
if stage == "IN_LIVE_ROOM":
    # 处理直播间逻辑
    analyser._handle_live_room_has_or_not_fudai()
elif stage == "FUDai_DETAIL":
    # 处理福袋详情页
    analyser._handle_in_fudai_detail()
elif stage == "FUDai_RESULT":
    # 处理开奖结果
    analyser._handle_lottery_result()
else:
    # 导航到直播间
    analyser._navigate_to_live_room()

10.3 福袋信息获取示例

# 获取福袋信息(并行OCR)
content, countdown_text, participants, task_count, prize_value_yuan = \
    get_fudai_contain(analyser, renwu=2)

logger.info(f"福袋内容: {content}")
logger.info(f"倒计时: {countdown_text}")
logger.info(f"参与人数: {participants}")
logger.info(f"任务数量: {task_count}")
logger.info(f"奖品价值: {prize_value_yuan}元")

# 判断是否参与
if basic_join_decision(analyser, {
    "content": content,
    "countdown_text": countdown_text,
    "participants": participants,
    "task_count": task_count,
    "prize_value_yuan": prize_value_yuan
}):
    # 参与福袋
    attend_choujiang(analyser)

10.4 预约管理示例

# 加载预约数据
load_reservations_from_state(analyser)

# 添加预约
if prize_value_yuan >= analyser.config.get("high_value_fudai_threshold_yuan", 500.0):
    reservation = {
        "room_title": room_title,
        "room_pos": room_pos,
        "lottery_time_ts": time.time() + countdown_seconds,
        "prize_value_yuan": prize_value_yuan,
        "fudai_x": fudai_x
    }
    analyser.reservations.append(reservation)
    save_reservations_to_state(analyser)

# 处理预约回退窗口
if process_reservation_attend_window(
    analyser,
    analyser.reservations,
    room_pos,
    reservation_focus_until_ts_ref,
    reservation_after_action_pending_ref,
    reservation_back_swipe_delay_s,
    swipe_down_back_callback,
    seek_reservation_room_callback,
    sort_reservations_callback,
    write_state_callback
):
    logger.info("已触发预约回退")
    return

11. 模块详解

11.1 核心模块 (douyin/core/)

11.1.1 douyin_fudai.py - 主调度器

  • 职责: 核心调度器,主流程控制
  • 主要类: fudai_analyse(使用Mixin模式组合功能)
  • 设计模式: Mixin组合模式
  • 主要方法:
    • fudai_choujiang(): 主循环入口
    • run_once_basic(): 单次循环执行,包含所有核心逻辑;检查 _just_recorded_reservation 标志并强制切换直播间
    • load_config(): 加载配置

11.1.2 douyin_flow_control.py - 流程控制

  • 职责: 流程控制辅助函数
  • 主要函数:
    • find_and_open_fudai_detail(): 查找并打开福袋详情
    • handle_no_fudai_situation(): 处理无福袋情况

11.1.3 fudai_modules/ - Mixin模块

  • NavigationMixin: 导航功能(滑动、返回等)
  • StageDetectionMixin: 阶段检测
  • PopupHandlerMixin: 弹窗处理
  • LotteryResultMixin: 抽奖结果处理
  • RoomUtilsMixin: 直播间工具
  • MainLogicMixin: 主逻辑

11.2 阶段诊断模块 (douyin/stage/)

11.2.1 douyin_stage.py - 阶段诊断核心

  • 职责: 综合诊断当前页面阶段
  • 主要函数: diagnose_stage_from_current_screen()
  • 支持的阶段: IN_LIVE_ROOM, RECOMMEND_PAGE, FUDai_DETAIL, FUDai_RESULT, 等

11.2.2 douyin_stage_handler.py - 阶段处理

  • 职责: 阶段处理逻辑,包括直播间检测等

11.3 检测模块 (douyin/detection/)

11.3.1 douyin_pixel.py - 像素检测

  • 职责: 像素级检测(弹窗、按钮、页面等)
  • 主要函数:
    • read_pixel_stage_state_from_screenshot(): 并行像素检测
    • detect_live_room_icons_by_pixel(): 检测直播间图标
    • detect_attend_button_red_area(): 检测参与按钮
    • detect_fansclub_join_red_area(): 检测粉丝团加入按钮
    • detect_coupon_popup_background(): 检测优惠券弹窗
    • detect_redpacket_popup_background(): 检测红包弹窗
    • detect_lucky_draw_result_popup(): 检测开奖结果弹窗
    • detect_fudai_detail_page(): 检测福袋详情页

11.3.2 douyin_detection.py - 综合检测

  • 职责: 整合像素、模板、OCR检测
  • 主要函数: check_have_fudai_with_ready_screenshot()

11.4 福袋模块 (douyin/fudai/)

11.4.1 douyin_fudai_core.py - 福袋核心逻辑

  • 职责: 福袋核心业务逻辑
  • 主要函数:
    • get_fudai_contain(): 获取福袋信息(并行OCR)
    • basic_join_decision(): 判断是否参与;支持预约更新后的强制切换(设置 _just_recorded_reservation 标志并返回 False 触发切换,避免循环)

11.4.2 douyin_fudai_detail.py - 福袋详情处理

  • 职责: 福袋详情页处理

11.4.3 douyin_fudai_finder.py - 福袋查找器

  • 职责: 查找福袋图标

11.4.4 core/ - 福袋核心子模块

  • fudai_filter.py: 福袋筛选逻辑
  • fudai_result_checker.py: 开奖结果检查
  • fudai_attend.py: 参与抽奖逻辑

11.5 预约模块 (douyin/reservation/)

11.5.1 douyin_reservation_logic.py - 预约逻辑

  • 职责: 高价值福袋预约核心逻辑
  • 主要函数:
    • load_reservations_from_state(): 加载预约数据
    • process_reservation_attend_window(): 处理预约回退窗口
    • add_reservation(): 添加预约
    • sort_reservations(): 排序预约队列

11.5.2 douyin_reservation_handler.py - 预约处理器

  • 职责: 预约处理逻辑

11.6 处理器模块 (douyin/handlers/)

11.6.1 douyin_popup_handler.py - 弹窗处理器

  • 职责: 弹窗检测与处理

11.6.2 douyin_screenshot_handler.py - 截图处理器

  • 职责: 截图处理逻辑

11.6.3 douyin_swipe_handler.py - 滑动处理器

  • 职责: 滑动操作处理

11.7 工具模块 (douyin/utils/)

11.7.1 douyin_config.py - 配置管理

  • 职责: 配置加载和管理

11.7.2 douyin_helpers.py - 辅助函数

  • 职责: 通用辅助函数

11.7.3 douyin_text_utils.py - 文本工具

  • 职责: 文本处理工具(倒计时解析、价值提取等)

12. 数据流和状态管理

12.1 数据流概述

项目的数据流主要分为以下几个阶段:

  1. 输入: ADB截图 → 图像数据
  2. 处理: 图像处理 → OCR识别 → 阶段诊断 → 决策
  3. 输出: 点击操作 → 滑动操作 → 状态更新

12.2 主要数据流

12.2.1 截图数据流

ADB设备
  ↓ (adb exec-out screencap -p)
截图文件 (pic/screenshot.png)
  ↓ (PIL.Image.open)
图像对象 (PIL.Image)
  ↓ (转换为RGB)
RGB图像 (Image.Image)
  ↓ (裁剪/处理)
处理后的图像

12.2.2 OCR数据流

裁剪后的图像
  ↓ (OCR引擎识别)
OCR原始结果 (List)
  ↓ (extract_ocr_content)
文本字符串 (str)
  ↓ (文本处理)
结构化数据 (dict)

12.2.3 阶段诊断数据流

截图文件
  ↓ (并行像素检测)
像素检测结果 (dict)
  ↓ (模板匹配)
模板匹配结果 (bool)
  ↓ (OCR识别)
OCR识别结果 (str)
  ↓ (综合判断)
阶段结果 (str)

12.2.4 预约数据流

福袋信息
  ↓ (判断是否高价值)
高价值判断 (bool)
  ↓ (添加到预约队列)
预约对象 (dict)
  ↓ (保存到文件)
state/reservations.json
  ↓ (加载预约数据)
内存中的预约列表
  ↓ (处理预约窗口)
预约回退操作

12.3 状态转换图

[初始化]
  ↓
[主循环开始]
  ↓
[加载预约数据]
  ↓
[处理预约回退窗口]
  ├─> 触发回退 → [回退到目标直播间] → [参与福袋] → [清除预约]
  └─> 未触发 → 继续
  ↓
[获取截图]
  ↓
[阶段诊断]
  ├─> IN_LIVE_ROOM → [查找福袋] → [打开详情页] → [处理详情页]
  ├─> FUDai_DETAIL → [获取福袋信息] → [判断是否参与] → [参与/跳过]
  ├─> FUDai_RESULT → [检查开奖结果] → [领取奖品/关闭]
  └─> 其他 → [导航到直播间]
  ↓
[更新状态]
  ├─> 成功参与 → 更新 _last_successful_attend_ts
  ├─> 添加预约 → 更新 reservations
  └─> 等待开奖 → 设置 _waiting_for_lottery_result
  ↓
[检查超时]
  ├─> 30分钟超时 → [返回推荐页]
  └─> 未超时 → 继续
  ↓
[主循环结束]
  ↓
[等待/继续循环]

13. 关键技术实现

13.1 像素检测技术

13.1.1 原理

像素检测通过分析指定区域的像素颜色特征来判断UI元素的存在。主要步骤:

  1. 区域定义: 基于基准分辨率(1080x2400)定义检测区域
  2. 坐标缩放: 根据实际设备分辨率缩放坐标
  3. 像素采样: 在检测区域内采样像素点
  4. 特征匹配: 根据颜色特征(RGB值)判断是否符合预期
  5. 阈值判断: 计算符合特征的像素占比,与阈值比较

13.1.2 实现示例

def detect_attend_button_red_area(
    pic_rgb: Image.Image,
    red_ratio_threshold: float = 0.25,
    return_info: bool = False
) -> bool | tuple[bool, dict]:
    """检测参与按钮红色区域"""
    width, height = pic_rgb.size
    scale_x = width / 1080.0
    scale_y = height / 2400.0
    
    # 定义检测区域(基于1080x2400)
    x1 = int(100 * scale_x)
    y1 = int(1500 * scale_y)
    x2 = int(980 * scale_x)
    y2 = int(1700 * scale_y)
    
    # 采样像素
    red_count = 0
    total_samples = 0
    step_x = max(1, (x2 - x1) // 10)
    step_y = max(1, (y2 - y1) // 10)
    
    for y in range(y1, y2, step_y):
        for x in range(x1, x2, step_x):
            r, g, b = pic_rgb.getpixel((x, y))
            total_samples += 1
            # 红色按钮特征:R >= 245 且 R 明显大于 G 和 B
            if r >= 245 and (r - g) >= 50 and (r - b) >= 50:
                red_count += 1
    
    # 计算红色占比
    red_ratio = red_count / total_samples if total_samples > 0 else 0.0
    result = red_ratio >= red_ratio_threshold
    
    return result if not return_info else (result, {
        "red_ratio": red_ratio,
        "red_count": red_count,
        "total_samples": total_samples
    })

13.1.3 并行像素检测

使用 ThreadPoolExecutor 并行执行多个像素检测任务:

def read_pixel_stage_state_from_screenshot(
    pic_path: str,
    ...
) -> dict[str, bool]:
    """并行执行所有像素检测"""
    pic_rgb = _safe_open_screenshot_rgb(pic_path)
    
    # 定义检测任务
    detection_tasks = {
        "has_coupon_bg": lambda pic: detect_coupon_popup_background(pic, ...),
        "has_redpacket_bg": detect_redpacket_popup_background,
        "has_lucky_draw_result": lambda pic: detect_lucky_draw_result_popup(pic, ...),
        "has_attend_button_red": lambda pic: detect_attend_button_red_area(pic, ...),
        "has_fansclub_join_red": lambda pic: detect_fansclub_join_red_area(pic, ...),
        "has_fudai_detail": lambda pic: detect_fudai_detail_page(pic, ...),
    }
    
    # 使用线程池并行执行
    with ThreadPoolExecutor(max_workers=6) as executor:
        futures = {
            key: executor.submit(task, pic_rgb)
            for key, task in detection_tasks.items()
        }
        
        # 等待所有任务完成
        results = {}
        for key, future in futures.items():
            try:
                result = future.result(timeout=2.0)
                results[key] = result if isinstance(result, bool) else result[0]
            except Exception as e:
                results[key] = False
    
    return results

13.2 模板匹配技术

13.2.1 原理

模板匹配使用OpenCV的模板匹配算法,在截图中查找模板图片的位置。主要步骤:

  1. 模板准备: 准备模板图片(如福袋图标、直播间图标等)
  2. 图像预处理: 将截图和模板转换为灰度图
  3. 模板匹配: 使用 cv2.matchTemplate() 进行匹配
  4. 阈值判断: 计算匹配分数,与阈值比较

13.2.2 实现示例

import cv2
import numpy as np
from PIL import Image

def detect_fudai_detail_page(
    pic_rgb: Image.Image,
    template_threshold: float = 0.7,
    ...
) -> bool:
    """使用模板匹配检测福袋详情页"""
    try:
        # 加载模板图片
        template_path = "assets/fudai_detail_template.png"
        template = cv2.imread(template_path, cv2.IMREAD_GRAYSCALE)
        if template is None:
            return False
        
        # 转换截图
        pic_gray = cv2.cvtColor(np.array(pic_rgb), cv2.COLOR_RGB2GRAY)
        
        # 模板匹配
        result = cv2.matchTemplate(pic_gray, template, cv2.TM_CCOEFF_NORMED)
        min_val, max_val, min_loc, max_loc = cv2.minMaxLoc(result)
        
        # 判断匹配分数
        return max_val >= template_threshold
    except Exception:
        return False

13.3 OCR识别技术

13.3.1 OCR引擎选择

项目支持两种OCR引擎:

  1. EasyOCR(优先): 速度快,识别准确率高
  2. PaddleOCR(回退): 兼容性好,支持中文

13.3.2 并行OCR处理

使用 ThreadPoolExecutor 并行执行多个OCR任务:

def get_fudai_contain(analyser, renwu: int = 2):
    """并行OCR获取福袋信息"""
    
    def ocr_content():
        analyser.operation.cut_pic(..., name="福袋内容")
        return analyser.operation.analyse_pic_word("福袋内容")
    
    def ocr_countdown_mm():
        analyser.operation.cut_pic(..., name="倒计时分钟")
        return analyser.operation.analyse_pic_digits("倒计时分钟")
    
    def ocr_countdown_ss():
        analyser.operation.cut_pic(..., name="倒计时秒数")
        return analyser.operation.analyse_pic_digits("倒计时秒数")
    
    def ocr_value():
        analyser.operation.cut_pic(..., name="奖品价值")
        return analyser.operation.analyse_pic_digits("奖品价值")
    
    def ocr_button():
        analyser.operation.cut_pic(..., name="参与按钮")
        return analyser.operation.analyse_pic_word("参与按钮")
    
    # 并行执行所有OCR任务
    with ThreadPoolExecutor(max_workers=6) as executor:
        future_content = executor.submit(ocr_content)
        future_countdown_mm = executor.submit(ocr_countdown_mm)
        future_countdown_ss = executor.submit(ocr_countdown_ss)
        future_value = executor.submit(ocr_value)
        future_button = executor.submit(ocr_button)
        
        # 等待所有任务完成
        content = future_content.result()
        countdown_mm = future_countdown_mm.result()
        countdown_ss = future_countdown_ss.result()
        value = future_value.result()
        button_text = future_button.result()
    
    # 处理结果
    # ...

13.3.3 OCR结果处理

def extract_ocr_content(content: List, return_confidence: bool = False) -> str:
    """从OCR结果中提取文本"""
    texts = []
    confidences = []
    
    for item in content:
        if isinstance(item, (list, tuple)) and len(item) >= 2:
            # EasyOCR格式: [[坐标], 文本, 置信度]
            if len(item) >= 3:
                text = item[1]
                confidence = item[2]
            # PaddleOCR格式: [[坐标], [文本, 置信度]]
            elif len(item) >= 2 and isinstance(item[1], (list, tuple)):
                text = item[1][0]
                confidence = item[1][1]
            else:
                continue
            
            texts.append(text)
            confidences.append(confidence)
    
    # 拼接文本
    result_text = " ".join(texts)
    
    if return_confidence:
        avg_confidence = sum(confidences) / len(confidences) if confidences else 0.0
        return result_text, avg_confidence
    
    return result_text

13.4 并行处理技术

13.4.1 线程池使用

项目使用 concurrent.futures.ThreadPoolExecutor 实现并行处理:

from concurrent.futures import ThreadPoolExecutor, as_completed

# 创建线程池
with ThreadPoolExecutor(max_workers=6) as executor:
    # 提交任务
    futures = {
        "task1": executor.submit(func1, arg1),
        "task2": executor.submit(func2, arg2),
        "task3": executor.submit(func3, arg3),
    }
    
    # 等待所有任务完成
    results = {}
    for key, future in futures.items():
        try:
            results[key] = future.result(timeout=5.0)
        except Exception as e:
            results[key] = None
            logger.error(f"任务{key}失败: {e}")

13.4.2 并行处理场景

  1. 像素检测: 并行检测多个UI元素(弹窗、按钮等)
  2. OCR识别: 并行识别多个文本区域(内容、倒计时、价值等)
  3. 阶段诊断: 并行执行多种检测方法(像素、模板、OCR)

14. 扩展指南和最佳实践

14.1 添加新的检测方法

14.1.1 添加像素检测函数

  1. 在 douyin/detection/douyin_pixel.py 中添加新函数
  2. 在 read_pixel_stage_state_from_screenshot() 中添加检测任务
  3. 在阶段诊断中使用检测结果

示例:

def detect_new_popup(pic_rgb: Image.Image, threshold: float = 0.5) -> bool:
    """检测新弹窗"""
    width, height = pic_rgb.size
    scale_x = width / 1080.0
    scale_y = height / 2400.0
    
    # 定义检测区域
    x1 = int(100 * scale_x)
    y1 = int(200 * scale_y)
    x2 = int(980 * scale_x)
    y2 = int(400 * scale_y)
    
    # 检测逻辑
    # ...
    
    return result

14.1.2 添加模板匹配检测

  1. 准备模板图片(放在 assets/ 目录)
  2. 在检测函数中使用 cv2.matchTemplate()
  3. 在阶段诊断中调用检测函数

14.2 添加新的阶段类型

  1. 在 douyin/stage/douyin_stage.py 中定义新阶段常量
  2. 在 diagnose_stage_from_current_screen() 中添加检测逻辑
  3. 在 run_once_basic() 中添加处理逻辑

示例:

# 定义新阶段
NEW_STAGE = "NEW_STAGE"

# 在阶段诊断中添加检测
def diagnose_stage_from_current_screen(analyser):
    # ... 现有检测逻辑
    
    # 检测新阶段
    if detect_new_stage(analyser):
        return NEW_STAGE
    
    # ...

# 在主循环中添加处理
def run_once_basic(self):
    # ...
    stage = diagnose_stage_from_current_screen(self)
    if stage == NEW_STAGE:
        self._handle_new_stage()
    # ...

14.3 添加新的配置项

  1. 在 config/config.json 中添加配置项
  2. 在 fudai_analyse.__init__() 中初始化属性
  3. 在 load_config() 中加载配置

示例:

# 在 __init__() 中
self.new_config_item: bool = False

# 在 load_config() 中
self.new_config_item = self.config.get("new_config_item", False)

14.4 最佳实践

14.4.1 错误处理

  • 所有可能失败的操作都应该有异常处理
  • 使用 try-except 捕获异常,记录日志,返回默认值
  • 不要让异常中断主循环

14.4.2 日志记录

  • 使用统一的日志系统记录关键操作
  • 记录足够的上下文信息(参数、结果、错误等)
  • 使用适当的日志级别(DEBUG、INFO、WARNING、ERROR)

14.4.3 性能优化

  • 使用并行处理提高效率(像素检测、OCR识别)
  • 避免频繁截图(使用最小间隔)
  • 缓存识别结果(避免重复识别)

14.4.4 代码组织

  • 使用模块化设计,功能拆分到独立模块
  • 使用Mixin模式组合功能
  • 保持函数职责单一,易于测试和维护

15. 关键文件索引和调试指南

15.1 关键文件索引

15.1.1 入口文件

  • bin/run_cli.py: 命令行入口,初始化设备和分析器
  • gui/gui_app.py: Tkinter GUI入口
  • gui/web_gui.py: Web GUI入口

15.1.2 核心文件

  • douyin/core/douyin_fudai.py: 主调度器类 fudai_analyse
  • douyin/core/douyin_main_flow.py: 主流程控制

15.1.3 阶段诊断

  • douyin/stage/douyin_stage.py: 阶段诊断核心逻辑
  • douyin/stage/douyin_stage_handler.py: 阶段处理逻辑

15.1.4 检测模块

  • douyin/detection/douyin_pixel.py: 像素检测函数
  • douyin/detection/douyin_detection.py: 综合检测逻辑

15.1.5 福袋模块

  • douyin/fudai/douyin_fudai_detail.py: 福袋详情处理
  • douyin/fudai/douyin_fudai_finder.py: 福袋查找器
  • douyin/fudai/core/fudai_attend.py: 参与抽奖逻辑
  • douyin/fudai/core/fudai_result_checker.py: 开奖结果检查

15.1.6 预约模块

  • douyin/reservation/douyin_reservation_logic.py: 预约核心逻辑
  • douyin/reservation/douyin_reservation_handler.py: 预约处理器

15.1.7 底层操作

  • douyin/core/underlying_operations.py: 底层操作类(ADB、OCR、图像处理)

15.1.8 配置文件

  • config/config.json: 主配置文件
  • state/reservations.json: 预约状态文件

15.2 调试指南

15.2.1 启用调试日志

在 config.json 中设置:

{
  "logging": {
    "level": "DEBUG",
    "debug_detail_level": "detailed"
  }
}

15.2.2 保存调试图像

在 config.json 中设置:

{
  "fudai_detail_save_debug_images": true,
  "debug_captures": {
    "enabled": true,
    "keep_days": 3
  }
}

调试图像保存在 pic/debug/ 目录下。

15.2.3 常见问题排查

问题1: 截图失败

  • 检查ADB连接: adb devices
  • 检查设备是否锁屏
  • 检查文件系统权限

问题2: OCR识别失败

  • 检查OCR引擎是否初始化成功
  • 检查图片质量
  • 检查裁剪区域是否正确

问题3: 阶段诊断错误

  • 检查截图是否成功
  • 检查检测阈值是否合适
  • 查看调试图像确认检测区域

问题4: 预约回退失败

  • 检查预约数据是否正确
  • 检查直播间标题匹配
  • 检查滑动次数是否超限

15.2.4 日志分析

日志文件位置:

  • 统一日志: logs/unified_YYYY-MM-DD.log
  • 操作日志: logs/action_YYYY-MM-DD.log

关键日志标签:

  • [截图]: 截图相关操作
  • [阶段诊断]: 阶段诊断结果
  • [福袋查找]: 福袋查找过程
  • [OCR识别]: OCR识别结果
  • [预约]: 预约相关操作
  • [参与]: 参与抽奖操作

15.2.5 性能分析

启用性能跟踪:

{
  "logging": {
    "performance_tracking": {
      "enabled": true,
      "track_function_calls": true,
      "slow_operation_threshold_ms": 100
    }
  }
}

查看日志中的执行时间信息,识别性能瓶颈。

15.2.6 阶段诊断详细步骤说明

阶段诊断是项目的核心功能之一,以下是详细的步骤说明:

步骤0: 检测直播间(最优先)

  1. 像素检测(优先级最高)

    • 检测右上角区域(60%-100%宽度,0%-40%高度)的像素特征
    • 检测x图标(白色/浅色)和xin图标(粉色/红色)
    • 计算置信度(0.0~1.0)
    • 如果置信度 >= live_room_match_threshold(默认0.8),判定为在直播间
  2. 模板匹配(像素检测失败时)

    • 使用OpenCV模板匹配检测直播间图标
    • 匹配模板:assets/x.png 和 assets/xin.png
    • 计算匹配分数(0.0~1.0)
    • 如果分数 >= live_room_match_threshold,判定为在直播间
  3. OCR回退(前两种方法都失败时)

    • 裁剪直播间标题区域
    • OCR识别标题文本
    • 如果识别到文本,判定为在直播间

步骤1: 并行像素检测

使用 ThreadPoolExecutor 并行执行以下检测:

  1. 优惠券弹窗检测 (has_coupon_bg)

    • 检测区域:底部中央区域
    • 方法:模板匹配 + 像素检测
    • 阈值:coupon_template_match_threshold(默认0.4)
  2. 红包弹窗检测 (has_redpacket_bg)

    • 检测区域:中央区域
    • 方法:像素检测(红色背景)
  3. 开奖结果弹窗检测 (has_lucky_draw_result)

    • 检测区域:"我知道了"按钮区域(181, 1261)- (890, 1389)
    • 方法:像素检测(红色占比)
    • 阈值:lucky_draw_red_ratio_threshold(默认0.8)
  4. 参与按钮检测 (has_attend_button_red)

    • 检测区域:参与按钮区域
    • 方法:像素检测(红色占比)
    • 阈值:attend_button_red_ratio_threshold(默认0.25)
  5. 粉丝团加入按钮检测 (has_fansclub_join_red)

    • 检测区域:粉丝团加入按钮区域
    • 方法:像素检测(红色占比)
    • 阈值:fansclub_join_red_ratio_threshold(默认0.25)
  6. 福袋详情页检测 (has_fudai_detail)

    • 检测区域:福袋详情页特征区域
    • 方法:模板匹配 + 像素检测
    • 阈值:fudai_detail_template_threshold(默认0.54)

步骤2: 根据检测结果判断阶段

  1. 如果检测到开奖结果弹窗 → 返回 FUDai_RESULT
  2. 如果检测到福袋详情页 → 返回 FUDai_DETAIL
  3. 如果检测到粉丝团加入按钮 → 返回 FANSCLUB_JOIN
  4. 如果检测到优惠券/红包弹窗 → 处理弹窗后继续
  5. 如果在直播间 → 返回 IN_LIVE_ROOM
  6. 其他情况 → 返回 UNKNOWN 或 RECOMMEND_PAGE

超时保护:

  • 总诊断时间不超过 stage_diag_max_time(默认5.0秒)
  • 每个步骤不超过 stage_diag_max_step_time(默认2.0秒)
  • 超时后返回 UNKNOWN

15.2.7 常见错误代码和解决方案

错误代码/现象 可能原因 解决方案
截图失败 ADB连接断开、设备锁屏 检查ADB连接、解锁设备
OCR识别失败 OCR引擎未初始化、图片质量差 检查OCR引擎、提高图片质量
阶段诊断超时 设备响应慢、检测步骤过多 增加超时时间、优化检测逻辑
福袋查找失败 福袋图标未出现、检测阈值过高 降低检测阈值、增加等待时间
预约回退失败 找不到目标直播间、滑动次数超限 检查预约数据、增加最大滑动次数
参与失败 按钮状态识别错误、前置条件未满足 检查按钮识别、处理前置条件

15.2.8 性能优化建议

  1. 减少截图频率

    • 使用 screenshot_diagnose_min_interval_seconds 控制最小间隔
    • 缓存截图结果(如果阶段未变化)
  2. 优化OCR识别

    • 使用并行OCR处理多个区域
    • 缓存识别结果(5秒内有效)
    • 使用EasyOCR(比PaddleOCR快)
  3. 优化像素检测

    • 使用并行检测多个UI元素
    • 减少采样点数(在保证准确性的前提下)
    • 使用合适的阈值(避免过度检测)
  4. 优化阶段诊断

    • 优先使用快速检测方法(像素检测 > 模板匹配 > OCR)
    • 设置合理的超时时间
    • 避免重复检测(使用缓存)

15.2.9 调试技巧

  1. 启用详细日志

    {
      "stage_diag_verbose": true,
      "logging": {
        "level": "DEBUG"
      }
    }
    
  2. 保存调试图像

    {
      "fudai_detail_save_debug_images": true,
      "debug_captures": {
        "enabled": true
      }
    }
    
  3. 查看日志文件

    • 统一日志:logs/unified_YYYY-MM-DD.log
    • 操作日志:logs/action_YYYY-MM-DD.log
    • 使用 grep 或文本编辑器搜索关键词
  4. 使用调试截图

    • 调试截图保存在 pic/debug_captures/YYYY-MM-DD/ 目录
    • 文件名包含时间戳和操作类型
    • 可以查看OCR识别前后的图像对比
  5. 性能分析

    • 启用性能跟踪:"performance_tracking": {"enabled": true}
    • 查看日志中的执行时间信息
    • 识别性能瓶颈(慢操作阈值:100ms)

16. 高级主题和深入理解

16.1 Mixin模式详解

16.1.1 Mixin模式原理

Mixin模式是一种多重继承的设计模式,用于在不使用传统继承的情况下组合功能。

优点:

  • 功能模块化: 每个Mixin负责特定功能,职责清晰
  • 代码复用: 可以在多个类中复用相同的功能
  • 灵活组合: 可以根据需要组合不同的Mixin
  • 易于测试: 每个Mixin可以独立测试

实现方式:

class fudai_analyse(
    NavigationMixin,        # 导航功能
    StageDetectionMixin,    # 阶段检测
    PopupHandlerMixin,      # 弹窗处理
    LotteryResultMixin,     # 抽奖结果
    RoomUtilsMixin,         # 直播间工具
    MainLogicMixin,         # 主逻辑
):
    def __init__(self):
        # 初始化所有Mixin需要的属性
        # ...

16.1.2 Mixin方法解析顺序(MRO)

Python使用C3线性化算法确定方法解析顺序(MRO):

# 查看MRO
print(fudai_analyse.__mro__)
# 输出: (
#   <class 'fudai_analyse'>,
#   <class 'NavigationMixin'>,
#   <class 'StageDetectionMixin'>,
#   <class 'PopupHandlerMixin'>,
#   <class 'LotteryResultMixin'>,
#   <class 'RoomUtilsMixin'>,
#   <class 'MainLogicMixin'>,
#   <class 'BaseFudaiMixin'>,
#   <class 'object'>
# )

方法查找顺序:

  1. 首先在 fudai_analyse 类中查找
  2. 然后按照MRO顺序在各个Mixin中查找
  3. 找到第一个匹配的方法后停止

16.2 坐标系统详解

16.2.1 基准分辨率

项目使用 1080x2400 作为基准分辨率,所有坐标都基于这个分辨率定义。

原因:

  • 抖音App在不同设备上的UI布局是相对固定的
  • 使用基准分辨率可以适配不同设备
  • 通过缩放比例转换到实际分辨率

16.2.2 坐标缩放

def _scale_from_base(self, base_x: int, base_y: int) -> tuple[int, int]:
    """从基准分辨率缩放到实际分辨率"""
    rx = self.resolution_ratio_x  # 实际宽度
    ry = self.resolution_ratio_y  # 实际高度
    scaled_x = int(base_x * rx // 1080)
    scaled_y = int(base_y * ry // 2400)
    return scaled_x, scaled_y

示例:

  • 基准坐标: (540, 1200)(屏幕中心)
  • 实际分辨率: 1440x3200
  • 缩放后: (720, 1600)

16.2.3 Y轴偏移(y_pianyi)

某些设备可能有状态栏或导航栏,需要Y轴偏移:

actual_y = base_y + y_pianyi

16.3 并行处理详解

16.3.1 ThreadPoolExecutor使用

from concurrent.futures import ThreadPoolExecutor, as_completed

# 创建线程池
with ThreadPoolExecutor(max_workers=6) as executor:
    # 提交任务
    futures = {
        "task1": executor.submit(func1, arg1),
        "task2": executor.submit(func2, arg2),
        "task3": executor.submit(func3, arg3),
    }
    
    # 等待所有任务完成
    results = {}
    for key, future in futures.items():
        try:
            results[key] = future.result(timeout=5.0)
        except Exception as e:
            results[key] = None
            logger.error(f"任务{key}失败: {e}")

16.3.2 线程池大小选择

  • CPU密集型任务: max_workers = CPU核心数
  • I/O密集型任务: max_workers = CPU核心数 * 2 或更多
  • 混合任务: 根据实际情况调整

本项目:

  • OCR识别:I/O密集型(文件读取、图像处理)
  • 像素检测:CPU密集型(像素计算)
  • 综合使用:max_workers=6(平衡性能和资源)

16.4 OCR引擎选择

16.4.1 EasyOCR vs PaddleOCR

特性 EasyOCR PaddleOCR
速度 快 慢
准确率 高 高
内存占用 中等 高
初始化时间 短 长
中文支持 好 好
GPU支持 是 是

选择策略:

  1. 优先使用EasyOCR: 速度快,准确率高
  2. 回退到PaddleOCR: EasyOCR初始化失败时
  3. CPU模式: 默认使用CPU模式(避免GPU依赖)

16.4.2 OCR预处理

为了提高OCR识别率,项目使用多种预处理方法:

  1. 颜色转换 (change_color):

    • 0: 不转换(RGB)
    • 1: 转换为黑白(提高数字识别率)
    • 2: 其他转换
  2. 图像增强:

    • 对比度增强
    • 亮度调整
    • 去噪处理
  3. 区域裁剪:

    • 精确裁剪文本区域
    • 去除无关背景
    • 提高识别准确率

16.5 状态持久化机制

16.5.1 预约状态持久化

预约数据存储在 state/reservations.json 文件中:

{
  "reservations": [
    {
      "room_title": "直播间标题",
      "room_pos": {"x": 540, "y": 1200, "title": "直播间标题"},
      "lottery_time_ts": 1704067200.0,
      "prize_value_yuan": 500.0,
      "fudai_x": 900,
      "created_ts": 1704066900.0
    }
  ],
  "updated_at": 1704067200.0
}

持久化时机:

  • 添加预约时
  • 清理过期预约时
  • 预约回退时
  • 队列裁剪时

加载时机:

  • 程序启动时
  • 每次循环开始时

16.5.2 运行时状态

大部分状态标志存储在内存中(重启后丢失):

  • _waiting_for_lottery_result: 等待开奖状态
  • _last_successful_attend_ts: 最后成功参与时间
  • _swipe_times: 滑动次数
  • _last_diag_stage: 上次诊断阶段

恢复机制:

  • 预约数据:从文件加载
  • 运行时状态:重新初始化

16.6 预约系统完整流程详解

16.6.1 预约添加流程

  1. 检测高价值福袋:

    • 在福袋详情页获取福袋信息(价值、倒计时等)
    • 判断价值是否 >= high_value_fudai_threshold_yuan
    • 判断倒计时是否 > high_value_fudai_join_ahead_seconds
  2. 创建预约记录:

    reservation = {
        "room_title": room_title,              # 直播间标题(规范化)
        "room_title_raw": room_title_raw,       # 直播间标题(原始)
        "room_pos": room_pos,                   # 直播间位置
        "pos_seen": room_pos,                   # 看到的位置(用于回退)
        "lottery_time_ts": time.time() + countdown_seconds,  # 开奖时间戳
        "prize_value_yuan": prize_value_yuan,  # 奖品价值
        "fudai_x": fudai_x,                    # 福袋图标X坐标
        "created_ts": time.time()               # 创建时间戳
    }
    
  3. 添加到预约队列:

    • 检查队列是否已满(len(reservations) >= max_reservations)
    • 如果已满,裁剪队列(保留优先级最高的N个)
    • 添加新预约到队列
  4. 排序预约队列:

    • 主排序键: lottery_time_ts(升序,最早开奖的优先)
    • 次排序键: prize_value_yuan(降序,价值高的优先)
    • 第三排序键: created_ts(升序,最早创建的优先)
  5. 保存到文件:

    • 调用 write_reservations_state() 保存到 state/reservations.json

16.6.2 预约回退流程

  1. 检查预约窗口:

    • 每次循环开始时调用 process_reservation_attend_window()
    • 遍历预约列表,计算距离开奖时间
    • 如果 remaining_seconds <= high_value_fudai_join_ahead_seconds,触发回退
  2. 查找目标直播间:

    • 调用 find_room_pos_by_title() 查找目标直播间位置
    • 如果找到,获取目标位置 target_pos
  3. 计算回退方向和次数:

    • 计算位置差: pos_diff = target_pos - current_pos
    • 如果 pos_diff < 0,向上回退(减少位置)
    • 如果 pos_diff > 0,向下切换(增加位置)
  4. 执行回退:

    • 向上回退: 调用 swipe_down_back_from_live() N次
    • 向下切换: 调用 swipe_up_to_next_live() N次
    • 每次滑动后延迟 reservation_back_swipe_delay 秒
  5. 设置回退标志:

    • 设置 _reservation_back_direct_attend = True
    • 设置 reservation_focus_until_ts = lottery_time_ts + 60
    • 设置 _skip_record_title_during_seek = True(避免重复记录标题)
  6. 验证回退结果(可选):

    • 如果启用 reservation_back_verify_enabled,验证是否在目标直播间
    • 通过OCR识别直播间标题,与预约的 room_title 比较

16.6.3 预约直接参与流程

  1. 检查预约队列:

    • 如果预约队列为空,回退到正常流程(调用 _handle_in_fudai_detail())
  2. 检查福袋是否过期:

    • 获取预约的 future_ts(开奖时间戳,从 first_reservation.get("future_ts") 获取)
    • 计算过期阈值: expired_threshold = future_ts + poll_before_seconds
    • 如果当前时间 > 过期阈值,清除标志并退出
    • 调用 cleanup_expired_reservations() 从预约队列中移除过期预约
  3. 步骤1: 查找并打开福袋详情:

    • 调用 find_and_open_fudai_detail() 查找并打开福袋详情
    • 如果未找到,回退到正常流程
    • 等待详情页加载(0.5秒,减少延迟)
  4. 步骤2: 检测参与按钮:

    • 获取截图(operation.get_screenshot())
    • 读取截图文件(path_config.get_screenshot_path())
    • 调用 detect_attend_button_red_area() 检测参与按钮(返回 (has_button, button_info) 元组)
    • 如果未检测到按钮,回退到正常流程
  5. 步骤3: 点击参与按钮:

    • 计算参与按钮坐标(基于截图优化坐标:OCR区域(306,2030)-(780,2110),区域中心(543, 2070))
    • 根据设备分辨率缩放坐标: attend_x = int(543 * rx / 1080), attend_y = int(2070 * ry / 2400)
    • 点击参与按钮(operation.click(device_id, attend_x, attend_y))
    • 等待点击后的响应(0.8秒,减少延迟)
  6. 步骤4: 验证参与状态(详细验证逻辑):

    • 再次查找并点击福袋图标:
      • 调用 find_and_open_fudai_detail() 再次查找福袋图标
      • 如果未找到,可能已参与成功(记录日志,继续执行)
    • 如果找到福袋图标:
      • 等待详情页加载(0.5秒)
      • 获取截图并检测按钮状态
      • 调用 detect_attend_button_red_area() 再次检测参与按钮
      • 如果仍检测到按钮,可能参与失败,回退到正常流程
      • 如果未检测到按钮,说明参与成功
  7. 步骤5: 参与成功,设置开奖等待状态并从预约队列中移除:

    • 设置开奖等待状态:
      • 计算剩余秒数: remain_seconds = max(0, future_ts - current_time)
      • 如果 remain_seconds > 0,设置 _waiting_for_lottery_result = True
      • 设置 _lottery_result_expected_ts = future_ts - 13.0(提前13秒检查开奖结果)
    • 设置锁定期:
      • 计算锁定期: reservation_focus_until_ts = future_ts + max(0.0, poll_before)
      • 防止过早切换直播间
    • 从预约队列中移除已参与的预约:
      • 遍历预约队列,匹配 future_ts(允许5秒误差: abs(res_future_ts - future_ts) <= 5.0)
      • 移除匹配的预约,保留不匹配的预约
      • 记录移除日志
    • 清除标志:
      • 清除 _reservation_back_direct_attend = False
      • 清除 reservation_after_action_pending = False

16.6.4 预约队列管理

队列裁剪:

  • 当队列长度超过 high_value_fudai_max_reservations 时
  • 保留优先级最高的N个预约(按排序规则)
  • 丢弃优先级最低的预约

过期清理:

  • 每次处理预约窗口时检查
  • 如果 lottery_time_ts <= 当前时间,则清理该预约
  • 调用 cleanup_expired_reservations() 清理过期预约

队列排序:

  • 每次添加预约后自动排序
  • 确保最早开奖的预约在队列最前面

16.6.5 预约聚焦机制

预约回退后,需要聚焦到目标直播间,直到开奖完成:

  1. 设置聚焦时间戳:

    • reservation_focus_until_ts = lottery_time_ts + 60
    • 聚焦到开奖后60秒(确保开奖结果处理完成)
  2. 聚焦期间限制:

    • 不允许上划离开预约直播间(swipe_up_to_next_live() 中检查)
    • 如果 current_time < reservation_focus_until_ts,禁止上划
  3. 聚焦结束后:

    • 清除聚焦标志
    • 恢复正常流程

16.7 直播间位置映射机制

16.7.1 映射表结构

运行时映射表存储在 analyser._room_pos_to_title_map 中:

_room_pos_to_title_map: Dict[int, Tuple[str, str]] = {
    0: ("直播间标题1", "直播间标题1(原始)"),
    1: ("直播间标题2", "直播间标题2(原始)"),
    2: ("直播间标题3", "直播间标题3(原始)"),
    ...
}

键: room_pos(直播间位置,整数) 值: (room_title, room_title_raw)(标题元组)

16.7.2 映射表更新

  1. 进入直播间时:

    • 调用 record_room_title_and_pos() 记录标题和位置
    • 更新映射表: _room_pos_to_title_map[room_pos] = (room_title, room_title_raw)
  2. 切换直播间时:

    • 更新 room_pos(增加或减少)
    • 记录新直播间的标题和位置
  3. 回退到推荐页时:

    • 重置 room_pos = 0
    • 清空映射表(可选,或保留历史记录)

16.7.3 映射表查找

使用 find_room_pos_by_title() 查找目标直播间位置:

  1. 规范化标题: 规范化目标标题和记录的标题
  2. 匹配算法:
    • 完全匹配(分数 = 1.0)
    • 子串匹配(分数 = 0.8)
    • 相似度匹配(使用 difflib.SequenceMatcher)
  3. 选择最佳匹配: 选择匹配分数 >= 0.6 且最高的位置

17. 预约验证和错误处理模块

17.1 预约验证模块 (douyin_reservation_verify.py)

预约验证模块提供回退到预约直播间后的详细校验功能,确保在正确的直播间和正确的福袋。

17.1.1 match_reservation(item, detail) -> Tuple[bool, str, Dict]

  • 作用: 校验回退后的福袋详情是否匹配预约记录
  • 匹配策略:
    1. 观看任务检测: 优先检测是否为"观看X分钟"类任务,如果是则直接判为不匹配
    2. future_ts验证: 必须同时有 expected_future 和 actual_future,否则无法确认回退成功
    3. 价值或内容匹配(二选一命中即可):
      • 价值匹配: 允许25%误差或至少50元误差
      • 内容匹配: 子串匹配(expected_content in actual_content 或 actual_content in expected_content)
    4. future_ts精确匹配:
      • 正常情况下 future_diff <= 180 秒
      • 如果 future_diff > 180 但 <= 1200 且价值+内容都匹配,允许放宽匹配(future_mismatch_relaxed)

匹配结果:

  • (True, "ok", debug_dict): 完全匹配
  • (True, "future_mismatch_relaxed", debug_dict): 放宽匹配(future_ts偏差较大但价值+内容匹配)
  • (False, "watch_task_detected", debug_dict): 检测到观看任务
  • (False, "future_missing", debug_dict): future_ts缺失
  • (False, "content_or_value_mismatch", debug_dict): 价值和内容都不匹配
  • (False, "future_mismatch", debug_dict): future_ts偏差过大

17.1.2 validate_back_to_reservation(analyser, item, quick=False, max_checks=3) -> Tuple[bool, Optional[Tuple]]

  • 作用: 回退后校验直播间标题,确保在正确的直播间
  • 验证流程:
    1. 检查验证开关: 如果 reservation_back_verify_enabled = False,直接返回 True
    2. 标题规范化: 使用 _normalize_room_title() 规范化标题,去除无关词
    3. 运行时映射表验证: 从 _room_pos_to_title_map 获取目标位置的记录标题,增强验证信心
    4. 读取当前标题: 调用 read_live_room_title_core() 读取当前直播间标题
    5. 相似度计算: 使用 difflib.SequenceMatcher 计算标题相似度
    6. 匹配判断:
      • 如果 expected_title in current_title 或 current_title in expected_title 或 ratio >= 0.45,验证通过
      • 如果标题不匹配(ratio < 0.45),尝试根据映射表找到正确位置并回退
    7. 自动回退: 如果标题不匹配,调用 _find_room_pos_by_title() 和 _seek_reservation_room() 自动回退到正确位置

验证结果:

  • (True, None): 验证通过
  • (False, None): 验证失败(标题不匹配且无法自动回退)

17.2 预约错误处理工具模块 (reservation_error_utils.py)

预约错误处理工具模块提供统一的预约相关错误处理和日志记录功能。

17.2.1 format_reservation_context(item=None, reservations=None, **kwargs) -> Dict[str, Any]

  • 作用: 格式化预约上下文信息,用于错误日志记录
  • 返回内容:
    • reservation_item: 预约项信息(future_ts、prize_value_yuan、room_title等)
    • queue_info: 预约队列信息(队列长度、前5个预约项)
    • 其他上下文信息(通过 **kwargs 传入)

17.2.2 log_reservation_error(analyser, error, context, level="WARNING", stage="") -> None

  • 作用: 统一的预约错误日志记录函数
  • 参数:
    • analyser: Any: 分析器对象
    • error: Exception: 异常对象
    • context: Dict[str, Any]: 错误上下文信息字典
    • level: str: 日志级别(ERROR/WARNING/INFO)
    • stage: str: 操作阶段描述(如"添加预约"、"回退验证"等)
  • 功能:
    • 构建详细的错误信息(错误类型、错误消息、上下文信息)
    • 对于严重错误(ERROR级别),添加调用栈信息
    • 调用 analyser._log_kv() 记录日志

17.2.3 safe_write_state(write_callback, analyser=None, context=None) -> bool

  • 作用: 安全的状态文件写入,带详细的错误处理
  • 错误处理:
    • PermissionError: 权限错误
    • OSError: 系统错误
    • ValueError/TypeError: 数据序列化错误
    • 其他异常: 未知错误
  • 返回: bool - 是否成功写入

17.2.4 validate_reservation_item(item) -> Tuple[bool, Optional[str]]

  • 作用: 验证预约项数据的有效性
  • 验证内容:
    • 检查必需字段: future_ts, prize_value_yuan
    • 验证 future_ts 格式和有效性(必须 > 0)
    • 验证 prize_value_yuan 格式和有效性(必须 >= 0)
  • 返回: (是否有效, 错误信息)

17.3 福袋筛选模块 (fudai_filter.py)

福袋筛选模块包含福袋内容过滤、观看任务检测、配置筛选等功能。

17.3.1 check_contain(analyser, contains="") -> bool

  • 作用: 检查福袋内容是否命中"黑名单"关键词
  • 返回值语义:
    • True: "建议丢弃"(内容命中黑名单 contains_not_want)
    • False: "可以保留"(未命中黑名单,或凌晨时段不做内容过滤)
  • 特殊处理:
    • 凌晨时段(0-7点): 不对内容做要求(不过滤),直接返回 False

17.3.2 is_watch_task_fudai(content) -> bool

  • 作用: 检测是否为"观看X分钟"类任务福袋
  • 匹配模式:
    • (?:观看|看)(?:直播)?(?:.*?)?(?:\d+|[\u4e00-\u9fff]+)\s*分钟
    • 需要(?:观看|看)(?:.*?)?(?:\d+|[\u4e00-\u9fff]+)\s*分钟
    • 观看时长(?:.*?)?(?:\d+|[\u4e00-\u9fff]+)\s*分钟
    • 看播(?:.*?)?(?:\d+|[\u4e00-\u9fff]+)\s*分钟
  • 返回: True 表示是"观看X分钟"类任务,应放弃

17.3.3 should_skip_fudai_by_config(analyser, detail) -> Tuple[bool, str]

  • 作用: 根据 config.json 中的阈值与关键词,判断是否应丢弃当前福袋
  • 筛选规则:
    1. 单间模式: 如果 needswitch = False,忽略所有阈值配置,永远不因为配置而跳过
    2. 观看任务检测: 优先检查是否为"观看X分钟"类任务,如果是则直接放弃
    3. 价值过滤: 如果 prize_value_yuan < min_prize_value_yuan,丢弃
    4. 参与人数过滤:
      • 如果 participants < min_participants,丢弃
      • 如果 participants > max_participants,丢弃
    5. 倒计时过滤:
      • 如果 remain_seconds < skip_if_countdown_lt_seconds,丢弃(不参与)
      • 如果 remain_seconds > skip_if_countdown_gt_seconds,丢弃(不参与,但高价值福袋可预约)
    6. 内容关键词过滤: 调用 check_contain() 检查是否命中黑名单
  • 返回: (skip, reason) - 是否跳过、原因

17.3.4 basic_join_decision(analyser, detail) -> bool

  • 作用: 基础版参与决策,根据配置筛选福袋,满足条件则尝试参与抽奖或记录高价值预约
  • 决策流程:
    1. 检查强制参与标志: 如果 _force_attend_after_reservation_back = True,跳过验证
    2. 检查状态: 如果 _last_fudai_detail_status == "coupon_popup" 或 "validation_failed",跳过处理
    3. 数据验证: 调用 validate_fudai_detail() 验证数据合理性
    4. 单间模式: 如果 needswitch = False,直接参与,不做任何阈值过滤
    5. 检查重复参与: 通过 future_ts 匹配 _participated_fudai_future_ts(允许5秒误差)
    6. 高价值判断: 如果价值 >= high_value_fudai_threshold_yuan,标记为高价值福袋
    7. 执行筛选: 调用 should_skip_fudai_by_config() 检查是否应丢弃
    8. 特殊处理高价值福袋:
      • 如果被倒计时过滤筛掉(倒计时 > 阈值),但价值达到高价值阈值:
        • 检查是否为观看任务(如果是,直接丢弃)
        • 如果剩余秒数 <= high_value_fudai_join_ahead_seconds 或强制参与,立即参与
        • 否则记录预约
    9. 参与抽奖: 如果通过筛选,调用 attend_choujiang() 参与抽奖
    10. 丢弃处理: 如果被筛掉,关闭详情页,如果允许切换直播间则切换
  • 返回: True 表示已经参与或已处理完成,False 表示未参与

17.4 福袋结果检查模块 (fudai_result_checker.py)

福袋结果检查模块提供开奖结果检测和奖励领取功能。

17.4.1 check_lucky_draw_result(analyser) -> int | bool

  • 作用: 检查开奖结果(是否中奖)
  • 检测方法:
    • 使用像素检测检测开奖结果区域的颜色特征
    • 使用OCR识别开奖结果文字
  • 返回:
    • 1: 中奖
    • 0: 未中奖
    • False: 检测失败

17.4.2 check_have_reward_notice_confirm(analyser) -> bool

  • 作用: 检查是否有奖励通知确认按钮
  • 返回: bool - 是否有奖励通知

17.4.3 check_in_order_confirm_page(analyser) -> bool

  • 作用: 检查是否在订单确认页面
  • 返回: bool - 是否在订单确认页面

17.4.4 get_reward(analyser, reward_y: int = 0) -> None

  • 作用: 自动领取奖励
  • 流程:
    1. 检测开奖结果
    2. 如果中奖,点击领取按钮
    3. 处理订单确认页面
    4. 保存奖励截图

18. 核心处理函数详解补充

18.1 福袋详情处理函数补充

18.1.1 fudai_analyse._handle_in_fudai_detail() -> None

  • 文件位置: douyin/core/douyin_fudai.py
  • 作用: 已经在福袋详情页:只跑详情识别 + 是否参与的基础逻辑
  • 参数: 无
  • 返回值: 无
  • 调用位置: run_once_basic() 中诊断到 FUDai_DETAIL 阶段时调用
  • 主要逻辑:
    1. 检查是否是第二次打开福袋详情:
      • 如果 _fudai_detail_first_read = True,说明已经读取过详情
      • 第二次打开时,直接使用第一次保存的详情数据(_last_fudai_detail_tuple)
      • 设置 _current_fudai_future_ts,供 attend_choujiang() 使用
      • 直接调用 attend_choujiang(),跳过验证和内容识别
      • 清除第一次读取标志,下次打开新福袋时重新识别
    2. 第一次打开:完整读取详情:
      • 调用 read_fudai_detail_with_retries() 读取福袋详情
      • 进行数据验证(validate_fudai_detail())
      • 如果验证失败,关闭详情页并返回
      • 保存详情数据到 _last_fudai_detail_tuple
      • 设置 _fudai_detail_first_read = True
      • 调用 basic_join_decision() 进行筛选和参与决策

关键状态变量:

  • _fudai_detail_first_read: 是否已经第一次读取过详情
  • _last_fudai_detail_tuple: 第一次读取的详情数据
  • _current_fudai_future_ts: 当前福袋的开奖时间戳

优化说明:

  • 第二次打开时跳过OCR识别,直接使用第一次的数据,提高效率
  • 避免重复识别导致的延迟和资源浪费

18.1.2 fudai_analyse._handle_live_room_has_or_not_fudai() -> None

  • 文件位置: douyin/core/douyin_fudai.py
  • 作用: 在直播间:寻找福袋图标;有则点开详情,无则交给 flow_control 决定"继续找/切换/养号"
  • 参数: 无
  • 返回值: 无
  • 调用位置: run_once_basic() 中诊断到 LIVE_ROOM 阶段时调用
  • 主要逻辑:
    1. 检查是否已验证过详情页:
      • 如果 _fudai_detail_verified = True,直接调用 _handle_in_fudai_detail(),不查找福袋
    2. 检查锁定期和时间窗口:
      • 如果 reservation_focus_until_ts > 当前时间 且 queue_full_waiting_at_earliest = True:
        • 检查预约队列中最早预约的时间窗口
        • 计算 time_window_start_ts = future_ts - join_ahead_seconds
        • 如果当前时间 < 时间窗口开始时间,避免重复打开福袋详情,直接返回
    3. 查找并打开福袋详情:
      • 调用 find_and_open_fudai_detail() 查找福袋图标并打开详情
      • 如果未找到福袋,调用 handle_no_fudai_situation() 处理无福袋情况
      • 如果成功打开详情,调用 _handle_in_fudai_detail() 处理详情

关键配置参数:

  • reservation_focus_until_ts: 预约锁定期时间戳
  • queue_full_waiting_at_earliest: 队列满等待标志
  • high_value_fudai_join_ahead_seconds: 提前参与秒数

优化说明:

  • 锁定期内避免重复打开福袋详情,减少不必要的操作
  • 时间窗口检查确保在合适的时机打开福袋详情

18.2 主流程控制函数补充

18.2.1 MainFlowController.fudai_choujiang(analyser, device_id, y_pianyi, needswitch, wait_minutes) -> None

  • 文件位置: douyin/core/douyin_main_flow.py
  • 作用: 主流程控制器的主循环入口(兼容原 fudai_choujiang 接口)
  • 参数: 同 fudai_analyse.fudai_choujiang()
  • 返回值: 无
  • 调用位置: 可能被 fudai_analyse.fudai_choujiang() 内部调用
  • 主要逻辑:
    1. 初始化设备信息(同 fudai_analyse.fudai_choujiang())
    2. 安全检查:
      • 最大循环次数限制:max_loops = 10000
      • 最大运行时间限制:24小时
      • 如果达到限制,停止运行并记录日志
    3. 主循环:
      • 循环计数:loop_count
      • 每次循环调用 MainFlowController.run_once_basic(analyser)
      • 等待指定时间(如果配置了 wait_minutes)

安全机制:

  • 防止无限循环:最大循环次数限制
  • 防止长时间运行:最大运行时间限制(24小时)
  • 异常捕获:每次循环捕获异常,记录日志,继续运行

18.2.2 MainFlowController.run_once_basic(analyser) -> None

  • 文件位置: douyin/core/douyin_main_flow.py
  • 作用: 单轮基础抢福袋流程(包含简化版高价值福袋预约回退)
  • 参数:
    • analyser: Any: 分析器对象
  • 返回值: 无
  • 调用位置: MainFlowController.fudai_choujiang() 中调用
  • 主要逻辑:
    • 由于 run_once_basic 方法非常复杂(1500+行),当前实现调用 analyser.run_once_basic_original() 保持原实现
    • 通过模块化组织,后续可以进一步拆分

设计说明:

  • 保持向后兼容:调用原有的 run_once_basic_original() 方法
  • 模块化设计:为后续拆分做准备

18.3 流程控制辅助函数

18.3.1 douyin_flow_control.handle_stage_after_diagnosis(analyser, stage, seen, loop_count) -> bool

  • 作用: 记录阶段诊断结果,当前不改变主流程走向
  • 参数:
    • analyser: Any: 分析器对象
    • stage: str: 阶段类型
    • seen: str: 阶段描述
    • loop_count: int: 循环计数
  • 返回值: bool - 当前实现返回 False(不改变主流程)
  • 调用位置: 阶段诊断后调用(当前主要用于日志记录)

设计说明:

  • 预留接口:为后续扩展阶段处理逻辑做准备
  • 当前实现:仅记录日志,不改变主流程

18.3.2 douyin_flow_control.find_and_open_fudai_detail(analyser, room_pos_ref) -> bool

  • 作用: 在当前直播间查找福袋图标并尝试点击打开详情
  • 参数:
    • analyser: Any: 分析器对象
    • room_pos_ref: List[int]: 直播间位置引用(用于更新位置)
  • 返回值: bool - True=成功打开详情, False=未找到福袋或打开失败
  • 调用位置: _handle_live_room_has_or_not_fudai() 中调用
  • 主要逻辑:
    1. 检查等待开奖状态:
      • 如果 _waiting_for_lottery_result = True,跳过打开福袋详情,返回 False
    2. 像素检测福袋图标:
      • 在配置的最大等待时间内(fudai_icon_max_wait_seconds)重复检测
      • 使用 check_have_fudai_with_ready_screenshot() 检测福袋图标X坐标
      • 重试延迟:fudai_icon_retry_delay_seconds
    3. 点击福袋图标:
      • 如果找到福袋图标,点击打开详情
      • 等待详情页加载(fudai_click_wait_seconds)
    4. 验证是否成功打开:
      • 重新诊断阶段,确认是否在福袋详情页
      • 如果成功,返回 True;否则返回 False

配置参数:

  • fudai_icon_max_wait_seconds: 福袋图标最大等待时间(秒,默认5.0)
  • fudai_icon_retry_delay_seconds: 福袋图标重试延迟(秒,默认0.6)
  • fudai_click_wait_seconds: 点击福袋后等待时间(秒)

优化说明:

  • 重试机制:在最大等待时间内重复检测,提高找到福袋的概率
  • 状态检查:等待开奖时不打开新福袋,避免干扰

18.3.3 douyin_flow_control.handle_no_fudai_situation(analyser, ...) -> bool

  • 作用: 在没有福袋时做简单的等待/上滑切换
  • 参数: 多个参数,包括 needswitch、reservations、回调函数等
  • 返回值: bool - 是否已处理
  • 调用位置: _handle_live_room_has_or_not_fudai() 中未找到福袋时调用
  • 主要逻辑:
    1. 检查是否允许切换直播间:
      • 如果 needswitch = False,只等待不切换
    2. 处理预约回退窗口:
      • 如果启用预约功能,调用 process_reservation_attend_window() 检查是否需要回退
    3. 切换直播间或等待:
      • 如果允许切换,调用 swipe_up_switch_callback() 上滑切换
      • 如果不允许切换,等待一段时间

设计说明:

  • 灵活配置:根据 needswitch 决定是否切换直播间
  • 预约集成:与预约回退逻辑集成,统一处理无福袋情况

19. 工具函数和辅助模块详解

19.1 辅助函数模块 (douyin_helpers.py)

HelperFunctions 类提供了一系列通用的工具方法,用于简化常见操作。

19.1.1 HelperFunctions.click(analyser, x, y) -> None

  • 文件位置: douyin/utils/douyin_helpers.py
  • 作用: 兼容原版 fudai_analyse.click,转发到底层 operation.click
  • 参数:
    • analyser: Any: 分析器对象
    • x: int: X坐标
    • y: int: Y坐标
  • 返回值: 无
  • 调用位置: 所有需要点击的地方
  • 主要逻辑:
    • 调用 analyser.operation.click(device_id, x, y) 执行点击
    • 如果耗时超过0.1秒,记录日志(用于性能分析)

19.1.2 HelperFunctions.read_pixel_stage_state(analyser, return_details=False) -> Union[Dict, Tuple]

  • 文件位置: douyin/utils/douyin_helpers.py
  • 作用: 读取像素阶段状态(封装 read_pixel_stage_state_from_screenshot)
  • 参数:
    • analyser: Any: 分析器对象
    • return_details: bool: 是否返回每个检测步骤的详细信息(包括分数)
  • 返回值:
    • dict: 检测结果(return_details=False 时)
    • tuple[dict, dict]: (检测结果, 详细信息)(return_details=True 时)
  • 调用位置: 阶段诊断时调用
  • 主要逻辑:
    • 获取截图路径(path_config.get_screenshot_path())
    • 获取分辨率比例和Y偏移参数
    • 获取模板匹配阈值(优先使用福袋详情页专用阈值)
    • 调用 read_pixel_stage_state_from_screenshot() 执行检测

19.1.3 HelperFunctions.check_lottery_result_by_ocr(analyser) -> Optional[str]

  • 文件位置: douyin/utils/douyin_helpers.py
  • 作用: 通过OCR识别开奖结果按钮区域,返回识别到的文本类型
  • 参数:
    • analyser: Any: 分析器对象
  • 返回值: Optional[str] - "我知道了" 或 "立即领取奖品" 或 None
  • 调用位置: 检查开奖结果时调用
  • 主要逻辑:
    1. 裁剪开奖结果按钮区域
    2. 使用OCR识别按钮文字
    3. 根据识别结果返回对应的文本类型

19.1.4 HelperFunctions.handle_lottery_result_by_ocr(analyser, result_type, use_direct_click=False) -> None

  • 文件位置: douyin/utils/douyin_helpers.py
  • 作用: 根据OCR识别结果处理开奖结果
  • 参数:
    • analyser: Any: 分析器对象
    • result_type: str: "我知道了" 或 "立即领取奖品"
    • use_direct_click: bool: 是否使用直接点击(默认False)
  • 返回值: 无
  • 调用位置: 检查到开奖结果后调用
  • 主要逻辑:
    1. 根据 result_type 确定点击坐标
    2. 点击对应的按钮
    3. 处理后续流程(如领取奖品)

19.1.5 HelperFunctions.shot_and_diagnose(tag, msg, device_id, diagnose=True) -> None

  • 文件位置: douyin/utils/douyin_helpers.py
  • 作用: 截图并执行阶段诊断(兼容旧版调用方式)
  • 参数:
    • tag: str: 日志标签
    • msg: str: 日志消息
    • device_id: str: 设备ID
    • diagnose: bool: 是否执行阶段诊断(默认True)
  • 返回值: 无
  • 调用位置: 需要截图和诊断的地方
  • 主要逻辑:
    1. 获取截图(operation.get_screenshot())
    2. 如果 diagnose=True,执行阶段诊断
    3. 记录日志

19.2 截图管理模块 (douyin_screenshot_manager.py)

截图管理模块提供双截图记录机制和调试图像保存功能。

19.2.1 双截图记录机制

实时操作截图 (latest_attempt.png):

  • 每次识别操作都覆盖保存
  • 用于查看最新的操作截图
  • 路径: pic/ocr/latest_attempt_{operation_type}.png

成功识别存档截图 (last_success.png):

  • 仅在成功时保存,不会被覆盖
  • 用于查看最近一次成功的识别截图
  • 路径: pic/ocr/last_success_{operation_type}.png

19.2.2 save_latest_attempt(image, operation_type="") -> bool

  • 作用: 保存实时操作截图(覆盖保存)
  • 参数:
    • image: Image.Image: PIL Image 对象
    • operation_type: str: 操作类型(用于分类,如 "template_match", "pixel_detect", "ocr", "cut_pic")
  • 返回值: bool - 是否保存成功

19.2.3 save_last_success(image, operation_type="") -> bool

  • 作用: 保存成功识别存档截图(不覆盖)
  • 参数: 同 save_latest_attempt()
  • 返回值: bool - 是否保存成功

19.2.4 save_debug_image(image, operation_type="", picname="", step="", coords=None, extra_info=None, annotate=True, auto_cleanup=True) -> Optional[str]

  • 作用: 保存调试图像,支持标注和自动清理
  • 参数:
    • image: Image.Image: PIL Image 对象
    • operation_type: str: 操作类型
    • picname: str: 图片名称
    • step: str: 步骤描述
    • coords: Optional[Tuple[int, int, int, int]]: 坐标区域 (x1, y1, x2, y2)
    • extra_info: Optional[dict]: 额外信息
    • annotate: bool: 是否标注(默认True)
    • auto_cleanup: bool: 是否自动清理旧文件(默认True)
  • 返回值: Optional[str] - 保存的文件路径
  • 主要功能:
    1. 在图像上标注坐标区域(如果 annotate=True)
    2. 添加额外信息文本(OCR识别结果等)
    3. 保存到 pic/debug_captures/ 目录
    4. 自动清理旧文件(如果 auto_cleanup=True)

19.2.5 cleanup_ocr_dir(keep_latest_attempt=True, keep_last_success=True, keep_success_files=True, max_files=50) -> int

  • 作用: 清理OCR目录中的旧文件
  • 参数:
    • keep_latest_attempt: bool: 是否保留最新尝试文件
    • keep_last_success: bool: 是否保留最后成功文件
    • keep_success_files: bool: 是否保留成功文件
    • max_files: int: 最大保留文件数(默认50)
  • 返回值: int - 清理的文件数量

19.3 截图处理模块 (douyin_screenshot_handler.py)

19.3.1 ScreenshotHandler.scale_from_base(analyser, base_x, base_y) -> Tuple[int, int]

  • 作用: 从基准分辨率缩放坐标
  • 参数:
    • analyser: Any: 分析器对象
    • base_x: int: 基准X坐标(1080基准)
    • base_y: int: 基准Y坐标(2400基准)
  • 返回值: Tuple[int, int] - 缩放后的坐标
  • 主要逻辑:
    • 根据设备分辨率比例缩放坐标
    • 考虑Y轴偏移(y_pianyi)

19.3.2 ScreenshotHandler.save_step_screenshot(analyser, label) -> None

  • 作用: 保存当前截图到 pic/steps/ 目录,供调试使用
  • 参数:
    • analyser: Any: 分析器对象
    • label: str: 标签(用于文件名)
  • 返回值: 无
  • 主要逻辑:
    1. 获取最新截图
    2. 保存到 pic/steps/{run_id}_{log_seq:04d}_{label}.png
    3. 文件名包含运行ID和日志序号,便于追踪

19.4 文本处理工具模块 (douyin_utils.py)

19.4.1 normalize_countdown_text(text) -> str

  • 作用: 对福袋倒计时类OCR文本做标准化
  • 参数:
    • text: str: OCR识别的倒计时文本
  • 返回值: str - 标准化后的倒计时文本(格式:mm:ss 或 mm:ss后开奖)
  • 主要逻辑:
    1. OCR混淆纠正: 将常见OCR错误字符替换为正确数字
      • O/o/Q/D → 0
      • I/l/|/! → 1
      • S/s → 5
      • B → 8
      • G → 6
      • Z → 2
    2. 格式解析:
      • 中文格式:x分y秒 → mm:ss
      • 仅分钟:x分钟 → mm:00
      • 仅秒数:x秒 → mm:ss
      • 标准样式:11:37后开奖 → 11:37后开奖
      • 无分割符:1413后开奖 → 14:13后开奖
    3. 分秒交换处理: 如果识别结果不合理(如秒数>=60),尝试交换分秒

19.4.2 extract_prize_value_yuan(text) -> float

  • 作用: 从OCR文本中提取奖品价值(元)
  • 参数:
    • text: str: OCR识别的价值文本
  • 返回值: float - 提取的价值(元),如果提取失败返回0.0
  • 主要逻辑:
    1. 提取数字和单位("元"、"¥"等)
    2. 转换为浮点数
    3. 支持格式:200元、¥200、价值200元 等

19.5 OCR预处理模块 (ocr_preprocess.py)

19.5.1 preprocess_for_ocr(analyser, cut_pic_name) -> str

  • 作用: 对图片进行OCR预处理,生成可供OCR使用的图片
  • 参数:
    • analyser: Any: 分析器对象
    • cut_pic_name: str: 裁剪后的图片名称
  • 返回值: str - 预处理后的图片名称(如果预处理失败,返回原名称)
  • 主要逻辑:
    1. 查找裁剪后的图片路径
    2. 对图片进行预处理(如二值化、去噪等)
    3. 保存预处理后的图片
    4. 返回预处理后的图片名称

预处理技术:

  • 图像二值化:提高OCR识别准确率
  • 去噪处理:去除图像中的噪声
  • 对比度增强:提高文字清晰度

19.6 文本工具模块 (douyin_text_utils.py)

19.6.1 extract_fudai_content(text) -> str

  • 作用: 从OCR文本中提取福袋内容
  • 参数:
    • text: Optional[str]: OCR识别的文本
  • 返回值: str - 提取的福袋内容
  • 主要逻辑:
    • 清理无关字符
    • 提取福袋内容描述

19.6.2 _safe_str(text) -> str

  • 作用: 将输入安全地转换为字符串,None → 空字符串
  • 参数:
    • text: Optional[str]: 输入文本
  • 返回值: str - 转换后的字符串

19.7 配置管理模块 (douyin_config.py)

19.7.1 ConfigManager.load_config_from_file(analyser, config_path=None) -> None

  • 作用: 从配置文件加载配置并设置到 analyser 对象
  • 参数:
    • analyser: Any: fudai_analyse 实例
    • config_path: Optional[str]: 配置文件路径,如果为 None 则使用 analyser.config_path
  • 返回值: 无
  • 主要逻辑:
    1. 确定配置文件路径(优先使用传入的路径,否则使用 analyser.config_path)
    2. 如果配置文件不存在,直接返回(使用默认值)
    3. 读取JSON配置文件
    4. 将配置项设置到 analyser 对象的属性上
    5. 保留 needswitch 的原始值(如果已通过命令行设置)

配置项映射:

  • min_prize_value_yuan → analyser.min_prize_value_yuan
  • min_participants → analyser.min_participants
  • max_participants → analyser.max_participants
  • 等等...

20. 检测功能详解

20.1 像素检测功能详解

20.1.1 detect_live_room_icons_by_pixel(pic_rgb) -> Tuple[bool, float]

  • 文件位置: douyin/detection/douyin_pixel.py
  • 作用: 通过像素检测右上角x和xin图标区域,判断是否在直播间
  • 参数:
    • pic_rgb: Image.Image: PIL Image对象(RGB格式)
  • 返回值: Tuple[bool, float] - (是否检测到, 置信度)
  • 检测区域: (972, 147) 到 (1047, 216)(基准1080x2400)
  • 检测特征:
    • x图标: 通常是白色或浅色的X形状
    • xin图标: 通常是粉色/红色的心形图标
  • 检测逻辑:
    1. 缩放坐标到实际分辨率
    2. 采样检测点(步长:区域宽高的1/20)
    3. 统计白色/浅色像素(x图标)和粉色/红色像素(xin图标)
    4. 计算置信度:confidence = (white_ratio + pink_red_ratio) / 2
    5. 如果置信度 >= 0.1,返回 (True, confidence)

调试支持:

  • 保存调试图像:标注检测区域和检测结果
  • 记录检测统计信息(白色像素数、粉色/红色像素数、总采样数)

20.1.2 detect_fudai_detail_page(pic_rgb, resolution_ratio_x, resolution_ratio_y, y_pianyi, template_threshold, return_info=False, analyser=None) -> bool | Tuple[bool, dict]

  • 文件位置: douyin/detection/douyin_pixel.py
  • 作用: 检测是否在福袋详情页,并检测任务数量
  • 参数:
    • pic_rgb: Image.Image: PIL Image对象(RGB格式,保留用于兼容性,实际不使用)
    • resolution_ratio_x: int: 分辨率X比例(默认1080,保留用于兼容性)
    • resolution_ratio_y: int: 分辨率Y比例(默认2400,保留用于兼容性)
    • y_pianyi: int: Y轴偏移(默认0,保留用于兼容性)
    • template_threshold: float: 模板匹配阈值(保留用于兼容性,不再使用)
    • return_info: bool: 是否返回详细信息(默认False)
    • analyser: Any: 分析器对象(必需,用于任务数量检测)
  • 返回值:
    • bool: 是否在福袋详情页(return_info=False 时)
    • Tuple[bool, dict]: (是否在福袋详情页, 详细信息)(return_info=True 时)
  • 检测策略: 任务数量检测
    1. 通过检测任务数量来判断是否在福袋详情页
    2. 如果任务数量 <= 0,则认为不在福袋详情页
    3. 如果任务数量 >= 1,则认为在福袋详情页,并返回任务数量
  • 实现: 调用 check_detail_height(analyser) 执行任务数量检测

详细信息字典 (return_info=True 时):

{
    "method": "task_count",      # 检测方法
    "task_count": 2,             # 检测到的任务数量(0、1、2或3)
    "reason": "detection_exception: ..."  # 如果检测失败,包含失败原因
}

调试支持:

  • 保存调试图像:标注检测区域、检测点、检测结果
  • 记录检测统计信息(任务数量、检测Y坐标、检测X坐标、检测点数量)

20.1.2.1 check_detail_height(analyser) -> int

  • 文件位置: douyin/detection/douyin_detection.py
  • 作用: 检测福袋详情页中需要完成的任务数量
  • 参数:
    • analyser: Any: 分析器对象
  • 返回值: int - 任务数量(0、1、2或3)
  • 检测原理:
    • 在参与按钮附近的特定Y坐标处检测像素颜色特征
    • 不同任务数量对应不同的Y坐标位置
    • 通过检测特定颜色的像素来判断任务数量
  • 检测点配置:
    check_points = [
        (983, 0, 2),        # 2个任务:Y坐标983(基准2400)
        (983, y_pianyi, 2), # 2个任务:Y坐标983 + y_pianyi
        (983, -y_pianyi, 2),# 2个任务:Y坐标983 - y_pianyi
        (883, 0, 3),        # 3个任务:Y坐标883
        (883, y_pianyi, 3), # 3个任务:Y坐标883 + y_pianyi
        (883, -y_pianyi, 3),# 3个任务:Y坐标883 - y_pianyi
        (1058, 0, 1),       # 1个任务:Y坐标1058
        (1058, y_pianyi, 1),# 1个任务:Y坐标1058 + y_pianyi
        (1058, -y_pianyi, 1),# 1个任务:Y坐标1058 - y_pianyi
    ]
    
  • 检测X坐标: x = 536 * rx // 1080(参与按钮的X坐标)
  • 像素颜色检测:
    • 检测RGB值是否在特定范围内:28 <= r <= 40 and 32 <= g <= 42 and 76 <= b <= 86
    • 这个颜色范围对应任务项的特征颜色
  • 检测流程:
    1. 读取截图(最多重试3次)
    2. 缩放X坐标到实际分辨率
    3. 遍历检测点列表,检查每个检测点的像素颜色
    4. 如果检测到匹配的像素颜色,返回对应的任务数量
    5. 如果所有检测点都不匹配,返回0
    6. 保存调试图像(标注检测区域和检测点)

调试支持:

  • 保存调试图像:标注检测区域、所有检测点、检测结果
  • 记录检测统计信息(任务数量、检测Y坐标、检测X坐标、检测点数量)
  • 记录截图时间戳和当前时间,便于分析时间差

20.1.3 detect_attend_button_red_area(pic_rgb, return_info=False, red_ratio_threshold=None, analyser=None) -> bool | Tuple[bool, dict]

  • 文件位置: douyin/detection/douyin_pixel.py
  • 作用: 检测参与按钮红色区域(用于判断是否可以参与)
  • 参数:
    • pic_rgb: Image.Image: PIL Image对象(RGB格式)
    • return_info: bool: 是否返回详细信息(默认False)
    • red_ratio_threshold: float | None: 红色比例阈值(默认None,使用配置值)
    • analyser: Any: 分析器对象(用于日志和调试图像)
  • 返回值:
    • bool: 是否检测到参与按钮(return_info=False 时)
    • Tuple[bool, dict]: (是否检测到, 详细信息)(return_info=True 时)
  • 检测区域: (306, 2030) 到 (780, 2110)(基准1080x2400,参与按钮区域)
  • 检测逻辑:
    1. 缩放坐标到实际分辨率
    2. 采样检测点(步长:区域宽高的1/20)
    3. 统计红色像素数量(RGB值在红色范围内)
    4. 计算红色比例:red_ratio = red_count / total_samples
    5. 如果红色比例 >= 阈值(默认0.25),返回 True

详细信息字典 (return_info=True 时):

{
    "method": "pixel_detect",
    "red_ratio": 0.35,           # 红色比例
    "red_count": 45,             # 红色像素数
    "total_samples": 128,        # 总采样数
    "threshold": 0.25,           # 使用的阈值
    "result": "success"          # 检测结果
}

20.1.4 detect_fansclub_join_red_area(pic_rgb, return_info=False, red_ratio_threshold=None, analyser=None) -> bool | Tuple[bool, dict]

  • 文件位置: douyin/detection/douyin_pixel.py
  • 作用: 检测粉丝团加入按钮红色区域
  • 参数: 同 detect_attend_button_red_area()
  • 返回值: 同 detect_attend_button_red_area()
  • 检测区域: (200, 1940) 到 (880, 2140)(基准1080x2400,粉丝团加入按钮区域)
  • 检测逻辑: 同 detect_attend_button_red_area()

20.1.5 detect_lucky_draw_result_popup(pic_rgb, red_ratio_threshold=0.8, return_info=False) -> bool | Tuple[bool, dict]

  • 文件位置: douyin/detection/douyin_pixel.py
  • 作用: 检测开奖结果弹窗(通过检测红色区域)
  • 参数:
    • pic_rgb: Image.Image: PIL Image对象(RGB格式)
    • red_ratio_threshold: float: 红色比例阈值(默认0.8)
    • return_info: bool: 是否返回详细信息(默认False)
  • 返回值: 同 detect_attend_button_red_area()
  • 检测区域: (181, 1261) 到 (890, 1389)(基准1080x2400,开奖结果弹窗区域)
  • 检测逻辑: 同 detect_attend_button_red_area()

20.2 并行像素检测 (read_pixel_stage_state_from_screenshot)

20.2.1 并行检测机制

read_pixel_stage_state_from_screenshot() 使用 ThreadPoolExecutor 并行执行所有检测函数,提高性能。

并行检测任务:

  1. has_coupon_bg: 检测优惠券弹窗背景(模板匹配)
  2. has_redpacket_bg: 检测购物红包弹窗背景(像素检测)
  3. has_lucky_draw_result: 检测开奖结果弹窗(像素检测)
  4. has_attend_button_red: 检测参与按钮红色区域(像素检测)
  5. has_fansclub_join_red: 检测粉丝团加入按钮红色区域(像素检测)
  6. has_fudai_detail: 检测福袋详情页(模板匹配 + 任务数量检测)

并行执行流程:

  1. 创建线程池(ThreadPoolExecutor)
  2. 提交所有检测任务
  3. 等待所有任务完成
  4. 收集检测结果
  5. 返回检测结果字典

性能优化:

  • 并行执行:所有检测任务同时执行,减少总耗时
  • 线程池大小:根据CPU核心数自动调整
  • 异常处理:单个检测任务失败不影响其他任务

20.3 任务数量检测详解

20.3.1 检测原理

任务数量检测通过检测福袋详情页任务列表区域的特征来判断任务数量(1、2或3个任务)。

检测区域: (486, 783) 到 (586, 1158)(基准1080x2400)

检测方法:

  1. Y坐标检测: 在Y坐标1058处检测任务项的位置
  2. X坐标检测: 在X坐标536附近检测任务项的特征
  3. 检测点统计: 统计检测点数量(通常为9个点)
  4. 任务数量判断:
    • 检测点数量 ≈ 3 → 1个任务
    • 检测点数量 ≈ 6 → 2个任务
    • 检测点数量 ≈ 9 → 3个任务

检测流程:

  1. 裁剪任务列表区域
  2. 在指定Y坐标处检测X坐标附近的像素特征
  3. 统计检测点数量
  4. 根据检测点数量判断任务数量
  5. 保存调试图像(标注检测区域和检测结果)

20.3.2 使用场景

任务数量检测主要用于:

  1. 福袋详情验证: 验证是否在福袋详情页
  2. 任务类型判断: 判断福袋是否有多个任务(用于筛选)
  3. 参与决策: 某些任务类型的福袋可能需要特殊处理

20.3.3 调试支持

调试图像保存:

  • 保存检测前图像:标注检测区域
  • 保存检测后图像:标注检测区域、检测点、检测结果
  • 图像文件名包含:操作类型、图片名称、步骤、坐标、检测结果等

调试信息记录:

  • 检测区域坐标
  • 检测到的任务数量
  • 检测Y坐标和X坐标
  • 检测点数量
  • 检测结果(成功/失败)

20.4 调试图像系统详解

20.4.1 调试图像保存机制

保存位置: pic/debug_captures/YYYY-MM-DD/

文件命名规则:

{timestamp}_{operation_type}_{picname}_{step}_{coords}_{result_info}.png

示例文件名:

20251230_123632_detection_福袋任务数量_task_count_detection_(486,783)-(586,1158)_task_count_1_detected_y_1058_check_x_536_check_points_count_9_区域_(486,783)-(586,1158).png

文件命名组成部分:

  1. 时间戳: YYYYMMDD_HHMMSS 格式
  2. 操作类型: pixel_detect、ocr、template_match、detection、cut_pic
  3. 图片名称: 操作的图片名称(如"福袋任务数量"、"开奖结果按钮")
  4. 步骤: 操作步骤(如"检测前"、"识别后"、"预处理后")
  5. 坐标: 检测/识别区域坐标 (x1,y1)-(x2,y2)
  6. 结果信息: 检测/识别结果(如"检测成功"、"task_count_1")

20.4.2 图像标注功能

标注内容:

  1. 坐标区域标注: 在图像上绘制矩形框,标注检测/识别区域
  2. 文本标注: 在图像上添加文本信息(OCR识别结果、检测结果等)
  3. 统计信息标注: 标注检测统计信息(红色比例、检测点数量等)

标注样式:

  • 矩形框:绿色(成功)或红色(失败)
  • 文本:白色背景,黑色文字
  • 字体大小:根据图像尺寸自动调整

20.4.3 自动清理机制

清理策略:

  • 按日期目录组织:每天一个目录
  • 自动清理旧目录:保留最近N天(默认3天)
  • 配置控制:通过 debug_captures.keep_days 配置保留天数

清理时机:

  • 每天第一次保存调试图像时执行清理
  • 清理超过保留天数的目录

20.4.4 启用调试图像

配置方法: 在 config.json 中设置:

{
  "debug_captures": {
    "enabled": true,
    "keep_days": 3
  }
}

注意事项:

  • 调试图像会占用磁盘空间,建议定期清理
  • 生产环境建议关闭调试图像保存(enabled: false)
  • 调试时启用调试图像,便于排查问题

21. 导航和滑动操作详解

21.1 上滑切换直播间

SwipeHandler.swipe_up_to_next_live(analyser) -> None

  • 文件位置: douyin/handlers/douyin_swipe_handler.py

  • 作用: 上滑切换到下一个直播间

  • 参数:

    • analyser: Any: 分析器对象
  • 返回值: None

  • 调用位置: swipe_up_to_next_live() 中调用

  • 主要逻辑:

    1. 预约锁定期检查:

      • 检查是否在预约锁定期内(reservation_focus_until_ts > 当前时间)
      • 如果在锁定期内,不允许上划离开预约直播间,直接返回
      • 记录日志:锁定期剩余秒数
    2. 执行上滑操作:

      • 调用 swipe_up_switch_live() 执行上滑
      • 基准坐标(1080x2400):从 (540, 1700) 滑动到 (540, 700)
      • 滑动距离约1000像素
      • 滑动持续时间:swipe_duration_ms(默认600ms)
    3. 更新直播间位置:

      • room_pos += 1(上滑后位置+1)
      • _swipe_times += 1(滑动次数+1)
    4. 检查滑动次数重置:

      • 调用 maybe_reset_after_swipes() 检查是否需要重置
    5. 设置标志:

      • _just_switched_room = True(标记刚刚切换了直播间)
      • _fudai_detail_first_read = False(清除第一次读取标志)
      • _last_fudai_detail_tuple = None(清除上次详情数据)
    6. 记录直播间标题和位置:

      • 调用 _record_room_title_and_pos() 记录当前直播间的标题和位置
      • 用于回退校验(如果不在回退过程中)

配置参数:

  • swipe_duration_ms: 滑动持续时间(毫秒,默认600)
  • reservation_focus_until_ts: 预约聚焦时间戳(如果 > 当前时间,不允许上划)

代码示例:

def swipe_up_to_next_live(analyser: Any) -> None:
    # 检查预约锁定期
    focus_until = float(getattr(analyser, "reservation_focus_until_ts", 0.0) or 0.0)
    now_ts = time.time()
    if focus_until > 0 and now_ts < focus_until:
        # 在锁定期内,不允许上划
        return
    
    # 执行上滑
    swipe_up_switch_live(analyser)
    
    # 更新位置
    analyser.room_pos += 1
    analyser._swipe_times += 1
    
    # 检查重置
    maybe_reset_after_swipes(analyser)
    
    # 设置标志
    analyser._just_switched_room = True
    analyser._fudai_detail_first_read = False

21.2 下滑回退直播间

SwipeHandler.swipe_down_back_from_live(analyser) -> None

  • 文件位置: douyin/handlers/douyin_swipe_handler.py

  • 作用: 下滑回退到上一个直播间(供预约/无福袋逻辑使用)

  • 参数:

    • analyser: Any: 分析器对象
  • 返回值: None

  • 调用位置: swipe_down_back_from_live() 中调用

  • 主要逻辑:

    1. 执行下滑操作:

      • 调用 swipe_down_back_live() 执行下滑
      • 基准坐标(1080x2400):从 (540, 800) 滑动到 (540, 1600)
      • 滑动距离约800像素
      • 滑动持续时间:swipe_duration_ms(默认600ms)
      • 如果下滑失败,退化为点击返回键
    2. 更新直播间位置:

      • room_pos -= 1(下滑后位置-1)
    3. 记录直播间标题和位置:

      • 调用 _record_room_title_and_pos() 记录当前直播间的标题和位置
      • 用于回退校验(如果不在回退过程中)

配置参数:

  • swipe_duration_ms: 滑动持续时间(毫秒,默认600)
  • reservation_back_swipe_delay_s: 回退滑动延迟(秒,默认0.6)

代码示例:

def swipe_down_back_from_live(analyser: Any) -> None:
    try:
        swipe_down_back_live(analyser)
    except Exception:
        # 退化为点击返回键
        analyser.operation.click_back(analyser.device_id)
    
    # 更新位置
    analyser.room_pos -= 1
    
    # 记录标题和位置
    if not getattr(analyser, "_skip_record_title_during_seek", False):
        analyser._record_room_title_and_pos()

21.3 滑动次数重置

SwipeHandler.maybe_reset_after_swipes(analyser) -> int

  • 文件位置: douyin/handlers/douyin_swipe_handler.py

  • 作用: 达到切换阈值后,在当前直播间页面回退到第一个直播间

  • 参数:

    • analyser: Any: 分析器对象
  • 返回值: int - 重置后的滑动次数(通常为0)

  • 调用位置: swipe_up_to_next_live() 中调用

  • 主要逻辑:

    1. 检查是否启用重置功能:

      • 如果 needswitch = False(单间模式),不执行重置
      • 如果 reset_after_swipes_enabled = False,不执行重置
    2. 检查是否达到阈值:

      • 获取当前滑动次数 _swipe_times
      • 获取阈值 reset_after_swipes(默认50)
      • 如果 _swipe_times < threshold,不执行重置
    3. 执行回退操作:

      • 计算回退次数:back_times = min(swipe_times, 100)(最多100次)
      • 循环执行下滑操作(从上往下滑动):
        • 基准坐标(1080x2400):从 (760, 800) 滑动到 (760, 1600)
        • 滑动持续时间:swipe_duration_ms(默认300ms)
        • 每次滑动后延迟2秒
    4. 重置计数器和位置:

      • _swipe_times = 0
      • room_pos = 0
      • 延迟3秒后返回

配置参数:

  • reset_after_swipes_enabled: 是否启用滑动次数重置(bool,默认False)
  • reset_after_swipes: 滑动次数阈值(默认50)
  • swipe_duration_ms: 滑动持续时间(毫秒,默认300)

代码示例:

def maybe_reset_after_swipes(analyser: Any) -> int:
    if not needswitch or not reset_after_swipes_enabled:
        return analyser._swipe_times
    
    swipe_times = analyser._swipe_times
    threshold = analyser.reset_after_swipes
    
    if swipe_times < threshold:
        return swipe_times
    
    # 执行回退
    back_times = min(swipe_times, 100)
    for i in range(back_times):
        # 从上往下滑动
        swipe_down_back_live(analyser)
        analyser.operation.delay(2)
    
    # 重置
    analyser._swipe_times = 0
    analyser.room_pos = 0
    return 0

21.4 返回推荐页面并重新进入直播间

SwipeHandler.return_to_recommend_and_reenter_live(analyser) -> None

  • 文件位置: douyin/handlers/douyin_swipe_handler.py

  • 作用: 返回推荐页面并重新进入直播间(用于30分钟超时等场景)

  • 参数:

    • analyser: Any: 分析器对象
  • 返回值: None

  • 调用位置: _return_to_recommend_and_reenter_live() 中调用

  • 主要逻辑:

    1. 多次点击返回键:

      • 最多点击 MAX_BACK_CLICKS_TO_RECOMMEND 次(默认10次)
      • 每次点击后:
        • 获取截图
        • 执行阶段诊断
        • 如果阶段为 RECOMMEND_PAGE,跳出循环
        • 延迟 BACK_KEY_CLICK_DELAY 秒(默认1.0秒)
    2. 等待页面稳定:

      • 延迟 PAGE_STABLE_DELAY 秒(默认2.0秒)
    3. 确认当前阶段:

      • 再次截图并执行阶段诊断
      • 记录日志
    4. 点击关注标签并进入直播间:

      • 点击关注标签:坐标 (709, 169)(基准1080x2400)
      • 延迟 FOLLOW_TAB_CLICK_DELAY 秒(默认2.0秒)
      • 点击进入直播间位置:坐标 (103, 385)(基准1080x2400),连点两次
      • 延迟 ENTER_LIVE_CLICK_DELAY 秒(默认0.6秒)
      • 延迟 ENTER_LIVE_FINAL_DELAY 秒(默认2.0秒)
    5. 设置标志和重置时间戳:

      • _just_switched_room = True(标记刚刚切换进入直播间)
      • _last_successful_attend_ts = time.time()(重置最后成功参与时间)
      • _run_start_ts = time.time()(重置运行开始时间)

类常量:

  • MAX_BACK_CLICKS_TO_RECOMMEND = 10: 返回推荐页面的最大返回键点击次数
  • BACK_KEY_CLICK_DELAY = 1.0: 返回键点击后的延迟(秒)
  • PAGE_STABLE_DELAY = 2.0: 页面稳定等待时间(秒)
  • FOLLOW_TAB_CLICK_DELAY = 2.0: 点击关注标签后的延迟(秒)
  • ENTER_LIVE_CLICK_DELAY = 0.6: 点击进入直播间的延迟(秒)
  • ENTER_LIVE_FINAL_DELAY = 2.0: 进入直播间后的最终等待时间(秒)

代码示例:

def return_to_recommend_and_reenter_live(analyser: Any) -> None:
    # 多次点击返回键
    max_back_clicks = analyser.MAX_BACK_CLICKS_TO_RECOMMEND
    for i in range(max_back_clicks):
        analyser.operation.get_screenshot(analyser.device_id)
        stage, seen = analyser._diagnose_stage_from_current_screen()
        
        if stage == "RECOMMEND_PAGE":
            break
        
        analyser.operation.click_back(analyser.device_id)
        analyser.operation.delay(analyser.BACK_KEY_CLICK_DELAY)
    
    # 等待页面稳定
    analyser.operation.delay(analyser.PAGE_STABLE_DELAY)
    
    # 点击关注标签
    follow_tab_x = int(709 * analyser.resolution_ratio_x // 1080)
    follow_tab_y = int(169 * analyser.resolution_ratio_y // 2400)
    analyser.operation.click(analyser.device_id, follow_tab_x, follow_tab_y)
    analyser.operation.delay(analyser.FOLLOW_TAB_CLICK_DELAY)
    
    # 点击进入直播间
    enter_live_x = int(103 * analyser.resolution_ratio_x // 1080)
    enter_live_y = int(385 * analyser.resolution_ratio_y // 2400)
    analyser.operation.click(analyser.device_id, enter_live_x, enter_live_y)
    analyser.operation.delay(analyser.ENTER_LIVE_CLICK_DELAY)
    analyser.operation.click(analyser.device_id, enter_live_x, enter_live_y)
    analyser.operation.delay(analyser.ENTER_LIVE_FINAL_DELAY)
    
    # 设置标志和重置时间戳
    analyser._just_switched_room = True
    analyser._last_successful_attend_ts = time.time()
    analyser._run_start_ts = time.time()

21.5 预约直播间查找

ReservationHandler.seek_reservation_room(analyser, item) -> bool

  • 文件位置: douyin/reservation/douyin_reservation_handler.py

  • 作用: 根据预约记录里的 pos_seen 与当前 room_pos 进行回退,靠近目标直播间

  • 参数:

    • analyser: Any: 分析器对象
    • item: dict: 预约记录(包含 pos_seen、room_title 等)
  • 返回值: bool - True=成功找到, False=未找到

  • 调用位置: _seek_reservation_room() 中调用

  • 主要逻辑:

    1. 计算回退次数:

      • back_times = abs(room_pos - pos_seen)
      • 限制最大回退次数:min(back_times, high_value_fudai_max_swipe_back)
    2. 执行回退操作:

      • 循环执行下滑操作(swipe_down_back_from_live())
      • 每次回退后延迟 reservation_back_swipe_delay_s 秒
      • 更新 room_pos
    3. 回退校验(如果启用):

      • 读取直播间标题
      • 验证标题是否匹配预约记录中的 room_title
      • 如果标题不匹配,尝试自动回退
    4. 记录标题和位置:

      • 调用 _record_room_title_and_pos() 记录当前直播间的标题和位置

配置参数:

  • high_value_fudai_max_swipe_back: 最大回退次数(默认10)
  • reservation_back_swipe_delay_s: 回退滑动延迟(秒,默认0.6)
  • high_value_fudai_back_verify_enabled: 是否启用回退校验(bool,默认False)

代码示例:

def seek_reservation_room(analyser: Any, item: dict) -> bool:
    pos_seen = item.get("pos_seen", 0)
    current_pos = analyser.room_pos
    back_times = abs(current_pos - pos_seen)
    
    # 限制最大回退次数
    max_back = analyser.high_value_fudai_max_swipe_back
    back_times = min(back_times, max_back)
    
    # 执行回退
    for i in range(back_times):
        swipe_down_back_from_live(analyser)
        analyser.operation.delay(analyser.reservation_back_swipe_delay_s)
    
    # 回退校验
    if analyser.high_value_fudai_back_verify_enabled:
        title = read_live_room_title(analyser)
        if title != item.get("room_title", ""):
            # 标题不匹配,尝试自动回退
            # ...
    
    return True

22. 桌面检测和自救机制详解

22.1 桌面检测机制

22.1.1 检测原理

桌面检测通过检查当前前台应用的包名来判断是否在抖音前台:

  1. 获取前台包名:

    • 调用 operation.get_top_package(device_id) 获取前台应用包名
    • 使用ADB命令:adb shell dumpsys window windows | grep mCurrentFocus
  2. 判断是否为抖音包:

    • 检查包名是否包含以下关键词:
      • "aweme"(抖音包名)
      • "douyin"(抖音)
      • "com.ss.android.ugc"(抖音包名前缀)
    • 如果包名存在且不包含以上关键词,判定为不在抖音前台
  3. 检测时机:

    • 在 run_once_basic() 中,阶段诊断后执行
    • 每次循环都会检测,确保及时发现异常

22.1.2 检测实现

代码位置: douyin/core/douyin_fudai.py 的 run_once_basic() 方法中

检测流程:

# 1. 获取前台包名
top_pkg = analyser.operation.get_top_package(analyser.device_id)

# 2. 判断是否为抖音包
is_douyin_pkg = top_pkg and (
    "aweme" in top_pkg
    or "douyin" in top_pkg
    or "com.ss.android.ugc" in top_pkg
)

# 3. 如果不在抖音前台,触发自救
if top_pkg and not is_douyin_pkg:
    # 执行自救操作
    # ...

22.2 自救机制

22.2.1 自救流程

当检测到不在抖音前台时,执行以下自救操作:

  1. 点击桌面图标:

    • 优先使用配置的坐标:desktop_icon_x, desktop_icon_y
    • 如果配置不存在,使用默认坐标:(153, 260)(基准1080x2400)
    • 延迟2秒
  2. 点击直播按钮:

    • 使用配置的坐标:yanghao_fallback_live_x, yanghao_fallback_live_y
    • 延迟1.5秒
  3. 点击进入直播间:

    • 使用配置的坐标:yanghao_fallback_enter_live_x, yanghao_fallback_enter_live_y
    • 连点两次(确保进入直播间)
    • 延迟0.6秒(第一次点击后)
    • 延迟2.0秒(第二次点击后)
  4. 重新执行主流程:

    • 延迟0.5秒
    • 递归调用 run_once_basic() 重新执行主流程
    • 自救完成后前台包名应为抖音,下一次循环不会再次进入自救分支

22.2.2 配置参数

桌面图标坐标:

  • desktop_icon_x: 桌面图标X坐标(默认153)
  • desktop_icon_y: 桌面图标Y坐标(默认260)

直播按钮坐标:

  • yanghao_fallback_live_x: 直播按钮X坐标(默认540)
  • yanghao_fallback_live_y: 直播按钮Y坐标(默认2000)

进入直播间坐标:

  • yanghao_fallback_enter_live_x: 进入直播间X坐标(默认540)
  • yanghao_fallback_enter_live_y: 进入直播间Y坐标(默认1200)

配置示例:

{
  "desktop_icon_x": 153,
  "desktop_icon_y": 260,
  "yanghao_fallback_live_x": 540,
  "yanghao_fallback_live_y": 2000,
  "yanghao_fallback_enter_live_x": 540,
  "yanghao_fallback_enter_live_y": 1200
}

22.3 自救机制代码实现

代码位置: douyin/core/douyin_fudai.py 的 run_once_basic() 方法中

完整实现:

# 检测是否意外返回桌面
try:
    top_pkg = analyser.operation.get_top_package(analyser.device_id) or ""
    
    # 判断是否为抖音包
    is_douyin_pkg = top_pkg and (
        "aweme" in top_pkg
        or "douyin" in top_pkg
        or "com.ss.android.ugc" in top_pkg
    )
    
    if top_pkg and not is_douyin_pkg:
        # 执行自救操作
        try:
            # 点击桌面图标
            try:
                analyser.click(
                    int(analyser.desktop_icon_x),
                    int(analyser.desktop_icon_y)
                )
            except Exception:
                # 退化为默认硬编码位置
                analyser.click(153, 260)
            analyser.operation.delay(2)
            
            # 点击直播按钮
            try:
                lx = int(analyser.yanghao_fallback_live_x)
                ly = int(analyser.yanghao_fallback_live_y)
                analyser.click(lx, ly)
                analyser.operation.delay(1.5)
            except Exception:
                pass
            
            # 点击进入直播间
            try:
                ex = int(analyser.yanghao_fallback_enter_live_x)
                ey = int(analyser.yanghao_fallback_enter_live_y)
                analyser.click(ex, ey)
                analyser.operation.delay(0.6)
                analyser.click(ex, ey)
                analyser.operation.delay(2.0)
            except Exception:
                pass
            
            # 重新执行主流程
            analyser.operation.delay(0.5)
            analyser.run_once_basic()  # 递归调用
            return
        except Exception as e:
            analyser._log_kv("自救", "恢复失败", error=str(e))
except Exception as exc:
    analyser._log_kv("自救", "桌面检测异常", error=str(exc))

22.4 自救机制的特点

  1. 自动检测: 每次循环都会检测,无需手动触发
  2. 自动恢复: 检测到异常后自动执行恢复操作
  3. 递归调用: 自救完成后递归调用 run_once_basic(),确保流程连续性
  4. 防止重复: 自救完成后前台包名应为抖音,下一次循环不会再次进入自救分支
  5. 错误处理: 每个步骤都有异常处理,确保自救流程的健壮性

22.5 使用场景

桌面检测和自救机制主要用于以下场景:

  1. 意外返回桌面: 用户手动返回桌面或系统自动返回桌面
  2. 应用切换: 用户切换到其他应用
  3. 系统弹窗: 系统弹窗导致抖音不在前台
  4. 应用崩溃: 抖音应用崩溃后自动恢复

22.6 注意事项

  1. 坐标配置: 不同设备的桌面图标和按钮位置可能不同,需要根据实际情况调整配置
  2. 延迟时间: 自救操作中的延迟时间需要根据设备性能调整
  3. 递归深度: 自救机制使用递归调用,但只递归一次,不会导致栈溢出
  4. 日志记录: 自救过程中的所有操作都会记录日志,便于排查问题

23. 日志系统详解

23.1 日志系统架构

项目采用分层日志系统,包含以下组件:

  1. LoggingWrapper: 统一日志包装器,提供增强的日志记录功能
  2. ActionLogger: 行为日志记录器,记录关键操作和耗时
  3. PerformanceTracker: 性能追踪器,统计函数和操作的耗时
  4. ErrorLogger: 错误日志记录器,记录异常和错误信息
  5. DebugLogger: 调试日志记录器,记录调试信息
  6. track_action: 操作追踪装饰器,自动记录函数耗时

23.2 LoggingWrapper 详解

23.2.1 核心功能

文件位置: douyin/logging/douyin_logging_wrapper.py

主要方法:

  • enhanced_log_kv(): 增强的日志记录方法
  • log_step_time(): 记录步骤耗时

23.2.2 enhanced_log_kv() 方法

功能: 增强的日志记录方法,始终输出到 stdout(供 GUI 捕获),同时可选输出到标准 logging

参数:

  • analyser: Any: 分析器对象
  • *args: 位置参数,第一个是tag,第二个是msg
  • **fields: 关键字参数字典

主要特性:

  1. 参数解析:

    • 优先使用位置参数(tag, msg)
    • 支持关键字参数(tag, msg, level等)
    • 自动处理参数冲突
  2. 日志格式:

    [时间戳] [级别] [标签] [调用者] 消息 字段...
    
    • 时间戳:YYYY-MM-DD HH:MM:SS.mmm 格式
    • 级别:DEBUG, INFO, WARNING, ERROR, CRITICAL
    • 标签:日志分类(如"流程"、"错误"、"参与"等)
    • 调用者:文件名:函数名:行号
    • 消息:日志消息内容
    • 字段:键值对形式(如 价值元=500.0)
  3. 字段映射:

    • 自动将英文字段名映射为中文(如 value_yuan → 价值元)
    • 支持自定义字段映射
  4. 自动分隔符:

    • 错误/警告发生时自动添加分隔符
    • 运行开始时添加分隔符
    • 阶段变化时添加分隔符
    • 重要操作时添加分隔符
  5. 调用者信息提取:

    • 自动提取调用栈信息
    • 跳过日志包装层,找到真正的调用者
    • 格式:文件名:函数名:行号

代码示例:

# 使用位置参数
analyser._log_kv("流程", "开始处理福袋", value_yuan=500.0, countdown=60)

# 使用关键字参数
analyser._log_kv(tag="错误", msg="处理失败", error="连接超时", level="ERROR")

# 输出格式:
# [2025-12-30 13:22:35.123] [INFO] [流程] [douyin_fudai.py:run_once_basic:551] 开始处理福袋 价值元=500.0 倒计时=60

23.2.3 log_step_time() 方法

功能: 记录步骤耗时

参数:

  • analyser: Any: 分析器对象
  • step_name: str: 步骤名称
  • start_time: float: 开始时间(时间戳)

代码示例:

start_time = time.time()
# ... 执行操作 ...
LoggingWrapper.log_step_time(analyser, "处理福袋详情", start_time)

23.3 ActionLogger 详解

23.3.1 核心功能

文件位置: douyin/logging/action_logger.py

主要方法:

  • log_operation(): 记录操作
  • log_ocr(): 记录OCR操作
  • log_decision(): 记录决策
  • log_state_change(): 记录状态变化
  • log_step(): 记录步骤

23.3.2 日志输出

输出位置:

  • 控制台输出(stdout)
  • 文件输出:logs/actions.log(轮转文件,最大10MB,保留5个备份)

日志格式:

时间戳 - 操作类型: 详细信息 耗时=秒数

代码示例:

action_logger = ActionLogger()

# 记录OCR操作
action_logger.log_ocr("福袋内容", "价值500元", elapsed=2.5)

# 记录决策
action_logger.log_decision("参与福袋", elapsed=0.1)

# 记录状态变化
action_logger.log_state_change("等待中", "已参与", elapsed=1.2)

# 记录步骤
action_logger.log_step("处理福袋详情", elapsed=3.5)

23.4 PerformanceTracker 详解

23.4.1 核心功能

文件位置: douyin/logging/performance_tracker.py

主要方法:

  • start_timer(): 启动计时器
  • end_timer(): 结束计时器并返回耗时
  • get_elapsed(): 获取当前耗时(不结束计时器)
  • get_statistics(): 获取统计信息(平均耗时)

23.4.2 使用方式

手动计时:

perf = PerformanceTracker()

# 启动计时器
timer_id = perf.start_timer("处理福袋")

# ... 执行操作 ...

# 结束计时器并获取耗时
elapsed = perf.end_timer(timer_id)

装饰器方式:

perf = PerformanceTracker()

@perf.track_function
def process_fudai():
    # ... 执行操作 ...
    pass

统计信息:

# 获取平均耗时统计
stats = perf.get_statistics()
# 返回: {"处理福袋": 2.5, "OCR识别": 1.2, ...}

23.5 track_action 装饰器

23.5.1 功能

文件位置: douyin/logging/action_tracker.py

功能: 自动记录函数耗时与操作信息

使用方式:

from douyin.logging import track_action

@track_action("swipe_up_to_next_live")
def swipe_up_to_next_live(analyser):
    # ... 执行操作 ...
    pass

工作原理:

  1. 函数执行前:启动计时器
  2. 函数执行后:结束计时器并记录日志
  3. 自动记录到 ActionLogger

23.6 ErrorLogger 详解

23.6.1 核心功能

文件位置: douyin/logging/error_logger.py

主要方法:

  • log_exception(): 记录异常
  • log_error(): 记录错误
  • log_warning(): 记录警告
  • capture_error_context(): 捕获错误上下文

23.6.2 使用方式

error_logger = ErrorLogger()

try:
    # ... 执行操作 ...
except Exception as e:
    # 记录异常
    error_logger.log_exception(e, context={"device_id": device_id})

# 记录错误
error_logger.log_error("处理失败", context={"reason": "超时"})

# 记录警告
error_logger.log_warning("配置缺失", context={"key": "min_prize_value_yuan"})

23.7 DebugLogger 详解

23.7.1 核心功能

文件位置: douyin/logging/debug_logger.py

主要方法:

  • log_function_entry(): 记录函数入口
  • log_function_exit(): 记录函数退出
  • log_variable(): 记录变量快照
  • log_call_stack(): 记录调用栈
  • log_exception(): 记录异常

23.7.2 使用方式

debug_logger = DebugLogger(enabled=True)

# 记录函数入口
debug_logger.log_function_entry("process_fudai", value=500.0)

# 记录变量
debug_logger.log_variable("room_pos", 5)

# 记录调用栈
debug_logger.log_call_stack()

# 记录异常
debug_logger.log_exception(e, context={"step": "处理福袋"})

23.8 日志系统配置

23.8.1 日志级别

  • DEBUG: 调试信息(函数入口/退出、变量快照等)
  • INFO: 一般信息(操作记录、状态变化等)
  • WARNING: 警告信息(配置缺失、非关键错误等)
  • ERROR: 错误信息(异常、失败操作等)
  • CRITICAL: 严重错误(系统级错误等)

23.8.2 日志文件

统一日志文件: logs/unified_YYYY-MM-DD.log

  • 按日期轮转
  • 包含所有日志信息

行为日志文件: logs/actions.log

  • 轮转文件(最大10MB,保留5个备份)
  • 包含操作记录和耗时信息
  • 每行支持 log_type 内容(如 OP, ERR, DEBUG, SCREENSHOT, PERF)以区分操作、错误、调试、截图、性能等类型;同一条输出来自 analyser._log_kv 的 log_type 或自动推断结果,GUI 侧可以据此高亮/过滤。

错误日志文件: logs/errors.log

  • 轮转文件(最大10MB,保留5个备份)
  • 包含错误和异常信息

23.9 日志系统最佳实践

  1. 使用合适的日志级别: 根据信息重要性选择合适的级别
  2. 提供上下文信息: 在日志中包含足够的上下文信息(设备ID、状态等)
  3. 记录耗时信息: 对关键操作记录耗时,便于性能分析
  4. 使用字段映射: 使用标准字段名,自动映射为中文
  5. 避免敏感信息: 不要在日志中记录敏感信息(密码、密钥等)

23.10 调试图像与截图说明

23.10.1 存放位置与路径工具

  • 所有截图与调试图像保存在项目 pic/ 目录,使用 path_config.get_pic_dir() 与 path_config.get_screenshot_path() 获取路径;
  • 裁剪供 OCR 使用的图片通过 path_config.get_cut_pic_path(name) 生成(即 pic/<name>.png);
  • 调试图像也会在日志目录 logs/ 下通过 actions.log 记录对应操作条目,便于追踪每张截图的来源。

23.10.2 配置开关与保留策略

  • 调试捕获配置位于 config/config.json 的 debug_captures 段(示例见 7.2.12);主要字段:
    • enabled:是否启用调试捕获(布尔);
    • keep_days:保留天数;
    • max_files:最大文件数;
    • async_save:是否异步保存以减少主流程阻塞;
    • log_on_complete:保存完成后是否在 actions.log 写入记录;

23.10.3 镜像与环境变量

  • 若需要将截图镜像到外部目录以便实时查看,可设置环境变量 EXTERNAL_DOUYIN_FUDAI_DIR 指向目标目录(程序会尝试在该目录下复制调试图像);
  • 若要禁用镜像或避免额外 IO,设置 DISABLE_SCREENSHOT_MIRROR=1;
  • 在仅需调试截图但不希望初始化OCR模型时,可设置 SKIP_OCR_INIT=1(跳过OCR模型加载);

23.10.4 性能注意事项与快速命令

  • 保存大量调试图像会增加 IO 开销:生产运行建议关闭 debug_captures 或启用限制(max_files、keep_days);
  • 推荐在开发/调试时使用异步保存(async_save=true)并启用 log_on_complete,方便排障而不阻塞主流程。

示例:快速启用截图镜像并保留调试图像(Linux/WSL 或 PowerShell 环境变量用法相似)

EXTERNAL_DOUYIN_FUDAI_DIR=<外部调试目录> SKIP_OCR_INIT=1 python bin/run_cli.py --device-id <DEVICE_ID> --needswitch

示例:禁用截图镜像以提高性能

DISABLE_SCREENSHOT_MIRROR=1 python bin/run_cli.py --device-id <DEVICE_ID>

24. OCR预处理和优化详解

24.1 OCR预处理系统

24.1.1 preprocess_for_ocr() 函数

文件位置: douyin/utils/ocr_preprocess.py

功能: 对已由 cut_pic 生成的裁剪图做预处理,返回可传入 analyse_pic_* 的图片名

参数:

  • analyser: Any: fudai_analyse 实例
  • cut_pic_name: str: cut_pic 时使用的名称(不含扩展名)

返回值: str - 预处理后图片的名称(不含扩展名)

预处理流程:

  1. 转灰度:

    • 使用 Image.convert("L") 将图像转换为灰度图
    • 减少颜色信息,提高OCR识别准确率
  2. 放大两倍:

    • 使用 Image.resize() 和 Image.LANCZOS 算法放大图像
    • 放大倍数:2倍(宽度和高度都放大2倍)
    • 提高小字体的识别准确率
  3. 自动对比度调整:

    • 使用 ImageOps.autocontrast() 自动调整对比度
    • 增强文字与背景的对比度
  4. 锐化处理:

    • 使用 ImageFilter.SHARPEN 锐化图像
    • 提高文字边缘清晰度

代码示例:

from douyin.utils.ocr_preprocess import preprocess_for_ocr

# 裁剪图像
analyser.cut_pic(200, 600, 880, 900, "福袋内容", "内容区域")

# 预处理图像
preprocessed_name = preprocess_for_ocr(analyser, "福袋内容")

# 使用预处理后的图像进行OCR
result = analyser.operation.analyse_pic_word(preprocessed_name, 0)

24.1.2 预处理效果

预处理前:

  • 原始彩色图像
  • 可能包含背景干扰
  • 文字可能较小或模糊

预处理后:

  • 灰度图像(减少颜色干扰)
  • 放大2倍(提高小字体识别率)
  • 对比度增强(文字更清晰)
  • 锐化处理(边缘更清晰)

24.2 OCR引擎优化

24.2.1 OCR引擎初始化

文件位置: operations/ocr_operations.py

初始化优化:

  1. 环境变量设置:

    # 禁用模型源连通性检查(避免启动耗时/卡死)
    os.environ.setdefault("DISABLE_MODEL_SOURCE_CHECK", "True")
    
    # 抑制冗余信息
    os.environ.setdefault("GLOG_minloglevel", "2")
    os.environ.setdefault("OMP_NUM_THREADS", "1")
    
  2. 延迟初始化:

    • 支持延迟初始化(测试流程/只做点击时不需要 OCR)
    • 通过 SKIP_OCR_INIT 环境变量控制
  3. CPU模式:

    • 默认使用CPU模式(删除GPU检测)
    • 如果需要GPU加速,需要手动配置

24.2.2 OCR识别优化

文件位置: douyin/core/underlying_operations.py

优化措施:

  1. 图像预处理:

    • 锐化处理:使用 ImageFilter.UnsharpMask
    • 对比度增强:使用 ImageEnhance.Contrast
    • 提高数字识别准确率
  2. 调试图像保存:

    • 保存OCR前的预处理图像
    • 使用完整截图(如果可用)
    • 标注OCR区域坐标
  3. OCR结果缓存:

    • 对于相同的图像区域,可以缓存OCR结果
    • 避免重复识别相同内容

24.3 并行OCR处理

24.3.1 并行OCR实现

实现方式:

from concurrent.futures import ThreadPoolExecutor

def get_fudai_contain(analyser, renwu: int = 2):
    # 使用线程池并行执行OCR任务
    with ThreadPoolExecutor(max_workers=6) as executor:
        # 提交多个OCR任务
        future_task_list = executor.submit(ocr_task_list)
        future_content = executor.submit(ocr_content)
        future_countdown_mm = executor.submit(ocr_countdown_mm)
        future_countdown_ss = executor.submit(ocr_countdown_ss)
        future_value = executor.submit(ocr_value)
        future_button = executor.submit(ocr_button)
        
        # 等待所有任务完成
        task_list_raw = future_task_list.result()
        fudai_content_raw = future_content.result()
        # ... 其他结果 ...

24.3.2 并行OCR优势

  1. 提高效率: 多个OCR任务同时执行,减少总耗时
  2. 充分利用资源: 充分利用多核CPU资源
  3. 独立任务: 每个OCR任务独立,互不影响

24.3.3 并行OCR任务

福袋详情读取中的并行OCR任务:

  1. 任务列表OCR: 识别任务列表区域
  2. 福袋内容OCR: 识别福袋内容描述
  3. 倒计时分钟OCR: 识别倒计时分钟数字
  4. 倒计时秒OCR: 识别倒计时秒数字
  5. 价值OCR: 识别奖品价值
  6. 按钮状态OCR: 识别参与按钮状态

24.4 OCR性能优化建议

24.4.1 硬件优化

  1. 启用GPU加速(如果可用):

    self.ocr = easyocr.Reader(
        gpu=True,  # 如果GPU可用
        verbose=False
    )
    
  2. 多线程处理:

    • 使用 ThreadPoolExecutor 并行执行OCR任务
    • 充分利用多核CPU资源

24.4.2 软件优化

  1. 减少OCR调用次数:

    • 如果任务列表OCR检测到"观看X分钟"任务,可以提前返回
    • 优化倒计时识别,减少分割OCR的使用
  2. 优化图像预处理:

    • 缓存裁剪后的图像,避免重复裁剪
    • 优化图像保存路径,使用内存缓存
  3. OCR结果缓存:

    • 对于相同的图像区域,可以缓存OCR结果
    • 避免重复识别相同内容
  4. 减少OCR区域大小:

    • 精确裁剪OCR区域,减少不必要的图像内容
    • 提高OCR识别速度

24.4.3 当前性能

根据日志分析:

  • 单次OCR耗时: 约3-4秒(CPU模式)
  • 福袋详情总OCR耗时: 约3-4秒(并行执行)
  • 阶段诊断OCR耗时: 约3-4秒

24.4.4 预期优化效果

如果启用GPU加速:

  • 单次OCR耗时: 可能降至0.5-1秒
  • 总耗时: 可能降至1-2秒

如果优化OCR调用次数:

  • 减少1次OCR调用: 节省约3-4秒
  • 提前返回: 可以节省后续OCR调用

24.5 OCR预处理最佳实践

  1. 统一使用预处理: 所有OCR操作前都使用 preprocess_for_ocr() 预处理
  2. 保存预处理图像: 保存预处理后的图像,便于调试和分析
  3. 调整预处理参数: 根据实际效果调整预处理参数(放大倍数、对比度等)
  4. 监控OCR性能: 定期监控OCR耗时,识别性能瓶颈
  5. 优化OCR区域: 精确裁剪OCR区域,减少不必要的图像内容

文档总结

本文档详细介绍了抖音福袋挂机项目的技术实现,包括:

  1. 项目概述: 项目简介、核心功能、技术栈
  2. 项目架构: 整体架构、目录结构、设计模式
  3. 完整流程图: 主循环流程、阶段诊断流程、福袋处理流程
  4. 关键函数说明: 所有关键函数的详细说明(参数、返回值、调用位置、实现细节)
  5. 底层操作函数: ADB操作、截图、OCR、图像处理等
  6. 核心类和数据结构: fudai_analyse 类、预约数据结构等
  7. 配置系统: 所有配置项的详细说明
  8. 状态管理机制: 运行状态、预约状态、等待开奖状态等
  9. 错误处理和异常情况: 常见错误和恢复机制
  10. 代码示例: 完整运行示例、各模块使用示例
  11. 模块详解: 各模块的职责和实现
  12. 数据流和状态管理: 数据流图、状态转换图
  13. 关键技术实现: 像素检测、模板匹配、OCR、并行处理
  14. 扩展指南和最佳实践: 如何扩展功能、最佳实践
  15. 关键文件索引和调试指南: 文件索引、调试方法

文档版本: V3.0
最后更新: 2025-12-30
维护者: AI助手、开发者


文档状态: ✅ 已完成
当前进度: 已完成所有章节(1-26章)
文档完整性: 100%

新增章节:

  • 第16章:高级主题和深入理解
  • 第17章:预约验证和错误处理模块
  • 第18章:核心处理函数详解补充
  • 第19章:工具函数和辅助模块详解
  • 第20章:检测功能详解
  • 第21章:导航和滑动操作详解
  • 第22章:桌面检测和自救机制详解
  • 第23章:日志系统详解
  • 第24章:OCR预处理和优化详解
  • 第25章:路径配置系统详解
  • 第26章:文本处理工具函数详解