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