MapLibreParticleLab/docs/40_任务/UPSTREAM-001_MapLibre官方升级兼容性架构审计_Codex任务_v1.md

UPSTREAM-001 MapLibre 官方升级兼容性架构审计（只读代码，2026-10-09）

授权与模式

• 用户明确授权 Mac 使用 GPT-6 Astra High 做以未来跟随官方升级为目的的架构审计。
• Codex 执行器须显式指定 gpt-6-astra、model_reasoning_effort=high，实际配置从 Codex JSONL 开始事件核实；如不一致，报告 BLOCKED，不能伪称。
• 只读源代码。仅允许生成/修改本任务书和 docs/报告/UPSTREAM-001_MapLibre官方升级兼容性架构审计_Codex完成报告_v1.md；禁止改 C++、RN、Java、ObjC、构建脚本和依赖。
• 仓库为独立干净审计 worktree，基于正式远端 origin/particle/main 的 .21，不可操作其他已有脏工作树。无需构建 APK、AAR、Xcode，无需 Jest。不能伪造运行验收。
• 不修改 Integration COORD/RFC/ADR/Contract；如建议跨平台契约变化仅列出待协调项。

权威输入

• /root/sourceserver/navsea-particle-integration 为 Linux Integration；已由 RDC 同步到 80667d6c343411d03a760425438e3d292f452118。Mac 上可读取到的合同以已存在文件为准，不要猜测。
• 阅读本仓库 AGENTS.md、PARTICLE_BASELINE.md、docs/10_架构/20_粒子系统总体架构设计_v1.md、docs/00_项目总则/粒子系统项目规则与设计决策_v1.md、docs/30_设计/STEP-094_通用RenderSegment模型与Style分类Diagnostics设计_v1.md 和相关 STEP-098/099/100/101/102/103 实现记录。
• 自定义现行发布：630ec657687bad4200c059bbccbb950d9c6f7ce9 (13.4.1-particle.21)。
• 初始 upstream Core：18545ca10d296704b2cba675b182ff2c8da24588 (见 PARTICLE_BASELINE.md)；验证实际 merge-base。
• 官方 MapLibre Native Android android-v13.6.1 peeled commit c7506d6aff3800e946f89e1a51432fc22d1a6534。
• 官方 MapLibre Native iOS ios-v6.31.0 peeled commit 01791ad02c1bfe3b22c42a97619b972aba962f82。
• 官方 MapLibre React Native v11.5.0；现有 Particle RN 11.3.6 peer/dev 锁及 Android AAR replacement、iOS SPM/Podspec 需独立审计。不能混淆 RN 11.5.0 与 Native 13.6.1。

必查问题

1. 原始目标“官方可持续升级、自研粒子和 RenderSegment 可重复移植”离目前真实代码有多远？用逐文件证据分类：纯新增扩展、不可避免的官方接入 hook、可外提的官方修改、深耦合必须重构，另列构建/平台桥接。不要用“62 个修改文件 = 62 个冲突”。
2. 在 git diff 与 git merge-tree dry-run 基础上，对 Android 13.6.1 和 iOS 6.31.0 分别量化冲突文件与交叉文件、可自动合并与疑似行为冲突。绝不可真实 merge/rebase 任何生产分支。优先核对 renderer_impl.cpp、render_orchestrator.cpp、render_target.cpp、render_layer.hpp、render_source.cpp、paint_parameters.cpp、RenderSegment/Retained cache、GPU backend、Style/Layer factory、JNI/Android/iOS 对接代码。
3. 以源代码里的函数/类名证明现有 Particle Core/Field/WeatherColorLayer/GPU 模块是否独立；列出真正只需 hook 的文件和未来易碎调用。用修复方案区分 thin hook、抽象接口、适配器、source-to-segment dependency、offscreen target/placement 等，不得建议一刀切“重写”。
4. RenderSegment 与 Particle Fast Path 的数据依赖、分层失效、Style 顺序、Opaque/Translucent、Placement、Context loss、资源所有权、Top/Bottom Retained、multi-segment 未来兼容约束。区分已实现功能和目前 fail-closed 限制。
5. 核查 packages/maplibre-particle-rn 的 package.json、app.plugin.js、MapLibreParticleRN.podspec、Native API 等；给出 RN 11.5.0 受官方 Android 13.6.1/iOS 6.31.0 依赖推动的单 SDK 依赖收敛风险、代码适配点、功能验证清单。
6. 准备升级顺序和可回滚 Gate：什么必须先重构、什么可以直接合并、哪些要不同平台分别验证，什么情况下必须停止并回 Integration 新 RFC/Contract。建议未来 upstream 版本跟踪工作流和“patch footprint budget”；明确对长期维护代价影响。
7. 逐项目给出 P0/P1/P2 表，包含路径、当前耦合证据、方案、风险、工作量相对估计、验收标准、Android/iOS影响；结论为 GO / CONDITIONAL GO / BLOCKED，不得把未编译当 PASS。

调查方法与客观限制

• 最少执行 git merge-base、git diff --name-status、git merge-tree --write-tree --messages 对两个官方 Native 目标作三方模拟；记录命令、exit code、冲突路径。merge-tree 会在 Git object db 创建对象但不改源码或分支，允许。
• 深入看源码定义和调用，不只扫描关键词；尽量提供可读且可复核的 path:line 和 commit hash。
• 官方 tag 比较若产生无共同祖先、shallow、无法下载等障碍，如实记录并提出可复现替代方案。
• 不强行运行常规编译、Android 实机、iOS 设备或 Jest。
• 对官方 RN 版本差异使用 release changelog、已有源码；未下载的 RN 文件不得假称已审查。
• 审计报告必须中文，章节包含：结论摘要、核对的版本与 SHA、方法和数据可信度、两条 Native 升级线冲突统计与具体文件、Particle 耦合清单、RenderSegment 耦合清单、RN 11.5.0 适配风险、改造优先级矩阵、阶段性迁移与验收、阻塞和未知、实际模型和文件修改清单。

必做输出和 Git 收尾

• 写入 docs/报告/UPSTREAM-001_MapLibre官方升级兼容性架构审计_Codex完成报告_v1.md；如不存在 docs/报告/ 则创建。
• 工作树中仅允许审计任务 MD 和审计报告两份新增文档；完成 git diff --check、路径与报告完整性检查。
• 不要自行 commit 或 push；执行器将先独立核对报告，再将仅这两份文档以隔离分支提交、确认快进后 push 到 origin/particle/main，最终回填 Git 状态。若未收到执行器的最终 Git 回执，报告必须写 Git 收尾待 RDC 验收，不能自称已推送。