docs: write dashboard exe readme
This commit is contained in:
1 parent
1bef130e51
commit
bd762f6be6
5 files changed
+201
-185
No files matched your search
@@ -1,226 +1,231 @@
|
||||
# 抖音自动化助手
|
||||
# 抖音自动化助手 - 数据看板版使用说明
|
||||
|
||||
这是一个 Windows 本地工具,用来通过 ADB 控制安卓设备,自动识别直播间福袋、按配置筛选并参与。项目提供桌面 GUI、数据看板 GUI、Web GUI 和命令行入口。
|
||||
这是打包成 exe 后给普通用户使用的说明。正常使用时不需要安装 Python,也不需要打开源码文件。
|
||||
|
||||
> 仅供学习和个人测试使用。使用前请了解平台规则,账号风险自行承担。
|
||||
## 文件说明
|
||||
|
||||
## 准备环境
|
||||
|
||||
1. 安装 Python 3.10 或更高版本。
|
||||
2. 安装 ADB / platform-tools,并确保命令行能运行 `adb devices`。
|
||||
3. 手机或模拟器开启 USB 调试。
|
||||
4. 首次连接设备时,在手机上允许 ADB 授权。
|
||||
|
||||
安装依赖:
|
||||
|
||||
```powershell
|
||||
python -m pip install -r requirements.txt
|
||||
```
|
||||
|
||||
如果只想先安装基础依赖,也可以运行:
|
||||
|
||||
```powershell
|
||||
bootstrap_deps.bat
|
||||
```
|
||||
|
||||
## 启动方式
|
||||
|
||||
推荐优先使用数据看板 GUI:
|
||||
|
||||
```powershell
|
||||
python gui/gui_dashboard_app_entry.py
|
||||
```
|
||||
|
||||
旧版桌面 GUI:
|
||||
|
||||
```powershell
|
||||
python gui/gui_app_entry.py
|
||||
```
|
||||
|
||||
Web GUI:
|
||||
|
||||
```powershell
|
||||
python gui/webgui_launcher.py
|
||||
```
|
||||
|
||||
默认访问地址:
|
||||
解压或安装后,主要会看到这些文件:
|
||||
|
||||
```text
|
||||
http://127.0.0.1:8000/
|
||||
DouyinGuajiGUI.exe 数据看板版主程序,优先打开这个
|
||||
web_gui.exe Web 控制台服务,一般不用手动打开
|
||||
run_cli.exe 后台运行程序,由主程序自动调用
|
||||
assets/ 识别模板资源,不要删除
|
||||
config/ 配置目录
|
||||
logs/ 日志目录
|
||||
pic/ 截图目录
|
||||
state/ 运行状态目录
|
||||
```
|
||||
|
||||
命令行运行:
|
||||
|
||||
```powershell
|
||||
python bin/run_cli.py --needswitch --wait-minutes 5
|
||||
```
|
||||
|
||||
## 基本使用流程
|
||||
|
||||
1. 启动 GUI。
|
||||
2. 在顶部选择设备,或先点击刷新设备。
|
||||
3. 填写筛选条件,例如最低价值、参与人数、倒计时限制。
|
||||
4. 需要切换直播间时,开启“允许切换直播间”。
|
||||
5. 点击“开始运行”。
|
||||
6. 运行中可以点击“暂停/继续”“停止”“强制停止”。
|
||||
7. 查看运行日志、行为日志、实时截图、预约队列和统计信息。
|
||||
|
||||
## 常用配置说明
|
||||
|
||||
主要配置文件:
|
||||
日常只需要双击:
|
||||
|
||||
```text
|
||||
config/config.json
|
||||
DouyinGuajiGUI.exe
|
||||
```
|
||||
|
||||
## 第一次使用
|
||||
|
||||
1. 手机或模拟器开启 USB 调试。
|
||||
2. 用数据线连接电脑,手机弹出授权时选择允许。
|
||||
3. 双击 `DouyinGuajiGUI.exe`。
|
||||
4. 在顶部设备下拉框选择设备。
|
||||
5. 如果没有设备,点击“刷新设备”。
|
||||
6. 进入“授权”页面,输入卡密并验证。
|
||||
7. 回到“运行设置”“筛选设置”填写参数。
|
||||
8. 点击底部“开始运行”。
|
||||
|
||||
## 主界面怎么用
|
||||
|
||||
### 顶部区域
|
||||
|
||||
- 设备:选择当前要控制的手机或模拟器。
|
||||
- 刷新设备:重新检测 ADB 设备。
|
||||
- 扫描 WiFi:用于 WiFi ADB 连接。
|
||||
- WiFi ADB:打开 WiFi 连接工具。
|
||||
- Y偏移:点击位置有偏差时填写,普通文本输入即可。
|
||||
- 截图+OCR:手动截图并识别当前画面。
|
||||
- 保存配置:保存当前界面参数。
|
||||
|
||||
### 底部按钮
|
||||
|
||||
- 开始运行:启动自动化流程。
|
||||
- 暂停/继续:临时暂停或恢复当前运行。
|
||||
- 停止:正常停止。
|
||||
- 强制停止:进程卡住时使用。
|
||||
- 发送返回键:向手机发送一次返回键。
|
||||
|
||||
## 常用页面
|
||||
|
||||
### 数据看板
|
||||
|
||||
默认首页,主要看:
|
||||
|
||||
- 本次运行时间
|
||||
- 总运行时间
|
||||
- 中奖截图数量
|
||||
- 预约队列
|
||||
- 实时截图
|
||||
|
||||
### 运行设置
|
||||
|
||||
设置运行方式,例如:
|
||||
|
||||
- 是否允许切换直播间
|
||||
- 运行时长
|
||||
- 倒计时大于多少秒时跳过
|
||||
- 连续无福袋退出阈值
|
||||
|
||||
### 筛选设置
|
||||
|
||||
设置福袋筛选条件,例如:
|
||||
|
||||
- 最低价值
|
||||
- 参与人数最小
|
||||
- 参与人数最大
|
||||
- 倒计时太短时跳过
|
||||
- 粉丝团失败策略
|
||||
|
||||
### 高价值预约
|
||||
|
||||
用于价值较高、开奖时间较晚的福袋。
|
||||
|
||||
常用项:
|
||||
|
||||
| 配置 | 说明 |
|
||||
| --- | --- |
|
||||
| `min_prize_value_yuan` | 最低奖品价值,低于该值跳过 |
|
||||
| `min_participants` | 最少参与人数,0 表示不限制 |
|
||||
| `max_participants` | 最多参与人数,0 表示不限制 |
|
||||
| `skip_if_countdown_gt_seconds` | 倒计时大于该秒数时跳过或预约 |
|
||||
| `skip_if_countdown_lt_seconds` | 倒计时小于该秒数时跳过 |
|
||||
| `needswitch` | 是否允许切换直播间 |
|
||||
| `high_value_fudai_enabled` | 是否启用高价值福袋预约 |
|
||||
| `high_value_fudai_threshold_yuan` | 高价值预约阈值 |
|
||||
| `auto_join_fansclub` | 是否自动加入粉丝团,可能消耗钻石 |
|
||||
| `yanghao_enabled` | 是否启用推荐页养号 |
|
||||
- 启用预约
|
||||
- 价值阈值
|
||||
- 提前参与秒数
|
||||
- 最多记录数量
|
||||
- 预约回退校验
|
||||
|
||||
大多数配置都可以直接在 GUI 中修改并保存。
|
||||
### 运行日志
|
||||
|
||||
## 日志和截图
|
||||
显示完整运行输出。运行异常时优先看这里。
|
||||
|
||||
常用路径:
|
||||
### 行为日志
|
||||
|
||||
显示更简洁的关键动作,例如:
|
||||
|
||||
- 进入直播间
|
||||
- 识别福袋
|
||||
- 点击参与
|
||||
- 切换直播间
|
||||
- 预约记录
|
||||
- 中奖结果
|
||||
|
||||
### 截图预览
|
||||
|
||||
显示当前截图。识别不准时先看这里确认画面是否正常。
|
||||
|
||||
### 预约队列
|
||||
|
||||
显示已记录的预约福袋。该页面会自动刷新,首页里的预约队列也会自动更新。
|
||||
|
||||
### 统计信息
|
||||
|
||||
显示本次运行的数据统计,比日志更方便查看。
|
||||
|
||||
### 映射表
|
||||
|
||||
显示运行过程中记录的直播间位置和标题映射。可开启自动刷新。
|
||||
|
||||
## 推荐使用流程
|
||||
|
||||
1. 打开 `DouyinGuajiGUI.exe`。
|
||||
2. 刷新并选择设备。
|
||||
3. 点击“截图+OCR”,确认截图能正常显示。
|
||||
4. 在“筛选设置”填好最低价值、人数范围。
|
||||
5. 如果要切换直播间,在“运行设置”开启允许切换直播间。
|
||||
6. 如需高价值预约,在“高价值预约”开启预约并设置价值阈值。
|
||||
7. 点击“保存配置”。
|
||||
8. 点击“开始运行”。
|
||||
9. 运行中观察“数据看板”“运行日志”“行为日志”。
|
||||
10. 需要临时停一下时点“暂停/继续”,结束时点“停止”。
|
||||
|
||||
## 日志和截图位置
|
||||
|
||||
如果需要排查问题,可以打开这些文件:
|
||||
|
||||
```text
|
||||
logs/unified.log 全量运行日志
|
||||
logs/actions.log 行为日志
|
||||
logs/unified.log 完整运行日志
|
||||
logs/actions.log 关键行为日志
|
||||
pic/screenshot.png 当前截图
|
||||
pic/lottery/ 中奖截图
|
||||
douyin/core/state/ 预约队列和运行状态
|
||||
```
|
||||
|
||||
排查问题时,优先看:
|
||||
|
||||
1. GUI 的运行日志。
|
||||
2. `logs/actions.log`。
|
||||
3. `pic/screenshot.png` 当前页面截图。
|
||||
|
||||
## 预约队列
|
||||
|
||||
高价值预约会写入:
|
||||
|
||||
```text
|
||||
douyin/core/state/reservations.json
|
||||
```
|
||||
|
||||
在数据看板 GUI 中,“预约队列”页面会自动刷新。首页里的预约队列也会自动更新。
|
||||
|
||||
## Web GUI 端口
|
||||
|
||||
默认端口是 `8000`。如需修改,可以在 `config/config.json` 中设置:
|
||||
|
||||
```json
|
||||
{
|
||||
"web_gui_host": "127.0.0.1",
|
||||
"web_gui_port": 9011
|
||||
}
|
||||
```
|
||||
|
||||
也可以用环境变量:
|
||||
|
||||
```powershell
|
||||
$env:WEB_GUI_PORT = "9011"
|
||||
python gui/webgui_launcher.py
|
||||
state/ 运行状态
|
||||
```
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 找不到设备
|
||||
### 检测不到设备
|
||||
|
||||
先运行:
|
||||
1. 确认手机开启 USB 调试。
|
||||
2. 重新插拔数据线。
|
||||
3. 手机授权弹窗选择允许。
|
||||
4. 点击主界面“刷新设备”。
|
||||
|
||||
```powershell
|
||||
adb devices
|
||||
```
|
||||
### 截图为空或不更新
|
||||
|
||||
如果显示 `unauthorized`,请在手机上重新确认 USB 调试授权。
|
||||
1. 先确认设备已连接。
|
||||
2. 点击“截图+OCR”手动刷新。
|
||||
3. 检查 `pic/screenshot.png` 是否生成。
|
||||
4. 仍不正常时重启程序和设备。
|
||||
|
||||
### 点击位置不准
|
||||
|
||||
在 GUI 顶部调整 `Y偏移`,然后截图确认位置。
|
||||
|
||||
### 识别不到福袋
|
||||
|
||||
检查:
|
||||
|
||||
1. 当前截图是否清晰。
|
||||
2. `assets/` 模板文件是否存在。
|
||||
3. 抖音界面是否和当前模板适配。
|
||||
4. 日志里是否有阶段诊断或 OCR 错误。
|
||||
在顶部 `Y偏移` 输入框调整数值,然后再次截图确认。
|
||||
|
||||
### 运行卡住
|
||||
|
||||
先点“停止”,无效时点“强制停止”。然后查看:
|
||||
1. 先点“停止”。
|
||||
2. 如果没有反应,再点“强制停止”。
|
||||
3. 查看 `logs/unified.log` 和 `logs/actions.log`。
|
||||
|
||||
### 预约队列没有内容
|
||||
|
||||
只有识别到符合高价值预约条件的福袋后才会出现内容。请检查:
|
||||
|
||||
1. 是否启用预约。
|
||||
2. 价值阈值是否过高。
|
||||
3. 是否允许切换直播间。
|
||||
4. 运行日志里是否出现预约相关记录。
|
||||
|
||||
### 授权失败
|
||||
|
||||
1. 检查网络是否正常。
|
||||
2. 确认卡密没有复制多余空格。
|
||||
3. 点击“刷新状态”后再验证。
|
||||
4. 仍失败请联系发卡方。
|
||||
|
||||
## 不要删除的文件夹
|
||||
|
||||
这些目录不要删除:
|
||||
|
||||
```text
|
||||
logs/unified.log
|
||||
logs/actions.log
|
||||
pic/screenshot.png
|
||||
assets/
|
||||
config/
|
||||
webui/
|
||||
```
|
||||
|
||||
### Web GUI 打不开
|
||||
|
||||
确认服务是否启动,并检查端口是否被占用。默认地址是:
|
||||
这些目录可以清理旧内容,但不建议删除目录本身:
|
||||
|
||||
```text
|
||||
http://127.0.0.1:8000/
|
||||
logs/
|
||||
pic/
|
||||
state/
|
||||
```
|
||||
|
||||
## 更新
|
||||
## 更新版本
|
||||
|
||||
如果是源码方式使用:
|
||||
如果你拿到新的安装包:
|
||||
|
||||
```powershell
|
||||
git pull
|
||||
python -m pip install -r requirements.txt
|
||||
```
|
||||
1. 先关闭正在运行的程序。
|
||||
2. 备份旧目录里的 `config/` 和 `state/`。
|
||||
3. 安装或解压新版本。
|
||||
4. 如需保留旧配置,把备份的 `config/` 和 `state/` 放回新目录。
|
||||
5. 重新打开 `DouyinGuajiGUI.exe`。
|
||||
|
||||
更新前建议备份:
|
||||
## 注意事项
|
||||
|
||||
```text
|
||||
config/config.json
|
||||
douyin/core/state/
|
||||
```
|
||||
|
||||
## 测试
|
||||
|
||||
开发或修改代码后可以运行:
|
||||
|
||||
```powershell
|
||||
python -m pytest
|
||||
```
|
||||
|
||||
只检查更新相关逻辑:
|
||||
|
||||
```powershell
|
||||
python -m pytest tests/test_auto_update.py tests/test_distribution_manifest.py
|
||||
```
|
||||
|
||||
## 目录速查
|
||||
|
||||
```text
|
||||
gui/ 桌面 GUI、数据看板 GUI、Web GUI 后端
|
||||
webui/ Web GUI 前端
|
||||
douyin/ 核心自动化逻辑
|
||||
assets/ 模板图片
|
||||
config/ 配置文件
|
||||
logs/ 运行日志
|
||||
pic/ 截图
|
||||
tests/ 测试
|
||||
docs/ 详细文档
|
||||
```
|
||||
|
||||
更多内部说明可以看 `docs/` 目录。
|
||||
- 自动化运行期间不要手动频繁操作手机。
|
||||
- 账号风控风险自行承担。
|
||||
- 运行异常时先保存日志和截图,再重启程序。
|
||||
- 如果杀毒软件提示拦截,请把程序目录加入信任后再试。
|
||||
+1
-1
@@ -53,7 +53,7 @@ dist\DouyinGuaji-<version>\
|
||||
|
||||
主要文件:
|
||||
|
||||
- `DouyinGuajiGUI.exe`:桌面 GUI 主入口
|
||||
- `DouyinGuajiGUI.exe`:数据看板版桌面 GUI 主入口
|
||||
- `web_gui.exe`:Web GUI 服务入口
|
||||
- `run_cli.exe`:后台运行入口,桌面 GUI / Web GUI 会调用它
|
||||
- `assets/`、`webui/`、`config/`:运行所需资源
|
||||
|
||||
@@ -100,7 +100,7 @@ if ($Obfuscate -and (Test-Path $HiddenImportsFile)) {
|
||||
}
|
||||
}
|
||||
|
||||
python -m PyInstaller @CommonArgs @GuiArgs --name DouyinGuajiGUI --windowed (Join-Path $BuildSourceRoot "gui\gui_app_entry.py")
|
||||
python -m PyInstaller @CommonArgs @GuiArgs --name DouyinGuajiGUI --windowed (Join-Path $BuildSourceRoot "gui\gui_dashboard_app_entry.py")
|
||||
python -m PyInstaller @CommonArgs @GuiArgs --name web_gui --console (Join-Path $BuildSourceRoot "gui\web_gui_entry.py")
|
||||
python -m PyInstaller @CommonArgs @CliArgs --name run_cli --console (Join-Path $BuildSourceRoot "bin\run_cli_entry.py")
|
||||
|
||||
|
||||
@@ -233,6 +233,6 @@ def test_windows_packaging_script_exposes_obfuscate_switch():
|
||||
assert "$IncludeLicense -and" in script
|
||||
assert '$ManifestArgs += "--allow-license"' in script
|
||||
assert "Get-ChildItem -LiteralPath $srcInternal -Force | Copy-Item" in script
|
||||
assert "Join-Path $BuildSourceRoot \"gui\\gui_app_entry.py\"" in script
|
||||
assert "Join-Path $BuildSourceRoot \"gui\\gui_dashboard_app_entry.py\"" in script
|
||||
assert "Join-Path $BuildSourceRoot \"gui\\web_gui_entry.py\"" in script
|
||||
assert "Join-Path $BuildSourceRoot \"bin\\run_cli_entry.py\"" in script
|
||||
@@ -60,7 +60,18 @@ def test_gui_app_runs_update_bootstrap_before_gui_imports():
|
||||
)
|
||||
_assert_wrapper_imports_target_after_bootstrap("gui/gui_app_entry.py", "from gui.gui_app import main")
|
||||
_assert_source_entry_bootstraps_under_main_guard("gui/gui_app.py", "from gui.gui_core import")
|
||||
_assert_packaging_uses_wrapper("gui\\gui_app_entry.py", "gui\\gui_app.py")
|
||||
|
||||
|
||||
def test_dashboard_gui_runs_update_bootstrap_before_gui_imports():
|
||||
_assert_bootstrap_before(
|
||||
"gui/gui_dashboard_app_entry.py",
|
||||
"from gui.dashboard_app.app import main",
|
||||
)
|
||||
_assert_wrapper_imports_target_after_bootstrap(
|
||||
"gui/gui_dashboard_app_entry.py",
|
||||
"from gui.dashboard_app.app import main",
|
||||
)
|
||||
_assert_packaging_uses_wrapper("gui\\gui_dashboard_app_entry.py", "gui\\dashboard_app\\app.py")
|
||||
|
||||
|
||||
def test_web_gui_runs_update_bootstrap_before_gui_imports():
|
||||
|
||||
Reference in new issue
Block a user