# Android AAR 与 RN Test Host 标准流水线

本目录固定 QBIN V4 Android Test Host 的交付链。Linux 是唯一的 AAR/RN package 生产端；Windows 11 只消费 Linux bundle 并构建 Test Host APK。正式实现不改变 Core、Renderer、QBIN、Binding 业务语义。

当前固定版本：

- RN package：`13.4.1-particle.3`
- Native AAR：`13.4.1-particle.3`
- Maven coordinate：`cc.navsea.maplibre:android-sdk-particle-opengl:13.4.1-particle.3`

以后正常流程只有：

```text
Linux: linux_build_publish.sh
        ↓ build-manifest.json
Windows: windows_build_testhost.ps1 -DryRun
         windows_build_testhost.ps1
```

版本升级时，必须先显式同步更新 `platform/android/VERSION` 和 `packages/maplibre-particle-rn/package.json` 的 `version`。Linux 脚本只做完全相等的 fail-closed 校验，绝不猜测、覆盖或修复版本；Windows 也只接受 `particle.3` 或更高的显式 particle 版本。

## Linux：生产 bundle

在仓库根目录运行：

```bash
tools/particle_android_pipeline/linux_build_publish.sh
```

脚本先记录 HEAD、分支与 dirty 条目数（只报告，不清理），解析 Android SDK（`ANDROID_HOME`、`ANDROID_SDK_ROOT`，再到 `platform/android/local.properties`），并只为已存在且被 Git ignore 的 Gradle `local.properties` 写同一 SDK 路径。它固定运行 OpenGL Release 的四 ABI `make apackage`，随后运行：

```text
:MapLibreAndroid:publishOpenglreleasePublicationToMavenLocal
```

所有 noisy build/typecheck/package 命令都经 build-output-throttle；找不到其 `run_limited.py` 即失败，可用 `BUILD_OUTPUT_THROTTLE=/绝对路径/run_limited.py` 显式指定。默认路径是本项目 Codex 环境的 skill 路径。

脚本验证 Maven Local 的 `.aar/.pom/.module`、POM 版本与 `13.4.1-particle.2` 历史目录字节不变；之后 typecheck RN package、生成 npm tgz。成功 bundle 写入（并由 Git ignore）：

```text
artifacts/maplibre-particle/<version>/
  android-sdk-particle-opengl-<version>.aar
  android-sdk-particle-opengl-<version>.pom
  android-sdk-particle-opengl-<version>.module
  navsea-maplibre-particle-rn-<version>.tgz
  build-manifest.json
```

每个文件都带 bytes/SHA-256；manifest 另有 HEAD、branch、dirty 状态、版本、Maven coordinate、时间、四 ABI、renderer 和 Linux validation result。目录已有同版本 handoff 文件时立即失败，避免覆盖历史 AAR/tgz。

如果 Native `.3` 已由一次受控完整构建发布到 Maven Local，且仅需补建可传输的 handoff bundle，可显式使用：

```bash
tools/particle_android_pipeline/linux_build_publish.sh --reuse-existing
```

这会在 manifest 明确标成 `PASS_REUSED_EXISTING_MAVEN_LOCAL`，不宣称重新构建；正常发布仍必须使用无参数命令。无写入的检查用 `--preflight`。

## Windows 11：消费 manifest 并构建 Test Host

将整个 Linux `<version>` bundle 原样传到 Windows 后，在 PowerShell 运行：

```powershell
tools\particle_android_pipeline\windows_build_testhost.ps1 `
  -ManifestPath C:\handoff\13.4.1-particle.3\build-manifest.json -DryRun

tools\particle_android_pipeline\windows_build_testhost.ps1 `
  -ManifestPath C:\handoff\13.4.1-particle.3\build-manifest.json
```

`-DryRun` 只校验 manifest 与 bundle 文件 SHA-256，并打印版本、AAR、tgz、Test Host 路径、Maven Local 和 Gradle 命令，不写 Maven Local、不改 package、不跑 npm/Gradle。

正常 Windows 流程以 manifest 为唯一 artifact/version 输入：校验 RN/Native/Maven coordinate、把 AAR/POM/module 安装到 Windows Maven Local（同路径已有不同 SHA 即失败）、在 clean Test Host tracked source 上同步 manifest `gitHead` 的源码/fixture、把 RN dependency 固定到 manifest tgz、把 native substitution（含已生成 Android `build.gradle` 的旧 marker）固定到 manifest coordinate、执行 `npm install --ignore-scripts`、明确执行 Expo Android prebuild，并构建 `:app:assembleDebug`。会输出 APK 绝对路径、bytes 与 SHA-256。

脚本不清理 checkout，也拒绝 dirty 的 Test Host tracked source；不会改写 Windows 用户自有 SDK 或 Gradle `local.properties`。默认绝不调用 ADB。只有显式 `-Install` 才会安装，只有 `-Install -Run` 才会启动，且两者固定 `adb -s 192.168.1.146`。

Linux 不运行 Windows/APK/ADB/设备步骤；本机没有 `pwsh` 时，只能记录 Windows 脚本未在 Linux 解析，不能把它写成 PASS。