- 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.
1536 lines
50 KiB
Markdown
1536 lines
50 KiB
Markdown
# 抖音福袋挂机脚本 - 详细文档
|
||
|
||
<div align="center">
|
||
|
||
**一个功能完善的抖音直播间福袋自动挂机工具**
|
||
|
||
基于 ADB + OCR + 像素检测 + 模板匹配技术
|
||
|
||
[](version.py)
|
||
[](https://www.python.org/)
|
||
[](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> |