Phase 3 玩法与内容
Phase 3 把框架从「视觉小说播放器」推进到「可玩的 ADV」：战斗、地图与探索、养成、图鉴与商店，以及最重要的扩展落点——第三方小插件可挂载的 gameplay:module@1。本阶段也是四档扩展模型第一次接受真实玩法模块的检验。
状态：实现中。
当前已落地导航外壳、主页／独立设置／剧情界面、皮肤引擎与内置默认皮肤。Battle 的 S5 与策略替换生命周期已完成验收。Extra 的 gameplay:module@1、受控挂载与卸载清理已落地，并通过签名外部插件夹具的契约与两种真实宿主验收。Explore 已完成地图逻辑与表现分离、四类热区动作、会话内道具、确定性寻路及地图与剧情往返。Growth 已完成等级与强化、显式旗标、可换公式、机制改写、存档往返与独立养成页。Collection 尚未实现；觉醒、装备、技能强化、Battle 数值交界、奖励与持久续玩不在已闭合范围内，Phase 3 出口未全部闭合。
目标与非目标
目标
- 建立战斗的宿主契约与生命周期，让战斗状态、回合推进与结算有统一入口。
- 把伤害、命中与判定等规则放进可替换的管线，允许 Mod 改写并通过审计。
- 提供地图逻辑、热区、场景点击与道具的最小闭环。
- 提供养成、图鉴、成就、任务与商店的内容登记面。
- 建立
gameplay:module@1，让第三方小插件能够独立加载、卸载，且不影响内核。 - 让外壳具备导航栈与皮肤能力，为后续玩法界面提供统一容器。
非目标
- 不实现联机战斗、排行榜与在线活动；这些属于 Phase 5。
- 不实现云存档、跨端同步与性能分级；这些属于 Phase 4。
- 不实现完整剧情编辑器与运营后台；这些属于 Phase 6。
- 不把具体玩法的数值、关卡与素材放进仓库；它们应作为数据包或资源包提供。
覆盖的大插件
| 大插件 | 本阶段职责 | 当前状态 |
|---|---|---|
| Battle | 战斗宿主、运行载荷、状态机、规则管线与机制插槽 | 实现中（S5、AUTO 与会话内序列已完成；奖励及其他玩法出口未闭合） |
| Explore | 地图逻辑、热区、场景点击、道具 | 已完成（本期地图、会话内道具与剧情导航范围；无地图存档协议） |
| Growth | 养成与强化、属性成长 | 实现中（等级与强化已落地；觉醒、装备与技能强化未实现） |
| Collection | 图鉴、成就、任务、商店 | 未实现 |
| Extra | gameplay:module@1 与第三方玩法模块范例 | 已完成（受控生命周期范围） |
| Platform | 界面实现、导航栈、皮肤与数据包默认声明 | 实现中（已接入外壳；Phase 4 平台适配未实现） |
交付内容清单
| 交付 | 大插件 | 关键接口或产物 | 状态 |
|---|---|---|---|
| 战斗运行载荷与状态机 | Battle | BattleSpec、即时／整回合 BattleAction、带显式随机状态的 BattleFrame；idle／active／ended／settled | 已完成（已有双端契约记录） |
| 战斗规则管线 | Battle | battle:disc-policy@1（默认 builtin）；一次行动提交整组校验，失败保留调用前状态 | 已完成（内置管线与 Mod 改写已核验） |
| 机制插槽载荷与校验 | Battle | 顺序必须为单位排列、目标必须为候选子集、事件保留返回顺序；插槽不直接改写 BattleFrame | 已完成（载荷与合成规则均有契约记录） |
| 终局与结算边界 | Battle | 规则产出 result 后拒绝新行动；首次结算只通知一次，重复结算返回独立同值副本 | 已完成（合成规则验证） |
| 战斗 AI 与伤害管线 | Battle | battle:ai@1、battle:damage-pipeline@1 | 实现中（AI 有内置条目；伤害管线仍为 vacant） |
| 具体战斗规则与奖励 | Battle | 默认回合推进、伤害、胜负／评价、奖励及进度写入 | 实现中（S5 规则与统计已完成；奖励及进度写入未闭合） |
| 地图与探索 | Explore | explore:maps、explore:presentations、explore:items、map:logic、core:explore、explore:map | 已完成（地图、会话内道具与剧情导航范围；两种真实宿主契约通过） |
| 等级与强化 | Growth | growth:profiles、growth:tables、growth:items、growth:stats、growth:formula@1、core:growth | 实现中（等级与强化本期范围已完成；觉醒、装备、技能强化与 Battle 数值交界未实现） |
| 图鉴、成就、任务与商店 | Collection | archive:gallery、quest:registry、vendor:shop | 未实现 |
| 玩法模块位 | Extra | gameplay:module@1 | 已完成（受控生命周期范围） |
| 第三方小插件范例 | Extra | 一个可加载、可卸载的玩法模块 | 已完成（原创签名外部插件夹具） |
| 界面导航与默认实现 | Platform／ScriptPlay | core:home、core:settings、core:story；用户选择优先于 ui:screen-defaults，再回落内置实现 | 测试中（已接入外壳） |
| 界面皮肤 | Platform／外壳 | ui:skins；设计变量、九宫格、控件属性与浅深主题；皮肤名覆盖检查 | 测试中（已接入外壳） |
| 内置默认皮肤 | 内置数据包／资源包 | 首启自动套用；明确选择不换皮后不再自动回落，选择指定皮肤可持久化 | 测试中（已有 Edge 与 Android 记录） |
出口条件
- [ ] 战斗可以从开始完整打到结算，状态与奖励可验证。
- [x] 一个由第三方提供的小插件落在
gameplay:module@1，可加载、可卸载，且不影响内核（原创签名外部插件夹具）。 - [x] 一个 Mod 可以替换伤害公式，改写经过审计并可回滚。
- [x] 战斗规则管线在替换实现后不改变生命周期契约（原创签名插件夹具，含结算、停止与卸载回落）。
- [x] 玩法模块的加载与卸载不残留注册、订阅或资源（真实 DOM 与卸载清理均通过）。
- [x] 地图可经剧本打开，热区、会话内道具、寻路、剧情往返与撤下清理均有真实实现和双端契约。
- [x] 网页与宿主两端的 Phase 3 契约测试全部通过（完整回归 1252 项通过、81 项按环境跳过；两种真实宿主各 438 项通过、2 项按条件跳过）。
Extra 生命周期、Mod 换公式、S5 完整范围、策略替换生命周期与 Explore 本期地图范围已有双端证据，Growth 的等级与强化也已完成本期验收；战斗奖励、Collection、后续养成内容与持久续玩尚未闭合，因此 Phase 3 保持「实现中」。
当前状态与证据
以下结论引用既有提交和根 README 的测试记录，不表示本轮在相同代码基线上重跑；历史框架回归不等于本轮文档站页面实测。
| 证据类型 | 位置或内容 | 结论 |
|---|---|---|
| 战斗运行载荷 | test/unit/battle-runtime.test.ts、test/contract/battle.test.ts | 既有记录覆盖种子、封装、原子回滚、终局、单次结算、快照隔离与可重放 |
| 机制插槽载荷 | test/unit/battle-mechanisms.test.ts | 最初 8 项校验用例对应全量 966 项通过、76 项跳过；后续新增输入校验及合成规则调用、事件与随机交接、失败回滚用例 |
| 界面实现与导航 | test/contract/platform.test.ts、test/ui/screen-host.test.ts、test/unit/story-screen.test.ts | 覆盖界面选择、默认回落、挂载撤销与剧情结果通知 |
| 皮肤 | test/contract/skin-pipeline.test.ts、test/ui/skin-engine.test.ts、skin-coverage.test.ts、skin-hit-area.test.ts | 覆盖真实装载链路、样式应用／撤回、皮肤名与透明可点区域 |
| 外壳操作 | 根 README 的系统 Edge 与 Android 记录 | 导航、设置、12 个内置界面覆盖检查、返回键与默认皮肤已有对应实跑记录 |
| 原生共用契约 | 见当前状态与测试 | S5、Explore、Growth、策略替换生命周期均已在两种真实宿主复跑；当前两种真实宿主各 438 项通过、2 项按条件跳过 |
| Extra 生命周期 | test/contract/extra.test.ts | 原创签名外部插件夹具覆盖登记、真实 DOM、退出通知、异常清理与卸载；Extra 的 7 项在两种真实宿主均通过 |
| Explore 地图与道具 | test/contract/explore.test.ts、explore-command.test.ts、test/ui/explore-screen.test.ts | 覆盖四类动作、机制与通知、库存扣减、寻路回落、真实图片、键盘、剧情往返和中止清理；不提供地图存档 |
| Growth 等级与强化 | test/contract/growth.test.ts、test/ui/growth-screen.test.ts | 覆盖数据表、显式旗标、公式与机制改写、存档往返、真实 DOM 与键盘；不覆盖觉醒、装备或技能强化 |
内置战斗包已能经剧本触发、完整结算并回写结果；S5 的场景、统计、AUTO 与序列均有双端及真实宿主契约记录。Explore 的地图、会话内道具与剧情导航，以及 Growth 的等级与强化均已完成本期验收。奖励范围、持久续玩、Collection 与后续养成内容仍未闭合；单项完成不代表 Phase 3 已整体完成。
尚未完成与风险
| 项目 | 说明 |
|---|---|
| 具体战斗与奖励 | S5 与策略替换生命周期已完成；奖励、进度写入与持久续玩仍未闭合，不能用统计结果代替奖励或存档。 |
| 探索持久化与后续养成 | Explore 的本期会话内范围已完成；地图与库存不自动写 Save。Growth 已完成等级与强化，觉醒、装备、技能强化及 Battle 数值交界仍须另行登记。 |
| 图鉴与商店 | Collection 尚未实现；条目登记与展示需要与导航栈一起验收。 |
| 玩法模块边界 | Extra 的受控生命周期已完成；异步工作由模块自己的作用域撤销，本期没有异步挂起协议。 |
| 界面验证边界 | 导航、独立设置与皮肤已接入；尚不能用已有界面测试代替完整玩法出口或所有原生平台验证。 |
| 范围蔓延 | 玩法内容容易把「框架能力」与「示例内容」混在一起；示例只保留最小可验证数据。 |