# 项目上下文与接手说明 更新日期:2026-11-16(Asia/Shanghai)\ 源码基线:`main` / `v2.0.12` / `a9b5f73552bf87efe65b4f0d6fd878bcb14dfbc9`\ 运维命令见 [OPERATIONS.md](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 `,再正常合入远程初始 MIT 提交。后来才形成当前 main/稳定标签流程;不要重做历史重写、改全局 Git 身份或凭旧会话把远程改回 GitHub。 | ## 合作偏好与下一步 - 用户希望直接推进,避免重复询问已授权的事项;中文、简洁、先讲结论。大量重复报错时要先找根因,不靠重试或表面改文案。 - 用户希望主代理负责诊断、拆解、审查和集成,具体实现尽量委派给子代理;主代理必须独立检查代码和复现关键边界,不能照单子代理结论。 - 修改共享核心时先约定文件/函数所有权,避免多个代理覆盖;测试使用 `python -X utf8 -B`,先写可失败的确定性离线回归,再修复。 - 不要重新设计 UI、重写战斗引擎、重跑 APK 逆向或顺手做全面重构。先读当前实现和发布说明,围绕实际问题做最小修复。 - 未经新一轮明确授权,不主动部署 X99。发布正式版本后由用户通过在线更新安装;不要以本地离线测试冒充生产结果。 - 下一会话最先确认:当前 Git remotes、实际 HEAD、用户是否已升级 2.0.12,以及隐藏战斗/旧 pending 的生产反馈。若只是源码交接,不要自行制造新版本。