Files
myrzx_bot/README.md
T
AttilaNet e26d37e9c5 revert: restore the original pre-redesign web console
Revert 688aad3, 39ac03a, c84dc36, and ff6a828 in reverse chronological order. Restore the exact tracked tree from 99aff42 while preserving history.

Validation: 29 authentication and base-path tests passed offline. All 23 prior UI browser tests ran in system Edge: 22 passed initially; the fake-login test passed on an unchanged isolated retry. Live game HTTP was blocked throughout browser validation.
2026-11-11 10:08:02 +08:00

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