Files
myrzx_bot/README.md
T

125 lines
16 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.
# 牧羊人之心Bot
原生 PySide6 桌面辅助,当前开发版本 **1.2.0.dev1**,适配资料基线为《牧羊人之心》Android **1.9.68**;最近正式版本为 **1.1.1**。
支持多账号独立运行、牧场培养、每日事务、自动扫荡及本地掉落分析;v1.2 新增任务、对话与战斗调度,完整集成验证仍在进行。
## 运行指引
1. 在 Windows 中安装 Python 3,并确保 `python` 命令可用。
2. 在项目目录执行 `python -m pip install -r ranch_assistant/requirements.txt`,安装 PySide6 等依赖。
3. 双击项目根目录下的 `Start_Ranch_Helper.cmd` 启动辅助。
4. 在“登录”页面输入账号和密码,登录后选择区服;详细功能及配置方法见[辅助使用说明](ranch_assistant/README.md)。
5. 登录后自动刷新状态;配置各页面的功能后,用顶部“开启 / 停止”统一控制自动操作。关闭策略后仍继续刷新。
也可以在项目目录运行 `python -m ranch_assistant` 启动。
首次使用可先查看各页面数据、配置规则,再开启策略;重启、恢复会话或导入配置后,策略开关默认关闭。
## 当前功能
| 模块 | 1.2.0.dev1 当前实现(战斗能力范围见下文) |
| --- | --- |
| 登录与多账号 | 第一弹渠道账号密码登录,选择官方返回的区服及角色;账号密码与会话在本机加密保存,支持恢复会话、多账号独立运行、退出登录及清除登录记录。关闭账号页签后重启不会重新打开,也可彻底移除该账号的本地记录。 |
| 状态刷新与策略开关 | 登录后自动刷新角色、培育室、背包及牧场状态;每个账号只有一个“开启 / 停止”开关,菜单支持批量控制。关闭策略后仍同步状态和到期成长;手动刷新不触发消耗类自动操作。 |
| 玩家信息 | 显示等级、经验与下一级门槛、金币、氪金、体力;经验达到门槛及体力恢复到期时,在后台请求服务器结算并更新显示。 |
| 培育室 | 显示已开启、未开启、VIP坑位及魔物阶段、剩余时间和成熟资质;孵化与成长到期自动同步。普通坑位可在确认费用后扩建。 |
| 分类背包 | 魔物蛋、可使用物品、消耗品、材料、其他、装备分别展示;支持搜索和排序。每种蛋可配置孵化开关、优先级、孵出后去向、补货下限/目标及市场;物品可配置赠礼开关和保留数量。 |
| 牧场与魔物管理 | 默认平铺全部魔物,可切换为按牧场折叠分组;显示容量、空位、普通等级上限、同种突破、突破经验、潜能阶段、资质、参考属性、好感上限及喜欢的物品。支持详情查看、多选锁定/解锁、派遣、指定喂养,以及确认费用后新建牧场。 |
| 自动孵蛋与补货 | 按手动规则完成金币市场买蛋/抽蛋、孵化、成长同步、成熟收取、派遣或喂养;默认只十连,可单独开启“允许单抽”,遵守金币保留和每日购蛋额度。空坑按优先级独立随机1~2秒装填,不受整体刷新间隔影响。 |
| 资质保留与经验喂养 | “背包 → 魔物蛋”的“牧场保留”默认1,是最低保留数量,0表示关闭数量保护;同种数量跨牧场及孵化批次统一保底。锁定、星级/资质保护仍可让实际保留数超过该值;资质提升依次按S项数、A项数、B项数、四项成长各自归一化后的平均值,与牧场已保留的同种最高资质比较,严格更高才额外保留,同分不额外保留,不自动解锁或强删旧魔物。经验喂养遵守普通等级上限;同种突破最高4级,每只同种素材增加1点突破经验,与潜能阶段分开计算。 |
| 自动突破与探险 | 牧场勾选突破目标并设置优先级,即授权先补满四项潜能、再提升潜能阶段,消耗对应元素材料并遵守物品/委托保留量,不购买材料、不消耗金币或氪金。自动探险默认关闭,每队配置地区、保留体力和队员,完成后先领奖再出发,不花钱开队或召回;未知请求持久化,新快照确认前不重发,停止策略后继续只读刷新。 |
| 自动赠礼与好感培养 | 在背包选择物品、牧场选择目标后自动赠礼;跳过冷却目标,连续处理其他可送目标,在本地倒计时并到期核对状态。支持喜欢物品筛选、库存保留及当前好感上限。可在本地自动为每种魔物选择唯一培养代表,依次按等级、好感、成长资质比较,完全相同时随机选定并记住。 |
| 每日事务 | 查看并领取每日签到礼包、七日签到、累计奖励、已有VIP日奖和邮件附件;支持手动领取及按勾选项目自动领取。 |
| 自动主线 | 展示主线、支线、委托的状态、位置、NPC、需求、对话和阻塞原因;推进已支持的接取、线性对话、交付、领奖与任务补链。材料、蛋或击杀不足时,按已知来源规划普通地图收集;开图受前置、资源和战斗能力限制。 |
| 自动委托 | 根据每日剩余次数、城市与库存接取委托,推进已支持的步骤并领奖;显示金币和氪金奖励,金币、道具及魔物提交可分别限制。实战委托已接入任务战斗调度,须开启对应选项并通过所选模式的能力检查;设置仍在“自动委托”。 |
| 战斗模式与记录 | “自动主线 → 推进策略”显式选择原版运行时(默认)或实验模拟(近似);按普通地图、任务专属战斗、任务通关战斗分别编排。记录胜负、模式、地图奖励事件和待核对原因,支持停止与中断恢复;局部能力不代表全部关卡可用。 |
| 自动扫荡与挑战 | 按地区折叠显示关卡、难度、通关星级及可能掉落;账号地图本地缓存,手动刷新或挑战结束后同步进度。逐关勾选、选择已解锁难度和本日次数上限,配置保留体力与战队;满足扫荡条件时扫荡,未满星时可自动模拟挑战,战败显示“打不过”,支持探索奖励事件。 |
| 掉落数据分析 | 按账号、关卡与难度在本地保存扫荡记录,分别统计普通扫荡、奖励事件或合计;展示样本数、出现次数、总数量、实测掉落率、平均数量和95%区间。支持掉落率/每点体力获得数量的条形图,不额外请求游戏服务器。 |
| 收益资料与执行计划 | 内置749种魔物的培育时间、派遣金币、强化经验及每小时收益,支持名称/星级筛选和CSV/XLSX覆盖;执行计划显示下一步操作与等待原因。 |
| 统一策略配置 | 规则修改后自动保存并应用;通过原生菜单保存、导入或导出当前账号的孵蛋、牧场、喂养、突破、赠礼、委托、每日事务、探险、扫荡、主线推进、战斗模式、刷新间隔及自定义收益资料。跨账号按魔物种类匹配培养/突破目标,探险按队序重新绑定并匹配队员,隐藏页不丢规则;不复制原账号实例ID,不包含凭据或服务器进度。 |
| 界面与调试 | 原生Qt菜单、可调整和隐藏的日志区、各页右键刷新;数字与勾选项可排序,数字框获得焦点后才响应滚轮,下拉框按内容扩宽。独立调试窗口查看请求、响应、耗时与错误,支持复制、导出和本地脱敏日志。 |
| 后台处理与离线演示 | 各账号后台线程独立处理网络与资料,单账号请求串行;只渲染当前查看页面,大列表分批更新并复用控件。支持随机30秒、60秒、2分钟或5分钟上限的刷新间隔,以及无需连接服务器的离线演示。 |
## 1.2 开发版使用要点
在“自动主线 → 任务状态”点击“刷新任务 / 预览”,查看下一步和阻塞原因;到“推进策略”选择任务范围、推进战斗队伍、保留体力和交付限制,再勾选“启用自动主线策略”,用顶部绿色“开启”运行、红色“停止”暂停。规则自动保存,重启、恢复会话或导入配置后仍需手动开启。委托接取、交付和“也接取需要实战的委托”继续在“自动委托”配置。
- **内置战斗模拟**:无需选择运行时,程序使用原始数值资料,在独立进程中计算 AP、出场、移动、攻击和部分技能,等待计算出的战斗时长后提交结果。模型仍有机制近似与遗漏,可能和原版胜负不同,未支持的战斗会显示原因。
- **委托优先**:按奖励氪金数量20→15→10接取可处理的委托,优先执行委托步骤和材料补缺,再处理主线及普通牧场策略。缺少材料时使用现有扫荡/挑战来源;按委托缺口自动购买并孵化魔物蛋的联动留待后续实现。
- **地图与扫荡**:在“自动扫荡”勾选“未满星时自动挑战”,已解锁普通关卡可使用内置模拟首次挑战,无需开启自动主线;满足三个难度全部通关的条件后自动使用扫荡。普通地图直接发放探索奖励时按事件处理;当前任务占用的关卡交由自动主线处理。
- **中断恢复**:后台最长每2分钟自动核对角色与任务。模型已完成、等待时长被中断且结算从未发出的记录,在策略开启后自动续交保存的胜利结果;不重新开战或模拟。已经发出但结果不明的写请求不重发,继续核对服务器状态。
详细设置、能力限制与恢复方法见[辅助使用说明](ranch_assistant/README.md#v12-自动主线与战斗设置);阶段证据及待验收事项见[v1.2 实施与交接](analysis/V1_2_IMPLEMENTATION.md)。当前仍为开发版,尚未发布 v1.2 正式标签。
## 1.1.1 更新内容
- 顶部策略按钮改为绿色“开启”和红色“停止”,运行状态更醒目。
- 修复赠礼误用物品种类编号的问题,改用背包实例编号,并以成功响应更新好感和冷却。
- 逐只判断赠礼条件,跳过冷却目标,连续处理其他可送目标;本地倒计时到期后重新核对,不再等待整体随机刷新。
- 勾选唯一培养代表或同种资质提升保护时,在本地后台按已有快照重新计算;补齐本地策略及页面异常的调试记录。
## 1.1.0 更新重点
- 重整登录、培育室、分类背包和牧场页面,合并魔物与牧场展示,保留平铺/分组切换。
- 打通按蛋规则补货、孵化、成长同步、收取、派遣及批量喂养的流程,增加4S和同种资质提升保护。
- 增加自动赠礼与同种唯一培养代表,避免重复培养多只同种魔物。
- 统一策略自动保存及跨账号导入/导出,将监控与执行控制简化为一个策略开关。
- 完善等级、体力、账号关闭/移除和本地地图缓存;扫荡奖励与事件分别处理,新增掉落概率及体力效率分析。
- 优化双账号、大量魔物及背包库存下的刷新响应,修复表格控件、下拉框裁字、滚轮误改数值和成长资质显示等问题。
## 功能范围与数据
当前登录适配第一弹渠道;需要短信验证的登录流程尚未提供验证码界面。
自动扫荡仅用于已满足游戏原有条件的普通关卡;v1.2 的首次挑战、任务及委托战斗受所选运行时能力检查限制,未支持内容显示原因并等待处理。当前不提供手机截图配置或ADB自动战斗。
地图与可能掉落来自客户端静态配置,实际奖励以服务器响应为准;统计概率为本账号已确认样本的实测值。
“每点体力数量”按已知消耗样本的物品总量除以实际扣除体力计算,未知消耗不参与。
资料包含1178个关卡和2079种道具名称;v1.2 的独立任务资料另含1165个任务、337个NPC和4269份剧情脚本,其中4239份属于已支持的线性类别,主线引用的720份中有718份属于该类别。脚本分类数量不代表任务或战斗全部通过;30份特殊选择等脚本、4类特殊接取入口及任务1001006的抽蛋钩子仍不支持。客户端热更新与当前账号资源是否一致尚未验证。
账号凭据、策略、地图缓存、购蛋/扫荡记录及统计数据库均保存在本机 `local_state/ranch_helper/`,按账号和角色隔离。
v1.2 常规回归检查497项,493项首轮通过,4项旧界面测试补齐异步等待后复测通过;14项原AIR长时间试跑不纳入常规回归。原版适配器最终集成仍待完成,自动原版开战准入保持关闭。各组准确数量及验证条件见[实施验证记录](analysis/V1_2_IMPLEMENTATION.md#验证记录)。本地模拟结果不代表真实账号通关、服务器接受结算或全部关卡支持。本轮开发验证未执行真实游戏请求,真实账号联网验收由用户手动进行;软件在用户开启策略后,可按配置和能力检查自动执行已支持操作。
详细配置与实现范围见[辅助使用说明](ranch_assistant/README.md)。
## 项目目录与测试
- `ranch_assistant/`:原生 PySide6 界面、登录会话、手动孵蛋规则、牧场管理及测试。
- `analysis/`:接口清单、行为分析、原始反编译源码及部分审计证据。
- `tools/`:本地资料提取、接口清单生成和历史分析工具。
- `backend/`:早期的独立本地接口原型,不是辅助连接的官方服务。
运行测试:
```console
python -B -m unittest discover -s ranch_assistant/tests -v
```
原始 APK、构建包、第三方工具、签名材料、账号会话、
密码、数据库、截图和运行日志均由 `.gitignore` 排除;账户数据仍保存在本机。
## 适配版本
| 辅助版本 | 《牧羊人之心》Android 客户端版本 | 状态 |
| --- | --- | --- |
| 1.2.0.dev1(开发分支 `develop/v1.2.0`) | 1.9.68 静态资料基线 | 开发中;任务与战斗调度已实现,运行时覆盖、实际阵容桥接及完整集成 QA 待完成;未发布正式标签 |
| 1.1.1(`v1.1.1`) | 1.9.68 | 当前正式版本,1.1系列修复与界面更新 |
| 1.1.0(`v1.1.0`) | 1.9.68 | 已发布版本 |
| 1.0.0(`v1.0.0`) | 1.9.68 | 已发布版本 |
本表仅记录已经分析、测试的版本对应关系,不代表对其他客户端版本的兼容承诺。
## v1.2 开发进展
[实施与阶段交接](analysis/V1_2_IMPLEMENTATION.md)汇总当前能力、测试证据与后续验收;[方案与阶段状态](analysis/V1_2_PLAN.md)保留客户端调用链研究和实施标准。
早期[离线普攻估算工具](analysis/V1_2_OFFLINE_EXPERIMENT.md)、[原 AIR 运行实验](analysis/V1_2_RUNTIME_IMPLEMENTATION.md)和[独立实验模型](analysis/V1_2_SIMULATION_IMPLEMENTATION.md)是三条不同路径,覆盖范围分别记录。本轮真实账号的任务、开战、结算及领奖验证由用户手动进行。
## 免责声明
本项目及其文档仅用于编程学习、技术研究与交流,不构成任何使用建议、服务承诺或法律依据。项目不提供、不指导也不协助制作、传播或使用游戏修改包、外挂、绕过安全检测、规避反作弊或其他破坏性工具;请勿将本项目用于上述用途。
游戏客户端、接口或规则更新后,相关内容可能失效或不再适用;本项目不承诺兼容其他版本,也不承诺提供后续适配、更新或技术支持。
本项目与相关游戏、厂商、平台及权利方无任何隶属、授权、合作或背书关系。涉及的游戏名称、程序、素材、接口、商标及其他第三方内容,其权利归相应权利人所有。请勿未经许可复制、分发或商用相关内容;如权利方认为本项目存在不妥内容,可联系项目维护者核实处理。
使用者应自行遵守适用的法律法规、平台规则、游戏用户协议及第三方权利要求,并在合法授权范围内使用本项目。因使用、修改、分发或无法使用本项目而产生的账号异常、数据丢失、设备故障、争议、处罚或其他直接或间接损失,由行为人自行承担;在法律允许的最大范围内,项目维护者及贡献者不承担相关责任。任何第三方的行为均不代表项目维护者的立场或授权。
请勿在公开页面、提交记录或 Issue 中上传账号、密码、Token、会话密钥、签名材料、个人身份信息或其他敏感数据。本项目按“现状”提供,不保证持续维护、功能完整、兼容性或适用于任何特定目的。继续使用即表示你已阅读并理解上述内容;如不同意,请停止使用并删除相关副本。