- Deleted `check_md_files.py` and `fix_cursor_md_issue.py` as they are no longer needed. - Added new functions in `path_config.py` for better path management, including actions log and run_cli paths. - Updated various modules to utilize the unified path configuration, ensuring backward compatibility and improved maintainability. - Enhanced documentation in `README.md` to reflect changes in path management and project structure.
50 KiB
抖音福袋挂机脚本 - 详细文档
📖 目录
📋 版本更新日志
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
- 基础功能实现
- 福袋检测和参与
- 自动领奖
⚠️ 免责声明
-
本工具仅供学习交流使用,请勿用于商业用途。
-
使用本工具产生的任何后果由使用者自行承担,包括但不限于:
- 账号被封禁或限制
- 数据丢失或泄露
- 设备损坏
- 其他法律风险
-
请遵守抖音平台相关规则,不要使用本工具进行违法违规操作。
-
作者不对使用本工具造成的任何损失负责。
-
使用本工具即表示您已阅读并同意本免责声明。
📞 支持与反馈
如有问题或建议,请优先在仓库中提交 Issue,或按照下列步骤提供反馈:
- 标题(必填):一句话概述问题或建议
- 环境信息(必填):操作系统、Python 版本、ADB 版本、设备型号
- 复现步骤(必填):最小复现步骤(命令、点击顺序等)
- 日志与截图(可选):运行日志(logs/ 下相关文件)、截图或录屏
- 期望行为与实际行为(可选):描述期望结果与实际观察到的结果
如果你愿意,可以在 Issue 中附上 --verbose 模式输出或 logs/ 中最新的日志文件,这有助于定位问题。
🤝 贡献(Contributing)
欢迎 PR、Issue、或参与讨论。贡献流程建议:
- Fork 本仓库并在本地新建分支:
git checkout -b fix/your-change - 在分支上实现改动,并尽量保持风格一致
- 运行现有测试(如适用)并确保无新错误
- 提交 PR,标题使用“类型:简短描述”(例如
fix: 修复 OCR 识别问题) - 在 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:数值计算和数组操作
检测技术
-
像素检测
- 基于颜色和像素模式的快速检测
- 用于检测弹窗背景、按钮区域等
- 速度快,资源占用低
-
模板匹配
- 使用 OpenCV 的模板匹配算法
- 用于识别图标、按钮等UI元素
- 支持多分辨率适配
-
OCR 识别
- 使用 PaddleOCR 识别文字内容
- 用于识别福袋内容、倒计时、价值等
- 支持中英文识别
-
阶段诊断
- 综合使用像素检测、模板匹配和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 可用空间
必需软件
-
Python 3.10+
- 下载地址:https://www.python.org/downloads/
- 安装时勾选"Add Python to PATH"
-
ADB(Android Debug Bridge)
- 下载 Android SDK Platform Tools:https://developer.android.com/studio/releases/platform-tools
- 解压后添加到系统 PATH,或放在项目目录下
- 验证安装:在命令行运行
adb version
-
Android 设备
- 安卓手机或平板(Android 5.0+)
- 已开启开发者模式和 USB 调试
- 已安装抖音 APP
安装步骤
1. 克隆或下载项目
# 如果使用 Git
git clone <repository-url>
cd douyin_guaji-main
# 或直接下载 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. 配置设备
-
开启开发者模式
- 进入手机"设置" → "关于手机"
- 连续点击"版本号"7次
- 返回设置,找到"开发者选项"
-
开启 USB 调试
- 进入"开发者选项"
- 开启"USB 调试"
- 开启"USB 安装"(部分机型)
-
连接电脑
- 使用 USB 线连接手机和电脑
- 在手机上选择"文件传输"或"MTP"模式
- 首次连接时,手机会弹出授权提示,选择"允许"
-
验证连接
adb devices
# 应该显示:xxxxxxx device
🚀 快速开始
方式一:桌面 GUI(推荐新手)
- 启动 GUI
python gui_app.py
-
配置参数
- 在"设备"下拉框选择你的设备
- 设置 Y 偏移(首次使用可设为 0)
- 在"运行设置"中配置基本参数
- 在"筛选设置"中配置福袋筛选条件
-
开始运行
- 点击"开始运行"按钮
- 在右侧日志窗口查看运行状态
- 点击"截图"按钮可查看实时截图
-
停止运行
- 点击"停止"按钮
- 或点击"强制停止"按钮(如果普通停止无效)
方式二:命令行(适合高级用户)
# 基本用法
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(适合远程控制)
- 启动 Web 服务
# 方式1:双击运行
一键启动WebGUI.bat
# 方式2:命令行运行
python webgui_launcher.py
-
访问界面
- 打开浏览器访问:
http://127.0.0.1:8000/ - 如果是远程访问,使用:
http://<服务器IP>:8000/
- 打开浏览器访问:
-
配置和运行
- 点击"刷新设备"获取设备列表
- 在各个配置标签页中设置参数
- 点击"开始运行"启动脚本
- 实时查看日志和截图
-
停止服务
# 双击运行 停止WebGUI服务.bat # 或在 Web 界面点击"停止"按钮
⚙️ 详细配置说明
所有配置保存在 config.json 文件中,可通过 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 | 120 |
提前参与秒数,开奖前 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 |
预约回退时的滑动延迟(秒) |
reservation_preempt_min_value |
float | 0.0 |
预约抢占最小价值(元),低于该价值的预约不会抢占当前任务 |
高价值直播间回访
| 参数名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
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) |
说明:静默时段内脚本会跳过福袋,但仍可执行养号等操作。
📚 使用指南
首次使用步骤
-
准备工作
- 确保手机已开启 USB 调试
- 连接手机到电脑
- 验证
adb devices能看到设备
-
启动脚本
- 使用 GUI 或命令行启动脚本
- 首次运行建议使用 GUI,便于观察日志
-
调整 Y 偏移
- 如果发现点击位置不准确,调整 Y 偏移值
- 通常范围在 -50~50 之间
- 可以通过"截图"功能查看实际截图位置
-
配置筛选条件
- 根据需求设置价值、参与人数等筛选条件
- 建议首次使用设置较宽松的条件,观察效果
-
观察运行
- 查看日志输出,确认脚本正常工作
- 观察是否出现误判或异常情况
- 根据实际情况调整配置参数
日常使用建议
-
定期检查日志
- 查看
logs/unified.log了解运行情况 - 关注错误和警告信息
- 查看
-
调整配置
- 根据实际效果调整筛选条件
- 优化高价值预约阈值
- 调整养号参数降低风控风险
-
保持设备连接
- 确保手机不断网、不关机
- 定期检查 USB 连接是否稳定
- 建议使用 USB 3.0 接口
-
监控账号状态
- 定期检查账号是否正常
- 关注是否出现人机验证
- 如频繁出现验证,降低运行频率或启用养号
高级使用技巧
-
多账号管理
- 可以为每个账号创建独立的配置目录
- 使用不同的
config.json文件 - 通过命令行参数覆盖配置
-
定时任务
- 使用 Windows 任务计划程序定时启动脚本
- 结合静默时段配置,实现自动化运行
-
远程控制
- 使用 Web GUI 实现远程控制
- 配置端口转发,实现外网访问
-
性能优化
- 调整阶段诊断时间参数,平衡速度和准确性
- 优化 OCR 缓存设置,减少重复识别
- 根据设备性能调整截图频率
🔍 工作原理
主流程
开始
│
├─> 初始化(加载配置、连接设备)
│
├─> 30分钟超时检查(防止脚本卡死)
│ ├─> 检查最后参与时间是否超过30分钟
│ ├─> 是 → 返回推荐页面重新开始
│ └─> 否 → 继续执行
│
├─> 阶段诊断(判断当前页面)
│ ├─> 直播间?
│ │ ├─> 是 → 检测福袋图标
│ │ │ ├─> 找到福袋 → 打开详情页
│ │ │ └─> 未找到 → 切换直播间(如果启用)
│ │ └─> 否 → 导航到直播间
│ │
│ ├─> 福袋详情页?
│ │ ├─> 读取福袋信息(内容、倒计时、价值、参与人数)
│ │ ├─> 筛选判断(价值、人数、关键词)
│ │ ├─> 通过 → 参与抽奖
│ │ └─> 不通过 → 关闭详情页
│ │
│ ├─> 抽奖结果页?
│ │ ├─> 中奖 → 自动领奖
│ │ └─> 未中奖 → 关闭弹窗
│ │
│ └─> 其他页面 → 导航到直播间
│
├─> 处理弹窗(优惠券、红包等)
│
├─> 处理人机验证
│
└─> 循环执行
阶段诊断流程
阶段诊断是脚本的核心功能,用于判断当前页面状态:
-
直播间检测(优先级最高)
- 使用模板匹配检测右上角关闭/心形图标
- 阈值可配置(默认 0.8)
-
像素检测(并行执行)
- 检测抽奖结果弹窗(大片红色区域)
- 检测参与按钮红色区域
- 检测粉丝团加入红色区域
- 检测优惠券/购物红包背景
-
OCR 检测(可选,当前默认关闭)
- 识别推荐页标签栏
- 识别关注列表标签
- 识别直播列表标签
- 识别福袋详情内容
-
综合判断
- 根据检测结果返回当前阶段
- 支持多阶段优先级判断
福袋检测流程
-
图标检测
- 在直播间内搜索福袋图标
- 使用模板匹配算法
- 支持多次重试(可配置)
-
详情页识别
- 点击福袋图标进入详情页
- 使用像素检测确认是否在详情页
- 处理各种弹窗干扰
-
信息提取
- OCR 识别福袋内容区域
- OCR 识别倒计时区域
- OCR 识别价值区域
- OCR 识别参与人数区域
-
信息解析
- 解析倒计时文本(支持多种格式)
- 提取奖品价值(元)
- 提取参与人数
- 提取福袋内容描述
筛选判断流程
福袋信息
│
├─> 价值筛选
│ ├─> 价值 < min_prize_value_yuan → 跳过
│ └─> 通过
│
├─> 参与人数筛选
│ ├─> 人数 < min_participants → 跳过
│ ├─> 人数 > max_participants → 跳过
│ └─> 通过
│
├─> 倒计时筛选
│ ├─> 倒计时 < skip_if_countdown_lt_seconds → 不参与(高价值可预约)
│ └─> 通过
│
├─> 关键词筛选
│ ├─> 包含 contains_not_want → 跳过
│ ├─> contains_want 为空 → 通过
│ ├─> 包含 contains_want → 通过
│ └─> 不包含 contains_want → 跳过
│
└─> 通过所有筛选 → 参与抽奖
高价值预约流程
-
识别高价值福袋
- 价值 ≥
high_value_fudai_threshold_yuan - 记录福袋信息和开奖时间
- 保存到
state/reservations.json状态文件
- 价值 ≥
-
继续寻找其他福袋
- 不立即参与,继续切换直播间(需要
needswitch=true) - 记录当前直播间位置(
room_pos)
- 不立即参与,继续切换直播间(需要
-
提前返回
- 开奖前
high_value_fudai_join_ahead_seconds秒 - 从状态文件加载预约数据
- 回退到目标直播间(通过直播间标题匹配)
- 参与抽奖
- 开奖前
-
预约管理
- 最多同时记录
high_value_fudai_max_reservations个预约 - 超过后丢弃最晚开奖的预约
- 预约数据持久化到状态文件,重启后自动加载
- 最多同时记录
注意事项:
- 预约回退功能仅在
needswitch=true(允许切换直播间)时生效 - 单间模式(
needswitch=false)下,预约会在当前直播间自动识别和参与,无需回退 - 预约数据会自动从
state/reservations.json加载,确保程序重启后仍能继续处理预约
📁 代码结构
项目架构
项目采用模块化设计,主要代码位于 douyin/ 目录下,按功能划分为多个子模块:
douyin_guaji-main/
├── 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.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
解决方案:
- 检查手机是否弹出授权提示,选择"允许"
- 重新插拔 USB 线
- 重启 ADB 服务:
adb kill-server && adb start-server - 检查 USB 驱动是否安装正确
问题:设备列表为空
解决方案:
- 确认已开启 USB 调试
- 检查 USB 线是否支持数据传输(有些线只能充电)
- 尝试更换 USB 接口
- 检查手机是否选择"文件传输"模式
识别错误问题
问题:点击位置不准确
解决方案:
- 调整 Y 偏移值(
--y-pianyi参数) - 检查设备分辨率是否正确识别
- 查看截图确认实际位置
- 检查是否有系统导航栏影响
问题:无法识别福袋图标
解决方案:
- 增加
fudai_icon_max_wait_seconds(福袋加载需要时间) - 检查
assets/目录下的模板图片是否存在 - 查看日志确认检测过程
- 尝试手动截图,检查福袋图标是否可见
问题:阶段诊断错误
解决方案:
- 调整
live_room_match_threshold(直播间检测阈值) - 检查模板图片是否匹配当前抖音版本
- 增加
stage_diag_max_time(给诊断更多时间) - 查看
pic/ocr/目录下的调试图片
OCR 识别问题
问题:OCR 识别错误或失败
解决方案:
- 检查 PaddleOCR 是否正常安装
- 确认截图清晰度足够
- 检查识别区域是否正确
- 尝试更新 PaddleOCR 版本
问题:OCR 识别速度慢
解决方案:
- 减少 OCR 识别频率
- 启用 OCR 缓存(如果支持)
- 优化识别区域大小
- 使用 GPU 版本的 PaddleOCR(如果有 GPU)
运行异常问题
问题:脚本频繁报错或崩溃
解决方案:
- 查看
logs/unified.log了解详细错误信息 - 检查 Python 版本是否兼容
- 检查依赖包版本是否正确
- 尝试重新安装依赖包
问题:脚本卡住不动
解决方案:
- 检查网络连接是否正常
- 查看日志确认卡在哪一步
- 尝试手动截图,检查当前页面状态
- 重启脚本或设备
风控问题
问题:频繁出现人机验证
解决方案:
- 启用推荐页养号功能
- 降低运行频率(增加延迟)
- 配置静默时段(夜间只养号)
- 调整养号参数,模拟真实用户行为
问题:账号被限制
解决方案:
- 立即停止脚本运行
- 手动操作账号,恢复正常使用
- 降低脚本运行频率
- 增加随机延迟和人工操作
性能问题
问题:CPU 占用过高
解决方案:
- 减少截图频率
- 优化 OCR 识别区域
- 使用 GPU 版本的 PaddleOCR
- 调整阶段诊断时间参数
问题:内存占用过高
解决方案:
- 限制日志文件大小
- 清理旧的截图文件
- 优化 OCR 缓存设置
- 重启脚本定期清理内存
🛠️ 开发指南
开发环境设置
-
克隆项目
git clone <repository-url> cd douyin_guaji-main -
创建虚拟环境
python -m venv .venv .venv\Scripts\activate -
安装开发依赖
pip install -r requirements.txt pip install pytest black flake8 mypy # 开发工具
代码规范
- Python 风格:遵循 PEP 8
- 类型提示:使用类型注解
- 文档字符串:使用 Google 风格
- 命名规范:
- 类名:大驼峰(
CamelCase) - 函数/变量名:小写下划线(
snake_case) - 常量:大写下划线(
UPPER_SNAKE_CASE)
- 类名:大驼峰(
添加新功能
-
创建新模块
- 在项目根目录创建
douyin_xxx.py - 实现核心功能
- 添加类型提示和文档字符串
- 在项目根目录创建
-
集成到主流程
- 在
douyin_fudai.py中导入新模块 - 在适当位置调用新功能
- 添加配置参数(如需要)
- 在
-
添加 GUI 支持
- 在
gui_app.py中添加 UI 控件 - 在
webui/index.html中添加配置项 - 在
webui/app.js中添加默认值
- 在
-
测试
- 编写单元测试(如需要)
- 手动测试新功能
- 更新文档
调试技巧
- 使用日志
self._log_kv("模块名", "操作", key1=value1, key2=value2)
-
使用截图
self.operation.get_screenshot(self.device_id) # 查看 pic/screenshot.png -
使用 GUI 截图功能
- 在 GUI 中点击"截图"按钮
- 查看实时截图和 OCR 结果
-
使用测试模式
python run_cli.py --test-yanghao-flow
提交代码
-
代码检查
black . --check flake8 . mypy . -
提交信息格式
类型: 简短描述 详细说明(可选)类型包括:
feat(新功能)、fix(修复)、docs(文档)、refactor(重构)等
❓ 常见问题 FAQ
Q1: 脚本支持哪些设备?
A: 支持所有 Android 5.0+ 的设备,包括手机和平板。脚本会自动适配分辨率,但不同机型可能需要微调 Y 偏移值。
Q2: 需要 Root 权限吗?
A: 不需要 Root 权限,只需要开启 USB 调试即可。
Q3: 可以同时运行多个账号吗?
A: 可以,但需要:
- 每个账号使用不同的设备或模拟器
- 每个账号使用不同的配置目录或配置文件
- 通过
--device-id参数指定不同设备
Q4: 脚本会被抖音检测吗?
A: 脚本通过模拟真实用户操作实现自动化,但任何自动化工具都存在被检测的风险。建议:
- 启用养号功能,模拟真实用户行为
- 不要运行过于频繁
- 配置静默时段
- 定期手动操作账号
Q5: 如何提高中奖率?
A: 中奖率主要取决于福袋本身,脚本无法提高中奖率,但可以:
- 筛选参与人数较少的福袋
- 快速参与,避免错过
- 同时管理多个账号
Q6: 脚本运行需要网络吗?
A: 手机需要连接网络(WiFi 或移动数据),电脑不需要网络(除了下载依赖包时)。
Q7: 可以自定义筛选条件吗?
A: 可以,通过 config.json 中的 contains_want 和 contains_not_want 配置关键词列表。
Q8: 高价值预约功能如何工作?
A:
- 脚本识别到高价值福袋(价值≥阈值)
- 记录福袋信息和开奖时间到状态文件
- 继续寻找其他福袋(需要启用"允许切换直播间")
- 开奖前提前返回参与抽奖
- 预约数据会自动从状态文件加载,重启后仍能继续处理
注意:预约回退功能需要启用"允许切换直播间"(needswitch=true)才能正常工作。如果勾选了"允许切换直播间"但预约回退不生效,请检查:
config.json中needswitch是否为truehigh_value_fudai_enabled是否为truestate/reservations.json中是否有预约数据- 查看日志中的
[预约] run_once_basic:检查预约回退触发条件日志
Q9: 如何查看运行日志?
A:
- 统一日志:查看
logs/unified.log文件,包含所有运行日志 - 行为日志:查看
logs/actions.log文件,包含关键操作记录(用于性能分析) - GUI/Web GUI:界面实时显示日志,支持筛选和搜索
- 命令行:运行时直接在终端查看
Q10: 脚本卡住了怎么办?
A:
- 查看日志确认卡在哪一步
- 使用 GUI 的"截图"功能查看当前页面
- 尝试点击"强制停止"按钮
- 重启脚本或设备
Q10.5: 脚本长时间没有参与福袋怎么办?
A:
- 这是 V3.3.3+ 新增的30分钟超时保护机制在工作
- 脚本会自动检测30分钟内没有成功参与福袋的情况
- 超时后自动返回推荐页面,重新开始正常的直播间切换流程
- 这有助于防止脚本在无效直播间或异常状态下卡死
- 如果不想启用此功能,可在配置中设置
no_attend_timeout_minutes: 0
Q11: 如何更新脚本?
A:
- 备份
config.json和state/目录 - 下载最新版本
- 替换文件(保留配置和状态文件)
- 检查
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
- 基础功能实现
- 福袋检测和参与
- 自动领奖
⚠️ 免责声明
-
本工具仅供学习交流使用,请勿用于商业用途。
-
使用本工具产生的任何后果由使用者自行承担,包括但不限于:
- 账号被封禁或限制
- 数据丢失或泄露
- 设备损坏
- 其他法律风险
-
请遵守抖音平台相关规则,不要使用本工具进行违法违规操作。
-
作者不对使用本工具造成的任何损失负责。
-
使用本工具即表示您已阅读并同意本免责声明。
📞 支持与反馈
如有问题或建议,欢迎:
- 📧 提交 Issue
- 💬 加入交流群
- 📖 查看详细文档
感谢使用抖音福袋挂机脚本!
如果这个项目对你有帮助,欢迎 Star ⭐