Files

20 KiB
Raw Permalink Blame History

项目上下文与接手说明

更新日期:2026-11-16(Asia/Shanghai)
源码基线:main / v2.0.12 / a9b5f73552bf87efe65b4f0d6fd878bcb14dfbc9
运维命令见 OPERATIONS.md。

先读这里

  • 这是《牧羊人之心》单游戏、单管理员的多账号牧场辅助。当前主产品是 Web 2.0.12;PySide6 桌面版保留在 1.2.0,不再作为新 Web 功能的主要界面。两者的游戏资料基线都是 Android 1.9.68。
  • 截至上述基线,没有待合并的开发功能分支。2.0.12 已发布源码、镜像和 Release,但用户尚未反馈升级后的生产验收;不要把“已发布”写成“现场已恢复”。
  • 项目已有大量真实账号状态、私有日志和恢复记录。新会话不得为了复现问题调用真实游戏写接口、清空 pending、重置密钥或修改用户策略。离线测试、合成 fixture 和明确授权的只读诊断优先。
  • 本地源码 remote 已迁移:Gitea 是唯一的 origin,旧 GitHub remote 仅从此工作区移除,GitHub 网站仓库未删除;在线更新链路并未迁移。本次只推 main 文档,不推 tag。详见运维文档的 Git 迁移章节。
  • 新会话先读根目录 HANDOFF.md、README.md、本文、运维文档和最新发布说明。历史记录用于理解约束,不应替代当前代码和测试。

产品目标与边界

目标是在浏览器中管理多个彼此隔离的游戏账号,让后台持续执行用户明确开启的策略;关闭网页或退出管理登录不应停止服务端任务。每个账号独立并行,同一账号内的游戏操作串行,避免账号间串数据、串日志或重复请求。

Web 保持现有管理工作台形态:账号页签、顶部玩家状态、15 个功能页、统一“开启/停止”,以及唯一的底部日志区。当前没有多管理员、多权限或接入其他游戏的计划,也没有 Node/npm 前端构建链。

“自动”有硬边界:已经发送但结果未知的写请求不能自动重放;不能为了解除阻塞伪造胜利、奖励、任务进度或服务端确认。恢复行为必须区分“本地可安全继续”“需要来源策略授权”“用户已停止”和“确实未知”。

已有能力

范围 当前行为与重要约束
登录与连接 第一弹账号密码登录、官方区服和角色选择、会话恢复。保存登录记录的账号在服务重启后自动登录;掉线按账号设置的时长重登。只有删除账号或清除登录记录取消这种恢复安排。
策略运行意愿 登录/重登成功后自动执行原有已勾选子功能,不会擅自全选功能。只有用户手动“停止”持久暂停;点击“开启”恢复。内部错误、待核对和服务重启不能把运行意愿永久清掉。
牧场基础数据 培育室坑位、蛋的分类背包、牧场/魔物、好感、资质、等级/突破/潜能、物品及锁定状态;支持搜索、排序、分组和部分手动操作。
孵蛋与补货 按蛋规则买蛋/抽蛋、孵化、成长同步、成熟收取、派遣或喂养;默认十连,可允许单抽,遵守金币保留、每日额度、库存下限和目标。空坑装填有独立的短间隔调度。
主培养与资质备用 已启用种类固定主培养 1 只、严格更优资质备用最多 1 只。主培养优先使用已养成的高等级魔物;备用只保留,不自动喂养、赠礼或突破。新备用更优时先处理旧备用;同分/更差不继续收为备用。锁定、在队、装备和委托保留等保护仍有效。
喂养、赠礼、突破 自动经验、同种突破材料、赠礼和潜能突破只作用于主培养;达到当前等级/好感/潜能条件后停止,不转喂同种备用。赠礼有冷却;突破遵守材料/委托保留量,不擅自买材料或消耗货币。
每日事务 每日签到、七日签到、累计奖励、已有 VIP 日奖、邮件附件的查看、手动领取与按勾选项自动领取。
自动委托 当前委托/每日记录分栏;合格候选跨城市按预计氪金 20→15→10 排序,并显示不可接取或回退原因。材料/蛋/击杀或成熟魔物备料复用已有收集与保护规则。领奖确认金额与静态预计奖励分开,未确认不能猜。
主线与任务 当前进行中、待接取和待领奖任务优先显示;支持部分接取、线性对话、交付、领奖、任务补链和普通地图备料。受前置、城市、资源、保护规则及战斗模型能力限制,不能声称所有主线均已支持。
探险 读取队伍状态,自动领取已完成奖励;再次出发默认关闭,按队配置地区、保留体力和成员。不花钱开队或召回,未知请求持久化且不重放。
扫荡与挑战 地区折叠、难度/星级、每日上限、保留体力和战队;未满星可走实验模拟挑战。普通关、事件和矿洞/门票资源关有不同入口;资源关单独授权并检查工具库存。队员探险中时不能静默换人入场。
数据分析 本地按账号、关卡和难度统计扫荡及事件奖励,含出现次数、数量、实测比例、95% 区间、平均每点体力数量;不需要为画图额外请求游戏服务。
策略与日志 策略自动保存、导入/导出;运行详情只进原底部日志区。切换页签只改变该区显示的账号+功能分类,不新增页内日志框或“总日志”。F5/重新进入默认收起,右上角是唯一显隐入口。

完整页面能力和桌面版差异见 README.md、ranch_assistant/README.md;不要把历史 APK 修改工具当成 Web 的正常运行依赖。

架构地图

  • ranch_assistant/:游戏协议、登录、状态快照、策略规划与执行、持久 journal、战斗模拟和桌面 UI。
    • login.py、api.py、sessions.py 处理登录、协议与会话;真实响应要经过既有解码和脱敏边界。
    • engine.py 是策略编排核心;progression.py、quests.py、sweeping.py、battles.py、management.py、market.py、gifts.py、exploration.py 等分领域实现。
    • battle_simulator.py 保留隔离运行时和逐帧研发实现;正常执行使用 battle_quick.py 的快速 HP/DPS 数值模型。
    • data/ 保存从 1.9.68 资料构建的任务、地图、战斗和收益数据;不应为通过测试手改配置来“支持”关卡。
  • ranch_web/:FastAPI/Uvicorn、账号 worker、调度、加密存储、视图 DTO、管理认证和更新客户端。
    • service.py / scheduler.py 管理账号生命周期、运行意愿、心跳、重试和恢复。
    • store.py 管持久化;views.py 组织 15 页数据;app.py 管 API、认证、CSRF/Origin、Host 和子路径。
    • static/ 是原生 HTML/CSS/ES Modules,无 Vue、React 或打包步骤。pages.js、app.js、task-logs.js 等保持现有页面和日志交互。
  • deploy/web/:Compose 启动脚本、宿主机更新器、配置示例与更新协议。
  • tools/:资料构建、离线研究、支持范围检查和 updater.pyz 构建工具。
  • analysis/:逆向资料、接口清单和历史版本发布说明。最新版本的事实以 analysis/RELEASE_2_0_12.md 为准。
  • ranch_web/tests/、ranch_assistant/tests/:离线单元/集成/浏览器测试。local_state/ 与 test-artifacts/ 是忽略目录,不属于可分源码。

部署是单容器、单 Uvicorn worker;账号并行在应用内部实现。不能让多个 worker、replica 或服务实例共享同一个 /data。

关键设计约定

用户意愿、连接状态与执行能力分开

持久化的“用户希望运行”不等于当前 worker 正在执行,也不等于游戏连接健康。内部故障可暂时挂起执行,但不能改写手动启停意愿。心跳成功也不代表角色数据在更新或策略未被 pending 阻塞;界面必须显示真实状态和具体原因。

停止策略后仍允许只读刷新;停止/代际切换必须撤销尚未发送的恢复写操作。恢复只能处理原 pending,不得顺带启动其他无关策略。

所有消耗性恢复都要有证据

战斗 journal 要保留请求阶段、原始响应、必要的原始队伍/装备/属性输入、内容摘要、执行状态和取消/停止信息。恢复时区分未发送、已确认入场、结果待提交和未知已发送写请求。相同实例和请求证据用于幂等,不靠“再试一次”判断成功。

战斗是近似模型

2.0.9 起正常入口采用快速 HP/DPS、伤害、有效血量、时间和关卡目标的估算;保留现有 client_v4_x10 伤害配置,逐帧实现仅用于研发。2.0.12 没有改战斗数学或伤害参数。离线胜利不是服务端验收,战败也不能当成“不支持”。不要擅自切回原逐帧大模拟或宣称完全复刻客户端。

保护规则和账号隔离不可绕过

主培养、严格更优备用、锁定、在队、装备、委托预留等硬保护不能为了清库存或交委托而绕过。配置导入保留用户既有启停意图,导入本身不自动开启策略,也不会把手动停止改为开启;不跨账号套用私有状态。日志、筛选、下载、运行状态和恢复记录都必须按账号隔离。

重要历史问题与修复

早期逆向与功能演进

项目最初研究 APK、接口与战斗数据,后来形成 PySide6 桌面辅助。早期伤害修改、抓包和原生 AIR 运行研究留下了工具与资料;当前 Web 不需要重新编译 APK,也不应重新展开这些耗时研究。1.x 逐步加入多账号、牧场、孵蛋、委托、扫荡、探险和数据分析;2.0.0 将现有能力迁移为 FastAPI + 原生前端和 Docker 单服务。

调度、状态与 UI

  • 快速定时器串跑全量策略:探险/突破等 1 秒级定时器曾调用完整 engine.poll,造成主线/扫荡被高频执行。修复方向是白名单化的快速动作分发,快速任务不能加速主线或地图。
  • 队伍探险仍可入场:旧检查只看魔物是否存在,没有识别 inExploreTeam / exploreTeams。现在普通扫荡、挑战、任务和委托战斗都要按整队可用性拒绝并说明原因,不能静默移除探险成员。
  • 心跳活着但策略停了:2.0.1~2.0.6 持续拆分持久运行意愿、临时故障、会话失效和自动重登。当前语义是登录后恢复已勾选策略,只有手动停止持久暂停。
  • 日志 UI 反复走偏:2.0.2 曾新增页内日志区,2.0.3 已纠正为一个原底部日志区。后续又删除设置页大段重复运行说明和“加载中”小字,加载使用居中 spinner。不要恢复总日志、页内第二日志框或自动弹日志。
  • 表单布局:2.0.6 收紧 checkbox/radio 与标签的间距,统一标签—控件关联、换行和窄屏布局。不要把说明文字重新铺得到处都是。
  • 子路径部署:生产保留 /myrzx_bot 前缀。后端使用配置的 base path 构造规范化路由、cookie 和页面元数据;前端所有 API/跳转需走统一 path helper。要防止双前缀鉴权旁路,且未登录不能加载工作台或 app.js。

牧场与委托

  • 每只新魔物都被喂养/送礼:2.0.7 将主培养与资质备用彻底分开。更优资质可以保留作转移材料,但不能取代已养成主培养自动吃资源。
  • 委托只写“不可接”:2.0.8 增加每日记录、具体原因和 20→15→10 的候选回退说明。次数耗尽、城市未解锁、资源/保护不足、暂态错误和模型限制要区分;不能为接 20 氪金委托绕过限制。
  • 委托备料不全:2.0.9 补材料、蛋/击杀及成熟魔物的采购/收集规划,先算现有库存再补缺口,并遵守金币、保护和未知写约束。城市锁定和每日额度仍需真实解锁/等待。
  • 潜能误报:修复过快照属性解释导致的 overpoten 误判。不能通过删除异常检查来放行;只有证实输入解释错误才可修正。

战斗恢复

  • 2.0.10 的待核对阻塞:2026-11-13 的现场是委托备料普通关已确认 stageStart,本地模型随后超时,旧版无法清除 pending。根因是 Linux 子进程 stdin 首次部分写入后,后续 communicate(input=None) 没有继续输入/EOF,子进程等输入直到 wall-clock timeout。
  • 2.0.11 的修复:有界输入先写入自动清理的 seekable 临时文件,再给子进程完整 stdin;之后 communicate() 不再传 input。新记录保存原始输入,允许仅重跑本地计算一次,不重发 stageStart。缺输入的精确旧技术失败按原始客户端失败退出协议记录一次;响应丢失仍不得重放。来源策略关闭显示等待授权,手动停止禁止恢复写。
  • 2.0.12 的隐藏关卡:旧扫荡拿到 stageEvent 后没有接续战斗。新记录或可完整恢复记录现在使用原响应的 stageEvent.hideStageId 构建隐藏关难度 1,不再次入场,结算也用隐藏 ID。
  • 旧现场不能凭空补全:用户当时的 0211 / 3 pending 只剩提示和 sampleId,原始响应已被 8 MB × 2 日志轮转覆盖,隐藏 ID 无法还原。仅符合精确四字段 legacy 形态、已确认入场且未结算的记录才本地归档为“未完成,已放弃”,不提交胜负或奖励。
  • 独立审查抓到的最后边界:如果旧 trace 能找回隐藏 ID,却没有 entry_snapshot 等原始输入,绝不能用当前队伍(例如后来升到 999 级)补算并结算。这种记录必须保持中文待核对、零游戏写请求。

2.0.12 验证证据与未验收部分

  • 仓库测试按测试 ID 去重共 491 项:489 通过、2 项 Windows 预期跳过、0 失败/错误;其中隐藏关卡专项 50 项、受影响引擎回归 74 项。不同阶段重复运行不能累加成新的测试数。
  • 另有 2 项 Web 离线恢复探针通过,验证恢复、启停、账号隔离和禁止重复请求,不计入上述 491 项。
  • 静态模型对两支队伍 × hd01~hd08 共 16 种配置各重复两次:13 种配置模型胜利、3 种模型失败,32 次合计约 102.646 ms,单次最长约 14.193 ms。只证明这些静态输入可复现,不证明生产通关。
  • 发布包含 GHCR 正式镜像、GitHub 稳定 Release、updater.pyz 和 SHA256 校验资产。旧 v2.0.11 发布物/refs 已有独立备份后按用户要求清理。
  • 没有在 2.0.12 验证轮中调用真实游戏 API、修改生产策略或手动部署 X99。用户那条历史隐藏战斗并未被实际打通;等待用户安装并反馈。

仍然有限或容易误判的地方

  1. 战斗是快速近似模型,特殊机制、剧情选择和部分任务类型仍可能不支持;覆盖一部分配置不等于全部主线/委托可完成。
  2. 新隐藏战斗依赖完整、可验证的原始输入。历史日志轮转后,不应从普通关 ID、难度或 sampleId 推造隐藏 ID。
  3. 本地“放弃/归档”只解除客户端持久阻塞,不代表服务端已经结算;是否值得增加只读核对必须先有明确、安全的协议证据。
  4. 委托的城市、次数、库存和保护限制不能绕过;20 氪金优先不是所有情况下都必须接 20。
  5. 生产升级、回滚和真实账号恢复仍需用户操作后观察。管理页面“已登录”本身不是验收。
  6. Git remote 改为 Gitea 不代表更新器支持 Gitea。现有代码、Actions 和发布辅助仍指向 GitHub AttilaNet/myrzx_bot Release 与 GHCR;未来迁移发布通道需单独设计、测试和更新用户文档。

历史技术索引:遇到对应问题再读

历史问题或决策 接手要点与证据入口
APK 与热更新 项目最初尝试过伤害倍率包、属性包和原生运行研究。用户曾确认后来的倍率包可用,但当前任务不是继续制作 APK;原始包、签名和构建中间产物可能已因磁盘清理删除。基础分析在 analysis/REPORT.md,不要假定旧工具所指的二进制仍在本机。
API 清单 analysis/API_INVENTORY.md 和 analysis/as3/scripts/net/pixvi/myr/net/ 是接口用途与原客户端字段的入口。界面上隐藏了地址、Token、协议密钥和请求序号,不代表协议不再需要它们。
登录区服解析 登录响应的 servers 曾包含 Fastjson $ref 重复引用,直接逐行取 id 导致 KeyError。当前 ranch_assistant/api.py 只解析受限的本数组引用并整理区服;角色信息来自 masterInfos。不要把合法 JSON 引用误当成第三、第四个区服。
“非法”登录 区服列表成功不等于角色入场成功。签名日期的原实现使用四位年份 yyyyMMdd;api.py 目前使用 %Y%m%d,保留这个修复和协议请求序号的持久化。排查时按渠道验证、区服、入场、角色读取分阶段看日志。
魔物的几种等级 普通等级/当前等级上限、同种突破 tpLevel/tpExp、潜能阶段 potentialLevel 是不同系统;同种突破最高 4 级的语义不能套到潜能阶段。低等级但尚未解锁上限的魔物不能一直吃经验,主培养到上限也不能自动转喂同种备用。
潜能材料协议 历史修复确认 monsterPotentialUpgrade 的 payload.itemId 和名字容易误解的 traceInfo.itemTypeId 都使用道具堆栈实例 ID,不是静态道具类型 ID。修改前对照 AS3 和既有突破测试。
UI 性能与表格 Qt 曾因跨表复用同一个 QTableWidgetItem 重复报警,也曾在大库存刷新后阻塞界面数秒。Web 延续后台工作线程、缓存视图与按需准备数据;不要在 GET 视图渲染里做游戏网络操作或每次全量重建所有账号。
地图与探险 地图解锁信息按角色落地缓存,库存和消耗量按新快照更新;用户手动刷新才拉完整关卡进度。探险结束应自动领奖并释放队伍;成员正在探险要阻止整个原战队入场,不是把该成员丢掉后照样提交。
反作弊研究 analysis/BATTLE_RULES.md 记录历史检查分析。当前不应删除异常记录或把不支持、战败、未知响应直接包装成胜利;修复过的潜能异常应从原始属性解释查证。
研究方案的时效性 analysis/V1_2_PLAN.md、analysis/V1_2_RUNTIME_IMPLEMENTATION.md、analysis/V1_2_SIMULATION_IMPLEMENTATION.md 是历史研究。后来的用户明确选定快速公式模型;这些旧文档不能推翻当前 battle_quick.py、battle_simulator.py 和最新发布说明。
Git 历史与身份 早期曾整理 4 个本地提交作者为 AttilaNet <zbolink@foxmail.com>,再正常合入远程初始 MIT 提交。后来才形成当前 main/稳定标签流程;不要重做历史重写、改全局 Git 身份或凭旧会话把远程改回 GitHub。

合作偏好与下一步

  • 用户希望直接推进,避免重复询问已授权的事项;中文、简洁、先讲结论。大量重复报错时要先找根因,不靠重试或表面改文案。
  • 用户希望主代理负责诊断、拆解、审查和集成,具体实现尽量委派给子代理;主代理必须独立检查代码和复现关键边界,不能照单子代理结论。
  • 修改共享核心时先约定文件/函数所有权,避免多个代理覆盖;测试使用 python -X utf8 -B,先写可失败的确定性离线回归,再修复。
  • 不要重新设计 UI、重写战斗引擎、重跑 APK 逆向或顺手做全面重构。先读当前实现和发布说明,围绕实际问题做最小修复。
  • 未经新一轮明确授权,不主动部署 X99。发布正式版本后由用户通过在线更新安装;不要以本地离线测试冒充生产结果。
  • 下一会话最先确认:当前 Git remotes、实际 HEAD、用户是否已升级 2.0.12,以及隐藏战斗/旧 pending 的生产反馈。若只是源码交接,不要自行制造新版本。