182 lines
12 KiB
Markdown
182 lines
12 KiB
Markdown
# 蔚蓝星球本地自动化
|
||
|
||
当前是本地 Python 桌面原型。先完成并验证单条流程，再扩展任务和打包成 macOS / Windows 独立程序。
|
||
|
||
## 已实现
|
||
|
||
- 桌面界面：主屏幕截图、框选游戏内容区域、流程预览、执行日志与停止。
|
||
- 小金猪流程：首页识别 → 打开挂机奖励 → 仅在金色领取按钮出现时长按领取 → 确认奖励弹框与灰色按钮 → 关闭弹框并回到首页。
|
||
- 脚本与识别模板分离，后续任务通过 `workflows/` 扩展。
|
||
- 截图像素与鼠标坐标分别换算，覆盖主屏幕 Retina 缩放的坐标情况。
|
||
- 已有17项任务脚本，涵盖首页领奖、英雄招募签到、领地收矿／体力／券／积分及公会日常；入口、范围和更新时间见 [脚本汇总](docs/261004_1607-首页功能与日常任务梳理.md#已实现脚本汇总)。
|
||
- 页面地图、只读识别、路线查询及任务分组预览。当前仍未接入统一导航执行和一键日常调度。
|
||
|
||
小金猪流程只领取挂机奖励，不执行消耗体力的快速扫荡。已于 2026-10-04 实机验证：领取后出现“恭喜获得”弹框、按钮变灰、挂机计时重置，并确认返回首页。灰色领取按钮时脚本不会点击领取。
|
||
|
||
红点规则：按钮右上角有红点表示其内部有奖励可领取。已有任务在各自配置区域检测红点，领取成功仍需验证内部状态。小金猪流程不依赖红点；通用入口定位和红点检测尚未接入地图导航。
|
||
|
||
## 本地启动
|
||
|
||
### 页面识别与地图（只读）
|
||
|
||
页面关系记录在 `workflows/page_map.json`，完整说明见 [页面地图与导航规则](docs/261005_1702-页面地图与导航规则.md)。识别当前游戏页面或查询候选路径：
|
||
|
||
```bash
|
||
.venv/bin/python inspect_page.py
|
||
.venv/bin/python inspect_page.py --from-page territory --to-page recruit.lamp
|
||
```
|
||
|
||
这两个命令不会点击游戏。主要页面已实机核对；未知、歧义、遮挡或未验证入口不能据此自动导航。现有任务脚本仍按其原来的启动页面运行，尚未接入地图与统一调度。
|
||
|
||
外观相同的进度奖励弹框需要已确认的进入来源，不能仅凭图片猜测：
|
||
|
||
```bash
|
||
.venv/bin/python inspect_page.py --image local/page_audit/territory_rank_progress.png --previous-page territory.rank.board
|
||
```
|
||
|
||
### 地图核查与任务分组（只读）
|
||
|
||
```bash
|
||
.venv/bin/python plan_tasks.py --audit
|
||
.venv/bin/python plan_tasks.py
|
||
.venv/bin/python plan_tasks.py --page guild
|
||
.venv/bin/python plan_tasks.py --include-deferred --include-manual
|
||
```
|
||
|
||
命令只读取配置，检查引用并列出按首页、商城、领地、公会分组的任务和开发缺口，不截图、不点鼠标。默认排除延期任务、按需快速扫荡和命令打造；已有脚本标注其原首页启动要求，不能直接送到子页面运行。当前可见页面核实结果及后续实现顺序见 [页面核实与自动化优化计划](docs/261006_0109-页面核实与自动化优化计划.md)。
|
||
|
||
### 已验证的小金猪挂机奖励脚本
|
||
|
||
```bash
|
||
.venv/bin/python claim_idle.py
|
||
```
|
||
|
||
流程为：首页 → 小金猪 → 判断右侧领取按钮。金色时长按领取，确认“恭喜获得”弹框和领取按钮变灰后关闭；灰色时不领取，直接关闭弹框。两种情况都会返回首页。使用 `--dry-run` 可只验证首页而不点击。
|
||
|
||
### 已验证的小金猪快速扫荡脚本
|
||
|
||
```bash
|
||
.venv/bin/python claim_sweep.py
|
||
.venv/bin/python claim_sweep.py --times 5
|
||
```
|
||
|
||
默认扫荡 1 次；`--times 5` 会扫荡 5 次，每次消耗 10 体力。每次扫荡后脚本确认奖励弹框、关闭弹框、等待 2 秒，再进行下一次；全部完成后返回首页。使用 `--dry-run` 可只验证首页和执行计划，不消耗体力。
|
||
|
||
### 已验证的任务奖励脚本
|
||
|
||
```bash
|
||
.venv/bin/python claim_tasks.py
|
||
```
|
||
|
||
仅在首页右侧任务按钮有红点时进入。脚本先处理当前日常或周常面板中全部可见的“领取”按钮；当前面板领完后，只在另一个标签自身有红点时才切换处理。面板没有领取按钮或任务入口没有红点时，不执行奖励点击并返回首页。使用 `--dry-run` 可只验证首页和执行计划。
|
||
|
||
### 已验证的特惠一键领取脚本
|
||
|
||
在首页执行：
|
||
|
||
```sh
|
||
.venv/bin/python claim_offer.py
|
||
```
|
||
|
||
只检查首页和显示计划：
|
||
|
||
```sh
|
||
.venv/bin/python claim_offer.py --dry-run
|
||
```
|
||
|
||
流程为：首页 → 特惠 → 若打开“超值月卡”则点击底部“战令” → 赏金战令 → 一键领取 → 确认“恭喜获得”弹框 → 关闭弹框 → 确认领取按钮变灰 → 返回首页。已于 2026-10-04 实际领取并返回首页，领取后奖励出现绿色勾且一键领取变灰。完整脚本再次运行时，已验证从月卡切换战令、识别灰色按钮并返回首页。
|
||
|
||
当前仅适配本次“赏金战令”领取，支持从“超值月卡”切换到“战令”，不会购买战令或遍历其他特惠标签。无法识别的页面样式或标签会使流程停止。macOS 自动读取已打开游戏窗口位置，每次识别重新定位，识别后窗口移动则停止；窗口标题栏高度按本次验证的 44 逻辑点处理，需收起微信侧栏。运行时保持游戏完整可见。Windows 使用 `main.py` 已校准的区域或 `--region X Y WIDTH HEIGHT`，实机尚未验证。
|
||
|
||
### 已验证的狂鼠之家收矿脚本
|
||
|
||
```bash
|
||
.venv/bin/python claim_mining.py
|
||
```
|
||
|
||
流程为：首页 → 领地 → 狂鼠之家 → 发现“一键收矿”时收矿 → 关闭奖励弹框 → 等待 10 秒 → 一键雇佣。雇佣弹框按白银罗盘、黄金罗盘、彩虹探测仪的顺序选择第一个可用项；三者均不可用时关闭弹框。最后返回首页。
|
||
|
||
已在 2026-10-04 实机验证收矿、10 秒等待、白银罗盘雇佣和返回首页。找不到“一键收矿”时，脚本不雇佣并直接返回首页。使用 `--dry-run` 可只验证首页而不点击。
|
||
|
||
### 已验证的食堂领体力脚本
|
||
|
||
```bash
|
||
.venv/bin/python claim_stamina.py
|
||
```
|
||
|
||
流程为：首页 → 领地 → 食堂 → 发现“一键领取”时领取体力 → 确认“恭喜获得”弹框 → 确认烤肉库存为 0/60 → 返回首页。没有可领体力时，脚本不点击领取并直接返回首页。使用 `--dry-run` 可只验证首页而不点击。
|
||
|
||
### 已验证的合作券领取脚本
|
||
|
||
```bash
|
||
.venv/bin/python claim_cooperation_ticket.py
|
||
```
|
||
|
||
流程为：首页 → 领地 → 合作模式 → 模式选择左侧“合作模式” → 左上“可领取” → 确认奖励弹框与“已领完” → 返回首页。只操作左侧合作模式，不进入“保卫宠物”；已领完时不点击领取，直接返回首页。使用 `--dry-run` 可只验证首页而不点击。
|
||
|
||
### 已验证的竞技积分领取脚本
|
||
|
||
```bash
|
||
.venv/bin/python claim_arena_points.py
|
||
```
|
||
|
||
流程为：首页 → 领地 → 巅峰决斗 → 模式选择左侧“竞技场” → 点击左下积分累积区域 → 确认“恭喜获得”奖励弹框 → 返回首页。积分会持续累积，脚本每次运行领取当前可领取的积分。使用 `--dry-run` 可只验证首页而不点击。
|
||
|
||
需要 Python 3.9 或更新版本，以及带 Tk 支持的 Python。macOS 若当前 Python 缺少 Tk，可使用 python.org 官方安装包。
|
||
|
||
macOS：
|
||
|
||
```sh
|
||
python3 -m venv .venv
|
||
.venv/bin/python -m pip install -r requirements.txt
|
||
.venv/bin/python main.py
|
||
```
|
||
|
||
Windows PowerShell：
|
||
|
||
```powershell
|
||
py -m venv .venv
|
||
.venv\Scripts\python.exe -m pip install -r requirements.txt
|
||
.venv\Scripts\python.exe main.py
|
||
```
|
||
|
||
## 首次运行
|
||
|
||
1. 将游戏放在主屏幕，打开首页，保持窗口完整可见。
|
||
2. 点击“校准游戏区域”。程序会最小化并在 1.5 秒后截图，在预览图中拖动框选**游戏内容**，不包含微信标题栏及边框。
|
||
3. 点击“预览流程”，在 3 秒内切回游戏。只验证当前首页并显示计划，后续页面尚未验证。
|
||
4. 预览通过后点击“执行领取”，在 3 秒内切回游戏，观察首次实际结果。
|
||
5. 可以点击程序中的“停止”，或把鼠标移到主屏幕左上角触发 PyAutoGUI 紧急停止。系统截图调用期间停止可能延迟到调用结束。
|
||
|
||
macOS 实际截图和点击需要为运行程序的宿主启用屏幕录制和辅助功能权限。程序不会自行改变系统权限。Windows 的主屏幕缩放与窗口尺寸、macOS Retina 坐标映射均需实机验证；当前没有完成双平台验证。
|
||
|
||
“导入截图校准”需要导入当前**主屏幕完整截图**，不能导入单独的游戏裁剪图，否则无法得到桌面位置。校准配置保存到忽略版本管理的 `local/region.json`。游戏移动、大小改变、屏幕配置改变后请重新校准。当前不支持跨屏或遮挡运行，界面样式不匹配时停止，不强制点击。
|
||
|
||
## 验证与后续
|
||
|
||
### 实机操作排查记录（2026-10-04）
|
||
|
||
通过 Codex 窗口控制工具尝试领取时，可以读取微信下的游戏画面，但点击小金猪未打开弹框。随后尝试直接绑定 `com.tencent.flue.WeApp` 超时，系统记录了 16:50:34 的 `WeApp` 崩溃：辅助进程启动后约 39 毫秒，在 `_libsecinit_appsandbox` 初始化中发生 `EXC_BREAKPOINT / SIGTRAP`。该记录支持异常发生在小游戏辅助进程启动阶段，尚不能证明微信主进程崩溃，也不能证明由点击动作直接导致。
|
||
|
||
本次操作使用窗口控制工具，未启动本项目 `main.py`，因此当前不能将该异常归因于本地原型。后续由用户从微信正常打开游戏，不再通过工具直接启动或绑定 WeApp 辅助程序；先验证单次截图和点击，再进行完整流程测试。本地原型只操作已打开的游戏区域，不负责启动微信或其辅助进程。
|
||
|
||
用户授权后进行了单次本地 PyAutoGUI 商城点击测试：沙盒外可读取主屏幕截图，但页面未切换；只读查询 `AXIsProcessTrusted()` 返回 `False`，确认本地 Python 进程缺少辅助功能权限。程序已增加点击前权限检查，权限缺失时停止并提示，不继续报告“已点击”。这不证明此前窗口工具不响应也出于相同原因。
|
||
|
||
用户授予权限后，查询返回已授予。普通点击将游戏窗口激活，但商城仍未打开；随后使用 PyAutoGUI 移动鼠标、按下保持 0.2 秒、释放，成功打开商城，游戏保持运行。本地原型已采用此方式，异常时也确保释放鼠标；这次验证仅证明商城切换有效，小金猪领奖流程仍待实机测试。
|
||
|
||
需要用户在“系统设置 → 隐私与安全性 → 辅助功能”中，为运行程序的宿主（当前为 ChatGPT/Codex；从终端启动则为对应终端）启用权限，之后重启宿主再检查。程序不自动授予或请求权限。可用以下命令只读确认：
|
||
|
||
```sh
|
||
.venv/bin/python -m automation.permissions
|
||
```
|
||
|
||
```sh
|
||
.venv/bin/python -m unittest discover -s tests -v
|
||
```
|
||
|
||
测试使用模拟桌面和识别夹具，不操作游戏，覆盖坐标换算、领取流程、预览、超时、停止、弹框来源和地图引用。已有脚本的领奖变化曾分别实测；新地图任务本轮只核实布局与导航，尚未验证领取、广告、购买后的结果。
|
||
|
||
后续先实现公共导航和列表／免费领奖执行器，逐项迁移已有脚本，再接广告、资源购买和任务记录；最后完善模型设置与 Key 存储并进行双平台打包。目前不调用模型 API，也不保存模型 Key。
|
||
|
||
实现参考：[PyAutoGUI 官方文档](https://pyautogui.readthedocs.io/en/latest/quickstart.html)、[OpenCV 模板匹配文档](https://docs.opencv.org/4.x/d4/dc6/tutorial_py_template_matching.html)。
|