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/卸载的真机运行验收。