# 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。