Files
myrzx_bot/ranch_assistant/README.md
T

278 lines
24 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.
# 牧羊人之心牧场辅助
原生 PySide6 窗口,使用 Qt 默认控件。双击项目根目录的
`Start_Ranch_Helper.cmd` 启动。这台机器所需依赖已经存在。
其他环境可先运行 `python -m pip install -r ranch_assistant/requirements.txt`。
底部日志区可拖动与页面之间的分隔条来调大或调小;顶部“隐藏日志 / 显示日志”切换显隐。
隐藏期间仍继续记录日志,重新显示恢复上次高度;高度和显隐状态随账号/角色配置保存。
孵蛋优先级、补货下限/目标和魔物喂养优先级均可直接输入数字,没有上下箭头。
横向、纵向滚动条均加宽为22个逻辑像素;仅调整滚动条,窗口与按钮保持原样。
## 当前功能
- 培育室:已开启、未开启和VIP坑位分别显示;支持金币/氪金开普通坑位,先显示费用再确认。
- 背包魔物蛋:逐种勾选孵化、设置优先级、选择孵出后派遣/喂养/保留,设置补货下限、目标和市场。
数量归零后保留规则;可添加当前无库存的蛋。未勾选的蛋不会自动孵化或触发补货。
- 魔物:勾选喂养目标、设置喂养优先级;显示突破、当前等级上限、成长资质、参考属性、好感和喜欢的物品。
双击查看详情;右键可锁定、解锁、派遣、喂给指定魔物。
- 牧场概况:名称、魔物数量、容量和空位;按钮或右键可新建金币/氪金牧场,提交前确认费用。
- 每个页面的表格和空白处可右键“刷新本页”;刷新只读取状态,不执行派遣、喂养等策略。
- 多账号:同一程序内多个独立账号页签,各自监控、自动执行、记录日志;切换页签不停止其他账号。
- 会话保存:成功读取角色后自动加密保存 Token、账号/区服/角色和请求编号,重启后可恢复。
- 自动孵蛋:按手动规则执行,提供开始执行、仅监控、停止按钮;支持十连优先、金币保留和每日购蛋额度。
5/10/30/60 秒刷新;喂养遵守当前突破上限,满级后转到下一喂养目标。
- 收益资料:749 种魔物数据来自用户提供的 APK 1.9.68,支持名称搜索和1–5星分别筛选,
可导入 CSV/XLSX 覆盖价格、经验和时间。
- 账号密码登录:第一弹渠道密码验证 → 官方区服列表 → 选择区服并读取角色。
区服数量和游戏服地址采用官方响应,不写死两个区。
- 记住密码:默认启用,保存账号和密码,重启自动填回,登录失败不清空输入框。
密码使用当前 Windows 账户的 DPAPI 加密;可取消勾选移除保存内容。
- 调试窗口:逐条查看请求地址、参数、HTTP 状态、耗时、解密响应和错误阶段,
支持复制/导出,自动保存本地脱敏日志。
- 自动委托:按每日剩余接取次数、解锁城市和库存,接取、推进已满足条件的步骤、
领取奖励;列表显示奖励金币和氪金数量。提交金币、道具、魔物分别受策略限制。战斗步骤等待游戏实际完成。
- 地图关卡:按地区折叠显示安装包内的关卡、难度、掉落及账号解锁/通关记录,
每关可勾选、选择已解锁难度和本日上限;满足游戏原有条件的普通关卡可接口扫荡,
其余可设为 ADB 自动战斗目标。
- 每日事务:集中查看每日签到礼包、七日签到、累计奖励、VIP日奖和邮件附件;
可立即领取勾选项目,或开启监控时自动领取。刷新本身只读。
- 页面截图配置:每个页面一个截图按钮,自动保存原图与设备、分辨率、关卡、难度。
截图无需登录或 Token,不会点击或切换手机页面;由助手查看样本后生成按钮配置。
- 布丁史莱姆牧场:通过 ADB 操作手机里的实际战斗;根据当前体力、
入场券和自定每日轮数决定是否继续,支持自动开战、倒计时、自动战斗、
结算按钮识别、失败停止和超时停止。完成一次界面标定后可循环运行。
- 离线演示:不连接游戏服务器即可查看数据、策略和模拟操作。
## 连接真实角色
默认进入离线演示,示例角色不是手机上的真实数据。
顶部账号页签用于切换账号,“新增账号页签”用于登录另一账号。每个页签顶部明确标注演示或真实数据。
1. 在“登录”页填写第一弹渠道账号和密码,点击“账号密码登录并获取区服”。
默认勾选“记住账号和密码”;编辑完、点击登录或关闭窗口时自动保存,也可点击“保存登录信息”。
密码保存在本机加密文件 `local_state/ranch_helper/credentials.json`,重启自动填回,不再自动清空。
2. 从“官方返回的区服 / 已有角色”选择区服,点击“进入选中区服”。
登录中心取自 APK,游戏服务器地址取自选中区服的 `gameServerAddress`。
3. 确认真实角色名称、培育室和背包数量。成功后 Token 自动保存到该账号工作区的 `sessions/`,无需复制。
4. 在“背包魔物蛋”逐种配置:勾选“孵化”,设置优先级(1最高),选择“孵出后”派遣、喂养或保留。
“低于补货”是可用蛋少于多少开始购买,0表示关闭;“补至”是希望补充到的可用蛋数量。
每行可选包含该蛋的金币市场;蛋用完后这一行仍会保留。规则自动保存。
5. 到“自动孵蛋”启用需要的买蛋、孵蛋、派遣、收取或喂养开关。
点“刷新 / 预览”查看下一步,再点“开始执行勾选功能”。页面会显示“执行中”、
下一步操作或等待原因。“仅监控”和手动刷新不会执行策略;“停止执行”保留只读监控。
已经发送的请求会返回,停止后不发送下一项。重启或恢复会话后需重新点开始执行。
6. 需要经验时,在“魔物”勾选接收经验的喂养目标并设置优先级。优先级数字小的先喂,达到当前突破上限后换下一个;
在“牧场策略”可设全局停止等级、星级/资质保护和保留蛋数量。“收益资料”的星级勾选只筛选表格显示。
可用“绿色史莱姆金币预设(仅孵此蛋)”快速设置:只勾选绿色史莱姆、优先级1、孵出后派遣、低于1补至10、
莉莉托斯市场。这个预设关闭喂养,保留4星以上/A资质魔物,仍需点击开始执行。
“登录”页不再展示服务器地址、Token、密钥和请求编号,也不自动弹出调试窗;这些信息由程序内部处理。
莉莉托斯市场单次价格为100金币(本地客户端表),买到的蛋随机,不能指定全部为绿色史莱姆。
绿色史莱姆总培育时间10分钟,成熟派遣150金币;这不代表整个随机蛋池都固定净赚50金币。
购蛋默认关闭,需要勾选或应用预设。默认优先十连,保留1000金币、每日额度5000金币。
补货缺口和可用金币均达到10枚时发送 `num=10`;有库存时等待缺口,无蛋且不足十连时可按单抽上限补充。
十连的赠蛋数量以服务端实际返回为准,“最近抽蛋”显示收到的蛋种类和数量。
只购买已解锁城市的金币市场蛋,不使用氪金、抽蛋券或酒馆抽蛋。
额度按北京时间自然日、账号区服角色分别累计,保存在角色目录的 `purchase_budget.json`;
发送前记账,超时不重试也不自动退回额度,以免重复购买。切换账号、重启不会重置当天额度。
离线演示的购买和成熟仅用于流程演示,不预测真实抽蛋结果,额度不写入真实角色记录。
该密码流程来自此 APK 内第一弹 SDK 的普通账号接口,不是游戏开发者登录。
官方要求短信验证(407)或限制登录(408)时会停止,目前未实现验证码界面。
其他渠道或接口格式变化时需调整登录实现。旧会话导入函数仍保留为内部工具,不在登录页展示。
区服编号兼容 `id` 和 `serverId`,包含数字字符串;
角色条目中的 `id` 单独作为角色编号,不与区服编号混用。用户已确认真实登录和角色数据读取成功。
区服列表里的 `{"$ref":"$.servers[0]"}` 是对同一数组条目的引用,程序会还原引用并按编号去重,
将对应的角色名显示在区服下拉框中。已用用户本地的实际响应验证两区、两个角色均能正确关联。
无法识别的区服条目会停止并在界面日志列出字段名;调试窗口保留解析前收到的响应,令牌已遮盖。
真实会话过期后会停止,需要重新登录或导入会话。游戏 Token 和协议密钥在 `sessions/` 中使用 Windows DPAPI 加密,
策略设置和调试日志不保存令牌原文;SDK Token 和 HAR 原文不持久化。密码由独立的本机加密文件保存。实际服务器如
更新了协议密钥,需要更新客户端配置;登录页不展示协议参数。
## 多账号与恢复会话
1. 每个账号使用独立页签。用顶部“新增账号页签”添加账号,用页签或“打开已保存账号”切换。
2. 每个账号首次在本版本正常登录一次;此前版本只保存在内存的 Token 不能从脱敏日志补回。
3. 重启后在“登录”页点击“恢复选中会话”,或在顶部点击“恢复各页签的保存会话”。
恢复会先读取角色并核对角色编号,成功后才显示为真实数据;不会自动开启策略或刷图。
4. 各页签可分别开启监控和自动执行。顶部“全部开始监控”只开启已连接账号的监控,
自动执行仍由各账号的勾选决定;“全部停止”停止所有页签的监控和刷图。
5. 关闭一个页签会停止该账号,其他账号继续运行;保存的账号和会话仍可再次打开。
账号工作区各自保存凭据、会话和日志;区服/角色各自保存策略、喂养目标、截图和刷图次数。
切换区服时不沿用其他角色的策略。相同账号区服不会在两个页签重复运行。
会话的请求编号在发送前保存,包括超时未确认的请求;写请求不会自动重发。
删除保存会话需先切回离线演示,再点击“删除选中保存会话”。“记住账号和密码”只控制密码,独立于会话保存。
正常会话心跳按客户端的 240 秒周期运行。ADB 刷图中,同一台手机同时只允许一个账号页签控制;
不同手机可分别配置。未实现脚本检测规避,也不保证服务端无法识别自动化。
## 页面数据与刷新
“培育室”“背包魔物蛋”“魔物”“牧场概况”可直接查看状态,顶部显示坑位、蛋数量、魔物数量和更新时间。
表格或页面空白处右键选择“刷新本页”,保持当前页面;请求进行中再次刷新会排队。
收益资料和截图配置页刷新本地资料。自动刷新的 5/10/30/60 秒间隔继续保留。
已修复实际响应里 `activityHistory.vipInfo=null` 导致策略报错、阻止数据显示的问题。
已用实际角色响应回放验证 4 个坑位、4 类蛋、4 只魔物和 1 个牧场能显示。
策略计算或配置出错时,基础数据仍可读取,自动操作会停止。
## 调试登录
点击顶部“调试窗口”手动打开。账号登录及选择区服时不自动弹窗,后台仍保存脱敏记录。
按顺序可看到:渠道账号验证、获取官方区服、选择区服、进入选中区服、读取角色。
账号验证和获取区服完成后停下来等你选服,选中后才会发送进入区服请求。
区服整理是本地将 JSON 字段转换成界面选项;“本地错误”不表示发送了额外请求。
同一个错误在网络/数据层和界面层传递时只记录一次。
进入区服前会增加“进入参数检查”本地记录,显示签名日期、规则和渠道,不包含 Token 或签名原文。
原客户端虽然写 `yyMMdd`,其格式函数实际使用四位年份,签名日期必须为八位 `yyyyMMdd`。
`channel=DYD` 与 APK 里的 `tjChannel=taptap` 分别读取和传递,不混用。
选中一条记录可看完整 JSON;游戏加密接口显示解密后的字段。HTTP 错误、连接超时、
响应解码失败和区服解析失败都记录,密码、Token、Cookie、Authorization 会遮盖。
界面显示本次运行最近 300 条记录,日志自动追加到:
首账号为 `local_state/ranch_helper/network_debug.jsonl`;新增账号位于其 `profiles/<账号页签编号>/` 目录。
窗口顶部会显示该账号的实际日志路径;超过约 8 MiB 会保留一份上一段日志。
重新尝试登录后,告诉助手“日志好了”,助手即可读取这个工作区内的调试文件;
不用发送账号密码。也可以用窗口里的复制、导出按钮取得脱敏记录。
接口静态清单见 [API_INVENTORY.md](../analysis/API_INVENTORY.md),包含用途、参数、回调字段和证据位置。
## 手动规则与保护
算法参考 [BWIKI 魔物收益表](https://wiki.biligame.com/myrzx/魔物收益表),
原页面作者 Monster-SCAG,页面标示更新于 2020-12-05。没有把旧攻略表的
所有数值直接套入当前游戏;本版使用 APK 中的事实数据计算。
- 金币/小时 = 派遣金币 / 总培育小时数。
- 经验/小时 = 强化经验 / 总培育小时数。
- 自动操作按各行手选的去向执行,不按收益表自动决定派遣还是喂养。优先级相同时先孵时间较短的蛋。
- 单体喂养经验按客户端公式计算:基础经验 + 截断(已获得经验 × 配置倍率)。
默认内置倍率从客户端数据提取为 0.2。
- 收益页的每小时金币是毛收益,不是购蛋净利润;实际购蛋金币会单独从余额和每日额度扣除。
- 默认保留三星及以上、综合 A 资质及以上,以及锁定、系统锁定、羁绊、
在队、探索中、携带装备和资质数据不完整的魔物。
- 自动派遣/喂养只处理本次运行在培育室观察到的魔物,不扫描并消耗已有
牧场魔物。未指定可用喂养目标时不消耗素材;手动右键操作可选择已有牧场魔物。
- 非 VIP 不使用客户端标识的第 4 个 VIP 坑。牧场满了停止收取;喂养停止等级为
用户目标和当前突破上限的较小值。客户端上限公式为 `potentialLevel × 10`,
例如突破等级2的上限是20,即使设置70级也会在20级停止;上限未知时停止喂养。
“魔物”和喂养目标下拉框显示等级/当前上限。每轮执行一项计划操作,随后重新读取状态;
成熟计时结束时会先结算成长并重新读取,再决定收取或派遣。
- 游戏对蛋的 `feedLock` 存在手机本地存档中,服务器会话看不到这项本地
偏好。需要保留某类蛋时,在策略页填写“编号:保留数量”。
## 手动管理与扩建
孵化与幼体成长阶段显示“待成熟后生成”,不把服务端的零值算成 C 资质。
自动执行会在两个阶段转换时请求成长结算,并使用结算响应中的阶段和四项成长值更新界面;
成熟、资质确定后才决定派遣、喂养或保留,旧查询结果不会覆盖尚未确认回写的结算数据。
培育室的“同步孵化 / 成长”可单独更新这些状态,本次不执行派遣或喂养。
“仅监控”不会结算或派遣;需点“开始执行勾选功能”才能自动处理。
保留原因会显示在培育室建议和日志中,例如达到保留星级、综合资质A/S、锁定或未启用派遣。
培育室魔物的 `roomId=null` 已兼容,统计牧场容量时不会再因空字段中断整轮策略。
- 魔物表可多选,使用按钮或右键锁定/解锁。派遣、指定喂养会列出将消耗的魔物并要求确认;
这些手动操作会暂停自动执行。锁定、系统锁、羁绊、在队、探索、建筑中及已装备的魔物不能作为素材。
- 喂养素材需已收取到牧场,目标不能是素材本身,且不能已满当前突破等级上限。
- 参考属性按基础值、成长、等级、潜能、好感及升星计算,不含装备、羁绊和全局加成;完整实战面板以游戏为准。
- 培育室按本地表列出11个坑位,并兼容服务器返回的更多位置。第4个为VIP专用,不走普通扩建接口。
选择未开启的普通坑位后可用金币或氪金开通。VIP资格需在游戏内处理。
- 牧场页的“新建牧场”支持金币或氪金。金币建牧场还要求账号已解锁相应建设功能。
- 金币建设解锁按已完成任务 `1001011` 判断,与客户端一致。
- 费用按客户端价格表与设施 `openType` 统计的扩建次数计算,提交前重读角色、检查等级和余额;
费用变化会要求重新确认。取消确认不会发送请求,超时不会自动重复购买。
- 实测日志里的空坑是 `monsterId=-1`,已按客户端 `<=0` 规则修复;此前买到蛋却不孵化的原因就是误判空坑。
## 页面截图配置(推荐)
1. 手机启用 USB 调试并允许 ADB。在“体力刷图”填写 ADB 路径(本机已自动找到),
选择关卡和难度。只有一台手机时设备编号可留空。
2. 打开“页面截图配置”。自己玩到对应页面时,点击该行“截取此页面”。
每次截图会暂停当前辅助监控和刷图;不自动登录、开战或跳转页面。
3. 最少拍齐“关卡准备页”(标题、难度、进入按钮)和“胜利结算页”(胜利标识、确认按钮)。
按需补拍“战斗倒计时”“自动关闭”“自动开启”“后续确认”“失败结算”五页。
不必特意输一局来收集失败页。点击页面行可预览已有图片。
4. 截图自动保存在项目目录:
当前角色目录下的 `capture_profiles/<设备>/<宽x高>/<关卡>_<难度>/`。
登录角色的目录为 `<账号工作区>/roles/<角色标识>/`,软件会显示实际路径。
原图为页面英文标识命名的 PNG,`profile.json` 保存设备、分辨率、时间和图片摘要。
“打开截图文件夹”可查看;重启后通过下拉框找回配置。
5. 拍好后告知助手“截图好了”。助手直接读取此工作区的文件,查看按钮位置,
生成同目录 `buttons.json` 和裁剪模板,不需要你手工框选或提供 Token。
这一步由助手完成,Qt 程序本身不包含自动理解任意截图的模型。
6. 点击“加载已生成的按钮配置”,然后用真实会话核对体力、入场券,
让手机停在相同账号的所选关卡准备页,设置每日轮数,开始刷图。
按钮配置绑定设备、分辨率、关卡、难度及生成时的截图摘要。重新拍摄改变了内容,
或更换设备/分辨率时需要重新生成。胜利标识的识别位置和确认按钮的点击位置可分开。
保留“体力刷图”里的手工框选作为可选工具;推荐流程不需要使用它。
必须同时匹配关卡名称与进入按钮才会开始一轮。请保持同一画面布局,
不要手动切换其他关卡或应用。分辨率/界面布局变化后需要重新标定。
模板匹配无法理解任意游戏弹窗;未知画面会等待,并在单轮超时后停止。
当前 APK 的 `bd00` 一般难度数据为 6 体力 + 道具 20047 一枚入场券,
`bd01` 使用另外一种入场券;程序按对应关卡配置检查,不把“免费”当成
“不限次数”。本地每日轮数按北京时间和角色/关卡分别持久化,统计已开始
的尝试,包括中断或失败;它不是服务器的每日次数查询接口。服务器的
入场券余量也会独立检查。暂未找到该活动独立的每日次数字段,不声称已
读取到该字段,遇到服务器限制或未知弹窗会停止/超时退出自动流程。
## 文件与验证
- 工作区:首账号使用 `local_state/ranch_helper/`,新增账号使用其 `profiles/<编号>/`。
`sessions/` 是加密会话;`roles/<角色标识>/` 是各角色的策略、截图和本日次数。
- `catalog.json` 是本地数据;游戏热更新后的新魔物/新售价需要更新资料。
未知魔物和不完整资质不会自动派遣或喂养。
- 自定义表:`typeId, sell_money, sell_exp, time_total`(秒),可只提供部分
覆盖列;中文列名“编号、派遣金币、强化经验、孵化秒数”也支持。
- 测试:`python -m unittest discover -s ranch_assistant/tests -v`。
- 100 项测试通过,覆盖难度列表解析、扫荡条件/请求顺序/异常暂停/跨角色每日额度、
签到与邮件JSON/空VIP/时间单位/失败不重试、树形规则恢复和截图页不重叠;以及
加密HTTP十连→实际赠蛋→负数空坑孵化→成长结算→派遣→余额刷新、逐种优先级和补货、
多目标喂养优先级、锁定/手动派遣/喂养、开坑与建牧场的费用复核和取消确认、金币/库存/每日额度限制、
购蛋超时记账、突破等级上限、星级筛选、启动/停止/忙时排队和委托奖励显示;也覆盖多账号并行/重启恢复、账号和角色隔离、请求计数持久化、超时恢复、错角色阻止、
右键只读刷新、空值响应显示、心跳、关闭页签,以及四位年份的进入签名、APK 追踪渠道、区服引用还原/去重、两个角色显示、选二区登录、本地错误去重,
Windows 密码加密保存/恢复、登录失败保留密码、调试窗与脱敏日志,
以及 Qt 截图按钮只读、不点击手机、配置恢复、图片变更失效、
设备/分辨率检查、两种区服编号下密码登录及选二区的 loopback HTTP 链路、
缺失/冲突编号停止、Qt 登录回调错误处理、委托、地图和牧场策略。
开发测试未向官方服务提交真实账号凭据,未对真实库存执行购蛋、派遣、喂养、委托或刷图。
用户已验证登录和角色读取;本次买蛋循环及多账号并行由本地模拟服务验证,真实账号效果仍需用户启动后验证。按钮配置需当前页面样本。
- 网络写请求发生异常后不会直接重试,以免重复消耗魔物或物品。
## 委托和扫荡的范围
“自动委托”需单独启用;可先关闭“牧场策略”的自动管理,只运行委托。
道具和魔物提交默认关闭,金币提交上限默认 0;锁定、队伍、高星和高资质保护继续生效。
已接委托需要的魔物种类和蛋会纳入牧场保留。
“也接取需要实战的委托”只允许接取此类任务,当前不会自动导航到每项委托的专用战斗。
普通关卡首次通关仍需在游戏内实际战斗。客户端有 `startSaodang` /
`doSaodangBattle` 扫荡分支:普通、非剧情定位关卡的三个难度全部通关后才开放。
它复用 `stageStart` → `battleEnd` → `recordBattleResult`,无需本地战斗演算或手机截图。
此前只搜索英文 sweep 和中文“扫荡”漏掉了这个拼音方法;现已按该分支实现。
在“地图关卡”展开地区,每关勾选“刷图”、选择难度、输入“本日上限”,再点击“开始扫荡”。
星级是服务器通关进度计算出来的,只读。未解锁难度不能选;特殊关卡、未全通关、剧情任务、
体力/金币/门票不足的关卡会显示原因并跳过。次数按角色、日期、关卡和难度保存,
是本地已开始次数,不冒充服务器每日限制。扫荡和ADB实战不能同时运行。
一次扫荡内部的几个请求顺序执行,完成后重读账号状态;开启其他策略时与孵蛋/委托逐轮串行。
触发随机事件或请求结果不明确时停止,不提交后续结算;在游戏内处理后可清除本地待处理记录。
“每日事务”选择要处理的奖励类别,点“领取勾选项目”可立即领取;
点“开始每日事务”会打开统一监控和自动执行,只处理符合状态的项目。
VIP奖励只对已有资格领取;不会购买VIP或升级礼包。邮件仅领取附件,不删除邮件。
启动/重启默认仍只读,自动化需要手动开始。勾选项、战队、保留体力及刷图规则按角色保存。
网络写请求发送前保存本地记录,异常不直接重试;本日已提交但服务器仍返回旧状态的奖励会明确提示。
资料包含此APK的1178个关卡、各难度奖励和2079种道具名称。
这些是安装包配置中的可能掉落,并非实时掉落概率保证;后续热更新新增数据需要重新提取。
本次签到、领邮件和扫荡均由本地模拟验证,尚未在真实账号上执行验证。
静态证据与字段规则见 `analysis/STAGES_DAILY.md`。