chore: freeze MapLibreParticleLab step 0 baseline

AGENTS.md

@@ -0,0 +1,11 @@
+# MapLibreParticleLab — Codex 总规则
+
+任何修改前必须阅读 `PARTICLE_BASELINE.md`、`docs/00_项目规范/`（包括官方基线来源）、当前 Step 和当前任务。
+
+项目目标：在 MapLibre Native Core 中 clean-room 独立实现 Raster/Vector Field Particle，支持 Android OpenGL/Vulkan 与后续 iOS Metal。
+
+固定边界：正式实现不使用 React Native/WebView/外部 Overlay；粒子模块高度隔离；官方原文件只做薄接入；Android/iOS 共用 C++ Core；WeatherColorLayer 与 RasterParticleLayer 分离；Wind=GLOBAL；Wave/Tide/Current=OCEAN_ONLY 且共用 Land/Ocean Mask；第一阶段只用离线 fixture；不得复制 Mapbox 新源码或 Windy APK 内代码。
+
+每一阶段必须有 `docs/50_Step记录/STEP-xxx_*.md`。完成报告固定写入 `docs/报告/STEP-xxx_<主题>_Codex完成报告_vN.md`。
+
+修改结束必须按构建规范验证、更新 Step、追加 `粒子开发记录.md`、生成中文完成报告，并明确所有未完成/阻塞。

PARTICLE_BASELINE.md

@@ -0,0 +1,17 @@
+# MapLibreParticleLab 基线记录
+
+- 初始化日期：2026-08-27
+- upstream：https://github.com/maplibre/maplibre-native.git
+- origin：https://git.eyaku.jp/tei/MapLibreParticleLab
+- Android：android-v13.4.1
+- iOS：ios-v6.28.0
+- 共同 core：18545ca10d296704b2cba675b182ff2c8da24588
+- 分支：particle/main
+- Ubuntu：Ubuntu 24.04.4 LTS
+- 架构：x86_64
+- Java：17
+- Android API：34
+- NDK：28.2.13676358
+- 默认并行度：3
+- upstream push：DISABLED
+- git rerere：true

docs/00_项目规范/00_文档目录与命名规范_v1.md

@@ -0,0 +1,3 @@
+# 文档目录与命名规范 v1
+
+正式目录：`00_项目规范/10_架构/20_调查/30_设计/40_任务/50_Step记录/60_测试/70_发布/报告`。正式说明文档文件名和正文使用中文；代码/API/命令保留英文。同主题只用 `_v1/_v2/_v3` 递增，不得用“最新版/修正版/final”制造近义文件。调查=`<主题>调查_vN.md`，设计=`<主题>设计_vN.md`，任务=`STEP-xxx_<主题>_Codex任务_vN.md`，Step=`STEP-xxx_<主题>_vN.md`，完成报告=`STEP-xxx_<主题>_Codex完成报告_vN.md`。完成报告只放 `docs/报告/`。

docs/00_项目规范/01_Codex协作规范_v1.md

@@ -0,0 +1,3 @@
+# Codex 协作规范 v1
+
+标准流程：只读调查 → 设计 → Step → 实现 → 构建/测试 → 完成报告 → Step 更新。没有调查结论不得凭猜测大改 Core。每个任务明确目标、必做项、允许/禁止范围、构建测试、必做输出、停止条件。无法完成必须明确阻塞，不伪造 PASS。默认禁止 force push、push upstream、改写官方 tag、删除历史 Step/报告、无授权扩大重构。

docs/00_项目规范/02_构建与验证规范_v1.md

@@ -0,0 +1,3 @@
+# 构建与验证规范 v1
+
+主环境 Ubuntu 24.04 x86_64，默认并行度 3。Linux 优先官方 CMake/Make 路线，至少保证 OpenGL build、mbgl-render、mbgl-render-test-runner。Android 官方路线：Java17、.nvmrc Node、npm install --ignore-scripts；`cd platform/android && RENDERER=opengl BUILDTYPE=Debug make apackage` 与 `RENDERER=vulkan BUILDTYPE=Debug make apackage`。涉及 renderer/backend 必须双 backend 验证。Linux 不得宣称 iOS/Metal PASS，必须 Mac 同 commit 验证。基础回归只用离线 fixture。GPU 阶段记录粒子数、FPS/frame time、backend 与 pan/zoom/rotate/pitch。

docs/00_项目规范/03_Step阶段记录规范_v1.md

@@ -0,0 +1,3 @@
+# Step 阶段记录规范 v1
+
+Step 连续编号 STEP-000/001/002，不跳号。状态只用：计划/进行中/阻塞/完成/冻结。每个 Step 至少有：状态、目标、基线、必做项勾选、允许修改、禁止修改、构建测试、必做输出、当前结果、阻塞、下一步。执行结束必须更新 Step、追加粒子开发记录、生成 docs/报告 完成报告；未完成项不得勾选。

docs/00_项目规范/04_Git与上游同步规范_v1.md

@@ -0,0 +1,3 @@
+# Git 与上游同步规范 v1
+
+upstream=MapLibre GitHub，仅 fetch，push=DISABLED；origin=用户 Gitea。日常分支 particle/main。提交小而单一。上游升级使用 upgrade/<release> 基于官方新 release 重放 Particle commits，完整回归后更新 PARTICLE_BASELINE.md；不得直接把 upstream/main 混进 particle/main。必须启用 git rerere。

docs/00_项目规范/05_粒子架构原则_v1.md

@@ -0,0 +1,3 @@
+# 粒子架构原则 v1
+
+目标链：RasterArraySource → RasterArrayTile/Velocity Field → WeatherColorLayer + RasterParticleLayer → RenderRasterParticleLayer → Particle State A/B + GPU Update/Draw/Trail → MapLibre gfx/backend → OpenGL/Vulkan/Metal。WeatherColor 表达定量颜色，Particle 表达方向/运动，默认不得靠降低 WeatherColor opacity 才看导航信息。Wind=GLOBAL；Wave/Tide/Current=OCEAN_ONLY 共用 Land/Ocean Mask。Particle State 格式/坐标系/生命周期/跨 tile 必须单独设计后冻结。

docs/00_项目规范/06_官方基线来源_v1.md

@@ -0,0 +1,18 @@
+# 官方基线来源 v1
+
+本项目初始化版本依据 MapLibre 官方资料固定：
+
+- MapLibre Native releases：`https://github.com/maplibre/maplibre-native/releases`
+- Linux 开发文档：`https://maplibre.org/maplibre-native/docs/book/platforms/linux/`
+- Render Tests：`https://maplibre.org/maplibre-native/docs/book/render-tests.html`
+- Android release CI：MapLibre Native `.github/workflows/android-release.yml`
+- Android `Versions.kt`：当前 core `18545ca` 的 `ndkVersion = 28.2.13676358`，`cmakeVersion = 3.24.0+`。
+
+当前冻结：
+
+- Android `android-v13.4.1` → core `18545ca`
+- iOS `ios-v6.28.0` → core `18545ca`
+- Android compileSdk = 34
+- Java = 17
+
+初始化脚本仍会运行时验证 Android/iOS tag 是否继续指向同一 core，避免只依赖本文档。

docs/10_架构/MapLibre粒子总体架构_v1.md

@@ -0,0 +1,3 @@
+# MapLibre 粒子总体架构 v1
+
+Layer：Base Map → WeatherColorLayer → RasterParticleLayer → Navigation Reference → AIS/Route/Ownship/Alarm。GPU 核心候选：Velocity Texture、Particle State A/B、Update、Draw、Trail Render Target、Color Ramp。

docs/20_调查/README.md

@@ -0,0 +1,3 @@
+# 调查目录
+
+第一份建议 `MapLibre粒子接入点调查_v1.md`，只读调查 Style/Source/Tile/RenderLayer/gfx/ShaderRegistry/OpenGL/Vulkan/Metal。

docs/30_设计/README.md

@@ -0,0 +1,3 @@
+# 设计目录
+
+调查后再写设计：ParticleState、VelocityField、Trail、RasterParticleLayer接口、LandOceanMask。

docs/40_任务/README.md

@@ -0,0 +1,3 @@
+# Codex 任务目录
+
+文件名 `STEP-xxx_<主题>_Codex任务_vN.md`；完成报告固定 `docs/报告/`。

docs/50_Step记录/README.md

@@ -0,0 +1,3 @@
+# Step 记录目录
+
+保存阶段权威状态，初始化脚本生成 STEP-000。

docs/50_Step记录/STEP-000_完整环境初始化_v1.md

@@ -0,0 +1,27 @@
+# STEP-000 完整环境初始化 v1
+
+## 状态
+进行中
+
+## 目标
+建立 MapLibreParticleLab 完整 Linux/Android 开发环境与 Codex 中文工程规范。
+
+## 必做项
+- [x] MapLibre 正式 release 基线
+- [x] 全 submodule
+- [x] upstream / origin
+- [x] particle/main
+- [x] 中文文档目录和命名规范
+- [x] Codex 协作规范
+- [x] 构建规范
+- [x] Step 规范
+- [x] Node/npm 环境
+- [x] Android SDK/NDK
+- [x] Linux Native 构建
+- [x] Android OpenGL 构建
+- [x] Android Vulkan 构建
+- [x] 初始化完成报告
+
+## 必做输出
+- PARTICLE_BASELINE.md
+- 环境初始化报告.txt

docs/60_测试/固定测试场景_v1.md

@@ -0,0 +1,9 @@
+# 固定测试场景 v1
+
+- uniform-east：恒定向东
+- uniform-north：恒定向北
+- vortex：旋涡
+- shear：剪切
+- coastal-mask：Coverage/Mask
+
+全部离线固定可重复。

docs/70_发布/README.md

@@ -0,0 +1,3 @@
+# 发布目录
+
+保存 Particle release、MapLibre upstream 升级、冻结 commit 和双平台回归结果。

docs/报告/README.md

@@ -0,0 +1,3 @@
+# Codex 完成报告目录
+
+统一 `STEP-xxx_<主题>_Codex完成报告_vN.md`，不得覆盖旧版本。

docs/报告/STEP-000_环境初始化_完成报告_v1.md

@@ -0,0 +1,118 @@
+# STEP-000 环境初始化完成报告 v1
+
+## 结论
+
+MapLibreParticleLab Linux / Android 主开发环境已完成建立，可以进入粒子系统开发阶段。
+
+## 主开发环境
+
+- Ubuntu 24.04 LTS
+- x86_64
+- 4 CPU 线程
+- 约 8 GB RAM
+- 默认编译并行度：3
+
+## Git
+
+- 正式开发分支：`particle/main`
+- `upstream`：MapLibre 官方 GitHub
+- `origin`：用户 Gitea
+- `upstream` 只用于读取官方更新
+- `git rerere` 用于长期 Fork 冲突复用
+
+## MapLibre 基线
+
+- Android：`android-v13.4.1`
+- iOS：`ios-v6.28.0`
+- Android/iOS 使用共同 MapLibre Native core 基线
+- 实际 commit 以根目录 `PARTICLE_BASELINE.md` 为准
+
+## Linux Native 验证
+
+已通过：
+
+- CMake `linux-opengl` configure
+- Linux OpenGL backend
+- `mbgl-render`
+- `mbgl-render-test-runner`
+
+## Android OpenGL
+
+已成功生成：
+
+`platform/android/MapLibreAndroid/build/outputs/aar/MapLibreAndroid-opengl-debug.aar`
+
+包含：
+
+- `arm64-v8a/libmaplibre.so`
+- `armeabi-v7a/libmaplibre.so`
+- `x86/libmaplibre.so`
+- `x86_64/libmaplibre.so`
+
+结论：PASS。
+
+## Android Vulkan
+
+已成功生成：
+
+`platform/android/MapLibreAndroid/build/outputs/aar/MapLibreAndroid-vulkan-debug.aar`
+
+包含：
+
+- arm64-v8a
+- armeabi-v7a
+- x86
+- x86_64
+
+四种 ABI 的 `libmaplibre.so`。
+
+Debug AAR 同时包含对应的 Khronos Vulkan Validation Layer。
+
+结论：PASS。
+
+## Android SDK
+
+已确认：
+
+- `ANDROID_HOME=/root/Android/Sdk`
+- Android Platform Tools 可用
+- NDK `28.2.13676358` 可用
+- `platform/android/local.properties` 已配置
+- `render-test/android/local.properties` 已配置
+
+## 已修正的问题
+
+### Linux preset 构建目录
+
+实际 CMake preset 输出：
+
+`build-linux-opengl`
+
+构建工具已统一使用该目录，不再错误引用 `build`。
+
+### Android SDK 定位
+
+Gradle 工程同时使用 `ANDROID_HOME` 和本机 `local.properties`，避免新 shell 或 Codex 环境找不到 SDK。
+
+## Codex 开发规范
+
+已建立：
+
+- `AGENTS.md`
+- 中文构建规范
+- 中文 Codex 协作规范
+- Step 阶段记录规范
+- 文档目录与命名规范
+- Git/upstream 同步规范
+- 粒子总体架构原则
+- `docs/报告/` 固定完成报告目录
+
+## STEP-000 状态
+
+**完成并冻结。**
+
+下一阶段：
+
+**STEP-001：MapLibre Native 粒子接入点只读调查。**
+
+STEP-001 暂不实现正式 RasterParticleLayer，先调查 Style / Source / Tile / RenderLayer / gfx / Shader / OpenGL / Vulkan / Metal 的最小接入点。

particle-fixtures/README.md

@@ -0,0 +1,3 @@
+# Particle 固定离线 Fixtures
+
+第一阶段禁止依赖真实天气服务器。具体数据格式在设计冻结后确定。

工具/仓库自检.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+cd "$(git rev-parse --show-toplevel)"
+echo "分支：$(git branch --show-current)"; echo "HEAD：$(git rev-parse HEAD)"; git remote -v
+[[ "$(git remote get-url --push upstream || true)" == DISABLED ]] && echo '[OK] upstream push disabled' || echo '[警告] upstream push'
+[[ "$(git config --get rerere.enabled || true)" == true ]] && echo '[OK] rerere=true' || echo '[警告] rerere=false'
+git submodule status --recursive
+for p in AGENTS.md PARTICLE_BASELINE.md docs/00_项目规范/00_文档目录与命名规范_v1.md docs/报告; do [[ -e "$p" ]] && echo "[OK] $p" || echo "[缺少] $p"; done
+git status --short

工具/同步上游.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+cd "$(git rev-parse --show-toplevel)"; git fetch upstream --tags --prune; git tag --sort=-creatordate | head -n20

工具/完整构建验证.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+
+JOBS=3
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --jobs) JOBS="$2"; shift 2 ;;
+    *) echo "未知参数：$1"; exit 2 ;;
+  esac
+done
+
+ROOT="$(git rev-parse --show-toplevel)"
+cd "$ROOT"
+
+mkdir -p build-particle
+REPORT="build-particle/构建验证报告.txt"
+: > "$REPORT"
+exec > >(tee -a "$REPORT") 2>&1
+
+# 环境文件内部会安全处理 nvm + nounset。
+if [[ -f "$HOME/.maplibre-particle-env" ]]; then
+  # shellcheck disable=SC1090
+  source "$HOME/.maplibre-particle-env"
+fi
+
+export CMAKE_BUILD_PARALLEL_LEVEL="$JOBS"
+export CTEST_PARALLEL_LEVEL="$JOBS"
+
+echo "=== MapLibreParticleLab 完整构建验证 ==="
+echo "HEAD：$(git rev-parse HEAD)"
+echo "并行度：$JOBS"
+echo "Node：$(node -v)"
+echo "npm：$(npm -v)"
+echo "Java：$(java -version 2>&1 | head -n1)"
+echo
+
+echo "[1/3] Linux OpenGL"
+cmake --preset linux-opengl
+cmake --build build-linux-opengl --target mbgl-render mbgl-render-test-runner -j "$JOBS"
+
+echo
+echo "[2/3] Android OpenGL Debug"
+(
+  cd "$ROOT/platform/android"
+  RENDERER=opengl BUILDTYPE=Debug JOBS="$JOBS" make apackage
+)
+
+echo
+echo "[3/3] Android Vulkan Debug"
+(
+  cd "$ROOT/platform/android"
+  RENDERER=vulkan BUILDTYPE=Debug JOBS="$JOBS" make apackage
+)
+
+cd "$ROOT"
+
+sed -i \
+  's/- \[ \] Linux Native 构建/- [x] Linux Native 构建/; s/- \[ \] Android OpenGL 构建/- [x] Android OpenGL 构建/; s/- \[ \] Android Vulkan 构建/- [x] Android Vulkan 构建/' \
+  docs/50_Step记录/STEP-000_完整环境初始化_v1.md 2>/dev/null || true
+
+echo
+echo "全部构建验证完成。"

工具/生成Codex任务.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+NUM="${1:-}"; TOPIC="${2:-}"; [[ -n "$NUM" && -n "$TOPIC" ]] || { echo "用法：$0 001 粒子接入调查"; exit 2; }; cd "$(git rev-parse --show-toplevel)"; F="docs/40_任务/STEP-${NUM}_${TOPIC}_Codex任务_v1.md"; [[ ! -e "$F" ]] || exit 1
+cat > "$F" <<EOF
+# STEP-${NUM} ${TOPIC} — Codex 任务 v1
+## 执行前必读
+- AGENTS.md
+- PARTICLE_BASELINE.md
+- docs/00_项目规范/
+- docs/50_Step记录/STEP-${NUM}_${TOPIC}_v1.md
+## 目标
+待填写。
+## 必做项
+- [ ] 待填写
+## 允许修改范围
+待填写。
+## 禁止修改范围
+待填写。
+## 构建与测试
+待填写。
+## 必做输出
+- [ ] 更新 Step
+- [ ] 更新 粒子开发记录.md
+- [ ] 生成 docs/报告/STEP-${NUM}_${TOPIC}_Codex完成报告_v1.md
+## 停止条件
+遇到架构不确定、上游接口不足或必须扩大范围时停止扩大修改并报告。
+EOF
+echo "已生成 $F"

工具/生成新Step.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+NUM="${1:-}"; TOPIC="${2:-}"; [[ -n "$NUM" && -n "$TOPIC" ]] || { echo "用法：$0 001 粒子接入调查"; exit 2; }; cd "$(git rev-parse --show-toplevel)"; F="docs/50_Step记录/STEP-${NUM}_${TOPIC}_v1.md"; [[ ! -e "$F" ]] || exit 1
+cat > "$F" <<EOF
+# STEP-${NUM} ${TOPIC}
+## 状态
+计划
+## 目标
+待填写。
+## 基线
+- MapLibre：见 PARTICLE_BASELINE.md
+- 分支：$(git branch --show-current)
+- HEAD：$(git rev-parse HEAD)
+## 必做项
+- [ ] 待填写
+## 允许修改范围
+待填写。
+## 禁止修改范围
+待填写。
+## 构建与测试
+待填写。
+## 必做输出
+- [ ] 更新本 Step
+- [ ] 更新 粒子开发记录.md
+- [ ] 生成 docs/报告/STEP-${NUM}_${TOPIC}_Codex完成报告_v1.md
+## 当前结果
+未开始。
+## 未完成/阻塞
+无。
+## 下一步
+待填写。
+EOF
+echo "已生成 $F"

工具/首次推送Gitea.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+cd "$(git rev-parse --show-toplevel)"; [[ "$(git branch --show-current)" == particle/main ]] || { echo '当前不是 particle/main'; exit 1; }; git push -u origin particle/main

粒子开发记录.md

@@ -0,0 +1,18 @@
+# 粒子开发记录
+
+## 2026-08-27 — STEP-000
+- 建立正式 Ubuntu MapLibreParticleLab 工作目录。
+- MapLibre core：18545ca10d296704b2cba675b182ff2c8da24588
+
+## 2026-08-28 — STEP-000 环境基线冻结
+
+- Ubuntu 24.04 x86_64 MapLibreParticleLab 主开发环境建立完成。
+- Linux OpenGL Native 构建通过。
+- `mbgl-render` 构建通过。
+- `mbgl-render-test-runner` 构建通过。
+- Android OpenGL Debug `apackage` 构建通过。
+- Android Vulkan Debug `apackage` 构建通过。
+- OpenGL/Vulkan AAR 均包含 arm64-v8a、armeabi-v7a、x86、x86_64 的 `libmaplibre.so`。
+- Vulkan Debug AAR 同时包含 Khronos Validation Layer。
+- Android SDK 路径已通过 `ANDROID_HOME` 与 `local.properties` 固化。
+- 下一步进入 STEP-001：MapLibre Native 粒子接入点只读调查。