STEP-097 V13 三轮审查问题合并修复 — Codex 完成报告 v1

1. 执行结论

PARTIAL，停在 A1。 阶段 0 已静态复核并建 24 项矩阵；A1 的 01/02/03/19 已做部分源码修改。01/02/03 缺少任务要求的专用可执行像素、Metal 附件及异常注入测试入口，不能标 CODE_IMPLEMENTED_STATIC_CHECKED。19 有 GTest 源码且静态核对完成，测试 NOT RUN。按照任务书“前一阶段没有明确代码完成和静态检查结果，不推进下一阶段”，A2/B/C 未开始。此次提交不是 V13 运行态验收，也不是软件发布。

2. Git、机器与版本基线

机器：Mac-mini-tei.lan；目录：/Users/tei/dev/MapLibreParticleLab；分支：particle/main。
起始 HEAD 与远端查询值：720d309364628f85049cf9969d71c71e8dfacce9；起始工作树 clean，子模块未见偏离。
A1 部分代码检查点：e67e4961b5b1a1ff8fa7c1e3263799d63f89cadc。本报告成稿时的代码 HEAD 为该提交；本报告及最终文档另作 scoped 交付提交，最终 HEAD 以交付后的 Git 记录为准。
.13 tag 解引用：ee0b89e711bf01335b3aa71d36def785cd97fec3；manifest 记录 RN/Android 13.4.1-particle.13、iOS 6.28.0-particle.13。没有更改 tag、manifest 或已发布产物。
Integration 本地只读 HEAD 39ad8415fbdb76c1822460bb09f3a3f35fe141e0，C-001/RFC-001 为既有合同；没有由 RDC 独立确认其远端同步。

3. 实际修改与新增文件

范围	文件与内容
A1 代码	`src/mbgl/renderer/paint_parameters.{hpp,cpp}`、`render_target.cpp`、`renderer_impl.cpp`、`render_orchestrator.hpp`、`retained_underlay_cache.{hpp,cpp}`、`retained_underlay_runtime_state.hpp`；`src/mbgl/mtl/offscreen_texture.cpp`、`render_pass.cpp`。
A1 测试源码	`test/renderer/retained_underlay_cache.test.cpp` 增加旧 topology release 不计入新同 index 的 GTest。
新增文档	`docs/30_设计/STEP-097_V13三轮问题去重与修复矩阵_v1.md`、`docs/50_Step记录/STEP-097_V13三轮审查问题合并修复_v1.md`、`docs/60_测试/STEP-097_V13修复后集中验证清单_v1.md`、本报告。
仅追加	根目录 `粒子开发记录.md`。

没有修改 Integration、NavSea、项目总则、旧调查、release manifest、公开 Field/QBIN 协议或已发布坐标。

4. 各问题状态

具体旧编号、源码定位、反例、测试入口和平台待测项见24 项矩阵。编号 01/02/03：源码已局部修改，仍为 WAITING_RDC_BUILD_AND_RUNTIME，且专用测试源码缺口阻止 A1 完成。19：CODE_IMPLEMENTED_STATIC_CHECKED，GTest NOT RUN。04/05/07/08/09/10/11/13/16/17/20：WAITING_RDC_BUILD_AND_RUNTIME 在矩阵中表示待实施，不表示已有代码。06/12/14/15/18/21/22/23/24：DEFERRED_DESIGN；其中 23/24 是 Integration 协调项。无项目被判产品级 PASS，无项因三轮重复编号被删除。

5. 已实施事实、差异与停止原因

01：新 render target 绑定后重置 nextStencilID 与 tile clipping map；同一 target 内未清 stencil 时仍可复用。接入 retained、普通 offscreen 与主目标三处目标切换。
02：Metal 离屏 isRenderable() 检查 color/depth/stencil，simulator/x86 combined depth-stencil 同时绑定两个附件；RenderPass 转换 color/depth/stencil clear/load/store，创建失败显式抛出供 retained fallback。实际 Metal validation NOT RUN。
03：范围 visitor 可回报绘制异常；retained build 收到错误后标失败并转 full fallback，不发布成功缓存。真实 layer 故障注入 NOT RUN。
19：旧 cache 的 release 仅在同 topology revision 更新当前 segment 计数，aggregate release 仍记录。新增同 index 换边界的定向 GTest 源码。

与任务书差异：未完成 A1 关键测试入口，故没有进入 A2/B/C，未形成各阶段成功提交。停止依据是任务书第 2、4、7 节的不可跨越检查点，而非将未运行的构建当作失败。当前代码检查点仍需 RDC 独立审查，特别核对 Metal API/资源所有权和异常后的 GL/Metal fallback。

6. 静态检查、构建与测试记录

已执行：git diff --check 与 git diff --cached --check，均无输出、exit 0；rg -n '[[:blank:]]+$' 核对新文档，无匹配；rg 核对 beginRenderTarget 三处调用和 recordSegmentResourceRelease 的新签名及测试调用。已只读核对 metal-cpp 的 StoreActionStore、setClearStencil 声明。
CMake/Ninja/Xcode/Gradle、codegen、链接、APK/AAR/XCFramework、npm install/typecheck、GTest、Jest、GPU capture、设备与 NavSea：NOT RUN。未有本轮 build log、测试数、耗时或性能数。
生成产物：无。大小/SHA-256/Renderer/Build Type/ABI：不适用。软件发布：NOT RUN。
后续精确命令、fixtures 缺口、预期与责任见集中验证清单。

7. 已知问题、未完成事项与下一步

先为 01 增加同 vector source/same tiles 的 R-R/R-C-R/C-R-R 可执行像素 fixture；为 02 增加 Metal descriptor/combined attachment 与失败注入入口；为 03 增加 layer render 异常注入及下一帧恢复入口。之后静态审查 A1，再由 RDC 在授权下集中编译和运行。
A2 的 PLAY/endpoint/零量化/Mercator，B 的 JSON/坏帧/Android listener/Host 版本，C 的 diagnostics/ordinal/物化/资源优化均未实施。不得将本报告用于关闭这些问题。
Integration C-001/RFC-001 未更新；23 的 Compatibility/Status 及 24 的共享地理 Ocean Mask 需粒子负责人协调。此次未触发需要改变公共合同的实现，因此没有伪造“公共接口阻塞报告”或声称决定已被接受。
建议继续 STEP-097 A1 的测试入口与独立审查，在完成当前检查点后再按原任务书进入 A2；不自行创建下一 Step。

8. 2026-09-26 A1 测试入口续作（补充，历史结论保留）

从 be5b9080ed926a2632c5126c3522e242a2a85967 的 clean particle/main 继续，只处理 A1 01/02/03 测试入口。新增 Step097StencilFixture.kt 与 Validation Activity 菜单，提供一个 GeoJSON source 上的 R-R/R-C-R/C-R-R；新增 render_orchestrator_error.test.cpp 正反范围异常/observer/cache 重试 GTest；新增 mtl_retained_attachments.test.cpp 离屏附件和 clear/load/store GTest。render_pass.{hpp,cpp} 将生产 clear 逻辑抽为内部辅助函数供测试共用；test/CMakeLists.txt 登记两个测试源。更新矩阵、Step、集中验证清单和开发记录。

代码 scoped commit：d0ced7235。此续作的 git diff --check 静态检查无输出；构建、GTest、Jest、APK、Metal/iOS、设备截图及软件发布均 NOT RUN。RDC 已于本续作之前执行第 19 项 GTest 1/1 PASS 和 FZG1 设备辅助冒烟；不能把那些旧结果归到本次新测试源码。01/02/03 仍需 RDC 编译与 runtime 验证，特别是 Metal 失败注入和 GPU 层异常 fallback，A1 仍 PARTIAL；A2/B/C 未开始。文档 scoped commit 与远端状态以最终 Git 记录为准。

7.1 KiB Raw Permalink Blame History Unescape Escape