# 抖音福袋挂机脚本
**基于 ADB + OCR + 像素检测 + 模板匹配的抖音直播间福袋自动挂机工具**
[](douyin/core/version.py)
[](https://www.python.org/)
[](https://www.microsoft.com/windows)
> ⚠️ **本工具仅供学习交流使用**。使用产生的任何后果(账号风控、数据丢失等)由使用者自行承担。完整免责条款见文末 [免责声明](#免责声明)。
---
## 📖 目录
- [项目简介](#项目简介)
- [核心功能](#核心功能)
- [技术架构](#技术架构)
- [环境要求与安装](#环境要求与安装)
- [快速开始](#快速开始)
- [详细配置说明](#详细配置说明)
- [使用指南](#使用指南)
- [工作原理](#工作原理)
- [代码结构](#代码结构)
- [测试](#测试)
- [开发指南](#开发指南)
- [故障排查](#故障排查)
- [常见问题](#常见问题)
- [版本更新日志](#版本更新日志)
- [贡献与反馈](#贡献与反馈)
- [免责声明](#免责声明)
---
## 项目简介
通过 ADB 连接安卓设备,结合像素检测 / 模板匹配 / OCR 三种技术识别抖音直播间状态,自动完成福袋发现、参与、领奖、人机验证、推荐页养号等操作。
适用场景:长时间挂机抢福袋、多账号管理、定时养号。**不适用**于商业用途。
更详细的内部技术资料:[`docs/完整技术文档.md`](docs/完整技术文档.md)、[`docs/archive/AI_PROJECT_SUMMARY.md`](docs/archive/AI_PROJECT_SUMMARY.md)(归档)。
---
## 核心功能
| # | 功能 | 说明 |
|---|------|------|
| 1 | **福袋检测** | 在直播间内通过模板匹配定位福袋图标,自动打开详情页 |
| 2 | **信息识别** | OCR 提取福袋内容、倒计时、价值(元)、参与人数 |
| 3 | **筛选参与** | 价值/人数/关键词三维筛选,命中黑白名单后决策是否参与 |
| 4 | **自动领奖** | 识别开奖结果,中奖后自动领取并处理订单确认页 |
| 5 | **高价值预约** | 价值 ≥ 阈值的福袋记录开奖时间,提前回退到目标直播间参与(需 `needswitch=true`) |
| 6 | **高价值回访** | 持久化记录高价值直播间,定时回访 |
| 7 | **推荐页养号** | 按概率点赞 / 收藏 / 评论,模拟真实用户行为 |
| 8 | **人机验证** | 自动处理滑块验证、图片点击、人脸识别(失败可重试) |
| 9 | **弹窗处理** | 自动关闭优惠券、购物红包等干扰弹窗 |
| 10 | **直播间切换** | 上划切换、N 次后回到首播、智能处理直播结束 |
| 11 | **超时保护** | 30 分钟未参与则自动返回推荐页重启流程,避免卡死 |
---
## 技术架构
### 核心技术栈
- **Python 3.10+** — 主语言
- **ADB**(Android Debug Bridge)— 设备控制
- **PaddleOCR**(>= 3.0.0)— OCR 文字识别
- **OpenCV** — 模板匹配 / 图像处理
- **Pillow / NumPy** — 图像 IO 与数值计算
- **tkinter + ttkbootstrap** — 桌面 GUI
- **内置 http.server** — Web GUI 服务
### 检测层次
| 技术 | 用途 | 速度 / 准确度 |
|------|------|---------------|
| 像素检测 | 弹窗背景色、按钮区域 | 极快 / 中 |
| 模板匹配(OpenCV) | 图标、按钮等 UI 元素 | 快 / 高 |
| OCR(PaddleOCR) | 文字识别(福袋内容、倒计时、人数) | 慢 / 高 |
| 阶段诊断 | 综合三种技术判断当前页面状态 | 可调 / 高 |
### 架构图
```
┌─────────────────────────────────────────┐
│ GUI / Web GUI / CLI(用户界面层) │
│ bin/gui_app.py / bin/webgui_launcher │
│ bin/run_cli.py │
└──────────────┬──────────────────────────┘
│
┌──────────────▼──────────────────────────┐
│ douyin/core/douyin_fudai.py │
│ class fudai_analyse(Mixin 组合) │
│ 核心调度器 - 主流程控制 │
└──────────────┬──────────────────────────┘
│
┌──────────┼──────────┐
│ │ │
┌───▼────┐ ┌───▼────┐ ┌──▼─────┐
│阶段诊断│ │福袋核心│ │弹窗处理│
│stage/ │ │fudai/ │ │handlers│
└────────┘ └────────┘ └────────┘
│ │ │
└──────────┼──────────┘
│
┌──────────────▼──────────────────────────┐
│ douyin/core/underlying_operations.py │
│ 底层 ADB / 截图 / OCR 封装 │
└──────────────┬──────────────────────────┘
│
┌──────────────▼──────────────────────────┐
│ douyin/core/path_config.py │
│ 统一路径配置(config / state / logs) │
└─────────────────────────────────────────┘
```
**设计要点**:
- **Mixin 组合**:`fudai_analyse` 把功能拆到 [`douyin/core/fudai_modules/`](douyin/core/fudai_modules) 各 Mixin
- **路径统一**:所有运行时路径通过 [`douyin/core/path_config.py`](douyin/core/path_config.py) 集中管理
- **日志分层**:统一日志 + 行为日志(`actions.log`)分离,便于性能分析
---
## 环境要求与安装
### 系统要求
| 项 | 要求 |
|----|------|
| 操作系统 | Windows 10/11 (64-bit) |
| Python | 3.10–3.12(推荐 3.10) |
| 内存 | 至少 4 GB(推荐 8 GB+) |
| 存储 | 至少 2 GB 可用空间 |
| 安卓设备 | Android 5.0+,已开启 USB 调试 |
### 必需软件
1. **Python 3.10+** — [下载](https://www.python.org/downloads/),安装时勾选 *Add Python to PATH*
2. **ADB(platform-tools)** — [下载](https://developer.android.com/studio/releases/platform-tools),解压加入 PATH,验证 `adb version`
3. **抖音 APP** — 安装在已开启 USB 调试的安卓设备
### 安装步骤
```bash
# 1. 克隆仓库
git clone
cd douyi_guaji
# 2. 创建虚拟环境(推荐)
python -m venv .venv
.venv\Scripts\activate # Windows CMD
# .venv\Scripts\Activate.ps1 # Windows PowerShell
# 3. 安装核心依赖
pip install -r requirements.txt
# 如 paddlepaddle 安装失败,可指定清华源:
pip install "paddlepaddle>=3.0.0" -i https://pypi.tuna.tsinghua.edu.cn/simple
# GPU 版本(需 CUDA):
pip install "paddlepaddle-gpu>=3.0.0" -i https://pypi.tuna.tsinghua.edu.cn/simple
# 4. 验证
python --version
adb version
adb devices # 应能看到设备,状态为 "device"
```
### 设备配置
1. 进入「设置 → 关于手机」连续点击「版本号」7 次开启**开发者模式**
2. 在「开发者选项」中开启 **USB 调试**(部分机型还需开启 *USB 安装*)
3. USB 连接电脑,选择 *文件传输/MTP* 模式,**首次连接**手机会弹授权对话框,选择「允许」
4. 运行 `adb devices` 应输出 ` device`
---
## 快速开始
三种启动方式,按场景选择:
### 方式一:桌面 GUI(推荐新手)
```bash
python bin/gui_app.py
```
1. 在「设备」下拉选择设备
2. 在「运行设置」/「筛选设置」配置参数
3. 点击「开始运行」,右侧日志窗口实时显示状态
4. 通过「截图」按钮查看实时截图,「停止」/「强制停止」终止运行
### 方式二:命令行(高级用户)
```bash
# 基本用法
python bin/run_cli.py --needswitch --wait-minutes 5
# 完整参数示例
python bin/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(远程控制)
```bash
python bin/webgui_launcher.py
```
打开浏览器访问 `http://127.0.0.1:8000/`,通过页面配置参数、查看实时日志/截图,远程访问改用机器 IP。
---
## 详细配置说明
所有配置在 [`config/config.json`](config/config.json) 中,可通过 GUI 修改或直接编辑 JSON。运行时通过 `path_config.get_config_path()` 读取。
### 运行设置
| 参数 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `needswitch` | bool | `true` | 允许上划切换直播间 |
| `wait_minutes` | int | `5` | 倒计时超过该值(分钟)时切换(仅 `needswitch=true` 生效) |
| `skip_if_countdown_lt_seconds` | int | `5` | 倒计时小于该值时不参与(高价值仍可预约) |
| `reset_after_swipes_enabled` | bool | `true` | 启用「切换 N 次后回到首播」 |
| `reset_after_swipes` | int | `30` | 触发回到首播的切换次数 |
| `fudai_find_max_attempts` | int | `10` | 找福袋图标的最大重试次数 |
| `fudai_icon_retry_delay_seconds` | float | `0.6` | 找福袋图标的重试间隔(秒) |
| `fudai_icon_max_wait_seconds` | float | `5.0` | 找福袋图标的最大等待(秒) |
| `live_room_match_threshold` | float | `0.8` | 直播间检测阈值(0~1,越高越严格,建议 ≥ 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` | int | `0` | 最少参与人数,0 = 不启用 |
| `max_participants` | int | `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": ["袜子", "优惠券", "代金券"]
}
```
### 高价值福袋预约
| 参数 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `high_value_fudai_enabled` | bool | `true` | 启用预约功能 |
| `high_value_fudai_threshold_yuan` | float | `500.0` | 预约阈值(元),价值 ≥ 该值则预约 |
| `high_value_fudai_join_ahead_seconds` | int | `300` | 提前 N 秒返回直播间参与 |
| `high_value_fudai_max_swipe_back` | int | `35` | 最多回退次数(防止过远) |
| `high_value_fudai_max_reservations` | int | `3` | 最多同时预约数 |
| `high_value_fudai_after_action` | string | `"continue"` | 完成预约后:`stay`(停留)或 `continue`(继续抢) |
| `reservation_back_verify_enabled` | bool | `false` | 启用回退验证 |
| `reservation_back_swipe_delay` | float | `0.6` | 回退滑动延迟(秒) |
> **重要**:预约回退需 `needswitch=true`。单间模式下预约会在当前直播间自动识别参与,无需回退。
### 高价值直播间回访
| 参数 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `high_value_room_revisit_enabled` | bool | `false` | 启用高价值直播间回访 |
| `high_value_room_revisit_only_current_run` | bool | `false` | 仅本次运行回访(true)或持久化(false) |
### 粉丝团
| 参数 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `auto_join_fansclub` | bool | `true` | 自动加入粉丝团(**可能消耗钻石**) |
| `fansclub_fail_action` | string | `"switch"` | 加入失败后:`stay` 或 `switch` |
### 推荐页养号
养号参数较多(约 30 项),完整列表见 [`docs/完整技术文档.md`](docs/完整技术文档.md) 的「推荐页养号设置」段。常用:
| 参数 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `yanghao_enabled` | bool | `false` | 启用养号 |
| `yanghao_enable_actions` | bool | `false` | 启用养号动作(点赞/收藏/评论) |
| `yanghao_recommend_duration_seconds` | int | `216` | 推荐页停留时长(秒) |
| `yanghao_recommend_interval_seconds` | int | `600` | 推荐页养号间隔(秒),0 = 不间隔 |
| `yanghao_like_prob` | float | `1.0` | 点赞概率 |
| `yanghao_fav_prob` | float | `0.85` | 收藏概率 |
| `yanghao_comment_prob` | float | `1.0` | 评论概率 |
### 静默时段
| 参数 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `fudai_quiet_hours_enabled` | bool | `true` | 启用静默时段(不抢福袋,仍可养号) |
| `fudai_quiet_start_hour` | int | `2` | 起始小时(0–23) |
| `fudai_quiet_end_hour` | int | `6` | 结束小时(0–23) |
---
## 使用指南
### 首次使用
1. 通过 GUI 启动,便于观察日志
2. 调整 Y 偏移(通常 -50~50),通过「截图」核对点击位置
3. 设置较宽松的筛选条件,观察实际效果再收紧
4. 关注是否触发人机验证;频繁出现说明运行频率过高,应启用养号或缩短运行时段
### 日常建议
- **查日志**:[`logs/unified.log`](logs/) 总览、[`logs/actions.log`](logs/) 关键操作
- **稳定连接**:USB 3.0 + 不掉线手机,定期检查 `adb devices`
- **风控防御**:启用养号 + 配置静默时段;账号疑似限制立即停止并人工操作
### 高级用法
- **多账号**:每账号独立 `config/` 目录或通过 `--device-id` 区分
- **定时**:Windows 任务计划程序 + 静默时段
- **远程**:Web GUI 端口转发到外网(注意安全)
- **性能调优**:调小 OCR 区域、降低截图频率、用 GPU 版 PaddleOCR
---
## 工作原理
### 主流程
```
开始
│
├─> 初始化(加载配置、连接设备)
│
├─> 30 分钟超时检查
│ └─ 超时 → 返回推荐页面重新开始
│
├─> 阶段诊断(判断当前页面)
│ ├─> 直播间 → 检测福袋图标 → 打开详情页
│ ├─> 福袋详情页 → 读取信息 → 筛选 → 参与
│ ├─> 抽奖结果页 → 中奖领取 / 关闭弹窗
│ └─> 其他 → 导航回直播间
│
├─> 处理弹窗(优惠券、红包、人机验证)
│
└─> 循环执行
```
### 阶段诊断
按优先级判断当前页面:
1. **直播间检测**(最高优先级):模板匹配右上角关闭/心形图标,阈值默认 0.8
2. **像素检测**(并行):弹窗背景色、参与按钮红色、粉丝团红色等
3. **OCR 检测**(按需):识别推荐页 / 关注列表 / 直播列表 / 福袋详情等
4. **综合判断**:返回当前阶段(`IN_LIVE_ROOM` / `RECOMMEND_PAGE` / `FUDai_DETAIL` / `FUDai_RESULT` / ...)
### 福袋筛选
```
福袋信息
│
├─> 价值 < min_prize_value_yuan → 跳过
├─> 人数不在 [min_participants, max_participants] → 跳过
├─> 倒计时 < skip_if_countdown_lt_seconds → 不参与(高价值可预约)
├─> 命中 contains_not_want → 跳过
├─> contains_want 非空且未命中 → 跳过
└─> 全部通过 → 参与抽奖
```
### 高价值预约
1. **识别**:价值 ≥ `high_value_fudai_threshold_yuan` → 记录到 `douyin/core/state/reservations.json`
2. **继续**:不立即参与,继续切换直播间(需 `needswitch=true`)
3. **回退**:开奖前 `high_value_fudai_join_ahead_seconds` 秒,从状态文件加载,按直播间标题匹配回退
4. **持久化**:最多 `high_value_fudai_max_reservations` 个,超出丢弃最晚开奖的;重启后自动加载
更详细:[`docs/预约系统详细流程.md`](docs/预约系统详细流程.md)。
---
## 代码结构
```
<项目根>/
├── bin/ # 入口脚本
│ ├── run_cli.py # 命令行入口
│ ├── gui_app.py # 桌面 GUI launcher
│ ├── webgui_launcher.py # Web GUI launcher
│ └── manage_logs.py # 日志管理 CLI
├── douyin/ # 核心业务逻辑
│ ├── core/ # 核心调度
│ │ ├── douyin_fudai.py # fudai_analyse(Mixin 组合)
│ │ ├── douyin_main_flow.py # 主流程控制
│ │ ├── douyin_flow_control.py
│ │ ├── path_config.py # 路径配置
│ │ ├── underlying_operations.py # 底层 ADB/截图/OCR
│ │ ├── io_utils.py # 文件 IO 辅助
│ │ ├── version.py
│ │ └── fudai_modules/ # 7 个 Mixin
│ ├── detection/ # 像素 + 模板检测
│ ├── stage/ # 阶段诊断
│ ├── fudai/ # 福袋核心
│ │ └── core/ # detail_reader / filter / attend / coords / ...
│ ├── handlers/ # 截图 / 滑动 / 弹窗处理
│ ├── reservation/ # 预约状态文件 / 逻辑 / 回退校验
│ ├── logging/ # 9 个日志模块(unified / wrapper / action / ...)
│ ├── other/ # 养号 / 人机校验 / 高价值房间 / ...
│ └── utils/ # 配置 / 文本 / 时间 / OCR 预处理
├── operations/ # 兼容层:re-export 给老代码
├── gui/ # GUI 实现(桌面 + Web)
│ ├── gui_app.py / web_gui.py / gui_core.py
│ ├── components/ # 桌面 GUI 子组件
│ └── web_components/ # Web GUI 子组件
├── webui/ # Web GUI 前端(HTML/CSS/JS)
├── tools/ # 47 个开发/调试脚本(按 adb/coords/dev/diagnostics/logs 分组)
├── tests/ # pytest 单元/冒烟测试(242 用例)
├── docs/ # 项目文档
│ ├── 完整技术文档.md # 7000+ 行内部技术参考
│ └── archive/ # 已过时文档归档
├── config/config.json # 用户配置
├── assets/ # 模板图片(x.png / xin.png / like.png / fav.png 等)
├── pic/ # 运行时截图(.gitignored)
├── logs/ # 运行时日志(.gitignored)
└── state/ # 运行时状态(.gitignored)
```
### 核心模块速查
| 模块 / 文件 | 职责 |
|-------------|------|
| [`douyin/core/douyin_fudai.py`](douyin/core/douyin_fudai.py) | 主类 `fudai_analyse`,Mixin 组合,主入口 |
| [`douyin/core/path_config.py`](douyin/core/path_config.py) | 统一路径配置(config / state / logs / pic) |
| [`douyin/core/underlying_operations.py`](douyin/core/underlying_operations.py) | 底层 ADB/截图/OCR 封装 |
| [`douyin/stage/douyin_stage.py`](douyin/stage/douyin_stage.py) | 阶段诊断核心 |
| [`douyin/fudai/core/fudai_filter.py`](douyin/fudai/core/fudai_filter.py) | 福袋筛选决策(含黑白名单) |
| [`douyin/reservation/douyin_reservation.py`](douyin/reservation/douyin_reservation.py) | 预约状态文件原子读写 |
| [`douyin/logging/unified_logger.py`](douyin/logging/unified_logger.py) | MDC(Mapped Diagnostic Context)+ 装饰器 |
| [`gui/gui_app.py`](gui/gui_app.py) / [`gui/web_gui.py`](gui/web_gui.py) | 桌面 / Web GUI 实现 |
| [`bin/run_cli.py`](bin/run_cli.py) | 命令行入口(含参数解析、shim 加载) |
资源目录:
- [`assets/`](assets/) — 模板图片:`x.png`(关闭)、`xin.png`(心形)、`like.png`、`fav.png`、`desktop.png`
- `pic/` — 运行时截图(`screenshot.png` 是最新;`ocr/` 子目录为 OCR 区域示例)
- `logs/` — `unified.log`(全部)+ `actions.log`(关键操作)
- `state/` — `high_value_rooms.json`;预约状态实际写入 `douyin/core/state/reservations.json`
---
## 测试
`tests/` 是 pytest 风格的单元测试 + 业务冒烟,覆盖路径配置、文本解析、福袋筛选决策、logger helper、MDC 上下文、io_utils 等核心纯函数链路。**242 用例 / < 1 秒**,不依赖 ADB / 真实设备 / OCR 引擎。
```bash
pip install pytest
# 全量
pytest
# 单文件 / 单用例
pytest tests/test_filter_logging.py
pytest tests/test_path_config.py::TestSpecificPaths::test_reservations_path_in_douyin_core_state -v
# 跑较慢的性能对比脚本(需 paddleocr/easyocr/psutil)
pytest -m slow
```
测试约定:
- [`tests/conftest.py`](tests/conftest.py) 自动把项目根加入 `sys.path`
- 性能脚本用 `pytest.importorskip` 自动跳过缺失依赖
- 自定义 marker:`smoke`(业务关键链路)/ `slow`(慢测试);新增需先在 [`pyproject.toml`](pyproject.toml) 注册
---
## 开发指南
### 开发环境
```bash
# 创建并激活虚拟环境
python -m venv .venv
.venv\Scripts\activate
# 安装运行依赖 + 开发工具
pip install -r requirements.txt
pip install pytest black ruff mypy
```
### 代码规范
- **风格**:PEP 8;类名 `CamelCase`;函数/变量 `snake_case`;常量 `UPPER_SNAKE_CASE`
- **类型注解**:尽量加,特别是公共函数
- **注释**:默认不写;仅在 *为什么* 非显然时(隐藏约束、变通方案、会让读者意外的行为)添加一行
- **不写多行 docstring**:一行总结即可
### 工作流
1. **新功能** — 在 `douyin//` 创建模块;`douyin/core/douyin_fudai.py` 中调用;如需配置项,更新 `config/config.json` + GUI/WebUI 同步
2. **GUI 同步检查** — 运行 [`tools/diagnostics/check_web_gui_config_sync.py`](tools/diagnostics/check_web_gui_config_sync.py),确保桌面 GUI 与 WebUI 的配置 key 一致
3. **测试** — 修改纯函数 / 业务逻辑后补 [`tests/`](tests/) 用例,跑 `pytest`
4. **提交** — 提交信息中文,格式:`<类型>: <简短描述>`;类型有 `feat` / `fix` / `refactor` / `docs` / `chore` 等
### 调试技巧
- **业务日志**:`analyser._log_kv("分类", "消息", key=value)` 走统一日志体系
- **截图调试**:`analyser.operation.get_screenshot(self.device_id)` → 查看 `pic/screenshot.png`
- **GUI 即时截图**:桌面 GUI 「截图」按钮 → 实时截图 + OCR 结果
- **测试模式**:`python bin/run_cli.py --test-yanghao-flow` 单独跑养号流程
更多文档:[`docs/完整技术文档.md`](docs/完整技术文档.md)、[`docs/DEBUG_IMAGE_SYSTEM.md`](docs/DEBUG_IMAGE_SYSTEM.md)。
---
## 故障排查
### 设备连接
| 症状 | 处理 |
|------|------|
| `adb devices` 显示 `unauthorized` | 手机授权对话框选「允许」 |
| 显示 `offline` | 重新插拔 USB;`adb kill-server && adb start-server` |
| 列表为空 | 检查 USB 调试 / 数据线 / USB 接口;选择「文件传输/MTP」模式 |
### 识别错误
| 症状 | 处理 |
|------|------|
| 点击位置不准 | 调整 Y 偏移(`--y-pianyi`);查看 `pic/screenshot.png` |
| 找不到福袋图标 | 增加 `fudai_icon_max_wait_seconds`;确认 `assets/` 模板存在 |
| 阶段诊断错误 | 调整 `live_room_match_threshold`;查看 `pic/ocr/` 调试图片 |
### OCR
| 症状 | 处理 |
|------|------|
| OCR 失败 | 重装 PaddleOCR;确认截图清晰;检查识别区域配置 |
| OCR 慢 | 启用 GPU 版 PaddleOCR;调小识别区域;降低截图频率 |
### 风控
| 症状 | 处理 |
|------|------|
| 频繁人机验证 | 启用养号;缩短运行时段;调宽筛选条件 |
| 账号被限制 | **立即停止脚本**;手动操作账号恢复正常 |
### 性能
| 症状 | 处理 |
|------|------|
| CPU 高 | 降低截图频率;优化 OCR 区域;用 GPU 版 PaddleOCR |
| 内存高 | 限制日志文件大小;定期重启脚本 |
---
## 常见问题
**Q: 支持 iOS 设备吗?**
A: 不支持,iOS 需要越狱。
**Q: 需要 Root 权限吗?**
A: 不需要,仅需 USB 调试。
**Q: 可以同时运行多个账号吗?**
A: 可以。每账号独立设备 + 独立 `config/` 目录,命令行用 `--device-id` 区分。
**Q: 脚本会被检测吗?**
A: 任何自动化都有风控风险。建议:启用养号、合理配置静默时段、定期手动操作账号。
**Q: 如何提高中奖率?**
A: 中奖率取决于福袋本身。可通过筛选小参与人数福袋 + 多账号并行提高总中奖期望。
**Q: 脚本卡住怎么办?**
A: 查 `logs/unified.log` 确认卡在哪一步;用「截图」按钮看当前页面;点击「强制停止」;必要时重启脚本/设备。30 分钟超时保护会自动恢复。
**Q: 高价值预约不生效?**
A: 检查:
- `config.json` 中 `needswitch=true` 且 `high_value_fudai_enabled=true`
- `douyin/core/state/reservations.json` 中是否有预约数据
- 日志中搜 `[预约] run_once_basic:检查预约回退触发条件`
**Q: 如何更新脚本?**
A: 备份 `config/config.json` 与 `state/` 目录 → `git pull`(或重新下载)→ 检查 `config.json` 是否需要补新配置项。
---
## 版本更新日志
完整变更见 [CHANGELOG.md](CHANGELOG.md)(Keep a Changelog 格式)。
所有发布都打了 git tag,可以通过 `git tag -l` 查看,或访问 [git tags 页面](../../tags)。
最近 3 个版本:
### V3.3.3 (2025-12-28) — 当前
- ✨ 新增:30 分钟超时保护机制
- 🐛 修复:模板与截图路径配置统一,使用 [`path_config.py`](douyin/core/path_config.py)
- 🔧 优化:行为日志路径统一为 `path_config.get_actions_log_path()`
### V3.3.2 (2025-12-25)
- 🐛 修复:预约回退功能不生效(`needswitch` 与 `self.reservations` 加载问题)
- 🔧 优化:每次 `run_once_basic` 自动从状态文件加载预约队列
### V3.3.1 (2025-12-14)
- ✨ 新增:直播间检测阈值可配置(`live_room_match_threshold`)
- ✨ 新增:福袋图标检测等待时间可配置
- 🔧 优化:阶段检测优先使用像素检测;合并阶段 1.5 与阶段 3 的 OCR
### 发布流程
新版本发布走 [`tools/dev/bump_version.py`](tools/dev/bump_version.py):
```bash
python tools/dev/bump_version.py patch # V3.3.3 → V3.3.4
python tools/dev/bump_version.py minor # V3.3.3 → V3.4.0
python tools/dev/bump_version.py major # V3.3.3 → V4.0.0
python tools/dev/bump_version.py --dry-run patch # 只看会改什么
```
脚本会自动同步 `version.py` / `pyproject.toml` / `CHANGELOG.md` 顶部并创建 git tag。
[`tests/test_version_consistency.py`](tests/test_version_consistency.py) 9 个用例守住三处版本号一致。
---
## 贡献与反馈
### 提交 Issue
请包含:
- **标题**:一句话概述
- **环境**:操作系统、Python、ADB、设备型号
- **复现步骤**:最小复现命令 / 点击顺序
- **日志/截图**(可选但推荐):`logs/unified.log` 片段、错误截图
- **期望 vs 实际**
### 贡献 PR
```bash
# 1. fork + 新分支
git checkout -b fix/your-change
# 2. 改动 + 测试
pytest
# 3. 提交(中文,type: 描述)
git commit -m "fix: 修复 OCR 识别问题"
# 4. PR 描述写清变更细节、测试方法、影响范围
```
代码风格保持现有约定,避免大面积重构而不提前沟通。
---
## 免责声明
1. **本工具仅供学习交流使用**,请勿用于商业用途。
2. **使用本工具产生的任何后果由使用者自行承担**,包括但不限于:
- 账号被封禁或限制
- 数据丢失或泄露
- 设备损坏
- 其他法律风险
3. **请遵守抖音平台相关规则**,不要使用本工具进行违法违规操作。
4. **作者不对使用本工具造成的任何损失负责**。
5. **使用本工具即表示您已阅读并同意本免责声明**。
---
## 许可
仓库当前未添加明确的开源许可文件(LICENSE)。如需对外发布或在项目中使用本代码,请先在 Issue 中联系作者或为仓库添加合适的许可证(MIT / Apache-2.0 / GPL-3.0 等)。
---
**感谢使用抖音福袋挂机脚本**
如果这个项目对你有帮助,欢迎 ⭐