docs(upgrade): establish native 13.6.1 migration gate and recorder
This commit is contained in:
tei
43
docs/40_任务/STEP-104_官方Native13.6.1升级阶段A_Codex任务_v1.md
Normal file
43
docs/40_任务/STEP-104_官方Native13.6.1升级阶段A_Codex任务_v1.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# STEP-104 官方 MapLibre Native Android 13.6.1 迁移：第一阶段 Codex 任务 v1
|
||||
|
||||
## 1. 基线与职责
|
||||
- 用户授权 **GPT-6.1 Sol / High** 实施官方跟进，使用 Mac 固定 GNU Screen 会话 `20825.7445.codex`，不要自行切换模型和推理档位。
|
||||
- 项目独立 worktree：`/Users/tei/dev/MapLibreParticleLab-upgrade-android-1361`，分支 `upgrade/android-native-13.6.1-20261009`。
|
||||
- 当前第一父基线：**官方 Android Native 13.6.1** peeled commit `c7506d6aff3800e946f89e1a51432fc22d1a6534`；原有自研稳定版本（.21）HEAD `630ec657687bad4200c059bbccbb950d9c6f7ce9`，审计与报告闭环 HEAD `b433775348373b10fba02dc0e1f728bacd72f9e7`。
|
||||
- Integrated repo Linux 远端 `main` 已同步至 `80667d6c343411d03a760425438e3d292f452118`；当前遵守 C-001/C-002、RFC-004、ADR-001，不得擅自改公开 API 或将 Android 新行为写进跨平台 contract。
|
||||
- 先读原工作树 `/Users/tei/dev/MapLibreParticleLab/AGENTS.md`、`PARTICLE_BASELINE.md`、`docs/00_项目规范/`、`docs/00_项目总则/README.md` 与四份有效总则，再读现有审计报告 `/Users/tei/dev/MapLibreParticleLab-upstream-audit-20261009/docs/报告/UPSTREAM-001_MapLibre官方升级兼容性架构审计_Codex完成报告_v1.md`、近期 STEP-100/101/102 记录以及本任务。
|
||||
- 另一个 Mac `particle/main` 工作树有用户未跟踪文件且落后远端，禁止修改；历史 release/STEP-103 工作树均不可改。
|
||||
|
||||
## 2. 本轮的工程目标和停点
|
||||
目标是形成一个**可测试的 Android Native 13.6.1 官方底座候选**，继续保留自研 Field/QBIN/Particle/WeatherColor/RenderSegment/Retained 功能，不重写、不扩大功能。当前不是新版发行。
|
||||
- A：在本分支以官方 13.6.1 为第一父，安全合入 `b433775348...` 自研历史的有效差异。优先使用 `git merge --no-commit --no-ff b433775348...`；解决全部 rename/content/modify-delete 冲突，不允许选择整文件 `ours/theirs` 丢失官方修复或自己的功能。核实 `git diff --check`、冲突标记和完整树，再创建明确 merge commit。可启用 rerere。
|
||||
- B：适配官方 `mbgl→mln` 命名空间、include、Layer/Source/Shader factory、`RenderLayer::update(PaintParameters)`、`RenderStaticData::backendSize` 移除、Renderer lifecycle、RenderSegment 和 GL 粒子后端。只修改当前升级必要的官方接入点，保留现有 fail-closed、source/placement/revision/fast-path gate、map Style 顺序、stencil/target 安全。
|
||||
- C：源码修改完成后，列出**精确可执行**的 Android Native C++/OpenGL 编译与定向测试命令，让 RDC 在 Mac 或 Linux 执行；Codex 自身不得进行耗时 build、link、codegen、打包或 Jest。可以执行 `git diff --check`、少量静态检查。
|
||||
- D：若完整迁移无法在本轮完成，优先形成单独的、可复现且可回退的 Git checkpoint、明确残留冲突/失败清单；未清除 Git 冲突不得提交伪造的成功 merge。发生公共 API/Contract 变化或 iOS 专属需求立即停下来报告，不自行扩大跨团队范围。
|
||||
|
||||
## 3. 必须保留的现有行为
|
||||
- C-002 QBIN V4 单帧 exact match、双帧合法插值、每 fieldKey 八帧和原子拒绝语义不变；不同 reference/dataset/profile 不混用；RN Host 负责加载、requestedForecastTime，Native submit 不调整时间。
|
||||
- WeatherColorLayer 与 RasterParticleLayer 独立；粒子 GPU ping-pong、trail 和 RenderSegment 局部缓存存在；不允许用 CPU 动画替代、不允许关闭关键保护逻辑使其编译通过。
|
||||
- Retained 保留 Z-order、opaque/translucent 绘制语义与 segment 索引；Source/layer/style/context/placement 变更失效安全、销毁不泄漏或使用陈旧 texture。
|
||||
- 官方新版 Feature State 接口不得被自研逻辑覆盖或静默禁用；只记录 Native 后续 RN 11.5 测试 Gate，不升级 RN 包本轮版本锁。
|
||||
|
||||
## 4. 范围
|
||||
- 允许：升级分支中的官方 Native Core/Shader/CMake、必要的 Android Native/JNI 接入、粒子模块源码、测试代码的机械迁移与必要接口适配，以及必要记录。
|
||||
- 禁止：修改 `particle/main`、`release/particle.21`、STEP-103 工作树、NavSea、Integration 合同、iOS 专属 Metal/Bridge 功能实现、官方仓库、Node/Gradle/NDK 工具链；禁止发布 AAR/npm、build APK、改 public API/ABI 语义。
|
||||
- 旧 .21 所有发布坐标保持冻结。iOS 旧实现应尽可能保留源码，但本轮只允许写 **NOT VERIFIED**，不允许声称 Metal/Swift/XCFramework PASS。
|
||||
|
||||
## 5. 记录和 Git：强制多次小提交
|
||||
- 在仓库**根目录的 `recoder_step.md`** 追加每项实质进展，简明中文且 append-only，记录日期、基线、当前变化、已完成、剩余问题、下一步、关联 commit。还需追加 `粒子开发记录.md`（合入后存在），同步更新 `docs/50_Step记录/STEP-104_官方Native13.6.1升级阶段A_v1.md`。
|
||||
- 本任务已有独立启动 checkpoint 提交。后续**至少尝试**按合并/结构迁移/接口修复/文档三个功能批次提交。每次提交限定本主题的文件并有清晰中英 commit message。不允许为了凑提交提交空文件或破坏历史；若阻塞，就如实说明只完成哪些。
|
||||
- **仅 push 本次升级分支**到 `origin/upgrade/android-native-13.6.1-20261009`；切勿 push `particle/main`、force push、合并回主线、push upstream。需等 RDC 独立编译验收后再由 RDC 最终执行 push；Codex 此轮只 commit，不负责最终远端验收。
|
||||
- 用户正式要求阶段记录必须叫 `recoder_step.md`，**不可擅自纠正拼写或用其它文件代替**。
|
||||
- 工作期间若发现现存不相关改动，不能纳入任何提交。
|
||||
|
||||
## 6. 完成报告与检查
|
||||
- 完成报告固定 `docs/报告/STEP-104_官方Native13.6.1升级阶段A_Codex完成报告_v1.md`，必须记录：实际模型与推理档位、原始 SHA 和候选 SHA、每个 commit 与变更范围、merge 冲突解决的准确状态、迁移清单、具体核心 API/行为检查、无 build 时 NOT RUN、给 RDC 的精确构建命令、剩余问题、Android/iOS/RN 明确边界、下一 Gate。
|
||||
- 命名绝对不能自称正式 SDK PASS；如只完成局部迁移标 PARTIAL / BLOCKED。Codex 结束前检查 `git status --short`、`git diff --check`、阶段日志存在，任务范围与 commit 对得上。
|
||||
- 对用户的最终下一停点是 Android 官方 13.6.1 候选的 Core/Android OpenGL 精确编译 Gate；RN 11.5/iOS/发布留后续。
|
||||
- 若需要新增跨平台语义/接口必须暂停并记录 Integration 协调所需证据，而不是自行做新合同。
|
||||
|
||||
## 7. 本阶段特殊实施规则
|
||||
按现有项目 `AGENTS.md`：**Codex 写代码，RDC 负责独立编译和验收**。仅在完成局部代码和提交后提供精确编译命令，等待 RDC 结果，如失败再进入下一轮修复。不要自行执行长时间构建。
|
||||
13
docs/50_Step记录/STEP-104_官方Native13.6.1升级阶段A_v1.md
Normal file
13
docs/50_Step记录/STEP-104_官方Native13.6.1升级阶段A_v1.md
Normal file
@@ -0,0 +1,13 @@
|
||||
# STEP-104 官方 Native 13.6.1 升级阶段 A
|
||||
|
||||
- 状态：进行中。
|
||||
- 当前基线：官方 Android Native `c7506d6aff3800e946f89e1a51432fc22d1a6534`；自研旧版本 .21 `630ec657687bad4200c059bbccbb950d9c6f7ce9`。
|
||||
- 目标：把现有 Particle、WeatherColor、RasterArray、RenderSegment/Retained 与 Android Native 接口移植到官方 13.6.1，保持原语义；形成能进行精确编译验证的候选代码。
|
||||
- 必做：合并/冲突、代码边界适配、append-only `recoder_step.md`、多提交、完成报告、RDC 静态及精确编译。
|
||||
- 允许：本分支 Core/Android Native/构建配置/必要测试/记录。
|
||||
- 禁止：NavSea、其他 worktree、主线和正式发行、未经协调的公共合同变化。
|
||||
- 构建与测试：暂未运行；由 RDC 独立执行，不因任务书生成而记 PASS。
|
||||
- 本轮输出：`docs/40_任务/STEP-104_官方Native13.6.1升级阶段A_Codex任务_v1.md`、`docs/报告/STEP-104_官方Native13.6.1升级阶段A_Codex完成报告_v1.md`、`recoder_step.md`、阶段代码 Git checkpoints。
|
||||
- 当前结果：Gate 0 官方第一父基线检出；自研合并未开始。
|
||||
- 阻塞：尚无；旧/新版差异已在 UPSTREAM-001 审计，需逐项移植。
|
||||
- 下一步：Codex 迁移，RDC 独立编译，失败反馈给 Codex；未获得真实编译/设备结果不得宣称发布成功。
|
||||
Reference in New Issue
Block a user