牧羊人之心Bot
本轮 Web 发布目标 2.0.2,源码入口为 main;原生 PySide6 桌面正式版本保留 1.2.0(v1.2.0)。两者的适配资料基线均为《牧羊人之心》Android 1.9.68。
支持多账号独立运行、牧场培养、每日事务、主线与委托推进、近似战斗模拟、探险、扫荡及本地掉落分析,能力与验证限制见下文。
运行指引
Web 2.0.2(main)
Windows 使用 Python 3.12+,在项目根目录执行:
py -3 -m venv .venv-web
.\.venv-web\Scripts\python.exe -m pip install -r ranch_web\requirements.txt
.\Start_Ranch_Web.cmd
访问 http://127.0.0.1:8765。配置管理密码后先在独立 /login 页面登录,再添加游戏账号、选择区服或恢复保存的会话;本机 loopback 未设置管理密码时可直接访问。手动选服、恢复会话及自动重登成功读取角色后,默认开启策略,自动执行已配置且已勾选的功能,可用顶部“停止”暂停;各子功能仍按原有勾选生效,不会全选。导入配置只替换规则并停止执行,下次成功登录仍会自动开启;服务重启后未成功登录时不直接执行。
Web 无需 Node/npm 或 PySide6,数据独立保存在 local_state/ranch_web。Linux Python 启动、离线演示与环境配置见 Web 运行说明;单服务 Docker、/data 持久化、子路径反代与宿主机受控更新见 Web 部署说明。
2.0.2 沿用登录成功后自动执行已勾选策略及用户手动触发在线更新。在线更新使用稳定 GitHub Release、对应正式镜像及心跳有效的宿主机受控更新器。已在 2.0.1 完成私有仓库和 GHCR 认证的部署,可在 2.0.2 发布就绪后直接通过“帮助 → 检查版本更新…”升级,无需重复初始化或替换宿主机更新器;升级完成后刷新网页以加载新版界面。操作条件见部署说明,更新结果以宿主机健康检查为准。
桌面 1.2.0
- 在 Windows 中安装 Python 3,并确保
python命令可用。 - 在项目目录执行
python -m pip install -r ranch_assistant/requirements.txt,安装 PySide6 等依赖。 - 双击项目根目录下的
Start_Ranch_Helper.cmd启动辅助。 - 在“登录”页面输入账号和密码,登录后选择区服;详细功能及配置方法见辅助使用说明。
- 登录后自动刷新状态;配置各页面的功能后,用顶部“开启 / 停止”统一控制自动操作。关闭策略后仍继续刷新。
也可以在项目目录运行 python -m ranch_assistant 启动。
首次使用可先查看各页面数据、配置规则,再开启策略;重启、恢复会话或导入配置后,策略开关默认关闭。
适配版本
| 组件与版本 | 《牧羊人之心》Android 基线 | 入口与状态 |
|---|---|---|
| Web 2.0.2 | 1.9.68 | 本轮发布目标;源码入口 main,Start_Ranch_Web.cmd / sh start-web.sh |
桌面 1.2.0(v1.2.0) |
1.9.68 | 当前桌面版本;Start_Ranch_Helper.cmd / python -m ranch_assistant |
桌面 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 | 历史已发布版本 |
本表记录适配资料基线,不代表其他客户端版本兼容或全部功能已完成实机验收。Docker 镜像以标签流水线成功结果为准,在线更新依赖对应 GitHub Release 条目;详见 部署说明。
Web 2.0.2 主要功能与分类日志
2.0.2 新增按功能查看的账号日志,页面范围与操作说明见 2.0.2 发布说明。其余功能沿用现有实现。
- 原布局与15页:沿用桌面页面顺序、账号页签、顶部玩家数值与统一启停、可调整日志区。
- 多账号与独立后台:各账号隔离并行、同账号请求串行;关闭网页或退出管理登录后,服务端继续监控及已开启的策略。
- 管理登录与子路径:独立管理登录页、HttpOnly / SameSite cookie、写请求来源校验;支持
/ranch等反代子路径,游戏凭据保存在服务端。 - 策略与数据:复用孵蛋、牧场、喂养、突破、赠礼、每日、主线、委托、探险和扫荡策略,支持自动保存、导入导出、执行计划及掉落分析。
- 分类日志:登录、每日事务、牧场、自动孵蛋、自动主线、自动赠礼、自动委托、自动探险和自动扫荡提供当前账号的日志面板,保留底部总日志与调试入口。功能面板支持文字搜索、级别筛选、独立清空显示与下载、隐藏及跟随/暂停滚动;共用同一账号日志拉取,浏览器共享缓存最多 1200 条,每面板最多显示最近 600 条。
- 分类归属与旧日志:分类随普通日志记录持久保存;孵蛋/牧场整理策略的自动喂养、出售、收取及暂停记录归入孵蛋,手动牧场操作与自动潜能突破归入牧场。无分类旧记录仅在明确前缀指向同一类别时保守推断,混合或未知记录保留为常规日志,在总日志和登录面板可见。
- 日志保存与更新:普通日志按账号限量持久保存,调试详情按进程缓存;仅检查官方稳定 2.x Release,未配置执行器时仅检查,受控安装与备份/回滚由宿主机执行,自动安装默认关闭。
连接状态区分在线、临时故障重试、游戏会话失效与未连接,显示最后成功通信及下次重试时间,旧快照标注为缓存。临时故障先停止策略,再退避执行只读探测;会话失效时停止游戏轮询,按自动重登设置等待,或手动恢复、重新登录。手动选服、恢复会话及自动重登成功后,均自动执行已勾选功能,可在顶部停止。获取区服候选或登录失败不视为成功;未确认的写操作不自动重发,页面轮询不会清除游戏连接错误。
战斗模拟仍为近似模型,特殊关卡并非全部支持。2.0.2 离线回归:后端 309 项,306 通过、3 项因 Windows 权限或符号链接限制跳过,0 失败、0 错误;完整浏览器 52 项全部通过,0 跳过、0 失败。本版验证范围见 发布说明,历史记录见 Web 验证说明;离线验证不代表真实游戏 API 或生产升级/回滚验收。
桌面 1.2.0 功能基线
| 模块 | 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分钟自动核对角色与任务。模型已完成、等待时长被中断且结算从未发出的记录,在策略开启后自动续交保存的胜利结果;不重新开战或模拟。已经发出但结果不明的写请求不重发,继续核对服务器状态。
在“自动主线 → 任务状态”点击“刷新任务 / 预览”,查看下一步和阻塞原因;到“推进策略”选择任务范围、推进战斗队伍、保留体力和交付限制,再勾选“启用自动主线策略”,用顶部绿色“开启”运行、红色“停止”暂停。规则自动保存,重启、恢复会话或导入配置后仍需手动开启。委托接取、交付和“也接取需要实战的委托”继续在“自动委托”配置。
详细设置、能力限制与恢复方法见辅助使用说明;逐项实测入口及结果模板见v1.2.0 验收清单,发布摘要见v1.2.0 Release 说明。
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/;Web 使用独立的 local_state/ranch_web/(Docker 为 /data),均按账号和角色隔离。
v1.2.0 功能基线回归为 56个模块逐模块独立进程测试,共724项通过、0项跳过;单进程运行整套Qt测试曾出现崩溃,不能表述为同进程整套测试成功。本次版本号发布14项定向测试及旧 dev1 配置兼容验证通过:正式版版本常量与导出断言已更新为1.2.0,旧 1.2.0.dev1 的 schema 1/2 配置导入兼容已验证;两组有重叠,不相加。当前桌面自动战斗固定使用内置近似模型,原 AIR 仅作离线研究,不是桌面可选运行时。历史阶段记录见实施验证记录,当前验收范围见验收清单。本地模拟结果不代表真实账号通关、服务器接受结算或全部关卡支持。本轮未调用真实游戏 API,未完成真实账号任务、开战、结算、领奖与资源消耗验收;软件在用户开启策略后,可按配置和能力检查自动执行已支持操作。
详细配置与实现范围见辅助使用说明。
项目目录与测试
ranch_assistant/:原生 PySide6 界面、登录会话、手动孵蛋规则、牧场管理及测试。ranch_web/:Web 工作台、独立账号后台、管理登录、策略与日志接口。deploy/web/:Docker 部署、宿主机受控更新与历史验证记录。analysis/:接口清单、行为分析、原始反编译源码及部分审计证据。tools/:本地资料提取、接口清单生成和历史分析工具。backend/:早期的独立本地接口原型,不是辅助连接的官方服务。
按模块独立进程复查测试,例如:
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 排除;账户数据仍保存在本机。
v1.2 实现与研究记录
实施与阶段交接与方案与阶段状态保留开发阶段的能力、测试证据和客户端调用链研究;其中版本状态与运行时方案是历史记录,正式版当前范围以本页、使用说明和验收清单为准。 早期离线普攻估算工具、原 AIR 运行实验和独立实验模型覆盖范围分别记录;原 AIR 仅用于离线研究,不是桌面可选运行时。本轮未执行真实游戏 API 验收,联网结果仍需用户实测记录。
免责声明
本项目及其文档仅用于编程学习、技术研究与交流,不构成任何使用建议、服务承诺或法律依据。项目不提供、不指导也不协助制作、传播或使用游戏修改包、外挂、绕过安全检测、规避反作弊或其他破坏性工具;请勿将本项目用于上述用途。
游戏客户端、接口或规则更新后,相关内容可能失效或不再适用;本项目不承诺兼容其他版本,也不承诺提供后续适配、更新或技术支持。
本项目与相关游戏、厂商、平台及权利方无任何隶属、授权、合作或背书关系。涉及的游戏名称、程序、素材、接口、商标及其他第三方内容,其权利归相应权利人所有。请勿未经许可复制、分发或商用相关内容;如权利方认为本项目存在不妥内容,可联系项目维护者核实处理。
使用者应自行遵守适用的法律法规、平台规则、游戏用户协议及第三方权利要求,并在合法授权范围内使用本项目。因使用、修改、分发或无法使用本项目而产生的账号异常、数据丢失、设备故障、争议、处罚或其他直接或间接损失,由行为人自行承担;在法律允许的最大范围内,项目维护者及贡献者不承担相关责任。任何第三方的行为均不代表项目维护者的立场或授权。
请勿在公开页面、提交记录或 Issue 中上传账号、密码、Token、会话密钥、签名材料、个人身份信息或其他敏感数据。本项目按“现状”提供,不保证持续维护、功能完整、兼容性或适用于任何特定目的。继续使用即表示你已阅读并理解上述内容;如不同意,请停止使用并删除相关副本。