Files
myrzx_bot/analysis/V1_2_IMPLEMENTATION.md

111 lines
18 KiB
Markdown

# v1.2 实施记录与阶段交接
状态日期:2026-11-08。开发分支:`develop/v1.2.0`。当前版本:**1.2.0.dev1**;原始资料基线:Android **1.9.68**。
任务资料、状态规划器、普通地图/任务/委托战斗编排和界面已经实现,当前进入独立 QA 与运行时集成阶段。原 AIR 已自然完成合成 1-1 离线实验,独立 Python 实验模型也已运行;任意实际阵容的原引擎输入桥接仍在完善,完整集成 QA 正在进行。当前没有全部主线、全部战斗或服务器接受结算的验证结论,也未发布 v1.2 正式标签。
用户操作见[辅助使用说明](../ranch_assistant/README.md#v12-自动主线与战斗设置)。研究依据和原验收标准见[实施方案](V1_2_PLAN.md)、[任务调用链研究](V1_2_TASK_RESEARCH.md)。本页汇总交接时已收到的阶段证据;最终集成结果尚待回填。
## 当前实施范围
| 模块 | 已实现内容 | 代码与证据 |
| --- | --- | --- |
| 完整任务与地图资料 | 独立资料包保留 1165 个任务、1178 个关卡、337 个 NPC、4269 份脚本,以及任务/地图/收集来源索引。4239 份脚本归入已支持线性类别,主线引用中为 718/720;这些是分类数量,不是任务完成率。 | [资料读取](../ranch_assistant/game_data.py)、[构建工具](../tools/build_progression_data.py)、[资料清单](../ranch_assistant/data/progression_manifest.json)、[支持范围](../ranch_assistant/data/progression_support.json) |
| 数据加载 | 任务与索引使用 `progression.json.gz`,地图战斗使用独立 `progression_battles.zip`,按所需关卡延迟读取并校验摘要。保留现有精简 `Catalog`,应用启动不解析 APK,也不一次展开全部地图战斗配置。 | [ProgressionData](../ranch_assistant/game_data.py)、[资料测试](../ranch_assistant/tests/test_progression.py) |
| 有状态任务规划 | 接取、前后剧情、本地位置、服务器步骤确认、本地收尾、领奖后继与补链分别建模;保存每个角色的检查点,防止旧快照、重复确认和跨角色状态污染。 | [ProgressionPlanner](../ranch_assistant/progression.py)、[任务研究](V1_2_TASK_RESEARCH.md) |
| 任务缺口收集 | 已识别的成年目标击杀、物品及蛋缺口可选择普通地图来源;物品可按条件选择扫荡。检查解锁、位置截获、体力、金币、道具保留和所选战斗能力,结算后重新核对真实库存/击杀。 | [规划器](../ranch_assistant/progression.py)、[引擎集成](../ranch_assistant/engine.py) |
| 委托调度 | 全量规划器负责已支持的委托步骤,既有 `QuestPolicy` 继续拥有启用、城市、接取、实战许可和交付保护。候选委托检查整份已知需求,支持日切刷新;旧委托规划器不会同时重复执行。 | [QuestPolicy](../ranch_assistant/quests.py)、[规划器](../ranch_assistant/progression.py)、[Engine](../ranch_assistant/engine.py) |
| 战斗与事件编排 | 普通地图、任务内嵌战斗、任务通关战斗分别开始和结算;地图奖励事件独立完成,隐藏战斗重新检查能力。包含战败、取消、模型时钟等待、未知结果与恢复保护。 | [BattleOrchestrator / BattleJournal](../ranch_assistant/battles.py)、[编排测试](../ranch_assistant/tests/test_battle_orchestration.py) |
| 用户界面与配置 | “自动主线”的任务状态、推进策略、模式选择和“战斗记录”已接入后台引擎。规则自动保存、按账号/角色隔离,并纳入统一策略导入/导出;顶部绿色“开启”/红色“停止”统一执行。 | [任务界面](../ranch_assistant/progression_gui.py)、[主界面](../ranch_assistant/gui.py)、[策略导入导出](../ranch_assistant/policy_io.py)、[界面测试](../ranch_assistant/tests/test_progression_gui.py) |
## 三条战斗路径
| 路径 | 当前用途和证据 | 边界 |
| --- | --- | --- |
| 早期普攻估算 | 使用简化战斗单位和有限公式做离线胜负/耗时估计,保留为研究工具。 | 不负责应用中的普通挑战或任务结算,不代表原引擎执行。见[估算实验](V1_2_OFFLINE_EXPERIMENT.md)、[估算工具](../tools/battle_estimate_v12.py)。 |
| 原始 AS3/AIR 内核 | 已通过原始 `BattlePanel` 自然完成合成阵容的 1-1 离线战斗,取得实际战场统计与原检查,样例 `cheatNum=0`。原版模式是应用默认选择。 | 已证明的范围仅限该离线样例;任意实际阵容的数据桥接、任务路线、资源匹配和广泛覆盖仍待集成验证。当前原版适配器尚未验证支持线上开战/结算,尚未验证的请求会被能力检查阻止。见[适配器](../ranch_assistant/battle_runtime.py)、[原引擎实验说明](V1_2_RUNTIME_IMPLEMENTATION.md)。 |
| 独立实验模型 | `ExperimentalBattleRuntime` 在单独 Python 进程中执行 AP、出场、移动、攻击、已知技能及自然终局,输出实际模型轨迹和统计,已经接入应用编排。 | 使用原始数值资料,仍包含机制近似与遗漏;必须显式选择实验模式,不能自动降级混入原版模式。完整集成、原引擎对拍和真实账号验证待完成。见[模型实现](../ranch_assistant/battle_simulator.py)、[机制与测试说明](V1_2_SIMULATION_IMPLEMENTATION.md)。 |
实验模型已实现技能 **3、5、7、9、38 的部分机制**,以及实际模型轨迹中的击杀、存活、AP、剩余时间、伤害与异常记录。出场、移动、攻击与技能会改变战场状态,胜负由模型运行产生;没有保证胜利、修改原始伤害或清空异常来构造结算。配置自带的缩放按其原有含义处理。
当前结构准入统计:地图战斗配置 **941/2512**,任务内嵌战斗配置 **106/199**。另有 **12 场合成阵容地图执行自然胜利**。准入数表示近似模型能接收这些配置;既不是原版机制覆盖率,也不是实际账号通关率。不能把 1178 个地图条目、各难度战斗配置数和可执行场次数混为一谈。
技术契约中,原版路线要求运行时支持且结果具备原版结算资格;实验结果始终标记 `execution_mode='experimental'`、`approximate=True`、`faithful=False`、`settlement_eligible=False`。编排仅在显式实验模式、自然完成、定位匹配、无异常且 `experimental_settlement_eligible=True` 等条件成立后,才允许进入对应的实验结算分支。该标志是本地集成条件,不证明服务器接受或原版完整校验通过。诊断、遗漏和异常随记录保存,原版样例的零检查分也不替代实际阵容验证。
## 调度与恢复约定
| 场景 | 当前路线 | 关键约束 |
| --- | --- | --- |
| 普通地图战斗 | 能力及资源预检 → `stageService/stageStart` → 事件分流 → 运行时 → 成功时 `battleService/battleEnd` → 对应战绩记录 → 刷新核对 | 当前位置关联任务时优先交给任务路线;不能直接当普通地图或扫荡。 |
| 普通地图奖励事件 | 开始响应中的已发奖励 → 本地奖励/事件记录 → 刷新 | 不运行战斗,不额外调用普通战斗结算,不把奖励事件记成战斗胜利。 |
| 任务 `battle` | `battleService/battleStart` 的任务分支 → 本步骤内嵌配置 → 实际运行 → `taskService/taskCompleteStep` 携带 `battleData` | 主线、支线与委托使用同一类任务路线;接取/交付仍受所属策略限制。 |
| 任务 `passStage` | 同一任务开始分支 → 引用地图/难度的战斗配置 → 任务步骤结算 → 已确认的本地通关/解锁收尾 | 不额外调用普通 `battleEnd`,也不用扫荡替代该任务专属战斗。 |
| 任务缺口收集 | 已识别来源 → 普通地图战斗或合规扫荡 → 刷新目标计数/库存 → 重新规划任务 | 来源任务信息只用于诊断;收集动作不能直接确认任务步骤。扫荡不提供击杀信用。 |
| 扫荡 | 既有 `SweepRunner` 处理三个难度已通关的普通关卡,奖励事件仍单独分流 | 检查特殊关卡、任务位置、开放状态、资源与队伍;逐关规则和本日次数继续由“自动扫荡”管理。 |
| 战败或自然战斗时间耗尽 | 保留实际失败结果,走对应失败/战绩路径并累计停止条件 | 不提交胜利结算或本地提前推进任务;工作进程超时、取消、未知结果另归待核对。 |
代码入口:[编排](../ranch_assistant/battles.py)、[引擎请求构建](../ranch_assistant/engine.py)、[扫荡](../ranch_assistant/sweeping.py)。客户端证据:[任务研究](V1_2_TASK_RESEARCH.md)、[地图分支](STAGES_DAILY.md)、[方案调用链](V1_2_PLAN.md#请求流程必须按战斗类型区分)。
规划器拥有任务客户端游标与普通剧情检查点。`none` 步骤也先取得服务器步骤确认,再执行后续剧情和本地收尾;不能因为没有资源需求就跳过确认。服务器使用的一基任务步骤和战斗定位中的零基步骤分别转换。领奖响应中的已接取后继与仅解锁任务分开处理,补链按已知图和条件核对,不按任务编号递增猜测后继。
同账号的请求与战斗串行,战斗计算在独立工作进程中执行。发送写请求前持久化 `BattleJournal`,任务状态和剧情检查点按账号/角色保存;战斗或任务存在未核对状态时,暂停可能改变阵容、资源的牧场、赠礼及任务等冲突写操作,其他账号独立运行。实际目录由账号工作区提供,策略导出不携带凭据、执行日志、待核对状态或服务器进度。
超时、开战后停止、结算响应未知、进程中断或未支持的隐藏事件都会保留 pending 记录。恢复后只用新取得且角色匹配的服务器快照核对;充分证据可解除阻塞并继续已保存的剧情收尾。旧通关记录、体力变化、未变化的步骤或单独的本地胜利不能证明未知请求已完成。核对过程不重放未知的接取、开战、提交、结算、领奖或战绩写请求;证据不足就继续阻塞,不能靠导入策略、重启或删除日志假装成功。
### 离线时钟与实际经过时间
独立离线模拟按模型时钟计算,可比战斗逻辑耗时更快返回,不为模拟时长休眠。实验结果声明需要真实时钟等待;应用编排从开战确认后开始计时,只补足尚未经过的战斗时长,等待可取消,取消后保留待核对状态。该等待不能证明网络结算已获服务器认可。
模型中的自然时间上限到期属于已完成的战败;工作进程墙钟超时或资源上限属于未完成执行,不携带可结算战果。原 AIR 样例仍按原生时钟运行;加速离线研究不能用于假定线上时序可省略。相关覆盖见[编排测试](../ranch_assistant/tests/test_battle_orchestration.py)和[模型测试](../ranch_assistant/tests/test_battle_simulator.py)。
## 尚不支持与待验证内容
- **剧情与入口:**30 份特殊选择等脚本(含 2 份主线引用)、4 类特殊接取入口和任务1001006第4步的 `task1` 抽蛋钩子尚不支持。活动、羁绊、未知任务类别及未验证引导按原因阻塞。线性脚本支持包含已识别的展示与布尔答案事件,不代表完整脚本解释器。具体分类见[支持清单](../ranch_assistant/data/progression_support.json)。
- **场地机制:**实验模型拒绝未支持的战斗/魔物控制器、触发器、非歼灭目标、保护/破坏单位及活动场地区域;动态控制器/技能生成目标也不是收集索引的完整来源。
- **技能和运动:**技能 3、5、7、9、38 仍是部分移植,其他技能逐项列为遗漏。直线移动、碰撞、惯性、击退、弹道、初始冷却、皮肤动作及随机流存在近似;部分装备效果与 `sunFire`、`moonHeal`、`deadBoom` 等属性机制未实现。可运行的模型仍须披露遗漏,不承诺原版胜负一致。
- **原始数值与资源事实:**资料来自原始 APK,实际阵容需完整成长、突破、潜能、装备/聚合属性、好感、升星及队伍等输入,不能用界面参考属性替代。资料摘要验证不等于线上热更新匹配;任意实际阵容的原 AIR 桥接和与原引擎相同时钟/操作/随机流的对拍仍待完成。
- **实际游戏:**本轮开发验证未执行真实游戏 API,真实账号的任务、开战、失败、结算、奖励、进度和服务器接受条件仍待用户手动验证。软件在用户开启策略后,可按配置和能力检查自动执行已支持操作;PVP、排行榜/BOSS及特殊活动不属于当前交付承诺。
## 验证记录
收尾常规回归检查 **497 项**:首轮 **493 项通过、4 项错误**;4 项均为旧界面测试在切换页面后立即访问尚未完成的后台魔物表格,补齐异步等待后,原 4 项复测全部通过。此结论来自一次全量常规运行及定向复测,并非修正后再次全量运行。常规回归不包含 **14 项原 AIR 长时间试跑**;真实游戏请求未执行。账号回归另有 **13 项通过**,86 份 Python 文件语法检查及暂存内容空白检查通过,未出现 Qt 表格所有权告警。
原版运行时已用本地缓存阵容离线完成三条战斗路线,原回调样例 `cheatNum=0`;Engine 到原版适配器的最终集成及完整装备/皮肤场景仍未验收,自动原版开战准入保持关闭。实验模式可对明确支持的配置执行,不代表全部主线可用。以下表格保留各阶段的定向验证记录,不能将各组数量相加。
以下是交接时收到的实现阶段记录,非本文编辑时重新执行的测试。测试组可能相互重叠,不相加为全量总数;常规回归结果见上文,原版运行时与真实账号集成仍待完成。
| 验证组 | 已报告证据 | 适用边界与复查入口 |
| --- | --- | --- |
| 数据与规划 | **145 项定向测试通过**;禁用 socket 后检查 **6 份本地日志中的 514 个快照,规划器异常 0 次** | 只读快照和离线规划,不证明写请求或战斗成功。[数据/规划测试](../ranch_assistant/tests/test_progression.py);不公开日志原文及账号资料。 |
| 战斗编排 | **66 项编排测试通过** | 模拟服务/运行时下的路线、资源、事件、时钟、取消、异常和恢复保护。[编排测试](../ranch_assistant/tests/test_battle_orchestration.py)。 |
| 选定集成回归 | **212 项选定回归通过** | 为实现阶段选定集合,包含重叠测试;不能视作最终全量 QA。[测试目录](../ranch_assistant/tests)。 |
| 界面定向验证 | **30 项界面目标测试通过** | 任务/记录界面、模式、配置和交互的目标验证,非真实账号实战。[任务界面测试](../ranch_assistant/tests/test_progression_gui.py)、[规则管理测试](../ranch_assistant/tests/test_rules_management.py)、[策略配置测试](../ranch_assistant/tests/test_policy_config.py)。 |
| 独立实验模型 | **38 项测试通过**;结构准入 **941/2512** 地图配置、**106/199** 任务内嵌配置;**12 场合成地图执行自然胜利** | 模型证据,不是原 AIR 对拍、全部关卡或真实账号验收。[模型测试](../ranch_assistant/tests/test_battle_simulator.py)、[模型说明](V1_2_SIMULATION_IMPLEMENTATION.md)。 |
| 原 AIR 实验 | 合成 1-1 自然完成,实际原始 `BattlePanel` 统计与检查,样例 **`cheatNum=0`** | 仅该合成离线场景;实际阵容桥接和广泛覆盖待验证。[原版适配器测试](../ranch_assistant/tests/test_battle_runtime.py)、[原引擎说明](V1_2_RUNTIME_IMPLEMENTATION.md)。 |
| 完整集成与真实账号 | 独立 QA 正在运行;原版/模型最终集成结论待回填;本轮开发验证未执行真实游戏请求 | 不能据局部结果标记全量通过、服务器接受或发布就绪。 |
从仓库根目录运行相应离线回归,使用 `-B` 避免生成字节码缓存;界面测试需要已安装的项目依赖。下列是复查命令,不表示本文已执行或这些命令对应所有历史测试组。
```console
python -B -m unittest discover -s ranch_assistant/tests -p "test_progression.py" -v
python -B -m unittest discover -s ranch_assistant/tests -p "test_battle_orchestration.py" -v
python -B -m unittest discover -s ranch_assistant/tests -p "test_progression_gui.py" -v
python -B -m unittest discover -s ranch_assistant/tests -p "test_battle_simulator.py" -v
python -B -m unittest discover -s ranch_assistant/tests -v
```
原 AIR 准备与运行涉及单独的本地运行时资源,依赖说明留在[原引擎技术文档](V1_2_RUNTIME_IMPLEMENTATION.md),不作为用户启动辅助的额外配置步骤。
## 阶段交接与后续验收
| 后续工作 | 完成判据 | 当前状态 |
| --- | --- | --- |
| 独立集成 QA | 对当前整合代码核对回归输出、失败/跳过原因、任务服务确认与本地收尾、路线分流、取消/时钟、配置和多账号隔离,记录准确命令与测试数量。 | 进行中;最终结果待回填。 |
| 原版输入桥接 | 任意受支持实际阵容快照能按原始规则构建输入,保持属性、站位、技能、检查与输出语义;能力检查只放行已验证场景。 | 完善中;合成 1-1 已证明原内核能够自然完成。 |
| 模型最终集成 | 真实模型进程在普通地图、任务 `battle`、`passStage` 和委托路线产生可追踪结果;保留近似、遗漏、异常、资格标志,并验证真实时钟等待与停止恢复。 | 编排已接入;独立集成与原引擎对拍待完成。 |
| 用户手动实际验证 | 本轮由用户操作真实账号,分别核对奖励事件、胜负、体力与物品、经验、任务/地图进度和未知响应恢复;写请求不重复。 | 尚无本阶段服务器验收结论;开发验证继续使用离线资料和模拟服务。 |
| 扩展覆盖 | 每次增加脚本、技能或控制器,都有明确支持清单、可复现轨迹与对应回归,覆盖不足继续显示原因。 | 按明确场景逐步增加,不承诺全关卡。 |
| 正式发布 | 完成最终验证与遗留问题评审,文档和版本一致。 | 验证完成前保持开发版;尚未创建稳定标签或合入main。 |
接续工作先读取各运行时的最新技术记录和独立 QA 结果,再更新本页、[方案阶段状态](V1_2_PLAN.md)及两份 README。不得沿用早期“只完成静态资料”的描述,也不能把局部原引擎成功或模型准入解释成全主线完成。保持原数值基线的离线近似实验继续推进;本轮真实账号联网验证由用户手动进行,软件在用户开启策略后可自动执行已支持操作。