Files

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