Files
douyi_guaji_main/README.md
T
Your Name b9849b9f5a chore: Remove obsolete scripts and enhance path configuration
- 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.
2025-12-28 20:47:30 +08:00

1536 lines
50 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 抖音福袋挂机脚本 - 详细文档
<div align="center">
**一个功能完善的抖音直播间福袋自动挂机工具**
基于 ADB + OCR + 像素检测 + 模板匹配技术
[![Version](https://img.shields.io/badge/version-V3.3.3-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)
</div>
---
## 📖 目录
- [项目简介](#项目简介)
- [核心功能](#核心功能)
- [技术架构](#技术架构)
- [环境要求与安装](#环境要求与安装)
- [快速开始](#快速开始)
- [详细配置说明](#详细配置说明)
- [使用指南](#使用指南)
- [工作原理](#工作原理)
- [代码结构](#代码结构)
- [故障排查](#故障排查)
- [开发指南](#开发指南)
## 📋 版本更新日志
### 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/` 目录),可使用以下方式运行:
```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 以贡献代码
---
<div align="center">
**感谢使用抖音福袋挂机脚本!**
如果这个项目对你有帮助,欢迎 Star ⭐ 并提出你的建议或贡献代码。
</div>
- 自动识别开奖结果(中奖/未中奖)
- 中奖后自动领取奖品
- 处理订单确认页面
- 自动关闭各种弹窗和提示
### 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+**
- 下载地址: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 <repository-url>
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` | 阶段诊断单步的最大耗时(秒) |
`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 | `[]` | 不想要的关键词列表(黑名单),福袋内容包含任一关键词则跳过 |
**示例**:
```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 缓存设置,减少重复识别
- 根据设备性能调整截图频率
---
## 🔍 工作原理
### 主流程
```
开始
│
├─> 初始化(加载配置、连接设备)
│
├─> 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_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`
**解决方案**:
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 <repository-url>
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. **统一日志**:查看 `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
- 💬 加入交流群
- 📖 查看详细文档
---
<div align="center">
**感谢使用抖音福袋挂机脚本!**
如果这个项目对你有帮助,欢迎 Star ⭐
</div>