From a32e4e1d5b3bc5a5ddc2ff618b964e116265561c Mon Sep 17 00:00:00 2001
From: tei <tei@Mac-mini-tei.lan>
Date: Tue, 22 Sep 2026 16:19:21 +0900
Subject: [PATCH] docs: record STEP-088 runtime cache baselines

---
 ...STEP-088_静态底图缓存PoC与Renderer观测_v3.md | 65 +++++++++++++++++++
 ...�底图缓存PoC与Renderer观测_Codex完成报告_v3.md | 45 +++++++++++++
 2 files changed, 110 insertions(+)
 create mode 100644 docs/50_Step记录/STEP-088_静态底图缓存PoC与Renderer观测_v3.md
 create mode 100644 docs/报告/STEP-088_静态底图缓存PoC与Renderer观测_Codex完成报告_v3.md

diff --git a/docs/50_Step记录/STEP-088_静态底图缓存PoC与Renderer观测_v3.md b/docs/50_Step记录/STEP-088_静态底图缓存PoC与Renderer观测_v3.md
new file mode 100644
index 000000000..2db3c371d
--- /dev/null
+++ b/docs/50_Step记录/STEP-088_静态底图缓存PoC与Renderer观测_v3.md
@@ -0,0 +1,65 @@
+# STEP-088 静态底图缓存 PoC 与 Renderer 观测 v3
+
+## 状态
+
+**ANDROID / NATIVE VALIDATION PASS；STEP-088 收尾。**
+
+STEP-088 已验证 retained underlay 能停止静态 LayerGroup 的重复 GPU draw，并补充了 Release 可用的运行时 Cache ON/OFF、最小诊断接口、Android/iOS Native API、React Native RendererRuntime，以及 Android Test App 的真实 NavSea PBF 性能基线工具。
+
+## 本轮新增能力
+
+- Retained Underlay 默认开启，可按 Map 实例运行时开启/关闭。
+- 关闭时立即失效缓存并恢复原始 full-render；重新开启后在满足条件时重新 build/reuse。
+- Release 保留最小 pull-based diagnostics：enabled/build/reuse/fallback/invalidation/lastReason。
+- Debug 继续保留详细 ParticleRetained 周期日志。
+- RN 新增 RendererRuntime：
+  - setRetainedUnderlayEnabled(reactTag, enabled)
+  - getRetainedUnderlayDiagnostics(reactTag)
+- Android Test App 新增：
+  - NavSea 正式 63 层 PBF Style；
+  - Particle 位置 BOTTOM / AFTER_SEA / AFTER_CLIP / BEFORE_SYMBOL_CLUSTER / TOP；
+  - runtime Cache ON/OFF；
+  - PBF ON/OFF；
+  - PURE PARTICLE；
+  - PURE PBF；
+  - CUSTOM PARTICLE COUNT，范围 1..10000。
+
+## 关键 Android 性能证据
+
+测试设备：Android 13 / x86_64 / FZG1-2，固定唐津 Camera，Particle target FPS 30。
+
+- PURE PARTICLE，2048 粒子，无 PBF：
+  - RenderThread ≈ 10.2%
+  - Process ≈ 13.7%
+  - Main ≈ 2.5%
+- PURE PBF，63 层正式 Style，无 Particle：
+  - RenderThread ≈ 0%
+  - Process ≈ 0%
+- NavSea Style 保留、60 个 navsea_delivery layer 全隐藏、Particle 2048：
+  - RenderThread ≈ 25.5%
+  - Process ≈ 29.1%
+- PBF + Particle，AFTER_CLIP：
+  - Cache ON RenderThread ≈ 96.5%，Process ≈ 102.2%
+  - Cache OFF RenderThread ≈ 99.5%，Process ≈ 111.8%
+- PBF + Particle，BEFORE_SYMBOL_CLUSTER：
+  - Cache ON RenderThread ≈ 96.5%，Process ≈ 102.8%
+  - Cache OFF RenderThread ≈ 100.2%，Process ≈ 114.2%
+- TOP 因 static-placement/static-transition 持续 fallback，不能作为稳定 retained 场景。
+
+结论：STEP-088 能消除静态 GPU draw，但主要 CPU 成本仍来自 Particle continuous repaint 下 PBF/vector/static renderer pipeline 被反复处理。该证据支持下一阶段先做 STEP-089 invalidation/revision 基础，再进入 STEP-090 Static CPU Fast Path。
+
+## 验证结果
+
+- Android x86_64 stripped Debug Validation APK：BUILD SUCCESSFUL，约 57 MB，实机通过。
+- Mac OpenGL mbgl-test-runner：PASS。
+- STEP-088 directed tests：5/5 PASS。
+- iOS Metal mbgl-core：BUILD SUCCEEDED。
+- iOS ios-sdk-static：BUILD SUCCEEDED。
+- RN package TypeScript：PASS。
+- RN Test Host TypeScript：PASS。
+- RN iOS bridge 单独编译：被 Test Host 仍引用旧 STEP-083 本地 SwiftPM 包阻塞；旧包缺少本轮新增 MLNMapView retained-underlay API。当前源码 iOS SDK 已通过编译，因此该项记录为测试宿主产物过期，不阻塞 STEP-089。
+- git diff --check：PASS。
+
+## 下一步
+
+进入 STEP-089：建立静态内容 invalidation/revision 可靠判据，只做 fast-path 前置安全基础，不提前实现 STEP-090 的 CPU fast path。
diff --git a/docs/报告/STEP-088_静态底图缓存PoC与Renderer观测_Codex完成报告_v3.md b/docs/报告/STEP-088_静态底图缓存PoC与Renderer观测_Codex完成报告_v3.md
new file mode 100644
index 000000000..bd8ad8bf7
--- /dev/null
+++ b/docs/报告/STEP-088_静态底图缓存PoC与Renderer观测_Codex完成报告_v3.md
@@ -0,0 +1,45 @@
+# 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 / Final HEAD：见后续最终收尾提交。