MapLibreParticleLab/recoder_step.md

recoder_step.md — MapLibre 上游升级实施流水记录

中文追加式记录。每个已完成/阻塞阶段记录事实、commit、当前状态与下一步；不覆盖旧记录。仅适用于隔离升级分支，不代表正式版本发布。

2026-10-09 / STEP-104 / Gate 0

• 用户确认目标：以官方新版 Native 为底座重放自研 Particle + RenderSegment，并建立可重复升级流程。
• 执行模型：GPT-6.1 Sol / High（待实际会话核实）；RDC 负责独立构建和验收。
• 升级分支：upgrade/android-native-13.6.1-20261009，独立 Mac worktree。
• 官方新基线：Android Native 13.6.1，commit c7506d6aff3800e946f89e1a51432fc22d1a6534。
• 旧扩展来源：发布 .21 630ec657687bad4200c059bbccbb950d9c6f7ce9；审计文档闭环 b433775348373b10fba02dc0e1f728bacd72f9e7。
• 当前状态：官方代码已检出，尚未移植自研修改，尚未编译，尚未发布。
• 下一步：与旧扩展历史三方合并；逐项处理路径重命名、Renderer 接口及模块注册，不覆盖官方修复。

2026-10-09 / STEP-104 / 源码冲突处理批次 1

• 实际执行模型与档位：gpt-6.1-sol / high，已核对本会话 turn_context，RDC 亦独立确认。
• 基线：HEAD e4c7af7c401aebc0fdb9d85309ad781e328baff4；RDC 已启动 merge，MERGE_HEAD b433775348373b10fba02dc0e1f728bacd72f9e7，初始 76 个 index 未合并路径。
• 完成：对三方内容做路径/namespace 归一后合并，保留官方新增内容与 .21 扩展；24 个 Field/Ingress 文件搬到 mln，删除旧 include/mbgl/shaders/shader_manifest.hpp，在官方新 manifest 注册两个扩展 shader。
• 完成：Particle/WeatherColor override、普通/隐藏清理/粒子 Fast Path update 入口传入官方新增 PaintParameters；Retained key/revision viewport 使用同帧 renderableSize，不恢复已删除 backendSize。
• 完成：官方 CustomMVTVector factory 与 RasterArray factory 并存；新 source 的 retained reuse 保守退回 live；官方 ErrorScope、symbol error 转发、commandBuffer 所有权及 .21 资源清理/observer teardown 均保留。
• 当前问题：源码写入后的静态完整性仍在核查；index 76 路径尚待 RDC 审查并暂存，不能把文本清理声称为 Git merge 完成。全部 build/link/codegen/GTest/Jest/设备检查 NOT RUN。
• 下一步：检查构建清单、shader 注册、JNI 和未迁移引用，再交付 RDC Native OpenGL 编译 Gate。
• 关联 commit：沿用启动 checkpoint e4c7af7c40；本批次未 commit，按用户新指令由 RDC 分批审查、暂存与提交。

2026-10-09 / STEP-104 / Gate 1：真实三方合并 checkpoint

• 执行器：GPT-6.1 Sol / High，实际会话 turn_context 已通过 RDC 核实；Codex 编辑源码，RDC 完成 Git index 与提交。
• 官方第一父：e4c7af7c401aebc0fdb9d85309ad781e328baff4，其父为官方 Android Native c7506d6aff3800e946f89e1a51432fc22d1a6534。
• 旧扩展第二父：b433775348373b10fba02dc0e1f728bacd72f9e7（Particle .21 + UPSTREAM-001 文档）。
• RDC 实际运行 Git 三方合并，76 个未合并路径；Codex 处理新旧目录映射及 Renderer/Source/Shader/JNI 接口，RDC 验证工作树冲突标记 0、index 未合并条目 0。
• 新合并提交：f8378fd7113c4d230500f0b82902d2356907f4a9，message merge(upgrade): port particle extensions onto official native 13.6.1 (unverified)。
• 代码路径的 git diff --cached --check PASS；整个 merge 的 git diff --cached --check 不通过，但仅涉及 3 份来自 .21 的原样历史文档既有尾随空格，未改写历史文档。
• 已完成：合并树可提交、官方修复与自研层/Source/Particle/RenderSegment 并存；尚未编译、链接、运行、Android GPU 验证及 iOS 验证。
• 下一步：RDC 以官方 Android 新树独立配置/精确编译；若失败保留首个真实错误并按明确范围修正或停止。

2026-10-09 / STEP-104 / Gate 2：Android Native OpenGL 编译 PASS

• 目标与范围：仅验证官方 Android Native 13.6.1 底座上的自研 Particle / WeatherColor / RenderSegment 合并代码可编译链接；架构和正式发布未变化。
• 实际验证提交：a4b5f4eaa0eccb734e00d67adb5e750bba320404，其中合并源码提交 f8378fd7113c4d230500f0b82902d2356907f4a9；执行器 GPT-6.1 Sol / High，Native 构建由 RDC 独立执行。
• Mac 构建命令（在 platform/android）：JAVA_HOME=/usr/local/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home ANDROID_HOME=/Users/tei/Library/Android/sdk ANDROID_SDK_ROOT=/Users/tei/Library/Android/sdk ./gradlew --no-daemon --max-workers=3 --console=plain -Pmaplibre.abis=x86_64 :MapLibreAndroid:externalNativeBuildOpenglDebug（环境变量需导出供子进程使用）。
• 前两次尝试失败在 CMake 配置：第一次缺少 cheap-ruler-cpp，第二次缺少 tile-spec 内部 earcut 与 supercluster/LICENSE，均是新 worktree 第三方依赖未初始化/未检出，并非已知自研源码编译错误。RDC 按 Git 固定 SHA 检出 31 个顶层 Native 依赖，修复内部依赖与残缺工作树；中途 GitHub DNS/HTTPS 不稳定，不得伪报成功。
• 第三次编译：BUILD SUCCESSFUL in 22m 24s，Gradle 18 tasks（4 executed / 14 up-to-date）；RDC 确认构建进程 exit code 0、Ninja 编译与最终链接完成。
• 产物：platform/android/MapLibreAndroid/build/intermediates/cmake/openglDebug/obj/x86_64/libmaplibre.so，ELF 64-bit x86-64 动态库，包含 debug_info，大小 377246848 bytes，SHA-256 ff5a5eb45f84ff633a87fe385fb04ee39ba63ed3bc486003408e02cea78c8907。
• Gate 结论：Android x86_64 / OpenGL Native compile+link PASS。这不是 APK 实机验证，不是全 ABI、Vulkan/iOS/RN 11.5.0/发布 PASS；其他 ABI 和运行态 Gate 暂未执行。
• 下一步建议：保留此为可复验的 Native 编译检查点；下阶段批量执行 Android 多 ABI 编译与 Test Host GPU 场景（Field/QBIN、Pan/Zoom/Rotate、RenderSegment、Style lifecycle），确认后再推进 RN 11.5.0。

2026-10-09 / STEP-105 / FZG1-2 Android 13.6.1 Validation APK 打包及安装

• 范围：Mac 的 upgrade/android-native-13.6.1-20261009，Native/源码基线 30d0e6665eb16a258e47b3a8cc0d16932e43762b；仅 Android Test App，未修改 NavSea、particle/main、iOS 或共享合同。
• 设备：FZG1-2，ADB 192.168.200.139:5555，Android 13、首选 ABI x86_64；未操作另一台 Odin。
• 打包：使用 tools/particle_android_validation/build_validation_apk.sh，Gradle :MapLibreAndroidTestApp:assembleOpenglDebug -Pmaplibre.abis=x86_64 -Pmaplibre.validation.stripNativeDebugSymbols=true --console=plain。第一轮 Gradle BUILD SUCCESSFUL in 6m 48s，但验证脚本因 Sentry 辅助动态库同时包含其它 ABI 而拒绝；没有安装不合格包。
• 修复：脚本仍严格要求 MapLibre 与 example-custom-layer 仅有 x86_64，并仅对白名单 libsentry.so / libsentry-android.so 允许 arm64-v8a、armeabi-v7a、x86 的辅助库；其余意外 ABI 库 fail-closed。第二轮增量 Gradle BUILD SUCCESSFUL in 10s，完整 ZIP/ABI/包体校验 PASS；脚本独立提交 73db0356ac5860366f314ddba23b716220e7c16a。
• 产物：artifacts/maplibre-particle/step105-native1361-fzg/MapLibreAndroidTestApp-validation-opengl-debug-x86_64.apk，package org.maplibre.android.testapp，versionName 13.6.1，66,505,502 bytes，Native libmaplibre.so 打包后 39,970,088 bytes；SHA-256 77bc0b238fb476494410a603443030b104d78f97a737307be52460bf5a68f5aa。
• 安装前验证：FZG 已安装旧版 13.4.1-particle.21，旧新 APK 签名证书 SHA-256 均为 e3f8fae6451ed6322259d090dd8e8788df554ab25ed89a01c78014f1d5ef8236。
• 安装：Mac adb -s 192.168.200.139:5555 install -r <APK> 返回 Success，2026-10-09 12:03:06 JST 完成；FZG dumpsys package 返回 versionName=13.6.1，firstInstallTime 仍为 2026-09-22 07:34:56，未卸载/清除原有应用数据；设备上已安装 APK 的 SHA-256 与 Mac 文件一致。
• FZG 原版 APK 备份：artifacts/maplibre-particle/step105-native1361-fzg/rollback/MapLibreAndroidTestApp-original-13.4.1-particle.21.apk（不纳入 Git），SHA-256 999f773276b29fffae05c1edc977e19df6cebecd94e4a4095508d0c5e97e07c2。
• 当前 FZG 前台依旧 com.navsea.app/.MainActivity；本轮不自动启动 Test App，未进行 Particle/RenderSegment GPU 画面或功能回归。
• 结论：APK_BUILD_PASS / FZG_INSTALL_PASS / INSTALLED_FILE_SHA_PASS / RUNTIME_NOT_RUN。下一步单独进行 FZG Test App 启动、粒子/QBIN、Pan/Zoom/Rotate、RenderSegment/Style/卸载的真机运行验收。

2026-10-09 / STEP-105 / FZG 实机运行验收

• 基线：Android Native 13.6.1，升级分支源码 c30add4d335c5c02aadac5756c1606b5bc497269，FZG1-2 x86_64 / Android 13，ADB 192.168.200.139:5555。Mac RDC/ADB 执行，不重新编译、不改 NavSea。
• 默认界面：用户目视看到粒子，ADB 确认 GLOBAL / ACTIVE / EAST / MIX 0% / 256，启动及基线日志无崩溃。
• Cache ON/OFF/ON PASS：控制状态与诊断回读一致；关闭出现 runtime-disabled，重新开启恢复 CACHE ON。
• 平移及双击缩放基础存活 PASS：Activity 未退出，诊断出现 camera-or-boundary 失效后继续复用；未进行视图精确像素比较。
• STEP-101 单次销毁重建 T1 PASS。循环 T2 首次因设备 Logcat 环形缓冲丢失早期记录，不记正式 PASS；第二次改 Mac 流式 Logcat，真实记录 20 requests、20 destroy enter/return、20 Native reset enter/complete、40 Render reset enter/complete、21 renderer ready、DONE1；Crash Buffer 0，PASS。
• STEP-099 T4 R-C-R PASS（仅限无关底层 R0）：71 次动态 GeoJSON 更新，窗口 tick8/130，R0 build 2→2、reuse 5696→9373（+3677）、invalidation 35→35；R1 安全 fallback static-placement。
• QBIN V4 Golden PASS：T0/T1 两片均 ACCEPTED_INSERTED；Seek25/Seek75/Play/Speed2×/Pause/Clear 六项均 ACCEPTED；最后 UI 为 V4 CLEARED。未验证像素级场值。
• STEP-102 T1_FREE_SYMBOL PASS：无 Symbol 的 R0 build 1→1、reuse 196→3879（+3683）、invalidation 6→6，composite；带 Symbol 的 R1 placement gate=false，live 安全回退。
• STEP-102 T2_TWO_FREE FAIL：底层 R0 build 1→1、reuse 197→3879（+3682）、invalidation 5→5；测试 fixture 上层只有 Fill，实际 R1 仍 placementCapable=true、gate=false、live、fallback=static-placement，reuse=0、invalidation 202→3884，不满足两个 Retained 区段均可复用的用例预期。无 crash，不能据此认定错绘，也不能认定相对 .21 已证实回归。
• 候选原因：需要核实 Style 中默认注入的 annotation/symbol layer 是否被划入 R1，以及 Segment 范围；不要移除保守安全 gate 来凑 PASS。
• 收尾：已恢复正常 GLOBAL/ACTIVE/EAST/MIX 0%/256 默认粒子页面，FZG 前台 Test App 13.6.1，进程存活，Crash Buffer 0。整体状态 PARTIAL / T2 EXPECTATION FAIL。
• 原始证据保存在 Git 忽略目录 artifacts/maplibre-particle/step105-fzg-runtime-20261009/01-baseline 到 10-restored。未执行 Gradle、Jest、NavSea、iOS；下阶段先解决 T2 再复测。

2026-10-09 / STEP-106 / STEP-102 T2 Placement 边界修正（仅 Test App，待手工编译）

• 问题来源：STEP-105 FZG Android Native 13.6.1 运行回归中，STEP-102 T2_TWO_FREE 的 R1 虽然 fixture 自有的 step102-upper 是 Fill，却仍 placementCapable=true、gate=false、actual=live、fallback=static-placement、reuse=0。
• 老版对照：FZG1-2 临时覆盖安装原 13.4.1-particle.21 APK，签名相同、包名及 versionCode=14 不变；通过 --es step102_scenario T2_TWO_FREE 运行，Logcat tick29/30 同样 R1 placementCapable=true、gate=false、live、static-placement、reuse=0，R0 composite/reuse。说明这不是 13.6.1 新引入的特有回归。
• 设备恢复：旧版比较后 adb install -r 恢复 13.6.1，设备 SHA-256 与当前新版 APK 完全一致：77bc0b238fb476494410a603443030b104d78f97a737307be52460bf5a68f5aa；已重新启动普通 Particle Core Layer Validation 页面，NavSea 未被修改。
• 根因：源码核对两版 AnnotationManager::updateStyle() 都自动在 Style 末尾添加 org.maplibre.annotations.points（Symbol），STEP-102 原 R-C-R plan 最后 Retained 从 step102-upper 一直延伸至 Style 末尾，包含内部 Symbol。Renderer 对 Symbol 的 placementCapable=true / static-placement fail-closed 是合理行为；T2 原计划没有隔离隐式 Annotation 层。
• 源码修正（限定 Android Test App）：Step102PlacementFixture.planJson() 在两场景共同的 R0 → 粒子 C0 → 上层 R1 之后增加明确的尾部 C2，startLayerId=org.maplibre.annotations.points，保持 Style Z-order 和 Symbol 安全门，T1/T2 用相同边界；ParticleCoreLayerValidationActivity 在 tick8 增加一次性 STEP102_STYLE_LAYER_LAYOUT，打印真实 Style Layer id/type 和各 Segment index 范围。
• 代码提交：86906c8a6af474a8d064c6f6d7d431e2a7e3efe6；只改 Test App 两个 Kotlin 文件，无 Shared Core、Renderer、公开 API、NavSea、iOS 修改。
• 静态检查 PASS：git diff --check；合成 Layer 顺序下 T1 R1 Symbol / T2 R1 Fill / 尾部 Annotation Symbol 分段吻合，4 段覆盖完整（这是模拟，不是实际编译或设备验证）。
• PENDING：本轮没有执行 Android Gradle/Kotlin 编译、没有构建更新 APK，也没有对新修正后的 T1/T2 进行真实 FZG 测试。设备目前仍是已经安装的修正前 13.6.1 APK。遵守用户手工编译边界，需用户在 Mac 运行 ./tools/particle_android_validation/build_validation_apk.sh；之后 RDC 核对 APK SHA、更新安装并运行 STEP-102 T1/T2 tick8/130 + STEP-099 T4 + STEP-101 定向回归。
• 重要边界：为了测试场景保留 Annotation 的 Z-order，新计划成为 R-C-R-C；增加第二个 Continuous 会失去原 fixture 的单一 Continuous fast-path 资格，该修正仅用于验证 Retained Placement 局部缓存，不能拿它证明生产路径快帧性能。未确认的目标必须继续标记待验收。
• 详细报告：docs/报告/STEP-106_STEP102_T2_Placement边界修正_RDC实施报告_v1.md；原始对照日志：artifacts/maplibre-particle/step105-fzg-t2-rootcause-20261009/old21-t2-stream.log（Git 忽略目录）。

2026-10-09 / STEP-106 编译、FZG 安装和真机验收最终结果

• 用户明确允许本轮 Mac Android 编译与 FZG ADB 安装。Integration main 在执行前通过 RDC 同步到 80667d6c343411d03a760425438e3d292f452118。
• 源码基线：upgrade/android-native-13.6.1-20261009 / 23f7b8a4d7b33d3fb63cd8691fc3a2f070936d03；工作区干净，无额外代码更改。构建脚本 tools/particle_android_validation/build_validation_apk.sh，Mac Android x86_64/OpenGL Debug，BUILD SUCCESS，Kotlin 编译 PASS，APK ZIP/ABI/大小校验 PASS；build-info.txt git_dirty=false。
• 修正版 APK：artifacts/maplibre-particle/step106-t2-fix/MapLibreAndroidTestApp-validation-opengl-debug-x86_64.apk；66,505,495 bytes，libmaplibre.so 39,970,088 bytes，SHA-256 0ef3b033cd33139db07258745e9cd9d023170ce69767e3f8a5159821776ec9ef。
• FZG1-2 / Android 13 / 192.168.200.139:5555：与现有签名相同，adb install -r 于 2026-10-09 13:08:17 JST 返回 Success；设备内 base.apk SHA 与 Mac 完全一致，versionName 13.6.1，保留数据。
• STEP-102 T1_FREE_SYMBOL tick8→130：真实 Style/Segment 顺序为 R0 [0,2) Background+Fill、C0 [2,3) Particle、R1 [3,4) 测试 Symbol、C2 [4,5) 内部 Annotation Symbol；R0 buildΔ0、reuseΔ+3682、invalidationΔ0、composite；R1 placementCapable=true/gate=false、Live、static-placement；crash 0。PASS。
• STEP-102 T2_TWO_FREE tick8→130：同样四段，测试 R1 为 Fill、Annotation Symbol 在 C2；R0 与 R1 都 placementCapable=false/gate=true/composite，分别 buildΔ0、reuseΔ+3683、invalidationΔ0；C2 Live；crash 0。PASS，STEP-105 T2 阻塞解除。
• STEP-099 T4 R-C-R 局部复用回归：69 次动态 GeoJSON 源更新，tick8/130 R0 build 1→1、reuse 193→3868（Δ+3675）、invalidation 13→13；crash 0。PASS。
• STEP-101 T1 Native 单次重建：request1、destroy enter/return1、nativeReset enter/complete1、newReady2、DONE1、crash0。PASS。
• STEP-101 T2 20 次重建：request20、destroy enter/return20、nativeReset entered/completed20、Renderer reset enter/complete40、newReady21、DONE1、crash0；使用 Mac 持续流式 Logcat 防止早期事件被设备环形缓冲覆盖。PASS。
• QBIN V4 Golden 最小回归：color/particle/clear/time 均 ACCEPTED，t0/t1 都 ACCEPTED_INSERTED，状态 V4 READY；PASS（不宣称 Seek/Play/Pause 六项全量本轮重复验收）。
• 最终 FZG 已冷启动回默认 Particle Core Layer Validation，GLOBAL/ACTIVE/EAST/MIX0%/256，versionName 13.6.1，APK SHA 0ef3b...，crash 0，前台 Test App；NavSea 未修改。
• 原始运行证据在 Mac Git 忽略目录 artifacts/maplibre-particle/step106-t2-fix/runtime-{T1,T2,STEP099-T4,STEP101-T1,STEP101-T2,V4-smoke,restored}；本轮未执行 Jest、Android ARM64 编译、RN 11.5.0、iOS、Vulkan、性能 profile。
• 结论：STEP-106 FZG x86_64/OpenGL 修正与定向回归 CLOSED/PASS。新增第二 Continuous 只为测试 Annotation 隔离；不得将 R-C-R-C 场景当作生产 Particle fast-path 性能验收，更不代表整个 MapLibre 13.6.1 Android/iOS 发布完成。