Codex 299ced21c8 精修 WebUI 第二轮:数据表/表格/图表/预约卡
- workspaceHeader 加左侧 2px primary accent + uppercase eyebrow
- stats 卡片:tabular-nums + uppercase 标签 + 字号统一 text-xl
- table:sticky 表头 uppercase + zebra 奇偶行 + hover 高亮 + mono 列灰度
- timeline 图:4 等分水平网格虚线 + Y 轴 0/mid/max 三档 mono 标签
- 空状态:.hint 单独使用时升级为虚线圆框居中占位 + 圆形 dot
- 预约卡片:reservationIndex 加圆点 + reservationValue 改 uppercase pill;hover 去 transform,纯 box-shadow 反馈
- cache-bust v4 → v5
2026-05-21 09:29:38 +08:00
2026-05-20 20:49:19 +08:00

抖音福袋挂机脚本 - 详细文档

一个功能完善的抖音直播间福袋自动挂机工具

基于 ADB + OCR + 像素检测 + 模板匹配技术

Version Python Platform


📖 目录

📋 版本更新日志

V3.3.3 (2025-12-28)

  • ✨ 新增:30分钟超时保护机制
    • 自动检测长时间无参与的情况,防止脚本卡在无效状态
    • 可配置超时时间(默认30分钟)
    • 超时后自动返回推荐页面重新开始
  • 🐛 修复:修复模板和截图路径配置问题
    • 统一使用项目根目录的 assets 和 pic 目录
    • 修复直播间检测模板文件路径错误
    • 确保所有模板文件路径配置正确
  • 🔧 优化:路径配置统一化
    • 使用 path_config.py 统一管理所有文件路径
    • 简化路径配置逻辑,提高代码可维护性
  • 🔧 优化:行为日志系统
    • 修复行为日志路径问题,统一使用 path_config.get_actions_log_path()
    • 修复 GUI 和 Web GUI 中的日志读取路径
    • 实现完整的行为日志查看器组件
  • 📝 更新:完善文档和流程图
    • 更新流程图以反映30分钟超时检查
    • 修正阶段诊断步骤编号
    • 完善预约回退子流程图
    • 更新代码结构说明,反映模块化重构

V3.3.2 (2025-12-25)

  • 🐛 修复:修复预约回退功能不生效的问题
    • 修复 needswitch 配置未从 config.json 正确加载的问题
    • 修复 self.reservations 未从状态文件加载的问题
    • 添加预约回退逻辑的详细调试日志
  • 🔧 优化:预约回退逻辑优化
    • 每次 run_once_basic 执行时自动从状态文件加载预约数据
    • 确保预约队列始终包含最新数据

V3.2.0

  • ✨ 新增:高价值福袋预约功能
  • ✨ 新增:高价值直播间回访功能
  • 🔧 优化:推荐页养号逻辑优化

V3.1.0

  • ✨ 新增:推荐页养号功能
  • 🔧 优化:OCR 识别准确率提升

V3.0.0

  • 🔄 重大更新:引入 PaddleOCR 替换 pytesseract
  • ✨ 新增:自动分辨率适配
  • 🐛 修复:修复大量已知问题

V2.x

  • 多分辨率支持
  • 稳定性提升
  • 各种 bug 修复

V1.x

  • 基础功能实现
  • 福袋检测和参与
  • 自动领奖

⚠️ 免责声明

  1. 本工具仅供学习交流使用,请勿用于商业用途。

  2. 使用本工具产生的任何后果由使用者自行承担,包括但不限于:

    • 账号被封禁或限制
    • 数据丢失或泄露
    • 设备损坏
    • 其他法律风险
  3. 请遵守抖音平台相关规则,不要使用本工具进行违法违规操作。

  4. 作者不对使用本工具造成的任何损失负责。

  5. 使用本工具即表示您已阅读并同意本免责声明。


📞 支持与反馈

如有问题或建议,请优先在仓库中提交 Issue,或按照下列步骤提供反馈:

  • 标题(必填):一句话概述问题或建议
  • 环境信息(必填):操作系统、Python 版本、ADB 版本、设备型号
  • 复现步骤(必填):最小复现步骤(命令、点击顺序等)
  • 日志与截图(可选):运行日志(logs/ 下相关文件)、截图或录屏
  • 期望行为与实际行为(可选):描述期望结果与实际观察到的结果

如果你愿意,可以在 Issue 中附上 --verbose 模式输出或 logs/ 中最新的日志文件,这有助于定位问题。


🤝 贡献(Contributing)

欢迎 PR、Issue、或参与讨论。贡献流程建议:

  1. Fork 本仓库并在本地新建分支:git checkout -b fix/your-change
  2. 在分支上实现改动,并尽量保持风格一致
  3. 运行现有测试(如适用)并确保无新错误
  4. 提交 PR,标题使用“类型:简短描述”(例如 fix: 修复 OCR 识别问题)
  5. 在 PR 描述中说明变更细节、测试方法和影响范围

代码风格与规范:保持现有代码风格,使用清晰的函数和变量名,避免大面积重构而不提前沟通。


🐞 报告问题模板(建议)

Issue 模板参考:

标题:简短描述

环境:
- 操作系统:Windows 10/11
- Python:3.10
- ADB:platform-tools 版本
- 设备型号:例如 Mi 10

复现步骤:
1. 启动脚本:`python run_cli.py --...`
2. 执行到 XX 步骤
3. 观察到异常

日志:请粘贴相关 logs/ 下的日志片段或上传文件

截图/录屏:如有请附上

期望:期望看到的行为
实际:实际看到的行为

✅ 测试

本仓库包含若干测试文件(tests/ 目录),可使用以下方式运行:

# 运行所有测试
pytest -q

# 运行单个测试文件
pytest tests/unit/test_example.py::test_some_behavior -q

📜 许可(License)

本仓库当前未在根目录添加明确的开源许可文件(LICENSE)。如果你希望对外发布或在项目中使用本代码,请先在 Issue 中联系作者或为仓库添加合适的许可证(例如 MIT / Apache-2.0 / GPL-3.0)。


联系方式

  • 提交 Issue:仓库 Issues 页面
  • Pull Request:提交 PR 以贡献代码

感谢使用抖音福袋挂机脚本!

如果这个项目对你有帮助,欢迎 Star ⭐ 并提出你的建议或贡献代码。

- 自动识别开奖结果(中奖/未中奖) - 中奖后自动领取奖品 - 处理订单确认页面 - 自动关闭各种弹窗和提示

5. 高价值福袋预约

  • 自动识别高价值福袋(可配置阈值)
  • 记录福袋开奖时间
  • 提前返回直播间参与抽奖
  • 支持多个预约同时管理
  • 防止回退过远导致异常
  • 重要:预约回退功能需要启用"允许切换直播间"(needswitch=true)才能正常工作
  • 预约数据自动从状态文件加载,确保重启后仍能继续处理预约

6. 高价值直播间回访

  • 记录高价值直播间信息
  • 定时回访高价值直播间
  • 支持仅本次运行回访或持久化回访

7. 推荐页养号功能

  • 自动点赞(可配置概率)
  • 自动收藏(可配置概率)
  • 自动评论(可配置概率和内容)
  • 模拟真实用户行为,降低风控风险
  • 支持关键词触发(仅对特定内容点赞/收藏)

8. 人机验证处理

  • 自动检测人机验证弹窗
  • 支持滑块验证(自动计算距离)
  • 支持图片点击验证
  • 支持人脸识别验证
  • 失败后自动重试

9. 弹窗处理

  • 自动关闭优惠券弹窗
  • 自动关闭购物红包弹窗
  • 处理各种系统提示弹窗

10. 直播间切换

  • 支持上划切换直播间
  • 可配置切换策略(倒计时阈值)
  • 支持切换N次后回到第一个直播间(循环模式)
  • 智能处理直播结束、网络异常等情况

11. 30分钟超时保护

  • 自动检测长时间无参与的情况
  • 防止脚本在无效状态下卡死
  • 可配置超时时间(默认30分钟)
  • 超时后自动返回推荐页面重新开始
  • 记录最后成功参与时间,提高脚本稳定性

🏗️ 技术架构

核心技术栈

  • Python 3.10+:主要编程语言
  • ADB(Android Debug Bridge):设备连接和控制
  • PaddleOCR:OCR 文字识别引擎
  • OpenCV(cv2):图像处理和模板匹配
  • Pillow(PIL):图像处理库
  • NumPy:数值计算和数组操作

检测技术

  1. 像素检测

    • 基于颜色和像素模式的快速检测
    • 用于检测弹窗背景、按钮区域等
    • 速度快,资源占用低
  2. 模板匹配

    • 使用 OpenCV 的模板匹配算法
    • 用于识别图标、按钮等UI元素
    • 支持多分辨率适配
  3. OCR 识别

    • 使用 PaddleOCR 识别文字内容
    • 用于识别福袋内容、倒计时、价值等
    • 支持中英文识别
  4. 阶段诊断

    • 综合使用像素检测、模板匹配和OCR
    • 判断当前页面状态(直播间、推荐页、详情页等)
    • 支持并行检测,提高效率

架构设计

┌─────────────────────────────────────────┐
│     GUI / Web GUI / CLI (用户界面层)     │
│  gui_app.py / web_gui.py / run_cli.py   │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│    douyin/core/douyin_fudai.py          │
│    fudai_analyse (Mixin 组合模式)        │
│    (核心调度器 - 主流程控制)              │
└──────────────┬──────────────────────────┘
               │
    ┌──────────┼──────────┐
    │          │          │
┌───▼───┐ ┌───▼───┐ ┌───▼───┐
│阶段诊断│ │福袋核心│ │弹窗处理│
│stage/ │ │fudai/ │ │handlers│
└───────┘ └───────┘ └───────┘
    │          │          │
    └──────────┼──────────┘
               │
┌──────────────▼──────────────────────────┐
│    operations/ (底层操作模块)             │
│    device / screenshot / ocr            │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│    path_config.py (路径配置)             │
│    统一管理所有文件路径                   │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│    ADB / PaddleOCR (系统底层接口)        │
└─────────────────────────────────────────┘

设计特点:

  • 模块化设计:功能按模块划分,便于维护和扩展
  • Mixin 模式:核心类使用 Mixin 组合,功能解耦
  • 路径统一管理:所有路径通过 path_config.py 统一配置
  • 日志系统:统一日志和行为日志分离,便于调试和分析

💻 环境要求与安装

系统要求

  • 操作系统:Windows 10/11(64位)
  • Python:3.10 或更高版本(推荐 3.10-3.12)
  • 内存:至少 4GB RAM(推荐 8GB+)
  • 存储:至少 2GB 可用空间

必需软件

  1. Python 3.10+

  2. ADB(Android Debug Bridge)

  3. Android 设备

    • 安卓手机或平板(Android 5.0+)
    • 已开启开发者模式和 USB 调试
    • 已安装抖音 APP

安装步骤

1. 克隆或下载项目

# 如果使用 Git
git clone <repository-url>
cd <项目目录>

# 或直接下载 ZIP 文件并解压

2. 创建虚拟环境(推荐)

# 创建虚拟环境
python -m venv .venv

# 激活虚拟环境
# Windows PowerShell:
.venv\Scripts\Activate.ps1
# Windows CMD:
.venv\Scripts\activate.bat

3. 安装 Python 依赖

# 安装核心依赖
pip install pillow paddlepaddle paddleocr numpy opencv-python

# 如果 paddlepaddle 安装失败,可以尝试:
# CPU 版本(推荐)
pip install paddlepaddle==2.5.2 -i https://pypi.tuna.tsinghua.edu.cn/simple

# 或 GPU 版本(需要 CUDA)
pip install paddlepaddle-gpu==2.5.2 -i https://pypi.tuna.tsinghua.edu.cn/simple

# 安装 GUI 依赖(可选)
pip install ttkbootstrap

# 安装 Web GUI 测试工具依赖(可选)
pip install playwright
python -m playwright install chromium

4. 验证安装

# 检查 Python 版本
python --version

# 检查 ADB
adb version

# 检查设备连接
adb devices
# 应该能看到你的设备,状态为 "device"

5. 配置设备

  1. 开启开发者模式

    • 进入手机"设置" → "关于手机"
    • 连续点击"版本号"7次
    • 返回设置,找到"开发者选项"
  2. 开启 USB 调试

    • 进入"开发者选项"
    • 开启"USB 调试"
    • 开启"USB 安装"(部分机型)
  3. 连接电脑

    • 使用 USB 线连接手机和电脑
    • 在手机上选择"文件传输"或"MTP"模式
    • 首次连接时,手机会弹出授权提示,选择"允许"
  4. 验证连接

adb devices
   # 应该显示:xxxxxxx    device

🚀 快速开始

方式一:桌面 GUI(推荐新手)

  1. 启动 GUI
   python gui_app.py
  1. 配置参数

    • 在"设备"下拉框选择你的设备
    • 设置 Y 偏移(首次使用可设为 0)
    • 在"运行设置"中配置基本参数
    • 在"筛选设置"中配置福袋筛选条件
  2. 开始运行

    • 点击"开始运行"按钮
    • 在右侧日志窗口查看运行状态
    • 点击"截图"按钮可查看实时截图
  3. 停止运行

    • 点击"停止"按钮
    • 或点击"强制停止"按钮(如果普通停止无效)

方式二:命令行(适合高级用户)

# 基本用法
python run_cli.py --needswitch --wait-minutes 5

# 完整参数示例
python run_cli.py \
  --device-id MB75DEFQZHZTGMLJ \
  --y-pianyi 0 \
  --needswitch \
  --wait-minutes 5 \
  --min-prize-value-yuan 200.0 \
  --min-participants 100 \
  --skip-if-countdown-lt-seconds 5

常用参数说明:

  • --device-id:设备 ID(可省略,自动选择第一个)
  • --y-pianyi:Y 轴偏移(-200200,通常 -5050)
  • --needswitch:允许切换直播间
  • --wait-minutes:倒计时超过 N 分钟时切换
  • --min-prize-value-yuan:最低奖品价值(元)
  • --min-participants:最少参与人数
  • --skip-if-countdown-lt-seconds:跳过倒计时小于 N 秒的福袋

方式三:Web GUI(适合远程控制)

  1. 启动 Web 服务
   # 方式1:双击运行
   一键启动WebGUI.bat

   # 方式2:命令行运行
   python webgui_launcher.py
  1. 访问界面

    • 打开浏览器访问:http://127.0.0.1:8000/
    • 如果是远程访问,使用:http://<服务器IP>:8000/
  2. 配置和运行

    • 点击"刷新设备"获取设备列表
    • 在各个配置标签页中设置参数
    • 点击"开始运行"启动脚本
    • 实时查看日志和截图
  3. 停止服务

    # 双击运行
    停止WebGUI服务.bat
    
    # 或在 Web 界面点击"停止"按钮
    

⚙️ 详细配置说明

所有配置保存在 config/config.json 文件中(运行时通过 path_config.get_config_path() 读取),可通过 GUI 界面修改,也可以直接编辑 JSON 文件。

运行设置

参数名 类型 默认值 说明
needswitch boolean true 是否允许上划切换直播间
wait_minutes integer 5 倒计时超过该分钟数时切换直播间(仅在 needswitch=true 时生效)
skip_if_countdown_lt_seconds integer 5 倒计时小于该秒数时不参与(高价值福袋可预约)
reset_after_swipes_enabled boolean true 是否启用"切换N次后回到第一个直播间"功能
reset_after_swipes integer 30 切换直播间达到该次数后,下滑回退到第一个直播间
fudai_find_max_attempts integer 10 找福袋图标的最大尝试次数
fudai_icon_retry_delay_seconds float 0.6 找福袋图标的重试间隔(秒)
fudai_icon_max_wait_seconds float 5.0 找福袋图标的最大等待时间(秒),实际识别常见 4-6 秒
live_room_match_threshold float 0.8 直播间检测阈值(0.0~1.0),值越高越严格,建议≥0.8
stage_diag_max_time float 15.0 阶段诊断的最大耗时(秒)
stage_diag_max_step_time float 4.0 阶段诊断单步的最大耗时(秒)
no_attend_timeout_minutes float 30.0 30分钟超时保护:距离最后成功参与超过该分钟数则返回推荐页面(0表示禁用)

福袋筛选设置

参数名 类型 默认值 说明
min_prize_value_yuan float 0.0 最低奖品价值(元),低于该价值不参与,0 表示不启用
min_participants integer 0 最少参与人数,低于该人数不参与,0 表示不启用
max_participants integer 0 最多参与人数,高于该人数不参与,0 表示不启用
contains_want array [] 想要的关键词列表(白名单),福袋内容包含任一关键词则参与
contains_not_want array [] 不想要的关键词列表(黑名单),福袋内容包含任一关键词则跳过

示例:

{
  "min_prize_value_yuan": 200.0,
  "min_participants": 100,
  "max_participants": 10000,
  "contains_want": ["手机", "现金", "红包"],
  "contains_not_want": ["袜子", "优惠券", "代金券"]
}

粉丝团设置

参数名 类型 默认值 说明
auto_join_fansclub boolean true 是否自动加入粉丝团(谨慎:可能消耗钻石)
fansclub_fail_action string "switch" 粉丝团加入失败后的策略:"stay"=停留当前直播间,"switch"=切换直播间

高价值福袋预约

参数名 类型 默认值 说明
high_value_fudai_enabled boolean true 是否启用高价值福袋预约功能
high_value_fudai_threshold_yuan float 500.0 高价值福袋的阈值(元),价值≥该值则预约
high_value_fudai_join_ahead_seconds integer 300 提前参与秒数,开奖前 N 秒返回直播间参与
high_value_fudai_max_swipe_back integer 35 最多回退直播间次数,防止回退过远导致异常
high_value_fudai_max_reservations integer 3 最多同时记录的预约数量,超过后丢弃最晚开奖的
high_value_fudai_after_action string "continue" 完成预约后的动作:"stay"=停留,"continue"=继续抢福袋
reservation_back_verify_enabled boolean false 是否启用预约回退验证(回退后验证是否在目标直播间)
reservation_back_swipe_delay float 0.6 预约回退时的滑动延迟(秒)

高价值直播间回访

参数名 类型 默认值 说明
high_value_room_revisit_enabled boolean false 是否启用高价值直播间回访
high_value_room_revisit_only_current_run boolean false 是否仅本次运行回访(true=仅本次,false=持久化记录)

推荐页养号设置

参数名 类型 默认值 说明
yanghao_enabled boolean false 是否启用推荐页养号功能
yanghao_enable_actions boolean false 是否启用养号动作(点赞/收藏/评论)
yanghao_recommend_duration_seconds integer 216 推荐页停留时长(秒)
yanghao_recommend_interval_seconds integer 600 推荐页养号间隔(秒),0 表示不间隔
yanghao_like_prob float 1.0 点赞概率(0.0~1.0),1.0 表示 100% 点赞
yanghao_fav_prob float 0.85 收藏概率(0.0~1.0)
yanghao_comment_prob float 1.0 评论概率(0.0~1.0)
yanghao_icon_roi_size integer 240 图标检测区域大小(像素)
yanghao_icon_match_threshold float 0.72 图标匹配阈值(0.0~1.0)
yanghao_step_screenshot boolean false 是否在养号步骤中截图(用于调试)
yanghao_like_roi_offset_x integer 0 点赞图标 ROI X 偏移
yanghao_like_roi_offset_y integer -50 点赞图标 ROI Y 偏移
yanghao_fav_roi_offset_x integer 40 收藏图标 ROI X 偏移
yanghao_fav_roi_offset_y integer 0 收藏图标 ROI Y 偏移
yanghao_like_icon_x integer 0 点赞图标 X 坐标(0 表示自动检测)
yanghao_like_icon_y integer -1 点赞图标 Y 坐标(-1 表示自动检测)
yanghao_fav_icon_x integer -1 收藏图标 X 坐标
yanghao_fav_icon_y integer 0 收藏图标 Y 坐标
yanghao_like_template_path string "assets/like.png" 点赞图标模板路径
yanghao_fav_template_path string "assets/fav.png" 收藏图标模板路径
yanghao_after_dwell_swipe_direction string "up" 停留后的滑动方向:"up"=上滑,"down"=下滑
yanghao_after_dwell_swipe_distance_px integer 900 停留后的滑动距离(像素)
yanghao_comment_btn_x integer 0 评论按钮 X 坐标
yanghao_comment_btn_y integer 0 评论按钮 Y 坐标
yanghao_comment_input_x integer 0 评论输入框 X 坐标
yanghao_comment_input_y integer 0 评论输入框 Y 坐标
yanghao_comment_send_x integer 0 评论发送按钮 X 坐标
yanghao_comment_send_y integer -1 评论发送按钮 Y 坐标
yanghao_comment_close_x integer 0 评论关闭按钮 X 坐标
yanghao_comment_close_y integer 0 评论关闭按钮 Y 坐标
yanghao_comment_texts array [] 评论内容列表,随机选择一条评论
yanghao_like_keywords array [] 点赞关键词列表,内容包含关键词才点赞
yanghao_fav_keywords array [] 收藏关键词列表,内容包含关键词才收藏

静默时段设置

参数名 类型 默认值 说明
fudai_quiet_hours_enabled boolean true 是否启用静默时段(该时段内不抢福袋)
fudai_quiet_start_hour integer 2 静默时段开始时间(小时,0-23)
fudai_quiet_end_hour integer 6 静默时段结束时间(小时,0-23)

说明:静默时段内脚本会跳过福袋,但仍可执行养号等操作。


📚 使用指南

首次使用步骤

  1. 准备工作

    • 确保手机已开启 USB 调试
    • 连接手机到电脑
    • 验证 adb devices 能看到设备
  2. 启动脚本

    • 使用 GUI 或命令行启动脚本
    • 首次运行建议使用 GUI,便于观察日志
  3. 调整 Y 偏移

    • 如果发现点击位置不准确,调整 Y 偏移值
    • 通常范围在 -50~50 之间
    • 可以通过"截图"功能查看实际截图位置
  4. 配置筛选条件

    • 根据需求设置价值、参与人数等筛选条件
    • 建议首次使用设置较宽松的条件,观察效果
  5. 观察运行

    • 查看日志输出,确认脚本正常工作
    • 观察是否出现误判或异常情况
    • 根据实际情况调整配置参数

日常使用建议

  1. 定期检查日志

    • 查看 logs/unified.log 了解运行情况
    • 关注错误和警告信息
  2. 调整配置

    • 根据实际效果调整筛选条件
    • 优化高价值预约阈值
    • 调整养号参数降低风控风险
  3. 保持设备连接

    • 确保手机不断网、不关机
    • 定期检查 USB 连接是否稳定
    • 建议使用 USB 3.0 接口
  4. 监控账号状态

    • 定期检查账号是否正常
    • 关注是否出现人机验证
    • 如频繁出现验证,降低运行频率或启用养号

高级使用技巧

  1. 多账号管理

    • 可以为每个账号创建独立的配置目录
    • 使用不同的 config.json 文件
    • 通过命令行参数覆盖配置
  2. 定时任务

    • 使用 Windows 任务计划程序定时启动脚本
    • 结合静默时段配置,实现自动化运行
  3. 远程控制

    • 使用 Web GUI 实现远程控制
    • 配置端口转发,实现外网访问
  4. 性能优化

    • 调整阶段诊断时间参数,平衡速度和准确性
    • 优化 OCR 缓存设置,减少重复识别
    • 根据设备性能调整截图频率

🔍 工作原理

主流程

开始
  │
  ├─> 初始化(加载配置、连接设备)
  │
  ├─> 30分钟超时检查(防止脚本卡死)
  │   ├─> 检查最后参与时间是否超过30分钟
  │   ├─> 是 → 返回推荐页面重新开始
  │   └─> 否 → 继续执行
  │
  ├─> 阶段诊断(判断当前页面)
  │   ├─> 直播间?
  │   │   ├─> 是 → 检测福袋图标
  │   │   │       ├─> 找到福袋 → 打开详情页
  │   │   │       └─> 未找到 → 切换直播间(如果启用)
  │   │   └─> 否 → 导航到直播间
  │   │
  │   ├─> 福袋详情页?
  │   │   ├─> 读取福袋信息(内容、倒计时、价值、参与人数)
  │   │   ├─> 筛选判断(价值、人数、关键词)
  │   │   ├─> 通过 → 参与抽奖
  │   │   └─> 不通过 → 关闭详情页
  │   │
  │   ├─> 抽奖结果页?
  │   │   ├─> 中奖 → 自动领奖
  │   │   └─> 未中奖 → 关闭弹窗
  │   │
  │   └─> 其他页面 → 导航到直播间
  │
  ├─> 处理弹窗(优惠券、红包等)
  │
  ├─> 处理人机验证
  │
  └─> 循环执行

阶段诊断流程

阶段诊断是脚本的核心功能,用于判断当前页面状态:

  1. 直播间检测(优先级最高)

    • 使用模板匹配检测右上角关闭/心形图标
    • 阈值可配置(默认 0.8)
  2. 像素检测(并行执行)

    • 检测抽奖结果弹窗(大片红色区域)
    • 检测参与按钮红色区域
    • 检测粉丝团加入红色区域
    • 检测优惠券/购物红包背景
  3. OCR 检测(可选,当前默认关闭)

    • 识别推荐页标签栏
    • 识别关注列表标签
    • 识别直播列表标签
    • 识别福袋详情内容
  4. 综合判断

    • 根据检测结果返回当前阶段
    • 支持多阶段优先级判断

福袋检测流程

  1. 图标检测

    • 在直播间内搜索福袋图标
    • 使用模板匹配算法
    • 支持多次重试(可配置)
  2. 详情页识别

    • 点击福袋图标进入详情页
    • 使用像素检测确认是否在详情页
    • 处理各种弹窗干扰
  3. 信息提取

    • OCR 识别福袋内容区域
    • OCR 识别倒计时区域
    • OCR 识别价值区域
    • OCR 识别参与人数区域
  4. 信息解析

    • 解析倒计时文本(支持多种格式)
    • 提取奖品价值(元)
    • 提取参与人数
    • 提取福袋内容描述

筛选判断流程

福袋信息
  │
  ├─> 价值筛选
  │   ├─> 价值 < min_prize_value_yuan → 跳过
  │   └─> 通过
  │
  ├─> 参与人数筛选
  │   ├─> 人数 < min_participants → 跳过
  │   ├─> 人数 > max_participants → 跳过
  │   └─> 通过
  │
  ├─> 倒计时筛选
  │   ├─> 倒计时 < skip_if_countdown_lt_seconds → 不参与(高价值可预约)
  │   └─> 通过
  │
  ├─> 关键词筛选
  │   ├─> 包含 contains_not_want → 跳过
  │   ├─> contains_want 为空 → 通过
  │   ├─> 包含 contains_want → 通过
  │   └─> 不包含 contains_want → 跳过
  │
  └─> 通过所有筛选 → 参与抽奖

高价值预约流程

  1. 识别高价值福袋

    • 价值 ≥ high_value_fudai_threshold_yuan
    • 记录福袋信息和开奖时间
    • 保存到 state/reservations.json 状态文件
  2. 继续寻找其他福袋

    • 不立即参与,继续切换直播间(需要 needswitch=true)
    • 记录当前直播间位置(room_pos)
  3. 提前返回

    • 开奖前 high_value_fudai_join_ahead_seconds 秒
    • 从状态文件加载预约数据
    • 回退到目标直播间(通过直播间标题匹配)
    • 参与抽奖
  4. 预约管理

    • 最多同时记录 high_value_fudai_max_reservations 个预约
    • 超过后丢弃最晚开奖的预约
    • 预约数据持久化到状态文件,重启后自动加载

注意事项:

  • 预约回退功能仅在 needswitch=true(允许切换直播间)时生效
  • 单间模式(needswitch=false)下,预约会在当前直播间自动识别和参与,无需回退
  • 预约数据会自动从 state/reservations.json 加载,确保程序重启后仍能继续处理预约

📁 代码结构

项目架构

项目采用模块化设计,主要代码位于 douyin/ 目录下,按功能划分为多个子模块:

<项目目录>/
├── douyin/                    # 核心业务逻辑模块
│   ├── core/                  # 核心调度和主流程
│   │   ├── douyin_fudai.py    # 主类 fudai_analyse(Mixin 组合)
│   │   ├── douyin_main_flow.py # 主流程控制器
│   │   ├── douyin_flow_control.py # 流程控制
│   │   └── fudai_modules/     # 功能模块(Mixin)
│   │       ├── fudai_navigation.py      # 导航功能
│   │       ├── fudai_stage_detection.py # 阶段检测
│   │       ├── fudai_popup_handler.py   # 弹窗处理
│   │       ├── fudai_lottery_result.py  # 抽奖结果
│   │       ├── fudai_room_utils.py      # 直播间工具
│   │       └── fudai_main_logic.py      # 主逻辑
│   ├── detection/             # 检测模块
│   │   ├── douyin_detection.py # 综合检测逻辑
│   │   └── douyin_pixel.py    # 像素检测
│   ├── stage/                 # 阶段诊断模块
│   │   ├── douyin_stage.py    # 阶段诊断核心
│   │   └── douyin_stage_handler.py # 阶段处理
│   ├── fudai/                 # 福袋相关模块
│   │   ├── douyin_fudai_core.py # 福袋核心逻辑
│   │   ├── douyin_fudai_detail.py # 福袋详情
│   │   ├── douyin_fudai_finder.py # 福袋查找
│   │   └── core/              # 福袋核心子模块
│   ├── handlers/              # 处理器模块
│   │   ├── douyin_popup_handler.py # 弹窗处理
│   │   ├── douyin_screenshot_handler.py # 截图处理
│   │   └── douyin_swipe_handler.py # 滑动处理
│   ├── reservation/           # 预约模块
│   │   ├── douyin_reservation_logic.py # 预约逻辑
│   │   └── douyin_reservation_handler.py # 预约处理
│   ├── logging/               # 日志模块
│   │   ├── douyin_logging.py  # 日志系统
│   │   ├── douyin_logging_wrapper.py # 日志包装器
│   │   └── douyin_logger.py   # 日志器
│   ├── other/                 # 其他功能模块
│   │   ├── douyin_yanghao.py  # 养号功能
│   │   ├── douyin_robot.py    # 人机验证
│   │   └── douyin_popups.py   # 弹窗检测
│   └── utils/                 # 工具模块
│       ├── douyin_config.py   # 配置工具
│       └── douyin_helpers.py  # 辅助函数
├── gui/                       # GUI 界面模块
│   ├── gui_app.py             # 桌面 GUI
│   ├── web_gui.py             # Web GUI 服务
│   └── components/            # GUI 组件
├── operations/                # 底层操作模块
│   ├── device_operations.py   # 设备操作
│   ├── screenshot_operations.py # 截图操作
│   └── ocr_operations.py      # OCR 操作
├── fudai_detail_modules/      # 福袋详情页模块
├── path_config.py             # 路径配置统一管理
├── Underlying_Operations.py   # 底层操作封装(兼容旧代码)
└── run_cli.py                 # 命令行入口

核心模块说明

douyin/core/douyin_fudai.py

  • 职责:核心调度器,主流程控制
  • 主要类:fudai_analyse(使用 Mixin 模式组合功能)
  • 设计模式:Mixin 组合模式,将功能拆分到 fudai_modules/ 下的各个模块
  • 主要方法:
    • fudai_choujiang():主循环入口
    • run_once_basic():单次循环执行
    • load_config():加载配置
    • _diagnose_stage_from_current_screen():阶段诊断入口

douyin/stage/ - 阶段诊断模块

  • douyin_stage.py:阶段诊断核心逻辑
    • diagnose_stage_from_current_screen():综合诊断函数
    • 支持的阶段类型:
      • IN_LIVE_ROOM:直播间
      • RECOMMEND_PAGE:推荐页
      • FOLLOW_LIST:关注列表
      • LIVE_LIST:直播列表
      • FUDai_DETAIL:福袋详情页
      • FUDai_RESULT:抽奖结果页
      • FANSCLUB_JOIN:粉丝团加入页
      • LIVE_CLOSED:直播已结束
  • douyin_stage_handler.py:阶段处理逻辑,包括直播间检测等

douyin/detection/ - 检测模块

  • douyin_pixel.py:像素检测模块
    • 检测弹窗背景颜色
    • 检测按钮区域颜色
    • 并行采集像素特征
  • douyin_detection.py:综合检测逻辑,整合像素、模板、OCR 检测

douyin/fudai/ - 福袋模块

  • douyin_fudai_core.py:福袋核心业务逻辑
    • get_fudai_contain():获取福袋信息
    • check_contain():检查福袋内容
    • attend_choujiang():参与抽奖
  • douyin_fudai_detail.py:福袋详情页处理
  • douyin_fudai_finder.py:福袋图标查找
  • core/:福袋核心子模块
    • fudai_filter.py:福袋筛选逻辑
    • fudai_result_checker.py:开奖结果检查
    • fudai_attend.py:参与抽奖逻辑

douyin/handlers/ - 处理器模块

  • douyin_popup_handler.py:弹窗检测与处理
    • check_coupon_popup():检测优惠券弹窗
    • check_shopping_redpacket_popup():检测购物红包弹窗
  • douyin_screenshot_handler.py:截图处理和管理
  • douyin_swipe_handler.py:滑动操作处理

douyin/reservation/ - 预约模块

  • douyin_reservation_logic.py:高价值福袋预约管理
    • 预约记录管理
    • 高价值直播间记录
    • 状态持久化
  • douyin_reservation_handler.py:预约处理逻辑

douyin/logging/ - 日志模块

  • douyin_logging.py:统一日志系统
  • douyin_logging_wrapper.py:日志包装器,支持行为日志(actions.log)
  • douyin_logger.py:日志器实现

douyin/other/ - 其他功能模块

  • douyin_yanghao.py:推荐页养号逻辑
    • 点赞、收藏、评论操作
    • 关键词触发
  • douyin_robot.py:人机验证处理
    • check_have_robot_analyse():检测人机验证
    • deal_robot_analyse():处理人机验证
  • douyin_popups.py:弹窗检测(兼容旧代码)

path_config.py - 路径配置模块

  • 职责:统一管理所有文件路径
  • 主要函数:
    • get_project_root():项目根目录
    • get_assets_dir():模板图片目录
    • get_pic_dir():截图目录
    • get_screenshot_path():截图文件路径
    • get_logs_dir():日志目录
    • get_actions_log_path():行为日志路径
    • get_state_dir():状态文件目录
    • get_reservations_path():预约状态文件路径
  • 优势:统一路径管理,便于维护和迁移

operations/ - 底层操作模块

  • device_operations.py:设备连接和操作
  • screenshot_operations.py:截图获取和处理
  • ocr_operations.py:OCR 识别操作

Underlying_Operations.py

  • 职责:底层操作封装(兼容旧代码)
  • 主要类:underlying_operations
  • 主要方法:
    • get_screenshot():获取截图
    • click():点击操作
    • swipe():滑动操作
    • analyse_pic_word():OCR 识别

界面模块

gui_app.py

  • 职责:桌面 GUI 应用
  • 技术栈:tkinter + ttkbootstrap
  • 主要功能:
    • 设备选择和管理
    • 配置参数设置
    • 实时日志显示
    • 截图预览

web_gui.py

  • 职责:Web GUI 服务
  • 技术栈:Python HTTP Server
  • 主要功能:
    • RESTful API
    • 实时日志推送
    • 配置管理
    • 统计信息

webui/

  • 职责:Web GUI 前端
  • 文件:
    • index.html:页面结构
    • styles.css:样式文件
    • app.js:前端逻辑

工具模块

run_cli.py

  • 职责:命令行入口
  • 主要功能:
    • 参数解析
    • 配置覆盖
    • 进程管理

tools/

  • 职责:开发和测试工具
  • 主要脚本:
    • test_web_gui.py:Web GUI 自动化测试
    • pick_coords.py:坐标选择工具

配置文件

config/config.json

  • 职责:所有配置参数
  • 格式:JSON
  • 说明:详见"详细配置说明"章节

version.py

  • 职责:版本信息管理
  • 内容:版本号、发布日期等

资源文件

assets/

  • 内容:模板图片
    • x.png:直播间关闭图标模板
    • xin.png:直播间心形图标模板
      • like.png:点赞图标模板
      • fav.png:收藏图标模板
    • desktop.png:桌面图标模板

pic/

  • 内容:
    • screenshot.png:最新截图
    • ocr/:OCR 区域示例图片

logs/

  • 内容:
    • unified.log:统一日志文件(所有日志)
    • actions.log:行为日志文件(关键操作记录,用于性能分析和调试)

state/

  • 内容:
    • reservations.json:预约记录
    • high_value_rooms.json:高价值直播间记录

🔧 故障排查

设备连接问题

问题:adb devices 显示 unauthorized 或 offline

解决方案:

  1. 检查手机是否弹出授权提示,选择"允许"
  2. 重新插拔 USB 线
  3. 重启 ADB 服务:adb kill-server && adb start-server
  4. 检查 USB 驱动是否安装正确

问题:设备列表为空

解决方案:

  1. 确认已开启 USB 调试
  2. 检查 USB 线是否支持数据传输(有些线只能充电)
  3. 尝试更换 USB 接口
  4. 检查手机是否选择"文件传输"模式

识别错误问题

问题:点击位置不准确

解决方案:

  1. 调整 Y 偏移值(--y-pianyi 参数)
  2. 检查设备分辨率是否正确识别
  3. 查看截图确认实际位置
  4. 检查是否有系统导航栏影响

问题:无法识别福袋图标

解决方案:

  1. 增加 fudai_icon_max_wait_seconds(福袋加载需要时间)
  2. 检查 assets/ 目录下的模板图片是否存在
  3. 查看日志确认检测过程
  4. 尝试手动截图,检查福袋图标是否可见

问题:阶段诊断错误

解决方案:

  1. 调整 live_room_match_threshold(直播间检测阈值)
  2. 检查模板图片是否匹配当前抖音版本
  3. 增加 stage_diag_max_time(给诊断更多时间)
  4. 查看 pic/ocr/ 目录下的调试图片

OCR 识别问题

问题:OCR 识别错误或失败

解决方案:

  1. 检查 PaddleOCR 是否正常安装
  2. 确认截图清晰度足够
  3. 检查识别区域是否正确
  4. 尝试更新 PaddleOCR 版本

问题:OCR 识别速度慢

解决方案:

  1. 减少 OCR 识别频率
  2. 启用 OCR 缓存(如果支持)
  3. 优化识别区域大小
  4. 使用 GPU 版本的 PaddleOCR(如果有 GPU)

运行异常问题

问题:脚本频繁报错或崩溃

解决方案:

  1. 查看 logs/unified.log 了解详细错误信息
  2. 检查 Python 版本是否兼容
  3. 检查依赖包版本是否正确
  4. 尝试重新安装依赖包

问题:脚本卡住不动

解决方案:

  1. 检查网络连接是否正常
  2. 查看日志确认卡在哪一步
  3. 尝试手动截图,检查当前页面状态
  4. 重启脚本或设备

风控问题

问题:频繁出现人机验证

解决方案:

  1. 启用推荐页养号功能
  2. 降低运行频率(增加延迟)
  3. 配置静默时段(夜间只养号)
  4. 调整养号参数,模拟真实用户行为

问题:账号被限制

解决方案:

  1. 立即停止脚本运行
  2. 手动操作账号,恢复正常使用
  3. 降低脚本运行频率
  4. 增加随机延迟和人工操作

性能问题

问题:CPU 占用过高

解决方案:

  1. 减少截图频率
  2. 优化 OCR 识别区域
  3. 使用 GPU 版本的 PaddleOCR
  4. 调整阶段诊断时间参数

问题:内存占用过高

解决方案:

  1. 限制日志文件大小
  2. 清理旧的截图文件
  3. 优化 OCR 缓存设置
  4. 重启脚本定期清理内存

🛠️ 开发指南

开发环境设置

  1. 克隆项目

    git clone <repository-url>
    cd <项目目录>
    
  2. 创建虚拟环境

    python -m venv .venv
    .venv\Scripts\activate
    
  3. 安装开发依赖

    pip install -r requirements.txt
    pip install pytest black flake8 mypy  # 开发工具
    

代码规范

  • Python 风格:遵循 PEP 8
  • 类型提示:使用类型注解
  • 文档字符串:使用 Google 风格
  • 命名规范:
    • 类名:大驼峰(CamelCase)
    • 函数/变量名:小写下划线(snake_case)
    • 常量:大写下划线(UPPER_SNAKE_CASE)

添加新功能

  1. 创建新模块

    • 在项目根目录创建 douyin_xxx.py
    • 实现核心功能
    • 添加类型提示和文档字符串
  2. 集成到主流程

    • 在 douyin_fudai.py 中导入新模块
    • 在适当位置调用新功能
    • 添加配置参数(如需要)
  3. 添加 GUI 支持

    • 在 gui_app.py 中添加 UI 控件
    • 在 webui/index.html 中添加配置项
    • 在 webui/app.js 中添加默认值
  4. 测试

    • 编写单元测试(如需要)
    • 手动测试新功能
    • 更新文档

调试技巧

  1. 使用日志
   self._log_kv("模块名", "操作", key1=value1, key2=value2)
  1. 使用截图

    self.operation.get_screenshot(self.device_id)
    # 查看 pic/screenshot.png
    
  2. 使用 GUI 截图功能

    • 在 GUI 中点击"截图"按钮
    • 查看实时截图和 OCR 结果
  3. 使用测试模式

    python run_cli.py --test-yanghao-flow
    

提交代码

  1. 代码检查

    black . --check
    flake8 .
    mypy .
    
  2. 提交信息格式

    类型: 简短描述
    
    详细说明(可选)
    

    类型包括:feat(新功能)、fix(修复)、docs(文档)、refactor(重构)等


❓ 常见问题 FAQ

Q1: 脚本支持哪些设备?

A: 支持所有 Android 5.0+ 的设备,包括手机和平板。脚本会自动适配分辨率,但不同机型可能需要微调 Y 偏移值。

Q2: 需要 Root 权限吗?

A: 不需要 Root 权限,只需要开启 USB 调试即可。

Q3: 可以同时运行多个账号吗?

A: 可以,但需要:

  1. 每个账号使用不同的设备或模拟器
  2. 每个账号使用不同的配置目录或配置文件
  3. 通过 --device-id 参数指定不同设备

Q4: 脚本会被抖音检测吗?

A: 脚本通过模拟真实用户操作实现自动化,但任何自动化工具都存在被检测的风险。建议:

  1. 启用养号功能,模拟真实用户行为
  2. 不要运行过于频繁
  3. 配置静默时段
  4. 定期手动操作账号

Q5: 如何提高中奖率?

A: 中奖率主要取决于福袋本身,脚本无法提高中奖率,但可以:

  1. 筛选参与人数较少的福袋
  2. 快速参与,避免错过
  3. 同时管理多个账号

Q6: 脚本运行需要网络吗?

A: 手机需要连接网络(WiFi 或移动数据),电脑不需要网络(除了下载依赖包时)。

Q7: 可以自定义筛选条件吗?

A: 可以,通过 config.json 中的 contains_want 和 contains_not_want 配置关键词列表。

Q8: 高价值预约功能如何工作?

A:

  1. 脚本识别到高价值福袋(价值≥阈值)
  2. 记录福袋信息和开奖时间到状态文件
  3. 继续寻找其他福袋(需要启用"允许切换直播间")
  4. 开奖前提前返回参与抽奖
  5. 预约数据会自动从状态文件加载,重启后仍能继续处理

注意:预约回退功能需要启用"允许切换直播间"(needswitch=true)才能正常工作。如果勾选了"允许切换直播间"但预约回退不生效,请检查:

  • config.json 中 needswitch 是否为 true
  • high_value_fudai_enabled 是否为 true
  • state/reservations.json 中是否有预约数据
  • 查看日志中的 [预约] run_once_basic:检查预约回退触发条件 日志

Q9: 如何查看运行日志?

A:

  1. 统一日志:查看 logs/unified.log 文件,包含所有运行日志
  2. 行为日志:查看 logs/actions.log 文件,包含关键操作记录(用于性能分析)
  3. GUI/Web GUI:界面实时显示日志,支持筛选和搜索
  4. 命令行:运行时直接在终端查看

Q10: 脚本卡住了怎么办?

A:

  1. 查看日志确认卡在哪一步
  2. 使用 GUI 的"截图"功能查看当前页面
  3. 尝试点击"强制停止"按钮
  4. 重启脚本或设备

Q10.5: 脚本长时间没有参与福袋怎么办?

A:

  1. 这是 V3.3.3+ 新增的30分钟超时保护机制在工作
  2. 脚本会自动检测30分钟内没有成功参与福袋的情况
  3. 超时后自动返回推荐页面,重新开始正常的直播间切换流程
  4. 这有助于防止脚本在无效直播间或异常状态下卡死
  5. 如果不想启用此功能,可在配置中设置 no_attend_timeout_minutes: 0

Q11: 如何更新脚本?

A:

  1. 备份 config.json 和 state/ 目录
  2. 下载最新版本
  3. 替换文件(保留配置和状态文件)
  4. 检查 config.json 是否有新增配置项

Q12: 支持 iOS 设备吗?

A: 目前不支持 iOS 设备,因为 iOS 需要越狱才能使用类似 ADB 的工具。


📜 版本历史

V3.3.3 (2025-12-28)

当前版本

  • ✨ 新增:30分钟超时保护机制
    • 自动检测长时间无参与的情况,防止脚本卡在无效状态
    • 可配置超时时间(默认30分钟)
    • 超时后自动返回推荐页面重新开始
  • 🐛 修复:修复模板和截图路径配置问题
    • 统一使用项目根目录的 assets 和 pic 目录
    • 修复直播间检测模板文件路径错误
    • 确保所有模板文件路径配置正确
  • 🔧 优化:路径配置统一化
    • 使用 path_config.py 统一管理所有文件路径
    • 简化路径配置逻辑,提高代码可维护性
  • 📝 更新:完善文档和流程图
    • 更新流程图以反映30分钟超时检查
    • 修正阶段诊断步骤编号
    • 完善预约回退子流程图

V3.3.2 (2025-12-25)

  • 🐛 修复:修复预约回退功能不生效的问题
    • 修复 needswitch 配置未从 config.json 正确加载的问题
    • 修复 self.reservations 未从状态文件加载的问题
    • 添加预约回退逻辑的详细调试日志
  • 🔧 优化:预约回退逻辑优化
    • 每次 run_once_basic 执行时自动从状态文件加载预约数据
    • 确保预约队列始终包含最新数据

V3.3.1 (2025-12-14)

  • ✨ 新增:直播间检测阈值可配置(live_room_match_threshold)
  • ✨ 新增:福袋图标检测等待时间可配置
  • 🐛 修复:修复直播间检测模板文件路径警告
  • 🔧 优化:优化阶段检测流程,优先使用像素检测
  • 🔧 优化:合并阶段 1.5 和阶段 3 的 OCR 检测
  • 📝 更新:完善文档和 README

V3.3.0 (2025-12-XX)

  • 🔄 重构:模块化重构,代码结构优化
  • ✨ 新增:像素检测优先策略
  • ✨ 新增:GUI 截图+OCR 功能
  • ✨ 新增:强制停止按钮
  • 🐛 修复:修复各种已知问题

V3.2.0

  • ✨ 新增:高价值福袋预约功能
  • ✨ 新增:高价值直播间回访功能
  • 🔧 优化:推荐页养号逻辑优化

V3.1.0

  • ✨ 新增:推荐页养号功能
  • 🔧 优化:OCR 识别准确率提升

V3.0.0

  • 🔄 重大更新:引入 PaddleOCR 替换 pytesseract
  • ✨ 新增:自动分辨率适配
  • 🐛 修复:修复大量已知问题

V2.x

  • 多分辨率支持
  • 稳定性提升
  • 各种 bug 修复

V1.x

  • 基础功能实现
  • 福袋检测和参与
  • 自动领奖

⚠️ 免责声明

  1. 本工具仅供学习交流使用,请勿用于商业用途。

  2. 使用本工具产生的任何后果由使用者自行承担,包括但不限于:

    • 账号被封禁或限制
    • 数据丢失或泄露
    • 设备损坏
    • 其他法律风险
  3. 请遵守抖音平台相关规则,不要使用本工具进行违法违规操作。

  4. 作者不对使用本工具造成的任何损失负责。

  5. 使用本工具即表示您已阅读并同意本免责声明。


📞 支持与反馈

如有问题或建议,欢迎:

  • 📧 提交 Issue
  • 💬 加入交流群
  • 📖 查看详细文档

感谢使用抖音福袋挂机脚本!

如果这个项目对你有帮助,欢迎 Star ⭐

S
Description
No description provided
Readme
54 MiB
0 Stars 8 Watchers 0 Forks
Languages
Python 89.1%
CSS 5%
JavaScript 3.4%
HTML 1.3%
PowerShell 1%
Other 0.2%