3.3 KiB
开发环境与系统构建规范 v1
1. 正式基线
源码：/mnt/sda1/MapLibreParticleLab；稳定分支：particle/main。Linux：Ubuntu 24.04 LTS、x86_64、4 CPU threads、约 8GB RAM、默认 JOBS=3。Win11：NavSea、Android 模拟器、Particle Test APK 运行、NavSea Android 手工编译。
2. Step 开始前
记录：git branch --show-current、git rev-parse HEAD、git status --short、git submodule status。
3. Git 远端
origin=ssh://git@192.168.200.230:2222/tei/MapLibreParticleLab.git；upstream=https://github.com/maplibre/maplibre-native.git，只读，push 禁用；保留 git rerere。
4. Step branch
建议 step/0001-...。流程：particle/main → Step branch → Codex → build/test/report → GPT/用户审查 → PASS → merge particle/main → push → freeze。
5. 构建磁盘
大型 build 必须使用 Linux 本地 SSD；禁止 NAS/SMB/NFS 作为 build root。NAS 只做备份、APK/AAR 中转、归档。
6. 环境入口
构建前 source /root/.maplibre-particle-env。Codex 不得自行升级 Node/Java/SDK/NDK/Gradle/AGP/CMake/MapLibre baseline，除非 Step 明确要求。
7. 已验证环境
Linux Native OpenGL PASS；mbgl-render PASS；mbgl-render-test-runner PASS；Android OpenGL Debug AAR PASS；Android Vulkan Debug AAR PASS；Android OpenGL Release AAR PASS。SDK=/root/Android/Sdk；NDK=28.2.13676358。
8. Development Build
默认 Debug + OpenGL + 增量 + Particle Test App。小改不强制 clean/Release/Vulkan/NavSea/全量回归。
9. Gate Build
关键 Step 才做 Release（按需）、明确 Git commit、完整 build、APK/AAR、Renderer、ABI、大小、SHA256、执行报告、必要时 Vulkan/NavSea。
10. OpenGL/Vulkan
OpenGL 是主开发 backend；Vulkan 在专门 Step 做正式回归。核心必须遵循 MapLibre gfx 抽象。
11. Test App 日常链
MapLibre Native → Particle Test APK → 复制到 Win11 → Android Simulator。NavSea 不参与日常粒子调试。
12. 产物
建议统一 dist/android/。示例：particle-test-step-0005-opengl-debug.apk、particle-test-step-0009-opengl-release.apk、particle-test-step-0014-vulkan-debug.apk、maplibre-particle-step-0016-opengl-release.aar。Gate 产物记录 SHA256。
13. Linux/Win11 边界
Linux Codex 默认责任到 APK/AAR build PASS、产物存在、大小、SHA256、执行报告。用户负责复制到 Win11、安装模拟器、人工视觉/交互验证。
14. NavSea Android
继续由用户在 Win11 手工编译；Linux Codex 不代替用户编译 NavSea。
15. Gate A/B/C
Gate A：maplibre-react-native 11.3.6 + 官方 Native 13.2.0，PASS。 Gate B：11.3.6 + 官方 Native 13.4.1，PASS。 Gate C：11.3.6 + Linux 自编译 Native 13.4.1 OpenGL Release，PASS。
16. 当前 Release AAR
MapLibreAndroid-opengl-release.aar，约 156MB，SHA256=5c67d2751fafe211a0df4b82deded09ab1c07cf6ca0f4a12a880283287f85e5c，ABI：arm64-v8a/armeabi-v7a/x86/x86_64。
17. 构建失败
只修当前 Step 允许范围；若必须升级工具链/MapLibre、大改 gfx、修改 NavSea/冻结接口、删除测试或降低门槛，STOP 并报告 BLOCKED。
18. 禁止项
普通 Step 禁止自行升级 MapLibre/AGP/Gradle/NDK/Java/Node，禁止修改 NavSea/冻结接口、删除测试、降低门槛、用 CPU 粒子冒充正式 GPU 实现、修改 docs/00_项目总则/。