MapLibreParticleLab/docs/报告/STEP-088_静态底图缓存PoC与Renderer观测_Codex完成报告_v3.md

STEP-088 静态底图缓存 PoC 与 Renderer 观测 Codex 完成报告 v3

最终结论

本轮完成 STEP-088 的运行时 Cache 控制、Release 最小诊断、Android/iOS Native API、RN RendererRuntime、NavSea 正式 PBF 测试场景及性能基线。

Android 实测已经确认：

1. retained underlay 可以停止静态 LayerGroup 的重复 draw；
2. Cache ON/OFF 可以在同一进程、同一 Map 中运行时切换；
3. 静态 draw 不是当前主要 CPU 成本；
4. 真正的大头是 Particle continuous repaint 触发后，PBF/vector/static renderer pipeline 被反复处理；
5. 因此后续应按规划进入 STEP-089 invalidation/revision，再进入 STEP-090 Static CPU Fast Path。

主要验证

• PURE PARTICLE：RenderThread ≈ 10.2%
• PURE PBF idle：RenderThread ≈ 0%
• production Style + PBF layers hidden + Particle：RenderThread ≈ 25.5%
• production PBF + Particle：RenderThread ≈ 96~100%
• BEFORE_SYMBOL_CLUSTER Cache ON/OFF：
  • RenderThread 100.2% → 96.5%
  • Process 114.2% → 102.8%

构建/测试

• Android x86_64 Validation APK：PASS
• OpenGL target：PASS
• Directed C++ tests：5/5 PASS
• Metal mbgl-core：PASS
• ios-sdk-static：PASS
• RN TypeScript：PASS
• RN Test Host TypeScript：PASS
• RN iOS bridge：旧 STEP-083 SwiftPM 测试包缺少新增 MLNMapView API，因此失败；不是当前源码 platform SDK 编译失败，不作为 STEP-089 阻塞项。
• git diff --check：PASS

Git 收尾

提交与 push 信息在完成 scoped commit 后补入本文件。

Git 收尾记录

• Code commit: 8384c8bd241bcc70c974449475a9a8ca64a1e626
• Code commit message: feat: add retained underlay runtime controls
• Remote branch: origin/particle/main
• Push result: SUCCESS
• Final HEAD: a32e4e1d5b3bc5a5ddc2ff618b964e116265561c