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 再复测。