Files
NESLite/todo.md
T

49 KiB
Raw Blame History

NESLite V1.0 待办事项

依据:开发计划 V1.0。编制日期:2026-09-12;修订日期:2026-09-14。进度以条目和证据为准;本次增加 F15/XCORE,局部实现通过不等于实机或发布验收通过。

1. 执行与勾选规则

  1. 一个实现项交付一项可独立验证的能力或一份完整材料。 任务通常控制在约半天至一天半;不把编码、编译、补测试分别拆成待办,也不把整个模块塞进一个实现项。阶段验收与发布材料单列,不按实现项工期衡量。
  2. 编号对应开发计划。 例如 M2-02a、M2-02b 均属于计划的 M2-02;后缀只拆分工作,不改变所属阶段。每项均写明阶段内前置条件、交付结果和验收级别。
  3. 阶段依赖是共同前置条件。 M0 无阶段前置;M1~M9 依次依赖上一阶段门槛 G0~G8 通过,等价于计划中的累计依赖。条目内“无”仅表示没有额外的阶段内前置条件。列表顺序已按实际依赖排列,不要求父编号严格递增。
  4. 完成实现项不等于阶段通过。 实现、对应局部验收及必要文档更新完成后才能勾选实现项;阶段 G 项还需满足明确的集成/实机门槛。设备缺失时保留 G 项未勾选,不能以编译成功或模拟输入替代真实手柄验收。
  5. 等待不阻止独立工作。 前置未通过时,只能推进不依赖其结果的草稿或隔离实现;不能提交依赖未知接口的完成结论,也不能勾选依赖阶段的门槛。
  6. 状态与证据只记一次。 未勾选项默认“未开始”;进行中、待实机或失败时在条目末附状态和原因。通过后附源码提交及报告位置;阶段报告引用这些记录,不复制同一测试。尚未建立的文档路径是交付目标。
  7. 范围和参数不暗改。 保留 M0~M9 路线;用户新增内置内核选择已在计划第 11 节登记为 F15/XCORE,发布覆盖扩为 F01~F15。其他新需求先明确版本和边界;参数校准同步两份文档。
  8. 未定参数也有明确交付要求。 计划未给数值的 ROM/存档包大小上限、轴阈值、连发频率、缓冲/日志容量,由对应实现项确定并记录数值、单位、默认值及超限行为;配置、文档和验收一致后才算完成,不用“适当”“合理”等词代替实际参数。

2. 分级验收与重跑规则

2.1 验收等级

等级表示验证范围,不是每项任务必须从 L0 到 L4 全部重跑。高等级可直接引用仍有效的低等级结果。每项中的完成标准定义最小必要行为;只有失败、未知影响或下表所列变更才扩大范围。

等级 使用场景 要做的验证 不自动包含
L0 文档/材料检查 文档、清单、版本说明或材料整理 核对内容、编号、链接、版本与文件对应关系 编译、运行、游戏回归
L1 局部验证 单一逻辑、构建配置、解析器或映射规则 受影响目标的编译/静态检查;用最少的正常和必要边界用例验证本项行为 全部单元测试、整应用实机流程、耐久测试
L2 模块集成 JNI、设备、文件系统、UI 或两个模块交接 受影响模块及直接相邻接口;一个代表样本的正常流程,加本次涉及的失败/取消分支 全 ROM 集、30 分钟运行、100 次存读档、20 轮循环
L3 阶段验收 G1~G7 的阶段出口;G0 为构建基线检查 本阶段新增能力的连贯路径,以及分配到该阶段的专项指标 其他已通过阶段的全部测试、发布全量回归
L4 发布验收 M8 的候选发布版与 G8 核对 F01~F15,执行冻结的兼容集和候选包关键流程,补齐缺失/失效的专项证据 不分影响地重复所有历史用例、设备和长测

纯文案或排版改动用 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
内核提交、内核编译选项、libretro 宿主行为 开发时 L1 局部检查+L2 受影响链路;冻结时补受影响内核的冻结 ROM 集、H-AV、H-SAVE 和控制路径 原生打包补 H-NATIVE;L3/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/Nestopia,默认 FCEUmm;每次仅一个 ROM、一个活动内核实例、玩家一;内核操作全部在模拟线程;选择修改下次加载生效
导入与身份 只导入 .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 或外部内核下载/导入;内置选择按 F15;不增加商店上架工作

4. 实现待办与阶段门槛

条目中的 前置 仅列阶段内依赖;共同阶段依赖见第 1 节。完成 同时限定交付内容和可观察结果。所有任务保留计划原父编号,便于回填进度。

G1~G8 的共同交付物为对应阶段 APK、源码提交、构建说明、验收记录和已知问题清单。构建说明等未变化时引用现有文件及版本即可,不另写重复副本;以下 G 项只补充各阶段特有的材料。

M0:工程准备

  • M0-02a 锁定本机构建环境。前置:无。完成:核对 JDK/SDK/NDK/CMake,记录精确版本、安装位置和缺口;形成工具链及应用依赖版本清单。验收:L1,工具可调用且版本符合计划,清单无动态版本。证据:docs/toolchain.md、docs/reports/m0-baseline.md;Gradle 构建和原生链均已实际调用。

  • M0-01a 建立可构建的应用骨架。前置:M0-02a。完成:初始化 Git、Wrapper、单 app、Kotlin/View 页面、CMake 和 JNI 空入口,将锁定版本写入工程配置,生成 arm64 调试 APK。验收:L1,目标构建成功且 APK 包含预期原生库。证据:现行产物为 build/app/outputs/apk/debug/app-debug.apk;确认包含 lib/arm64-v8a/libneslite_jni.so。

  • 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。

  • M0-03a 固定上游来源。前置:M0-01a。完成:登记 FCEUmm 完整提交、libretro 头文件及 Oboe 固定版本,建立依赖获取方式和本地补丁清单。验收:L1,按记录可取得对应源码;此项不要求内核已编译。证据:third_party/manifest.json;三个固定提交已由 tools/fetch-third-party.ps1 检出。

  • M0-03b 建立许可证清单。前置:M0-03a。完成:逐项记录依赖来源、版本、许可证和待交付材料,建立 LICENSE/THIRD_PARTY_NOTICES 基线。验收:L0,已引入依赖无遗漏、记录与选定源码一致。证据:LICENSE、THIRD_PARTY_NOTICES.md、docs/dependencies.md。

  • M0-02b 编写可复现构建说明。前置:M0-01b、M0-03a。完成:docs/build.md 记录从检出到 APK 的步骤、精确工具版本、ABI 和依赖获取;不依赖手工复制未知库。验收:L0;干净检出实际构建统一放在 G0,不在此重复。证据:docs/build.md;调试 APK 已构建。

  • M0-04a 建立需求与验收资源表。前置:M0-01b。完成:docs/requirements.md 映射 F01~F14;列出设备待测参数和 ROM 来源/哈希/区域/Mapper/存档类型;登记 M2 至少 3 个样本的获取安排,其中一个有电池存档。验收:L0,已取得样本有使用依据,未齐资源列明缺口和取得办法,G2 前须齐备。证据:docs/requirements.md、docs/reports/rom-inventory.md。

  • M0-04b 建立按范围执行的检查入口。前置:M0-01a、M0-04a。完成:APK 构建统一用 打包.cmd;局部测试精确选择 Gradle 测试类/CTest 目标,模块和阶段验收汇总有效证据;docs/acceptance.md 和报告模板使用 L/H 编号。验收:L1,执行一个最小目标可获得结果,默认打包不启动测试。证据:现行命令见 docs/build.md;旧 smoke 结果保留在 M0 历史报告。

  • 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 调用成功,错误可定位。证据:2026-09-12 用户在荣耀 Magic8 安装启动 0.9.4-debug,页面显示 JNI 状态成功及 FCEUmm 内核信息;见 docs/reports/m1-diagnostics.md。

  • M1-01b 展示真实设备基线。前置:M1-01a。完成:读取机型、系统 API、ABI、页大小、屏幕尺寸和可用刷新率;未知值明确标记。验收:L2,与设备可读取信息核对,不按 MagicOS 名称推断硬件。证据:荣耀 BKQ-AN00、Android 16/API 36、arm64-v8a、4 KB、1256×2760,显示模式 60/90/120 Hz;见 docs/reports/m1-diagnostics.md。

  • M1-02a 枚举控制器能力。前置:M1-01a。完成:展示名称、描述符、厂商/产品标识、输入源和轴范围;连接/移除时更新列表。验收:L2,一次接入和移除可观察,设备临时编号不作持久身份。状态:GameSir-X5 Lite 已在目标手机枚举,VID/PID、sources 和轴范围已取得;尚缺按住拔出、移除及重连记录。

  • M1-03a 建立实时按钮状态页。前置:M1-02a。完成:显示 KeyEvent 按下/松开及组合状态,保留事件时间与来源。验收:L2,方向和 A/B 可同时按下,全部松开后状态清零。状态:组合状态与事件字段已实现并通过逻辑测试,待真实方向+A/B 路径。

  • M1-03b 展示轴与重复上报。前置:M1-03a。完成:展示 HAT、摇杆、扳机值,能辨认同一操作的按键/轴两种上报。验收:L2,各实际可用轴的往返变化可观察,未上报的能力不伪造。状态:按设备实际 motionRanges 展示和采样已实现,待真实轴往返验证。

  • 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,选择覆盖非紧密行跨度、重复帧和缓冲切换的最小输入集。补充证据:0.9.18 的基础尺寸随帧交接/切换局部用例通过,见显示修复记录;不代替本条其余要求。

  • M2-03b 显示保持比例的游戏画面。前置:M2-03a。完成:GL 线程显示最新完整帧,默认 4:3/最近邻;整数模式按内核基础尺寸使用最大共同整数倍率并居中,空间不足一倍时等比例缩小;丢显示帧不跳模拟帧。验收:L2,两个内核各用一个样本切换两种缩放,包含 Nestopia 扩展纹理,比例和缓冲复用正确;与 XCORE-04 共用对应操作证据。状态:0.9.18 尺寸算法及两内核桌面短检查通过,手机画面待复核,见 显示修复记录。

  • 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~F15 到有效证据的索引,列出需重跑项目;冻结至少 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 发布候选门槛。前置:本阶段全部实现项及 GCORE。验收:L4 汇总;F01~F15、全部 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
F15 内置内核选择 XCORE-01~XCORE-05 GCORE;发布汇总 G8

6. XCORE/0.9.16:用户增补的内置内核选择

对应计划第 11 节/F15。依赖现有 M2/M3/M5 接口的隔离实现;不要求先通过缺设备的 G2~G7 才能做 L1 检查,也不据此勾选它们。源码基线与局部工作区改动见 docs/reports/core-selection-0.9.16.md。

  • XCORE-01 接入第二个内置内核。前置:现有可构建的 M2/M3 接口。完成:固定 Nestopia 来源、构建和通知,统一内核调用,支持它的像素输出,与 FCEUmm 一同打包。验收:L1,arm64 APK 构建成功,21 个必需导出存在,局部像素转换/帧序号测试通过,全部原生库静态对齐合格。证据:双内核报告;尚未代表 Android 动态加载通过。
  • XCORE-02 保存并应用内核选择。前置:XCORE-01。完成:设置提供默认选择,长按游戏提供覆盖与跟随默认,持久保存后仅影响下一次加载,活动会话与存档页显示当前内核。验收:L1,应用编译通过;默认/覆盖/取消、存储重开、未知旧值回退的局部测试通过。证据:双内核报告;界面操作留给 XCORE-04。
  • XCORE-03 隔离内核进度。前置:XCORE-01、现有 M5 格式接口。完成:FCEUmm 保持原路径,Nestopia 的电池、手动/自动槽及恢复标记独立;包带内核身份并在写入前校验。验收:L1,旧路径保留、不同内核路径/恢复键不冲突、包往返与跨内核拒绝、无标识旧包只归 FCEUmm 的测试通过。证据:双内核报告;实际存读档留给 XCORE-04。
  • XCORE-04 验证 Android 上的切换与进度。前置:XCORE-02、XCORE-03。完成:在同一进程按 FCEUmm→Nestopia→FCEUmm 打开同一带电池样本,分别建立并恢复进度;再用一份无电池样本检查两内核的即时存读档;重启应用确认默认和单游戏覆盖保留,取消覆盖恢复默认。验收:L2,每个不同分支一次短路径,画面、声音、输入正常,切回后原槽可读,跨内核包拒绝且旧档不变。状态:待连接 Android 手机及样本;不做 100 次循环或长稳。
  • XCORE-05 验证龙珠英雄黑屏反馈。前置:XCORE-04、用户实际使用的 ROM 和目标手机;桌面复现可提前独立完成。完成:记录 ROM 哈希、Mapper、区域及内核/应用版本,对确认的制式误判按精确哈希修正,两个内核各检查加载、进入游戏、输入和音画。验收:L1 检查哈希匹配与选项隔离;L2 在手机上对照验证,不以桌面检查替代。状态:0.9.17 已定位该 ROM 的 NTSC 启动卡死并自动使用 Dendy;两个内核各 1800 帧中文启动/菜单导航、一次核心状态往返及局部规则测试通过。手机与完整玩法待复核,详见 docs/reports/long-zhu-ying-xiong-0.9.17.md。
  • GCORE 双内核门槛。前置:XCORE-01~05。验收:L3 汇总,核对选择、旧数据保留和用户问题结果;冻结时按第 2 节补受影响内核的兼容集、H-AV、H-SAVE、H-NATIVE,逐项标注通过/失败/未验证。与 G8 共用一份证据,不重复跑同一轮;新增内核不能继承 FCEUmm 的运行结论。状态:L1 已完成,L2/专项实机证据未完成。

所有需求在功能阶段通过后,仍须进入 G8 的发布覆盖核对;核对复用有效证据,不等于把每项的全部历史测试重新执行一遍。