# 抖音福袋挂机脚本 - 详细文档
**一个功能完善的抖音直播间福袋自动挂机工具** 基于 ADB + OCR + 像素检测 + 模板匹配技术 [![Version](https://img.shields.io/badge/version-V3.3.1-blue.svg)](version.py) [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/) [![Platform](https://img.shields.io/badge/platform-Windows-lightgrey.svg)](https://www.microsoft.com/windows)
--- ## 📖 目录 - [项目简介](#项目简介) - [核心功能](#核心功能) - [技术架构](#技术架构) - [环境要求与安装](#环境要求与安装) - [快速开始](#快速开始) - [详细配置说明](#详细配置说明) - [使用指南](#使用指南) - [工作原理](#工作原理) - [代码结构](#代码结构) - [故障排查](#故障排查) - [开发指南](#开发指南) ## 📋 版本更新日志 ### 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/` 目录),可使用以下方式运行: ```bash # 运行所有测试 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次后回到第一个直播间(循环模式) - 智能处理直播结束、网络异常等情况 --- ## 🏗️ 技术架构 ### 核心技术栈 - **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 │ │ (用户界面层) │ └──────────────┬──────────────────────────┘ │ ┌──────────────▼──────────────────────────┐ │ douyin_fudai.py │ │ (核心调度器 - 主流程控制) │ └──────────────┬──────────────────────────┘ │ ┌──────────┼──────────┐ │ │ │ ┌───▼───┐ ┌───▼───┐ ┌───▼───┐ │阶段诊断│ │福袋核心│ │弹窗处理│ │stage │ │core │ │popups │ └───────┘ └───────┘ └───────┘ │ │ │ └──────────┼──────────┘ │ ┌──────────────▼──────────────────────────┐ │ Underlying_Operations.py │ │ (底层操作封装 - ADB/OCR) │ └──────────────┬──────────────────────────┘ │ ┌──────────────▼──────────────────────────┐ │ ADB / PaddleOCR │ │ (系统底层接口) │ └─────────────────────────────────────────┘ ``` --- ## 💻 环境要求与安装 ### 系统要求 - **操作系统**:Windows 10/11(64位) - **Python**:3.10 或更高版本(推荐 3.10-3.12) - **内存**:至少 4GB RAM(推荐 8GB+) - **存储**:至少 2GB 可用空间 ### 必需软件 1. **Python 3.10+** - 下载地址:https://www.python.org/downloads/ - 安装时勾选"Add Python to PATH" 2. **ADB(Android Debug Bridge)** - 下载 Android SDK Platform Tools:https://developer.android.com/studio/releases/platform-tools - 解压后添加到系统 PATH,或放在项目目录下 - 验证安装:在命令行运行 `adb version` 3. **Android 设备** - 安卓手机或平板(Android 5.0+) - 已开启开发者模式和 USB 调试 - 已安装抖音 APP ### 安装步骤 #### 1. 克隆或下载项目 ```bash # 如果使用 Git git clone cd douyin_guaji-main # 或直接下载 ZIP 文件并解压 ``` #### 2. 创建虚拟环境(推荐) ```bash # 创建虚拟环境 python -m venv .venv # 激活虚拟环境 # Windows PowerShell: .venv\Scripts\Activate.ps1 # Windows CMD: .venv\Scripts\activate.bat ``` #### 3. 安装 Python 依赖 ```bash # 安装核心依赖 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. 验证安装 ```bash # 检查 Python 版本 python --version # 检查 ADB adb version # 检查设备连接 adb devices # 应该能看到你的设备,状态为 "device" ``` #### 5. 配置设备 1. **开启开发者模式** - 进入手机"设置" → "关于手机" - 连续点击"版本号"7次 - 返回设置,找到"开发者选项" 2. **开启 USB 调试** - 进入"开发者选项" - 开启"USB 调试" - 开启"USB 安装"(部分机型) 3. **连接电脑** - 使用 USB 线连接手机和电脑 - 在手机上选择"文件传输"或"MTP"模式 - 首次连接时,手机会弹出授权提示,选择"允许" 4. **验证连接** ```bash adb devices # 应该显示:xxxxxxx device ``` --- ## 🚀 快速开始 ### 方式一:桌面 GUI(推荐新手) 1. **启动 GUI** ```bash python gui_app.py ``` 2. **配置参数** - 在"设备"下拉框选择你的设备 - 设置 Y 偏移(首次使用可设为 0) - 在"运行设置"中配置基本参数 - 在"筛选设置"中配置福袋筛选条件 3. **开始运行** - 点击"开始运行"按钮 - 在右侧日志窗口查看运行状态 - 点击"截图"按钮可查看实时截图 4. **停止运行** - 点击"停止"按钮 - 或点击"强制停止"按钮(如果普通停止无效) ### 方式二:命令行(适合高级用户) ```bash # 基本用法 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 轴偏移(-200~200,通常 -50~50) - `--needswitch`:允许切换直播间 - `--wait-minutes`:倒计时超过 N 分钟时切换 - `--min-prize-value-yuan`:最低奖品价值(元) - `--min-participants`:最少参与人数 - `--skip-if-countdown-lt-seconds`:跳过倒计时小于 N 秒的福袋 ### 方式三:Web GUI(适合远程控制) 1. **启动 Web 服务** ```bash # 方式1:双击运行 一键启动WebGUI.bat # 方式2:命令行运行 python webgui_launcher.py ``` 2. **访问界面** - 打开浏览器访问:`http://127.0.0.1:8000/` - 如果是远程访问,使用:`http://<服务器IP>:8000/` 3. **配置和运行** - 点击"刷新设备"获取设备列表 - 在各个配置标签页中设置参数 - 点击"开始运行"启动脚本 - 实时查看日志和截图 4. **停止服务** ```bash # 双击运行 停止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` | 阶段诊断单步的最大耗时(秒) | ### 福袋筛选设置 | 参数名 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | `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 | `[]` | 不想要的关键词列表(黑名单),福袋内容包含任一关键词则跳过 | **示例**: ```json { "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) | **说明**:静默时段内脚本会跳过福袋,但仍可执行养号等操作。 --- ## 📚 使用指南 ### 首次使用步骤 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 缓存设置,减少重复识别 - 根据设备性能调整截图频率 --- ## 🔍 工作原理 ### 主流程 ``` 开始 │ ├─> 初始化(加载配置、连接设备) │ ├─> 阶段诊断(判断当前页面) │ ├─> 直播间? │ │ ├─> 是 → 检测福袋图标 │ │ │ ├─> 找到福袋 → 打开详情页 │ │ │ └─> 未找到 → 切换直播间(如果启用) │ │ └─> 否 → 导航到直播间 │ │ │ ├─> 福袋详情页? │ │ ├─> 读取福袋信息(内容、倒计时、价值、参与人数) │ │ ├─> 筛选判断(价值、人数、关键词) │ │ ├─> 通过 → 参与抽奖 │ │ └─> 不通过 → 关闭详情页 │ │ │ ├─> 抽奖结果页? │ │ ├─> 中奖 → 自动领奖 │ │ └─> 未中奖 → 关闭弹窗 │ │ │ └─> 其他页面 → 导航到直播间 │ ├─> 处理弹窗(优惠券、红包等) │ ├─> 处理人机验证 │ └─> 循环执行 ``` ### 阶段诊断流程 阶段诊断是脚本的核心功能,用于判断当前页面状态: 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_fudai.py` - **职责**:核心调度器,主流程控制 - **主要类**:`fudai_analyse` - **主要方法**: - `fudai_choujiang()`:主循环入口 - `run_once_basic()`:单次循环执行 - `load_config()`:加载配置 - `_diagnose_stage_from_current_screen()`:阶段诊断入口 - `_check_in_live_room_by_icon()`:直播间检测 #### `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_pixel.py` - **职责**:像素检测模块 - **主要功能**: - 检测弹窗背景颜色 - 检测按钮区域颜色 - 并行采集像素特征 #### `douyin_fudai_core.py` - **职责**:福袋核心业务逻辑 - **主要函数**: - `get_fudai_contain()`:获取福袋信息 - `check_contain()`:检查福袋内容 - `attend_choujiang()`:参与抽奖 - `check_lucky_draw_result()`:检查开奖结果 - `get_reward()`:领取奖品 #### `douyin_popups.py` - **职责**:弹窗检测与处理 - **主要函数**: - `check_coupon_popup()`:检测优惠券弹窗 - `check_shopping_redpacket_popup()`:检测购物红包弹窗 #### `douyin_robot.py` - **职责**:人机验证处理 - **主要函数**: - `check_have_robot_analyse()`:检测人机验证 - `deal_robot_analyse()`:处理人机验证 - `deal_swipe_robot_analyse()`:处理滑块验证 #### `douyin_yanghao.py` - **职责**:推荐页养号逻辑 - **主要功能**: - 点赞操作 - 收藏操作 - 评论操作 - 关键词触发 #### `douyin_reservation.py` - **职责**:高价值福袋预约管理 - **主要功能**: - 预约记录管理 - 高价值直播间记录 - 状态持久化 #### `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`:统一日志文件 #### `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. **克隆项目** ```bash git clone cd douyin_guaji-main ``` 2. **创建虚拟环境** ```bash python -m venv .venv .venv\Scripts\activate ``` 3. **安装开发依赖** ```bash 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. **使用日志** ```python self._log_kv("模块名", "操作", key1=value1, key2=value2) ``` 2. **使用截图** ```python self.operation.get_screenshot(self.device_id) # 查看 pic/screenshot.png ``` 3. **使用 GUI 截图功能** - 在 GUI 中点击"截图"按钮 - 查看实时截图和 OCR 结果 4. **使用测试模式** ```bash python run_cli.py --test-yanghao-flow ``` ### 提交代码 1. **代码检查** ```bash 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. GUI/Web GUI 界面实时显示日志 2. 查看 `logs/unified.log` 文件 3. 命令行运行时直接在终端查看 ### Q10: 脚本卡住了怎么办? **A**: 1. 查看日志确认卡在哪一步 2. 使用 GUI 的"截图"功能查看当前页面 3. 尝试点击"强制停止"按钮 4. 重启脚本或设备 ### Q11: 如何更新脚本? **A**: 1. 备份 `config.json` 和 `state/` 目录 2. 下载最新版本 3. 替换文件(保留配置和状态文件) 4. 检查 `config.json` 是否有新增配置项 ### Q12: 支持 iOS 设备吗? **A**: 目前不支持 iOS 设备,因为 iOS 需要越狱才能使用类似 ADB 的工具。 --- ## 📜 版本历史 ### 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 ⭐