MapLibreParticleLab/docs/报告/STEP-109_V23_CPU_FieldSnapshot深比较快路_RDC阶段报告_v1.md

STEP-109 V23 CPU FieldSnapshot 深比较快路 — RDC 阶段报告 v1

日期：2026-10-10（JST） 结论：PARTIAL / 开发态。已针对 V23 源码热点实施局部修正；尚无 V23 真机 CPU 改善证据。

1. 基线

• 仓库：Mac /Users/tei/dev/MapLibreParticleLab，particle/main。
• 起点：5b8bdfbfbb4263fe12a060e77bc310cf77f27d61，起点工作区干净。
• 正式已发布 V23：13.6.1-particle.23（Android/RN）、6.29.0-particle.23（iOS）；发行 Tag、Source Lock、制品均未变更。
• NavSea Mac V23 集成 checkout 为 /Users/tei/dev/NavSea-Build；Windows D:\React\NavSea 当前仍引用 13.4.1-particle.21，且有多项其他工作区修改。本轮未改 NavSea。

2. V23 实际源码发现

• render_particle_validation_layer.cpp 每帧调用 sameFieldGpuEndpoint() 校验既有 T0/T1，内部逐项比较 vector 和 valid。
• render_weather_color_layer.cpp 每帧调用 sameFieldGpuContent()，内部比较 scalar/vector/valid。
• 两条判断在 immutable T0/T1 未改变时仍可执行 O(N) 深比较。
• STEP-090 Fast Path 存在；STEP-102/106 RenderSegment Placement 局部修复已有 FZG 定向证据，因此不能直接照搬 V21 cache-invalid 诊断。
• V21 93.8% CPU 与 simpleperf 浮点数组采样仅为历史方向提示，不能归因于此次代码或称为 V23 基线。

3. 已实施代码

• src/mln/renderer/layers/render_particle_validation_layer.cpp：资源绑定持有 T0/T1 不可变快照 shared_ptr；当前资源已验证同一快照时 O(1) 判等，新对象仍严格核对内容。
• src/mln/renderer/layers/render_weather_color_layer.cpp：WeatherColor 纹理同样记录 Source 快照身份；相同内容的新对象仍使用原严格比较及资源复用。
• 全部身份绑定只在纹理准备成功或内容等价验证后建立；资源销毁、重新创建与 context loss 均自然清除。
• 未改 RN 对外 API、风场 canonical contract、T0/T1 mix、Runtime Field Window、粒子数量、GPU 纹理算法及 RenderSegment 安全回退。

4. 验证与限制

• scoped git diff --check：PASS。
• Mac Metal Core：INTERRUPTED / NOT COMPLETED / NOT PASS。执行 bazel build -c opt --//:renderer=metal //:mbgl-core 触发 649 actions 的通用 Native 重编译；基于本轮仅两文件微调、尚未安排设备验收，主动中止以控制开发成本。原远程 session 8049 和 Bazel PID 8350 均已停止；未取得构建最终通过或编译错误结论。日志：/tmp/maplibre_step109_cpu_field_identity_bazel_20261010.log。
• Android 用户手工编译/安装、OpenGL 实机、iOS 实机、性能同屏 A/B、全量定向测试：NOT RUN。
• 没有测得实际 CPU 下降百分比；本次不生成正式发行版，不覆盖 V23 Tag 或 Source Lock。

5. 后续验收门槛

1. Native 编译通过并定向执行现有 Field GPU / Timeline / Source 测试。
2. Android FZG1-2 以相同天气输入和粒子设置、相同 Layer stack、同一 BuildType 做 V23 原版与修正版 A/B，采样进程、RenderThread、JS，并检查 FieldTextureUpload/SimulationReset。
3. 时间切换、T0/T1 重叠窗口、clear/reload/context loss、切层、地图平移与关闭天气后恢复，在 Android/iOS 分别核对画面正确、无旧场、无多余纹理重建。
4. 用户验收后，再新建发行版本，按 GSRL 发布不可变制品与 SOURCE_LOCK.json。

6. Git

本次开发提交与远端回读事实见下一节。提交只意味着代码可追溯，不意味着已编译、通过真机或正式发行。

7. Git 开发提交与远端回读（2026-10-10）

• 本次仅提交两份 Renderer C++ 源码、STEP-109、RDC 阶段报告、粒子开发记录共五个相关文件，未执行 git add -A 或触碰正式发行文件。
• 首个开发提交：2aae38f4023f2ef682c9039c93dfa1e96b0e6e1b；perf(particle): skip repeated field snapshot deep comparisons。
• git push origin HEAD:refs/heads/particle/main：PASS，fast-forward；远端 git ls-remote 回读同一 SHA：PASS。
• 本次只是开发态代码与记录推送；Mac Metal build 中断、Android/iOS 真实 CPU A/B NOT RUN，STEP-109 保持 PARTIAL。正式 V23 GSRL Tag 和制品仍完全不变。