Files
douyi_guaji_main/README.md
T
CodexandClaude Opus 4.7 a6ce16f9c4 docs/README: 版本日志段引向 CHANGELOG.md + git tags + 发布流程
- 把 V3.0.0–V3.3.3 的散落条目统一到 CHANGELOG.md,README 只保留最近 3 个版本作为快照
- 加发布流程段:bump_version.py 用法 + test_version_consistency.py 守门
- 顶部链向 CHANGELOG.md 与 git tags 页面

回归:36 个路径引用全部存在;353 个测试通过。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-21 15:28:21 +08:00

708 lines
29 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)](douyin/core/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>
> ⚠️ **本工具仅供学习交流使用**。使用产生的任何后果(账号风控、数据丢失等)由使用者自行承担。完整免责条款见文末 [免责声明](#免责声明)。
---
## 📖 目录
- [项目简介](#项目简介)
- [核心功能](#核心功能)
- [技术架构](#技术架构)
- [环境要求与安装](#环境要求与安装)
- [快速开始](#快速开始)
- [详细配置说明](#详细配置说明)
- [使用指南](#使用指南)
- [工作原理](#工作原理)
- [代码结构](#代码结构)
- [测试](#测试)
- [开发指南](#开发指南)
- [故障排查](#故障排查)
- [常见问题](#常见问题)
- [版本更新日志](#版本更新日志)
- [贡献与反馈](#贡献与反馈)
- [免责声明](#免责声明)
---
## 项目简介
通过 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 <repository-url>
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-id> 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/<module>/` 创建模块;`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 等)。
---
<div align="center">
**感谢使用抖音福袋挂机脚本**
如果这个项目对你有帮助,欢迎 ⭐
</div>