Files
NESLite/todo.md
T

265 lines
45 KiB
Markdown
Raw 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.
# NESLite V1.0 待办事项
依据:[开发计划 V1.0](docs/development_plan_V1.0.md)。编制日期:2026-09-12。所有开发任务初始状态为未开始,本文不表示任何工程或实机验收已经完成。
## 1. 执行与勾选规则
1. **一个实现项交付一项可独立验证的能力或一份完整材料。** 任务通常控制在约半天至一天半;不把编码、编译、补测试分别拆成待办,也不把整个模块塞进一个实现项。阶段验收与发布材料单列,不按实现项工期衡量。
2. **编号对应开发计划。** 例如 `M2-02a`、`M2-02b` 均属于计划的 `M2-02`;后缀只拆分工作,不改变所属阶段。每项均写明阶段内前置条件、交付结果和验收级别。
3. **阶段依赖是共同前置条件。** M0 无阶段前置;M1~M9 依次依赖上一阶段门槛 G0~G8 通过,等价于计划中的累计依赖。条目内“无”仅表示没有额外的阶段内前置条件。列表顺序已按实际依赖排列,不要求父编号严格递增。
4. **完成实现项不等于阶段通过。** 实现、对应局部验收及必要文档更新完成后才能勾选实现项;阶段 G 项还需满足明确的集成/实机门槛。设备缺失时保留 G 项未勾选,不能以编译成功或模拟输入替代真实手柄验收。
5. **等待不阻止独立工作。** 前置未通过时,只能推进不依赖其结果的草稿或隔离实现;不能提交依赖未知接口的完成结论,也不能勾选依赖阶段的门槛。
6. **状态与证据只记一次。** 未勾选项默认“未开始”;进行中、待实机或失败时在条目末附状态和原因。通过后附源码提交及报告位置;阶段报告引用这些记录,不复制同一测试。尚未建立的文档路径是交付目标。
7. **范围和参数不暗改。** 保留计划的 F01~F14、M0~M9 及 0.1.x~1.0.0 路线。新需求另列后续版本;快进倍率、存档周期等计划允许校准的参数,在指定阶段形成记录并同步两份文档。
8. **未定参数也有明确交付要求。** 计划未给数值的 ROM/存档包大小上限、轴阈值、连发频率、缓冲/日志容量,由对应实现项确定并记录数值、单位、默认值及超限行为;配置、文档和验收一致后才算完成,不用“适当”“合理”等词代替实际参数。
## 2. 分级验收与重跑规则
### 2.1 验收等级
等级表示验证范围,不是每项任务必须从 L0 到 L4 全部重跑。高等级可直接引用仍有效的低等级结果。每项中的完成标准定义最小必要行为;只有失败、未知影响或下表所列变更才扩大范围。
| 等级 | 使用场景 | 要做的验证 | 不自动包含 |
| --- | --- | --- | --- |
| L0 文档/材料检查 | 文档、清单、版本说明或材料整理 | 核对内容、编号、链接、版本与文件对应关系 | 编译、运行、游戏回归 |
| L1 局部验证 | 单一逻辑、构建配置、解析器或映射规则 | 受影响目标的编译/静态检查;用最少的正常和必要边界用例验证本项行为 | 全部单元测试、整应用实机流程、耐久测试 |
| L2 模块集成 | JNI、设备、文件系统、UI 或两个模块交接 | 受影响模块及直接相邻接口;一个代表样本的正常流程,加本次涉及的失败/取消分支 | 全 ROM 集、30 分钟运行、100 次存读档、20 轮循环 |
| L3 阶段验收 | G1~G7 的阶段出口;G0 为构建基线检查 | 本阶段新增能力的连贯路径,以及分配到该阶段的专项指标 | 其他已通过阶段的全部测试、发布全量回归 |
| L4 发布验收 | M8 的候选发布版与 G8 | 核对 F01~F14,执行冻结的兼容集和候选包关键流程,补齐缺失/失效的专项证据 | 不分影响地重复所有历史用例、设备和长测 |
纯文案或排版改动用 L0;布局和焦点改动用对应页面的 L2;不为低影响改动编写仅重复实现的测试。新增或修复有状态逻辑时优先增加可复现行为测试,避免每个页面各写一套相同底层测试。
### 2.2 改动到验证范围的映射
本表的“重跑”针对已经实现并验收过的能力。首次开发按当前任务的 L1/L2 验证,完整 H 项到指定节点执行,不提前要求测试尚未实现的后续功能。同一轮连续修改先用局部验证排错,修改稳定后在阶段/发布门槛统一执行所需专项;不为每个函数或每次提交各跑一次长测。
| 改动 | 默认选择 | 扩大范围的条件 |
| --- | --- | --- |
| 文档、注释、无运行影响的说明 | L0 | 文档同时变更了产品行为时,转入对应实现项验收 |
| 游戏库/设置界面 | 对应 L1 或 L2;只跑改动页面和直接调用链 | 触及共享焦点、输入分发或会话控制时,补对应模块路径 |
| 映射、死区、来源合成、连发 | 输入 L1+改动链的 L2 | 改变断柄清理或设备识别时重跑 H-HOT;改变采样链时重跑 H-INPUT |
| 音频缓冲、重采样、时钟、快进 | 音频/时钟 L1+切换 L2 | 时钟或持续流行为变更,重跑完整 H-AV 及对应模式切换;不自动重跑游戏库或存档包测试 |
| 存档格式、提交/备份/恢复、序列化逻辑 | 存档 L1+集成 L2 | 重跑完整 H-SAVE;触及升级兼容时补 H-UPGRADE;槽位文案改动不触发 100 次循环 |
| 生命周期、Surface/音频重建、异步退出 | 受影响转换的 L2 | 改变后台/锁屏恢复时重跑 H-LIFE;改变资源释放或产生内存疑点时重跑 H-LONG |
| FCEUmm 提交、内核编译选项、libretro 宿主行为 | 内核对应完整集:冻结 ROM 集、H-AV、H-SAVE 和内核控制路径 | 改动涉及原生打包则补 H-NATIVE;影响无法界定时进入 L4 |
| 工具链、ABI、链接/原生依赖、APK 打包 | 受影响构建+H-NATIVE+实际包短路径 | 若改变运行库/优化行为,补受影响音频、状态或长时指标;仅重新签名不自动重跑 2 小时测试 |
| RC 后缺陷修复 | 复现用例、受影响模块及实际新包短路径 | 多模块影响无法界定或出现广泛回归时重跑 L4 |
**停止规则:** 本次选定范围通过且没有新增失败、未解释的统计异常或影响疑点,就结束验证并继续下一项;不以“再保险”为理由重复同一范围。
### 2.3 专项验收只在指定节点执行
H 编号是可复用的验收记录,不是额外实现任务。L1/L2 用例覆盖到同一场景时可合并执行;同一长时间会话可同时采集速度、音频、内存等指标。使用同一结果覆盖多个指标时,必须满足各自样本、时长和环境要求。
| 专项 | 首次完整执行节点 | 固定口径 |
| --- | --- | --- |
| H-AV 音画与速度 | G3 | NTSC、PAL 各连续至少 30 分钟;每个连续 60 秒窗口和全程速度均为 99.5%~100.5%;以实际模拟时间/有效单调时间计算,排除加载、暂停、快进。预热后的正常前台段欠载目标为 0,无持续爆音及累积偏移;模式/设备切换另做短路径 |
| H-HOT 插拔 | G4 | 目标手机+X5 Lite,20 轮按住方向及 A/B 时断开再重连;每轮确认暂停、状态清空、配置匹配和用户继续后输入正常 |
| H-SAVE 存档 | G5 | 同一锁定内核完成总计 100 次手动存读档循环,10 个槽各 10 次,每次对照预定状态和校验值确认恢复;同时安排自动恢复点轮换、电池存档重载、导出再导入的必要分支验证,不对每种类型再各做 100 次。截断、校验错、哈希/版本错、空间不足以及临时写入/替换前/替换后终止各覆盖对应失败路径,有效提交和备份保持可恢复 |
| H-LIFE 后台/锁屏 | G7 | 后台切换 20 轮、锁屏/解锁 20 轮;无后台声音、黑屏或残留键。Surface/Activity 重建、音频路由变化及异常启动另按不同状态转换覆盖,不再各做 20 轮 |
| H-LONG 长时稳定性 | M8-02a | 至少两个代表样本,分别覆盖动作/滚屏与电池存档,每个 2 小时;无崩溃、ANR 或持续内存增长;每分钟记录 Java/native 内存和 PSS,检查预热后趋势 |
| H-INPUT 软件输入延迟 | M8-02b | 正常负载下至少 1,000 次事件,以同一单调时间域记录应用接收到首次内核采样;P95 ≤ 1 个实际模拟帧,排除暂停/绑定界面,不作为按键到屏幕总延迟 |
| H-NATIVE 原生兼容 | M8-03a、M8-03b 合并记录 | 最终包的每个原生库通过 ELF 和 APK 16 KB 对齐检查;4 KB/16 KB 环境均完成加载、运行、声音和保存恢复。记录实际 ABI/页大小,x86_64 运行不替代 arm64 发布库检查 |
| H-UPGRADE 安装升级 | M8-04a | 新安装和至少一个旧测试版本的同 ID/同签名覆盖升级;ROM 关联、收藏、设置、游戏存档均保留,即时存档按兼容策略恢复或保留并提示 |
H-SAVE 的故障注入按不同失败路径选择代表样本;共用同一提交器的所有槽位不重复相同故障矩阵。需要触发自动周期时使用可控测试时钟验证状态转换,不靠重复等待增加测试时长;周期对真实帧时间的影响另在 M5 实测。
**证据复用条件:** 报告必须标明源码/内核提交、相关模块及依赖配置、设备系统、ROM 哈希、参数、结果和日志。M8 逐项记录自该报告后有哪些改动、为什么未影响该指标;模块、配置或环境已变或无法证明未受影响时,重跑对应 H 项。不能仅因“以前通过”就复用,也不能为每个新提交自动使全部证据失效。
**发布全量的含义:** G8 必须覆盖计划全部发布要求;冻结兼容集与候选包关键路径在 RC 上执行,长测和计数型测试可引用符合上述条件的证据。M9 的最终包必须再做一次短路径,但相同代码和配置的签名/版本元数据变化不自动触发全部长测。
## 3. 全程保持一致的行为约定
| 主题 | 固定约定 |
| --- | --- |
| 工程 | NESLite;单 `app`、Kotlin+原生 View;minSdk 28,compileSdk/targetSdk 36;AGP 8.13.2、Gradle 8.13、JDK 17;NDK r28 起选精确版本;发布 arm64-v8a |
| 内核与线程 | 固定 FCEUmm;单 ROM、单实例、玩家一;改变内核状态的操作全部在模拟线程;音频回调不执行内核或阻塞 I/O |
| 导入与身份 | 只导入 `.nes`;识别 iNES/NES 2.0;完整文件字节 SHA-256 作为身份;内部正式 ROM 位于 files 而非 cache |
| 显示与时钟 | 默认 4:3、最近邻;原始像素整数缩放独立;模拟速度读取内核时序,与手机刷新率解耦 |
| 快进 | M3 引擎支持、M4 绑定 RB、M6 提供设置;初始按住 2 倍且静音,松开/失焦/暂停/断柄取消;最终倍率在 G3 冻结 |
| 输入 | A/B 对应 NES A/B,X/Y 对应 A/B 连发,菜单/视图为 Start/Select,右摇杆按下为暂停菜单;键码来自 M1 实测;不占用视图+菜单长按;快读档不默认绑定易误触单键 |
| 存档阶段 | M2 只交付基础电池存档;M5 才承诺完整备份、即时存档和故障恢复;M4 不验收尚未实现的存档导航 |
| 存档规则 | 手动 10 槽、自动最近 3 份;变化电池存档初始每 10 秒提交、自动恢复点初始每 60 秒生成,M5 按实测冻结;暂停/退出补充提交;成功落盘才显示保存成功 |
| 读档与恢复 | 读档先备份当前状态及游戏存档;失败回滚,回滚失败安全重载;不同内核提交默认不自动读入;回前台/重连后由用户继续 |
| 游戏库 | M2 最小列表、M4 焦点导航、M6 完整列表;从列表移除只隐藏并保留存档,再导入同哈希恢复关联 |
| 后台与范围 | 后台不继续模拟;V1.0 不含联网、云存档、FDS、第二手柄完整体验、回溯、run-ahead 或切换内核;不增加商店上架工作 |
## 4. 实现待办与阶段门槛
条目中的 **前置** 仅列阶段内依赖;共同阶段依赖见第 1 节。**完成** 同时限定交付内容和可观察结果。所有任务保留计划原父编号,便于回填进度。
G1~G8 的共同交付物为对应阶段 APK、源码提交、构建说明、验收记录和已知问题清单。构建说明等未变化时引用现有文件及版本即可,不另写重复副本;以下 G 项只补充各阶段特有的材料。
### M0:工程准备
- [x] **M0-02a 锁定本机构建环境**。前置:无。完成:核对 JDK/SDK/NDK/CMake,记录精确版本、安装位置和缺口;形成工具链及应用依赖版本清单。验收:L1,工具可调用且版本符合计划,清单无动态版本。证据:`docs/toolchain.md`、`docs/reports/m0-baseline.md`;Gradle 构建和原生链均已实际调用。
- [x] **M0-01a 建立可构建的应用骨架**。前置:M0-02a。完成:初始化 Git、Wrapper、单 app、Kotlin/View 页面、CMake 和 JNI 空入口,将锁定版本写入工程配置,生成 arm64 调试 APK。验收:L1,目标构建成功且 APK 包含预期原生库。证据:`app/build/outputs/apk/debug/app-debug.apk`;确认包含 `lib/arm64-v8a/libneslite_jni.so`。
- [x] **M0-01b 固定应用与数据身份**。前置:M0-01a。完成:确定显示名、applicationId、版本号/versionCode 规则、长期测试与发布签名延续策略;在需求文档登记数据目录约定。验收:L0+受影响配置的 L1,构建配置与记录相符。证据:`docs/identity.md`;APK 为 `org.neslite.app.debug`、`0.0.1-dev-debug`、min/target SDK 28/36。
- [x] **M0-03a 固定上游来源**。前置:M0-01a。完成:登记 FCEUmm 完整提交、libretro 头文件及 Oboe 固定版本,建立依赖获取方式和本地补丁清单。验收:L1,按记录可取得对应源码;此项不要求内核已编译。证据:`third_party/manifest.json`;三个固定提交已由 `tools/fetch-third-party.ps1` 检出。
- [x] **M0-03b 建立许可证清单**。前置:M0-03a。完成:逐项记录依赖来源、版本、许可证和待交付材料,建立 LICENSE/THIRD_PARTY_NOTICES 基线。验收:L0,已引入依赖无遗漏、记录与选定源码一致。证据:`LICENSE`、`THIRD_PARTY_NOTICES.md`、`docs/dependencies.md`。
- [x] **M0-02b 编写可复现构建说明**。前置:M0-01b、M0-03a。完成:docs/build.md 记录从检出到 APK 的步骤、精确工具版本、ABI 和依赖获取;不依赖手工复制未知库。验收:L0;干净检出实际构建统一放在 G0,不在此重复。证据:`docs/build.md`;调试 APK 已构建。
- [x] **M0-04a 建立需求与验收资源表**。前置:M0-01b。完成:docs/requirements.md 映射 F01~F14;列出设备待测参数和 ROM 来源/哈希/区域/Mapper/存档类型;登记 M2 至少 3 个样本的获取安排,其中一个有电池存档。验收:L0,已取得样本有使用依据,未齐资源列明缺口和取得办法,G2 前须齐备。证据:`docs/requirements.md`、`docs/reports/rom-inventory.md`。
- [x] **M0-04b 建立按范围执行的检查入口**。前置:M0-01a、M0-04a。完成:本地入口可选择构建、局部测试、模块集成和阶段检查;原生测试接入可运行目标;docs/acceptance.md 和报告模板使用 L/H 编号。验收:L1,执行一个最小目标可获得结果,默认命令不启动全部耐久测试。证据:`tools/check.ps1`;固定 CTest 的原生 smoke target 通过。
- [x] **G0 工程门槛**。前置:本阶段全部实现项。验收:L3 构建基线;从干净检出按说明构建调试 APK 一次,核对依赖可追溯、无未知库;记录资源缺口与取得办法。此处不要求产品级界面或实机运行报告。证据:提交 `8fde6e1c8854930298135ab1ba3199ecc54e89d7` 的干净克隆执行 `tools/check.ps1 -Scope Stage`,APK 构建、原生 smoke 与 Kotlin 单测全部通过;详见 `docs/reports/m0-baseline.md`。
### M1/0.1.x:设备与手柄诊断
- [ ] **M1-01a 完成安装和 JNI 自检**。前置:无。完成:诊断页展示原生调用结果与库加载错误;应用可在目标手机启动。验收:L2,一次安装启动和一次 JNI 调用成功,错误可定位。状态:诊断页和 JNI 页大小入口已实现、APK 已构建;ADB 无已授权设备,待目标手机安装启动验证。
- [ ] **M1-01b 展示真实设备基线**。前置:M1-01a。完成:读取机型、系统 API、ABI、页大小、屏幕尺寸和可用刷新率;未知值明确标记。验收:L2,与设备可读取信息核对,不按 MagicOS 名称推断硬件。状态:读取与 JSON 字段已实现,待目标手机实值核对。
- [ ] **M1-02a 枚举控制器能力**。前置:M1-01a。完成:展示名称、描述符、厂商/产品标识、输入源和轴范围;连接/移除时更新列表。验收:L2,一次接入和移除可观察,设备临时编号不作持久身份。状态:监听和展示已实现,以独立 sessionId 区分重连;待 X5 Lite 接入/移除验证。
- [ ] **M1-03a 建立实时按钮状态页**。前置:M1-02a。完成:显示 KeyEvent 按下/松开及组合状态,保留事件时间与来源。验收:L2,方向和 A/B 可同时按下,全部松开后状态清零。状态:组合状态与事件字段已实现并通过逻辑测试,待真实方向+A/B 路径。
- [ ] **M1-03b 展示轴与重复上报**。前置:M1-03a。完成:展示 HAT、摇杆、扳机值,能辨认同一操作的按键/轴两种上报。验收:L2,各实际可用轴的往返变化可观察,未上报的能力不伪造。状态:按设备实际 motionRanges 展示和采样已实现,待真实轴往返验证。
- [x] **M1-03c 记录可回放输入序列**。前置:M1-03b。完成:按统一事件结构保存来源、时间、动作和值,记录有界;提供供后续逻辑测试读取的格式。验收:L1,一段组合输入记录读取后事件顺序和数值一致。证据:`InputDiagnosticsTest` 验证 512 条上限策略,以及 key/axis/key-up 序列 JSON 往返后顺序和值完全一致;详见 `docs/reports/m1-diagnostics.md`。
- [ ] **M1-04a 清理异常输入状态**。前置:M1-03b。完成:失焦、设备移除时清空相应状态;重连创建新的会话关联。验收:L2,按住后拔出、失焦、重连各一条代表路径无残留;此时不做 20 轮插拔。状态:清理与新会话逻辑已实现并通过自动测试,待真实拔出/失焦/重连路径。
- [ ] **M1-04b 导出诊断和实测键位表**。前置:M1-01b、M1-03c、M1-04a。完成:通过系统选择器导出设备与事件 JSON,写入 docs/controller-x5lite.md,记录安卓模式、硬件连发状态和厂商保留组合。验收:L2,导出可读且键位表对应实测事件。状态:系统选择器导出和待填键位表已完成,待真实 JSON 与键位回填。
- [ ] **G1 诊断门槛**。前置:本阶段全部实现项。验收:L3;在真实目标手机和 X5 Lite 完成“连接 → 组合输入 → 松开 → 按住拔出 → 重连”一次连贯检查,可复用本阶段有效实机记录。交付 0.1.x APK、源码提交、构建说明、设备 JSON、键位表和未覆盖项;重估后续工期。状态:0.1.3 诊断 APK 与自动测试已完成;ADB 未检测到设备,等待目标手机和 X5 Lite 实机验收,详见 `docs/reports/m1-diagnostics.md`。
### M2/0.2.x:内核、画面与基础操作
状态(2026-09-12):以下项目的隔离实现已进入 `0.2.4-debug`,本地构建和单元测试通过,详见
`docs/reports/m2-foundation.md`。依照本文件的阶段门规则,G1 尚未通过且没有目标手机/3 个合法
ROM 样本,因此所有需要 L2/L3 的 M2 项和 G2 继续保持未勾选,不以桌面测试替代实机验收。
- [ ] **M2-01a 编译固定内核**。前置:无。完成:FCEUmm 链接到原生宿主,记录构建选项/补丁并冻结实际编译通过的提交。验收:L1,arm64 目标链接成功、导出入口与 API 版本可检查。
- [ ] **M2-04a 建立单线程会话执行器**。前置:M2-01a。完成:单内核线程、有界命令队列、会话编号及 Idle/Loading/Paused/Running/Pausing/Stopping/Error 状态;定义命令完成通知。验收:L1,状态转换和重复/迟到命令用最小序列验证,旧会话不能被重新激活。
- [ ] **M2-01b 实现环境协商**。前置:M2-04a。完成:按内核要求注册回调、目录、配置和玩家一设备;不支持请求返回失败,必要能力缺失阻止加载;形成支持清单。验收:L1,支持、不支持和缺少必要能力各验证一条不同分支。
- [ ] **M2-01c 接通内核生命周期与 AV 信息**。前置:M2-01b。完成:在模拟线程初始化、加载、读取时序、运行、卸载和销毁;正确消费音频回调但暂不发声,使用单调时钟控制速度。验收:L2,由测试入口提供已准备的样本路径,验证加载、卸载及失败后重载;不依赖尚未完成的导入 UI。
- [ ] **M2-02a 实现 ROM 流式导入**。前置:M2-04a。完成:SAF 读取、大小上限、iNES/NES 2.0 头校验、内部临时副本和完整文件 SHA-256;取消/读取失败清理临时文件。验收:L1+SAF 的 L2,正常头、损坏头、中文文件名和取消覆盖不同路径。
- [ ] **M2-02b 提交内部文件与最小游戏索引**。前置:M2-02a。完成:正式 ROM 存在 files,Room 以哈希关联;重复内容去重、同名不同内容分开;最小列表能选择加载。验收:L2,两种重复场景不串档,content URI 不被当作原生路径。
- [ ] **M2-02c 恢复导入中断的不一致数据**。前置:M2-02b。完成:启动时核对临时/未登记文件和缺失文件记录,提供恢复或明确失败状态,不误删有效数据。验收:L2,在文件提交后数据库登记前中断、正式文件缺失各注入一次。
- [ ] **M2-03a 实现原生视频缓冲交接**。前置:M2-01c。完成:处理协商像素格式、宽高、pitch、重复帧和有界缓冲所有权,不保存失效指针。验收:L1,选择覆盖非紧密行跨度、重复帧和缓冲切换的最小输入集。
- [ ] **M2-03b 显示保持比例的游戏画面**。前置:M2-03a。完成:GL 线程显示最新完整帧,默认 4:3/最近邻,支持原始像素整数缩放;丢显示帧不跳模拟帧。验收:L2,一个样本切换两种缩放,比例和缓冲复用正确。
- [ ] **M2-04b 将基础手柄快照送入内核**。前置:M2-01c、M2-03b。完成:使用 M1 实测键码映射方向、A/B、Start/Select,按状态采样,跨 JNI 不逐帧搬图像。验收:L2,代表游戏可组合操作且松开生效;自定义映射留给 M4。
- [ ] **M2-04c 接通控制命令和基础生命周期**。前置:M2-04b、M2-02b。完成:UI 通过队列启动/暂停/继续/重置/退出;后台、锁屏、失焦、断柄及 Surface 丢失暂停清理;重建只重接会话;前台资源就绪后由用户继续。验收:L2,正常控制流程和相关状态转换各覆盖一次,不做 20 轮循环。
- [ ] **M2-04d 读取并提交基础电池存档**。前置:M2-04c。完成:按 ROM 哈希读取保存内存,在模拟线程取快照、文件线程写入;暂停/正常退出提交;成功写入后报告成功。验收:L2,一个电池存档样本退出再载入保留进度,另一个 ROM 不共享文件;不声明 M5 的完整故障保证。
- [ ] **G2 基础运行门槛**。前置:本阶段全部实现项。验收:L3;至少 3 个合法样本运行,其中一个支持电池存档;代表样本完成“加载 → 运行 → 暂停 → 继续 → 重置 → 退出 → 重载”,电池进度可恢复,损坏导入不影响现有数据。复用同轮样本检查,不对每个样本重复全部生命周期;交付 0.2.x APK、内核记录、docs/architecture.md 和兼容结果。
### M3/0.3.x:音频、时钟与快进
状态(2026-09-12):以下项目的隔离实现已进入 `0.3.4-debug`,Oboe arm64 链接、原生边界测试、
JVM 测试和 lint 通过,详见 `docs/reports/m3-audio.md`。依照阶段门规则,G1/G2 尚未通过且没有
目标手机/ROM,因此音频设备、焦点、路由、NTSC/PAL 速度及 H-AV 仍不能形成 L2/L3 证据;M3/G3
继续保持未勾选。
- [ ] **M3-01a 打开并管理 Oboe 流**。前置:无。完成:请求低延迟输出,检查实际参数,失败时按能力回退,停止时释放流。验收:L2,一次成功输出和一次受控回退,错误不导致内核无限运行。
- [ ] **M3-01b 接入有界音频环形缓冲**。前置:M3-01a。完成:生产/消费解耦、欠载补静音和计数;回调使用预分配内存,不阻塞或做文件操作。验收:L1,环绕、空/满边界各覆盖,运行时确认回调只消费数据。
- [ ] **M3-02a 完成采样率与格式适配**。前置:M3-01b。完成:按内核和设备实际采样率重采样,完成声道/格式转换,跨批次保持连续。验收:L1,不同采样率代表输入输出长度与连续性正确;无需枚举所有可能采样率。
- [ ] **M3-02b 展示音频诊断参数**。前置:M3-02a。完成:记录内核/设备采样率、回调帧数、缓冲水位、欠载及重建次数,诊断采集有界。验收:L2,实际流参数与展示一致,欠载注入使对应计数变化。
- [ ] **M3-03a 实现正常运行调度**。前置:M3-02a。完成:以单调时钟、内核时序和音频消费/水位调节推进;显示独立,无音频时切换时钟策略;静音不改变速度。验收:L1+L2,正常、无音频及静音各短路径,无挂起或失控追帧。
- [ ] **M3-03b 采集速度与帧时间指标**。前置:M3-03a、M3-02b。完成:按实际时序累计模拟时间,分离加载/暂停/快进时间,输出窗口统计和帧时间记录。验收:L1,受控时间序列的计数和排除区间正确;30 分钟测量留给 G3。
- [ ] **M3-04a 接入音量与静音控制**。前置:M3-03a。完成:UI 命令调整增益/静音,暂停停止输出,恢复不播放旧缓冲。验收:L2,一次音量、静音、暂停与恢复的组合路径,声音和速度符合状态。
- [ ] **M3-04b 处理音频焦点变化**。前置:M3-04a。完成:失去焦点按策略暂停、清理输入并停止声音;重新获得焦点不自行继续游戏。验收:L2,一次失去/恢复焦点及退出竞态,旧会话无回调复活。
- [ ] **M3-04c 重建音频设备输出**。前置:M3-04b。完成:路由/流断开后释放并重开,重新读取参数,清空旧音频并重建时间基线,失败时可留在安全暂停状态。验收:L2,可用路由切换和一次受控重开失败后可恢复。
- [ ] **M3-04d 实现按住快进模式**。前置:M3-03b、M3-04c。完成:支持初始 2 倍静音快进;释放、暂停、失焦、断柄和退出均取消,恢复正常时重建音频与时钟基线。验收:L1+L2,以控制命令验证切换;正式 RB 绑定在 M4,不作为本项前置。
- [ ] **G3 可玩音画门槛**。前置:本阶段全部实现项。验收:L3+H-AV;同一批 NTSC/PAL 会话同时记录速度、声音、水位和帧时间,再做受影响模式/路由的短切换。冻结实测可用快进倍率,交付 0.3.x APK 及性能基线;重估剩余工期。
### M4/0.4.x:完整手柄操作
状态(2026-09-12):以下项目的隔离实现已进入 `0.4.4-debug`,通用映射、自定义绑定、来源合成、
死区、模拟时间连发、暂停/快进边沿、焦点导航和 DataStore 档案已实现,详见
`docs/reports/m4-controller.md`。用户照片已确认 X5 Lite 物理布局,但不能替代 Android VID/PID、
descriptor 和事件实测;G1~G3 尚未通过且无目标手机/ROM,因此 M4/G4 继续保持未勾选。
- [ ] **M4-01a 建立默认与通用映射**。前置:无。完成:把 M1 档案转为 X5 Lite 默认配置,标准 Android 手柄使用通用映射;支持 A/B 交换并保留厂商组合。验收:L1,档案匹配和默认动作正确;未知设备不套用错误专属配置。
- [ ] **M4-01b 实现自定义绑定页面**。前置:M4-01a。完成:捕获待绑定输入、提示冲突、保存或取消、恢复默认;菜单始终保留可达入口。验收:L2,一个绑定、冲突、取消和恢复流程可完成,退出绑定模式不残留按键。
- [ ] **M4-02a 合成独立来源并去重**。前置:M4-01a。完成:分别维护设备/轴/按键/触屏来源状态;相同动作重复上报不会重复触发菜单,释放一个来源不清除其他来源。验收:L1,用覆盖双来源按住/释放和轴键重复的最小事件序列;此阶段触屏来源可用测试输入。
- [ ] **M4-02b 实现死区和方向规则**。前置:M4-02a。完成:轴按下/释放使用不同阈值,支持死区设置;左右或上下冲突时相应方向归零。验收:L1,阈值边界往返和相反方向序列结果确定,无边界抖动。
- [ ] **M4-03a 实现 A/B 软件连发**。前置:M4-02b。完成:X/Y 对应 A/B 连发,周期按模拟时间推进,退出运行状态清理连发。验收:L1+L2,NTSC/PAL 时间口径一致;关闭硬件连发验证软件行为,再记录硬件连发单独表现。
- [ ] **M4-03b 绑定暂停与快进动作**。前置:M4-01b、M4-03a。完成:右摇杆按下切换暂停菜单,RB 控制快进;单次命令按边沿触发,菜单键/视图键仍为 Start/Select,默认无易误触快速读档键。验收:L2,长按不重复开关菜单,RB 松开和断柄均结束快进。
- [ ] **M4-04a 接通列表与菜单焦点导航**。前置:M4-03b。完成:最小游戏列表、暂停菜单和已存在设置页可用手柄移动、确认和返回;焦点不丢失。验收:L2,仅用手柄启动、暂停、继续、重置和退出;本项不要求尚未实现的存档 UI。
- [ ] **M4-04b 持久化并恢复控制器档案**。前置:M4-01b、M4-04a。完成:DataStore 保存映射/死区等配置,以设备特征匹配,临时 deviceId 只在当前连接使用。验收:L2,一次重启和一次重连恢复配置,设备变号后仍正确关联。
- [ ] **G4 手柄门槛**。前置:本阶段全部实现项。验收:L3+H-HOT;引用输入回放结果,执行 20 轮真实插拔及全手柄运行路径,记录残留键/重复动作数为 0。交付 0.4.x APK、配置和操作说明;存档选择/读档导航延至 G5。
### M5/0.5.x:可靠存档与恢复
- [ ] **M5-01a 建立统一安全提交器**。前置:无。完成:不可变快照按 ROM 串行写入,同目录临时文件、刷新、校验、原子替换和有效备份;旧任务不能覆盖新版本。验收:L1+L2,一次提交、替换失败和乱序任务验证;完整故障矩阵集中在 G5。
- [ ] **M5-01b 完善电池存档提交策略**。前置:M5-01a。完成:检测内容变化,按初始 10 秒周期及暂停/退出请求提交;无变化不重复写,成功落盘才通知成功。验收:L1+L2,可控时钟覆盖周期和无变化分支,实机测一次保存前后帧时间以冻结周期。
- [ ] **M5-02a 定义并实现即时存档封装**。前置:M5-01a。完成:保存 ROM 哈希、内核名称/提交、格式版本、配置、时间、长度和校验值;在模拟线程帧边界序列化。验收:L1,封装往返和长度/校验异常可识别;更新 docs/save-format.md。
- [ ] **M5-02b 实现 10 槽和缩略图快照**。前置:M5-02a。完成:10 个固定手动槽记录时间/缩略图,内容与元数据关联一致;覆盖使用安全提交器;暂停菜单提供基本槽位入口。验收:L2,首次保存和覆盖一个槽位结果正确,失败不显示新存档成功。
- [ ] **M5-03a 实现自动恢复点轮换**。前置:M5-02b、M5-01b。完成:初始每 60 秒及暂停/退出请求自动快照,独立于手动槽,最多保留最近 3 份有效记录;新提交失败不挤掉旧记录。验收:L1+L2,可控时钟产生 4 份并核对轮换,实机测一次帧时间以冻结周期。
- [ ] **M5-03b 记录异常会话与恢复候选**。前置:M5-03a。完成:启动/正常结束会话有持久标记,异常重启时列出有效恢复点而不自动运行游戏。验收:L2,一次正常退出及一次进程终止后,提示与候选状态不同且正确;连续崩溃保护在 M7 完善。
- [ ] **M5-04a 校验读档并保护当前进度**。前置:M5-02b。完成:读档前检查哈希、内核提交、格式、配置和完整性,备份当前状态及电池存档;不同内核提交默认拒绝自动恢复并保留原件。验收:L1+L2,正确档及各不同拒绝分支不串档、不覆盖现有进度。
- [ ] **M5-04b 完成读档失败回滚**。前置:M5-04a。完成:暂停后在模拟线程反序列化;失败恢复读档前快照,回滚也失败则安全重载有效电池存档;清空旧音视频、重建时钟。验收:L2,成功、反序列化失败和回滚失败各覆盖一次,内核未知状态不可继续运行。
- [ ] **M5-04c 导出独立存档包**。前置:M5-03b、M5-04b。完成:通过 SAF 导出已提交存档及必要元数据,默认不含 ROM;明确导出失败和取消状态。验收:L2,一次成功导出及取消;包内容与选定游戏对应。
- [ ] **M5-04d 校验并导入存档包**。前置:M5-04c。完成:限制路径、单项/总大小及格式,校验匹配后安全提交;替换前保留有效版本,失败不留下可误用记录。验收:L1+L2,导出包往返一次,越界路径和无效包被拒绝。
- [ ] **G5 存档门槛**。前置:本阶段全部实现项。验收:L3+H-SAVE;100 次循环和故障路径只按第 2 节总口径执行,引用已覆盖的有效分支结果。仅靠手柄完成“选择槽 → 保存 → 读档 → 继续 → 退出”;交付 0.5.x APK、存档格式、已冻结周期及恢复报告。
### M6/0.6.x:日常使用界面
- [ ] **M6-01a 完善游戏库查询和状态**。前置:无。完成:列表显示元数据,支持搜索、收藏和最近游玩;状态写入 Room 并在重启后恢复。验收:L2,一个包含中文长文件名的混合列表验证查询、收藏和最近记录。
- [ ] **M6-01b 完成列表移除与重新关联**。前置:M6-01a。完成:移除仅隐藏条目并保留存档;重导入同哈希恢复原关联,同名不同内容仍独立。验收:L2,一次隐藏与重新导入后可找到原存档,无数据删除。
- [ ] **M6-02a 提供显示设置页面**。前置:无。完成:可选择保持比例/原始整数缩放、最近邻/线性过滤;设置持久化并作用于游戏显示。验收:L2,一个样本逐项切换并重启确认,不重跑 ROM 兼容集。
- [ ] **M6-02b 整合音频与手柄设置**。前置:M6-02a。完成:音量、静音、映射、死区、连发相关偏好和快进开关统一可访问;复用 M3/M4 实现,不重复建立状态来源。验收:L2,改动设置在当前会话和重启后生效,快进关闭后 RB 不加速。
- [ ] **M6-03a 完善存档管理页面**。前置:无。完成:展示手动槽、自动恢复点、时间/缩略图、导入导出入口;手柄和触屏都能完成既有存档操作。验收:L2,一个游戏的管理流程与原存档服务结果一致;不重跑 H-SAVE。
- [ ] **M6-03b 统一页面状态与错误反馈**。前置:M6-01b、M6-02b、M6-03a。完成:游戏信息及相关页面覆盖空、加载、失败、无手柄、长中文名;保存成功/失败与实际提交一致,有可用返回或重试入口。验收:L2,按不同页面状态选代表路径,共用组件只验一次。
- [ ] **M6-04a 实现基础虚拟按键**。前置:无。完成:方向、A/B、Start/Select 支持多点触控、滑出/取消和与手柄来源合成;触屏暂停入口可达。验收:L1+L2,方向+动作、取消、触屏与手柄先后释放各一条路径,无残留。
- [ ] **M6-04b 完成首次使用引导**。前置:M6-03b、M6-04a。完成:首次安装可理解如何导入、连接/测试手柄、开始、保存和退出;无手柄时可走纯触屏路径。验收:L2,清空测试应用数据后完成一次引导,不使用用户真实存档作清理对象。
- [ ] **G6 日常使用门槛**。前置:本阶段全部实现项。验收:L3;全手柄与纯触屏各完成一次“导入 → 开始 → 保存 → 退出 → 恢复”,可引用本阶段已录制的完整路径。验收新增页面和输入交接;H-HOT/H-SAVE 仍有效时不重复,失效时按第 2 节补测。交付 0.6.x Beta 与使用说明。
### M7/0.7.x:系统专项适配
- [ ] **M7-01a 统一系统返回处理**。前置:无。完成:采用 AndroidX 返回处理,运行中返回打开暂停菜单、菜单返回继续、设置返回上级、列表返回退出。验收:L2,每种页面状态各一次,系统手势和应用入口结果一致。
- [ ] **M7-01b 处理返回与游戏状态交接**。前置:M7-01a。完成:返回/菜单动作与暂停确认、加载中、退出中协调,不重复执行或跳回已退出会话。验收:L1+L2,代表重复动作及加载/退出竞态无双会话或错误继续。
- [ ] **M7-02a 适配横屏安全区域**。前置:无。完成:画面、菜单及虚拟键分别处理挖孔、系统栏和手势边缘,关键按钮可触达。验收:L2,目标设备实际布局下检查一次各不同布局,不改变模拟比例。
- [ ] **M7-02b 验证设备可用刷新率**。前置:M7-02a。完成:记录每个可用刷新率模式的显示与模拟速度短样本,切换后仍按内核时序运行。验收:L2,各实际模式一条短路径;只有时钟/音频指标异常才触发 H-AV 重跑。
- [ ] **M7-03a 完善后台与锁屏资源协调**。前置:M7-01b。完成:后台、锁屏、通知/来电导致焦点变化时暂停、静音、清输入并请求保存;回来先准备资源,由用户继续。验收:L2,不同原因各一条状态路径;20 轮循环统一在 G7。
- [ ] **M7-03b 完善 Surface/Activity 与路由重建**。前置:M7-03a。完成:重建时重绑资源而不新增内核线程,处理音频重开与退出交错;不持有已销毁界面。验收:L2,各不同重建路径与一次退出竞态,无持续黑屏、旧声音或多线程实例。
- [ ] **M7-04a 阻断异常启动循环**。前置:M7-03b。完成:进程重建从磁盘会话记录恢复选择,同一 ROM/状态连续异常时回列表,不自动重复加载故障内容。验收:L2,受控连续失败后仍可进入列表并启动另一有效游戏。
- [ ] **M7-04b 完成限额诊断导出**。前置:M7-04a、M7-02b。完成:整合版本、设备、输入、帧率、音频、存档及原生错误记录;日志轮换有上限,导出不包含 ROM。验收:L1+L2,超限轮换和一次导出可读,日志能对应当前会话。
- [ ] **G7 系统门槛**。前置:本阶段全部实现项。验收:L3+H-LIFE;后台和锁屏分别 20 轮,其他重建/异常启动引用有效分支记录。若 M7 修改使 H-HOT、H-AV 或 H-SAVE 失效,只补对应专项;交付 0.7.x APK、MagicOS 10 兼容报告与未覆盖条件。
### M8/0.9.x:候选发布与覆盖核对
- [ ] **M8-01a 冻结候选版和验收集合**。前置:无。完成:固定功能、源码、内核、依赖和配置;建立 F01~F14 到有效证据的索引,列出需重跑项目;冻结至少 12 个有权使用的代表样本,覆盖计划指定 Mapper/区域/文件头/电池存档维度。验收:L0,记录完整且不移除失败样本规避门槛。
- [ ] **M8-01b 执行 RC 兼容集与关键路径**。前置:M8-01a。完成:在候选包运行冻结样本的预定步骤/自检,覆盖输入、音频、暂停、保存恢复、退出等产品主链;H-SAVE/H-HOT/H-LIFE 仅补 M8-01a 标记失效或缺失的项目。验收:L4 的兼容/功能部分,结果可定位到 ROM 和版本,不对每个 ROM 重复全部专项矩阵。
- [ ] **M8-02a 完成长时稳定性验收**。前置:M8-01a。完成:执行 H-LONG 并分析崩溃、ANR、内存趋势;已有满足同样口径且仍有效的记录可引用。验收:L4 的 H-LONG;如需补 H-AV,可选满足区域要求的同一会话合并采集。
- [ ] **M8-02b 完成软件输入延迟验收**。前置:M8-01a。完成:执行 H-INPUT,记录时间域、样本来源、P95 与帧时长;汇总速度/音频统计的有效性。验收:L4 的 H-INPUT 及 H-AV 证据核对,只补失效或缺失部分。
- [ ] **M8-03a 检查发布原生库与打包对齐**。前置:M8-01a。完成:清点候选 APK 中 FCEUmm/JNI/音频及运行库,逐库检查 ELF 和最终 APK 16 KB 对齐,记录工具版本。验收:L4 的 H-NATIVE 静态部分,无遗漏库或不合格结果。
- [ ] **M8-03b 验证页大小与最低系统环境**。前置:M8-03a。完成:在实际 4 KB/16 KB 环境做原生运行、声音、保存恢复;API 28 做安装、导入、运行和保存冒烟,记录 ABI 与环境限制。验收:L4 的 H-NATIVE 运行部分+API 28 短路径,不扩展到每个 Android 版本。
- [ ] **M8-04a 验证新安装与覆盖升级**。前置:M8-01a。完成:执行 H-UPGRADE,核对 Room/设置迁移和存档兼容;保留至少一个可复用旧版本数据集。验收:L4 的 H-UPGRADE,签名/ID/版本记录与实际包一致。
- [ ] **M8-04b 准备候选交付材料**。前置:M8-01b、M8-02a、M8-02b、M8-03b、M8-04a。完成:整理对应源码、依赖/补丁、许可证、原生符号、构建及使用说明、报告和已知问题;引用前述任务汇总后的有效专项结果。验收:L0,材料版本和测试证据一致,不在材料整理项中重跑测试。
- [ ] **G8 发布候选门槛**。前置:本阶段全部实现项。验收:L4 汇总;F01~F14、全部 H 项、环境和发布材料均有有效结果,无阻断/高优先级缺陷,其他问题逐项记录处理结论。门槛只审查并合并证据,不再启动第二轮相同全量测试;有修复时按第 2 节确定重跑范围。
### M9/1.0.0:正式交付
- [ ] **M9-01a 核对范围与正式版本信息**。前置:无。完成:确认 G8 结论、已知问题和交付范围,设置 1.0.0 与递增 versionCode,保持 applicationId 和签名策略。验收:L0+受影响版本配置的 L1。
- [ ] **M9-01b 固定发布源码版本**。前置:M9-01a。完成:建立发布源码标记,记录与 RC 的全部差异;依赖、内核和构建配置均可追溯。验收:L0,差异若影响行为则先按第 2 节更新 G8 证据。
- [ ] **M9-02a 生成正式签名交付包**。前置:M9-01b。完成:生成 NESLite-1.0.0-arm64-v8a.apk、SHA-256、源码包、对应符号及必要混淆映射;私钥不进入仓库或源码包。验收:L1,校验和、签名、ABI、版本和符号对应;正式包对齐检查因产物变化重新执行。
- [ ] **M9-02b 完成交付说明与许可证材料**。前置:M9-02a。完成:最终说明涵盖构建、导入、手柄、保存/导出/恢复、兼容性及已知问题;源码和依赖许可证材料对应正式版本。验收:L0,交付文件齐全且不存在失效引用。
- [ ] **M9-03a 验证正式 APK 短路径**。前置:M9-02b。完成:在目标设备实际正式包上完成安装、导入/加载、输入、声音、暂停、保存恢复和退出。验收:L2,每条主链一次;若仅签名/版本元数据变化,不自动重复全部 H 项。
- [ ] **M9-03b 归档交付证据**。前置:M9-03a。完成:归档正式 APK 校验和、源码标记、工具链、报告、符号和后续问题清单,检查与实际交付文件对应。验收:L0,不重新执行已经通过的运行测试。
- [ ] **G9 正式交付门槛**。前置:本阶段全部实现项。验收:L0 交付核对;G8 结果仍有效、最终包短路径通过、计划第 9 节全部材料齐备,才记录应用 1.0.0 完成。任何必需实机/发布指标缺失均保留未完成状态。
## 5. 需求完成位置速查
此表是索引,不形成第二套待办或重复验收。具体行为与数量以上文条目和专项口径为准。
| 计划需求 | 实现位置 | 功能完成门槛 |
| --- | --- | --- |
| F01 导入与文件识别 | M2-02a~M2-02c | G2 |
| F02 游戏库 | M2-02b、M6-01a~M6-01b | G6 |
| F03 游戏控制 | M2-01c、M2-04a~M2-04d | G2 |
| F04 显示与过滤 | M2-03a~M2-03b、M6-02a | G6 |
| F05 音频与时序 | M3 全部,M7 的系统联调 | G3;系统联调 G7 |
| F06 映射与标准手柄 | M1 诊断、M4-01a~M4-01b、M4-04b | G4 |
| F07 输入细节与手柄导航 | M4-02a~M4-04b、M5 槽位联验 | G4;存档导航 G5 |
| F08 快进 | M3-04d、M4-03b、M6-02b | G4;设置入口 G6 |
| F09 游戏/即时/自动存档 | M2-04d、M5-01a~M5-03b | G5 |
| F10 存档导入导出与恢复 | M5-04a~M5-04d | G5 |
| F11 生命周期与异常恢复 | M2-04c、M3-04b~M3-04c、M5-03b、M7 | G7 |
| F12 虚拟按键 | M6-04a~M6-04b | G6 |
| F13 诊断 | M1、M3-02b/M3-03b、M7-04b | G7 |
| F14 原生兼容与交付 | M0 基线、M8-03a~M8-04b、M9 | G8;最终交付 G9 |
所有需求在功能阶段通过后,仍须进入 G8 的发布覆盖核对;核对复用有效证据,不等于把每项的全部历史测试重新执行一遍。