MapLibreParticleLab/docs/40_任务/STEP-063_MapLibre粒子Android_v1发布工程化与ReactNative可导入包_Codex任务_v1.md

STEP-063 MapLibre 粒子 Android v1 发布工程化与 React Native 可导入包 Codex 任务 v1

0. 任务性质

本任务开始把已经通过 Android 实机综合验证的 MapLibre Particle 从“开发工程状态”整理为“可版本化、可发布、可由 React Native 通过包依赖导入的组件”。

本任务属于发布工程化与包结构整理，不是继续开发新的粒子渲染能力。

当前用户已确认：

• Android MapLibre Particle 当前能力达到满意水平。
• STEP-062 可按 CLOSED / PASS 收尾。
• 当前阶段不接入 NavSea。
• 发布服务器、npm Registry、Maven Repository 的最终部署位置暂不决定。
• npm 正式包名采用：
  • @navsea/maplibre-particle-rn
• 正式版本规则采用：
  • <上游 MapLibre Native 版本>-particle.<NavSea 修订号>
• 当前计划首个正式版本：
  • 13.4.1-particle.1
• Android Maven artifact 计划采用：
  • group: cc.navsea.maplibre
  • artifact: android-sdk-particle-opengl
  • version: 13.4.1-particle.1

如果仓库实际调查证明基础 MapLibre Native 并非 13.4.1，必须停止版本改写并先报告，不得自行猜测或强行套用版本号。

---

1. 本任务目标

完成以下四个目标：

1. 冻结并记录当前 MapLibre Particle 的真实上游版本基线。
2. 建立正式版本号、release manifest、CHANGELOG 与发布契约。
3. 把当前 React Native 接入整理成一个正式 npm package：
   • @navsea/maplibre-particle-rn
4. 建立一个“只通过发布包消费”的独立 Consumer Test Host，用于后续证明 NavSea 不需要源码路径或 MapLibre Native 源码编译即可使用。

本任务结束时，不要求真正上传到任何服务器。

最终服务器发布位置后续单独决定。

---

2. 强制边界

2.1 禁止继续扩展粒子功能

本任务不得新增或重写：

• Particle GPU simulation
• WeatherColor 算法
• Timeline / Playback 算法
• HostField 二进制入口
• RasterArraySource 核心语义
• U/V canonical contract
• MapLibre renderer
• JNI 核心路径
• WeatherRuntime 业务语义

除非当前发布工程化过程中发现明确的“无法打包/无法消费”的结构性阻塞。

如果出现此类阻塞：

1. 停止扩大修改。
2. 明确记录阻塞位置。
3. 说明最小修复建议。
4. 不得借发布任务顺便重构 Native/Core。

---

2.2 不接入 NavSea

本任务不得修改 NavSea 仓库。

不得：

• 在 NavSea 中安装 npm package
• 修改 NavSea Metro
• 修改 NavSea Gradle
• 修改 NavSea Pod
• 修改 NavSea Store / Adapter / Action
• 将 Test Host 逻辑搬入 NavSea

本任务只负责把发布组件准备好。

---

2.3 不决定最终发布服务器

本任务不得擅自加入：

• 公司 npm Registry URL
• GitHub Packages
• GitLab Packages
• Gitea Packages
• Nexus
• Artifactory
• Verdaccio
• 私有 Maven Repository URL
• 生产用户名、密码、Token、证书

可以建立与 Registry 无关的标准发布配置和说明。

可以使用本地 .tgz、本地 staging 目录作为“未上传发布物”验证手段。

---

2.4 Android 编译边界

严格遵守项目长期规则：

所有 Android 编译由用户手工执行。

Codex 不得执行：

• Android Gradle assemble
• Android Gradle build
• AAR build
• AAR publish
• Maven Local publish
• APK build
• APK install
• ADB
• Android 实机测试

Codex 可以：

• 修改构建配置
• 修改版本号
• 准备 publication 配置
• 做非 Android 编译的静态检查
• 执行 TypeScript 编译/类型检查（若不触发 Android build）
• 执行 npm pack
• 检查 .tgz 内容
• 编写用户手工 Android 构建命令

---

2.5 不执行 Jest

本任务不执行 Jest，也不新增 Jest 作为验收要求。

---

3. 第一步：真实基线只读调查

开始修改前必须先从当前仓库真实代码调查。

至少确认：

3.1 MapLibre Native 基础版本

从实际构建文件、版本定义、Gradle publication、Git metadata 等确认：

• upstream MapLibre Native version
• 当前 Android renderer variant
• 当前 STEP-061 AAR 坐标
• 当前 STEP-061 AAR version
• 当前 Native/Core source 与该版本之间的关系

预期：

upstreamMapLibreNative = 13.4.1
currentDevelopmentArtifact = org.maplibre.gl:android-sdk-opengl:13.4.1-step061
renderer = opengl

但必须以仓库实际内容为准。

---

3.2 React Native 基线

调查当前 RN bridge / package 的真实位置与结构。

至少确认：

• 当前 RN package 名
• 当前 RN package version
• 当前 package.json
• 当前 Android module / Gradle 文件
• 当前 autolinking 方式
• 当前 MapLibre RN 公共 API 导出方式
• WeatherRuntime
• RasterParticleLayer
• WeatherColorLayer
• HostField submit API
• RN Test Host 当前如何引用该 RN 模块
• 是否存在 file:、workspace path、source path 等开发期依赖

必须明确：

哪些路径只是开发期源码引用，正式 npm package 后必须消失。

---

3.3 当前正式能力链路

只读确认当前已冻结链路：

React Native Host
  ↓ metadataJson + local file:// binary payload
RN bridge
  ↓
WeatherRuntime
  ↓
RasterArraySource::submitHostField()
  ↓
LocalParticleFieldFeed
  ↓
ParticleFieldDataAdapter
  ↓
ParticleFieldSnapshot
  ↓
Core Timeline / Runtime Field Window
  ↓
WeatherColorLayer + RasterParticleLayer

不得因为发布工程化另建第二套入口。

---

4. 第二步：正式版本契约

调查确认基础版本无误后，建立正式版本契约。

4.1 正式版本

首个正式版本：

13.4.1-particle.1

语义：

13.4.1
= 上游 MapLibre Native 基础版本

particle
= NavSea Particle 扩展发行线

1
= 基于该 upstream version 的第 1 个 NavSea Particle 正式修订

后续规则：

13.4.1-particle.2
13.4.1-particle.3

13.5.0-particle.1

14.0.0-particle.1

禁止以后恢复使用 step061 这种开发阶段编号作为正式发行版本。

---

4.2 npm package

正式 npm package：

@navsea/maplibre-particle-rn

正式首发 version：

13.4.1-particle.1

要求 package 名清楚表达：

• NavSea 维护
• MapLibre
• Particle
• React Native

---

4.3 Android Maven artifact

正式 Android artifact：

cc.navsea.maplibre:android-sdk-particle-opengl:13.4.1-particle.1

不得继续使用官方坐标作为 NavSea 正式发行坐标：

org.maplibre.gl:android-sdk-opengl

注意：

Java/Kotlin package namespace 不要求因此重命名。

本任务重点是 Maven publication coordinate 与依赖契约，不允许进行大规模 Java/C++ namespace rename。

---

5. 第三步：建立 Release Manifest

在项目中建立稳定、机器可读的 release manifest。

路径由 Codex根据现有仓库结构选择，但建议类似：

release/maplibre-particle/release-manifest.json

或：

release/maplibre-particle/13.4.1-particle.1.json

至少包含：

{
  "release": "13.4.1-particle.1",
  "upstreamMapLibreNative": "13.4.1",
  "extensionLine": "particle",
  "extensionRevision": 1,
  "platform": {
    "android": {
      "renderer": "opengl"
    }
  },
  "reactNativePackage": {
    "name": "@navsea/maplibre-particle-rn",
    "version": "13.4.1-particle.1"
  },
  "nativeArtifact": {
    "group": "cc.navsea.maplibre",
    "artifact": "android-sdk-particle-opengl",
    "version": "13.4.1-particle.1"
  },
  "publication": {
    "npmRegistry": null,
    "mavenRepository": null
  }
}

可以增加必要字段，例如：

• source commit
• compatibility
• canonical field schema
• RN compatibility
• minSdk / compileSdk（如果项目已有真实事实）
• release state

但不得猜测未确认版本。

---

6. 第四步：正式 React Native package

目标：

@navsea/maplibre-particle-rn@13.4.1-particle.1

必须成为 NavSea 未来唯一面对的 React Native MapLibre Particle 包入口。

---

6.1 设计原则

NavSea 未来目标使用方式：

import {
  MapView,
  Camera,
  RasterParticleLayer,
  WeatherColorLayer,
  WeatherRuntime,
} from '@navsea/maplibre-particle-rn';

实际导出名称必须依据当前仓库真实 API。

不得为了示例强行重命名现有稳定 API。

---

6.2 不允许正式消费源码路径

正式 package 不得要求 Consumer：

file:../MapLibreParticleLab/...
../../platform/react-native
workspace 源码路径
CMake source path
MapLibre Native source tree
本地源码软链接

Consumer 只能依赖正式 npm package。

Android Native 应通过正式 artifact dependency 解决，而不是 Consumer 直接编译 MapLibre Native 源码。

---

6.3 包内部结构

根据当前 React Native package 实际结构做最小整理。

要求：

• package.json 名称正式改为 @navsea/maplibre-particle-rn
• version = 13.4.1-particle.1
• 保留正确的 React Native autolinking
• 保留当前稳定 JS/TS 公共 API
• 保留 Native bridge
• 内部 Android Gradle dependency 改为正式 artifact：
  • cc.navsea.maplibre:android-sdk-particle-opengl:13.4.1-particle.1
• 不得同时再自动引入官方 org.maplibre.gl:android-sdk-opengl 导致双 Native AAR
• 不得引入第二份 MapLibre RN native module

---

6.4 唯一 MapLibre RN 入口原则

需要重点审计：

Consumer 是否仍然需要同时安装：

@maplibre/maplibre-react-native

如果当前 NavSea Particle RN package 本质上是对 MapLibre RN 的完整 fork/扩展，则正式目标应是：

Consumer
  ↓
@navsea/maplibre-particle-rn
  ↓
唯一 RN native module
  ↓
cc.navsea.maplibre:android-sdk-particle-opengl

不应形成：

@maplibre/maplibre-react-native
+
@navsea/maplibre-particle-rn

两套 Native MapLibre 同时进入 App。

如果仓库实际结构暂时无法做到唯一入口，必须在报告中明确说明，不得假装已经完成。

---

7. 第五步：发布包内容审计

必须能够执行：

npm pack

生成类似：

navsea-maplibre-particle-rn-13.4.1-particle.1.tgz

实际文件名以 npm 规则为准。

Codex 必须检查 tarball 内容。

至少确保：

必须包含：

• package.json
• JS/TS build output 或正式 package 所需源码
• type declarations
• React Native native module 必需文件
• android module 必需文件
• README
• LICENSE/NOTICE（依据仓库现有许可要求）
• 必需 plugin/config 文件

不得包含：

• node_modules
• .git
• 大量 build cache
• Android APK
• 临时 log
• Test Host
• WeatherV2 测试数据
• .codex-build-logs
• unrelated docs
• 任何 credential

---

8. 第六步：Android artifact publication 配置

把 Android Native publication 从开发阶段坐标整理成正式坐标。

目标：

groupId:
cc.navsea.maplibre

artifactId:
android-sdk-particle-opengl

version:
13.4.1-particle.1

必须保留：

renderer = opengl

本阶段只准备 publication 配置。

Codex 不执行 AAR build 或 publish。

---

9. 第七步：建立独立 Consumer Test Host

新增一个真正用于验证“发布包消费”的最小 React Native Test Host。

名称建议：

MapLibreParticlePackageConsumerTestHost

实际路径应遵守现有 integration 结构。

---

9.1 Consumer Test Host 的核心约束

它不得：

• 引用 MapLibreParticleLab RN 源码目录
• 使用 workspace source dependency
• 使用相对路径导入正式 RN package 源码
• 直接引用 MapLibre Native source tree
• 自己实现 WeatherRuntime bridge
• 复制 Native bridge 源码

它只能通过安装后的：

@navsea/maplibre-particle-rn

使用功能。

---

9.2 当前服务器未决定时的测试方式

由于最终 npm/Maven 服务器尚未决定，本阶段允许：

npm

使用本地：

npm pack

生成 .tgz 后安装：

npm install <package.tgz>

这属于“发布包消费”，不是源码路径消费。

Android Native artifact

本任务只准备正式 artifact publication。

后续由用户手工构建并放入 Maven Local 或临时 staging repository，再进行 Consumer APK 编译。

不得因为服务器未决定，就退回 source path。

---

9.3 Consumer Test Host 最低功能

先做最小 smoke host，不要求复制 STEP-062 全部复杂测试 UI。

最低要求：

• MapLibre MapView
• GSI basemap
• WeatherColorLayer
• RasterParticleLayer
• WeatherRuntime
• 一个最小真实或 canonical fixture 提交入口
• Runtime state 可见
• Particle / WeatherColor 显示

如果已有可复用 STEP-062 Test Host 逻辑，可以复用业务层代码，但不得通过源码 dependency 复用 RN package。

---

10. 第八步：文档

所有文档中文。

至少新增或更新：

10.1 架构/发布设计

建议：

docs/30_设计/MapLibre粒子Android发布与ReactNative包设计_v1.md

至少说明：

• upstream version
• NavSea Particle version rule
• npm package name
• Maven coordinate
• RN package 与 Native artifact 关系
• 为什么 Consumer 不编译 MapLibre Native 源码
• 为什么不能同时装官方 RN MapLibre 和 NavSea Particle RN
• server registry 尚未决定
• 本地 .tgz / staging 只是预发布验证手段
• 后续 upstream upgrade 规则

---

10.2 STEP 记录

建议：

docs/50_Step记录/STEP-063_MapLibre粒子Android_v1发布工程化_v1.md

---

10.3 Codex 完成报告

建议：

docs/报告/STEP-063_MapLibre粒子Android_v1发布工程化_Codex完成报告_v1.md

---

10.4 CHANGELOG

为正式 package 建立中文 CHANGELOG 或遵循仓库现有发布记录结构。

至少记录：

13.4.1-particle.1

- 基于 MapLibre Native 13.4.1
- Android OpenGL
- WeatherColor
- RasterParticle
- HostField binary ingress
- Timeline / Playback
- React Native WeatherRuntime
- STEP-061 Native/RN ingress 验证
- STEP-062 GSI + WeatherV2 + Particle Android 综合验证

不得把没有验证的能力写成已通过。

---

11. 静态验收

Codex 可执行且应执行：

• package JSON 校验
• TypeScript typecheck
• npm pack
• tarball 内容列表审计
• 检查正式 package 中不存在开发期 file: dependency
• 检查正式 package 中不存在 MapLibre Native source path
• 检查 Android Gradle dependency 指向正式 coordinate
• 检查没有同时依赖正式 Particle AAR 与官方 MapLibre AAR
• git diff --check
• repository search 审计旧 13.4.1-step061 使用位置

注意：

历史文档中出现 13.4.1-step061 是合法的。

但正式 release/package/build config 不得继续把它作为当前发行依赖。

---

12. 用户手工 Android 验证入口

Codex 完成本任务后，必须给出准确的用户手工命令，但不得自行执行。

后续用户将手工完成两个阶段：

阶段 A：正式 AAR

构建：

cc.navsea.maplibre:android-sdk-particle-opengl:13.4.1-particle.1

并验证 artifact 生成。

最终 publish server 尚未决定，因此可先由用户手工发布到 Maven Local 或指定 staging 目录用于验证。

---

阶段 B：Consumer Test Host APK

Consumer 只安装：

@navsea/maplibre-particle-rn@13.4.1-particle.1

通过正式 artifact dependency 获取 Android Native。

然后用户手工：

• Android assembleDebug
• 安装 APK
• 实机 smoke
• GSI
• WeatherColor
• Particle
• Runtime READY

通过后才能正式创建 release tag。

---

13. Git Tag 规则

本任务暂时不得创建正式 release tag。

原因：

13.4.1-particle.1 必须先经过：

1. 正式 AAR 手工构建
2. npm tarball package consumer 验证
3. Consumer Test Host Android APK 实机验证

全部通过后，再单独执行最终 Release Freeze 任务创建 tag。

建议未来 tag：

maplibre-particle/android/13.4.1-particle.1

实际 tag 命名在最终发布任务确认。

---

14. Git 收尾

本任务会修改项目文件，因此必须提交并 push 到：

origin/particle/main

严格遵守项目 Git 规则。

不得：

git add .
git add -A

必须精确 add 本任务文件。

不得提交历史无关 untracked 文件。

完成后：

git fetch origin
git rev-parse HEAD
git rev-parse origin/particle/main
git status --short

必须确认：

HEAD == origin/particle/main

如果 push 失败：

不得声称任务完成。

---

15. 任务完成状态

如果代码/package/publication 配置均完成，静态检查和 npm pack 均通过，但尚未执行用户手工 Android 构建：

状态写：

IMPLEMENTED / WAITING_MANUAL_RELEASE_VALIDATION

不得提前写：

RELEASED
CLOSED / PASS

正式 CLOSED / PASS 等待后续用户手工 AAR + Consumer APK 验证。

---

16. Codex 最终报告必须包含

• 实际确认的 upstream MapLibre Native version
• 当前 RN 基线
• 正式版本号
• npm package name
• Maven coordinate
• release manifest 路径
• 正式 RN package 路径
• Consumer Test Host 路径
• npm pack 结果
• tarball 文件名
• tarball 内容审计结果
• 是否仍存在正式配置中的 step061
• 是否存在 file: 或 source-path consumer dependency
• 是否修改 Native/Core 功能代码
• 是否执行 Android Gradle
• 是否构建 AAR
• 是否执行 ADB
• 是否执行 Jest
• 用户下一步手工命令
• commit hash
• commit message
• push result
• remote branch
• Final HEAD
• 历史无关 untracked 项说明