docs: add STEP-061 new-window execution handoff

docs/40_任务/STEP-061_新窗口交接与端到端执行流程_v1.md

@@ -0,0 +1,271 @@
+# STEP-061 新窗口交接与端到端执行流程 v1
+
+## 1. 文档目的
+
+本文件用于在新的 ChatGPT 会话窗口中无缝继续 MapLibreParticleLab / 粒子系统开发。
+新窗口不得依赖旧聊天记录猜测状态；应先读取本文件，再读取仓库中的实际基线与最新 Step 记录。
+
+本文件同时固定从“写 STEP-061 Codex 任务 MD”到“Codex 实现、源码审查、AAR、Win11 Maven、APK、Android 实机验收、Git 收尾”的完整协作流程。
+
+## 2. 当前冻结基线
+
+- Linux repo：`/mnt/sda1/MapLibreParticleLab`
+- branch：`particle/main`
+- 当前 Final HEAD / Remote HEAD：`3d34ec7628d6b429d223a9022f05a9192a0a8d4d`
+- STEP-060：`CLOSED / PASS`
+- STEP-060 最终文档：`docs/50_Step记录/STEP-060_RNTestHost与WeatherRuntime薄桥接_v3.md`
+- STEP-060F Android 最终验收：`docs/报告/STEP-060F_Android最终验收报告_v1.md`
+- 当前最后验证 AAR：`org.maplibre.gl:android-sdk-opengl:13.4.1-step060f`
+- 最后验证 AAR SHA256：`53dfcd43f3479ae43a3c0fd91c10ccbfec7cf1c84ae22ae3435c94393806da6d`
+
+STEP-060 已实测：横屏、双 Metro reverse、WeatherRuntime attach、CoreOnly source/layer 真值链、WeatherColor opacity typed setter 均通过。
+无 Binary Field 时 `TIMELINE_NOT_READY` 仍是预期 fail-closed。
+## 3. 新窗口第一步必须读取
+
+依次读取并以实际仓库内容为准：
+
+1. `AGENTS.md`
+2. `PARTICLE_BASELINE.md`
+3. `docs/50_Step记录/STEP-060_RNTestHost与WeatherRuntime薄桥接_v3.md`
+4. `docs/报告/STEP-060F_Android最终验收报告_v1.md`
+5. `粒子开发记录.md`
+6. STEP-053 Host → MapLibre submission contract 相关任务/记录
+7. 当前与 Binary U/V / Canonical Field / Runtime Field Window 相关源码
+
+若本文件中的 HEAD 已落后于远端，先以 `origin/particle/main` 的最新实际代码重新确认差异，不得用旧聊天内容覆盖新提交。
+
+## 4. STEP-061 架构边界
+
+STEP-061 才允许开始 Binary U/V Field Transport。
+正式数据获取、Weather Service、HTTP/provider、下载、重试、缓存、预取和业务调度属于最终宿主 React Native NavSea 的 JS/TS 层。
+MapLibre Native/C++ 不得引入 provider、network、vendor 或天气业务获取逻辑。
+
+底层 field 采用 Windy-style 二维规则网格向量场：metadata + U/V payload。
+宿主通过稳定的 Host → MapLibre 接口提交已取得并规范化的数据；不得把大 field 作为 `number[]` JSON 数组或 base64 方案长期传输。
+C++ 负责接收、校验、fail-closed、ParticleFieldSnapshot、Timeline、Runtime Field Window、GPU simulation/rendering。
+WeatherColorLayer 与 RasterParticleLayer 继续分离，现有 CoreOnly 架构不得倒退。
+## 5. 固定 tmux / Codex 工作流
+
+所有粒子系统 Codex 操作统一使用固定 session：`particle-codex`。
+不要为新任务创建第二个 tmux session；每个独立 Step 新建一个 window。
+
+当前历史窗口：
+- `0: manual`
+- `1: step060f`
+
+STEP-061 使用新 window，例如：`step061`。
+建议命令：
+
+```bash
+tmux new-window -t particle-codex -n step061 -c /mnt/sda1/MapLibreParticleLab
+```
+
+用户查看：
+
+```bash
+ssh root@192.168.200.184
+tmux attach -t particle-codex
+```
+
+只读查看：`tmux attach -r -t particle-codex`。
+ChatGPT/RDC 可用 `tmux capture-pane -pt particle-codex:step061` 读取执行状态。
+SSH 断开不影响 tmux 中的 Codex、编译或 shell 任务。
+## 6. Codex CLI 固定方式
+
+当前可用 Codex：`codex-cli 0.153.4`。
+已验证启动方式：
+
+```bash
+codex -C /mnt/sda1/MapLibreParticleLab \
+  -m gpt-5.6-terra \
+  -s workspace-write \
+  -a never \
+  --no-alt-screen \
+  "完整阅读并执行 <STEP-061任务MD>；严格遵守任务范围。"
+```
+
+默认使用 medium reasoning；需要改变模型/权限时必须先明确说明原因。
+`workspace-write` 可以改源码，但 Codex sandbox 已实测会把 `.git` 视为只读，无法可靠创建 `.git/index.lock` 或写 `FETCH_HEAD`。
+因此新固定流程是：
+
+- Codex：实现源码、允许范围内的静态/精确验证、中文文档和完成报告；
+- Codex 不得伪称 commit/push；报告写 `GIT_CLOSEOUT_BY_RDC_AFTER_REVIEW`；
+- ChatGPT：读取真实 diff 并审查；
+- 审查通过后，由 ChatGPT 通过 RDC 执行精准 `git add`、commit、push；
+- 不得把历史 untracked 文件顺手加入提交。
+
+除非用户明确要求，不写/跑 Jest。Android APK 编译仍由用户手工执行；AAR 编译可按本文件授权由 ChatGPT/RDC 在 tmux 中执行。
+## 7. AAR 构建固定流程
+
+只有 Codex 源码完成、ChatGPT 审查通过、source commit 已 push 后，才进入 AAR。
+AAR 在 STEP 对应的同一个 tmux window 中执行，不新建第二个编译 window。
+
+**JOBS 必须固定为 1。**
+
+```bash
+cd /mnt/sda1/MapLibreParticleLab/platform/android
+JOBS=1 RENDERER=opengl BUILDTYPE=Release make apackage
+```
+
+必须确认输出含 `--max-workers=1`，并最终 `BUILD SUCCESSFUL`。
+随后在同一 window：
+
+```bash
+./gradlew :MapLibreAndroid:publishOpenglreleasePublicationToMavenLocal --console=plain
+```
+
+再比较 build output 与 Maven Local AAR：
+
+```bash
+sha256sum \
+  MapLibreAndroid/build/outputs/aar/MapLibreAndroid-opengl-release.aar \
+  /root/.m2/repository/org/maplibre/gl/android-sdk-opengl/<VERSION>/android-sdk-opengl-<VERSION>.aar
+```
+
+两个 SHA256 必须完全一致，否则停止后续 Win11 流程。
+## 8. AAR → Win11 传输固定流程
+
+Linux 将新版本 AAR/POM/module 临时复制到 `/mnt/nas/pbf`，该目录对应公网根目录 `https://pbf.jpcn.ccwu.cc/`。
+只作为临时交接，Win11 验证完成后立即删除公开文件。
+
+Win11 固定设备：CARBON7i。
+下载目录：`D:\React\MapLibreParticleAAR\<VERSION>\`。
+必须使用 `curl.exe -L`，并在 URL 后加每次不同的 `?v=` 防止 CDN/cache 命中旧产物，例如：
+
+```powershell
+curl.exe -L --retry 5 --retry-delay 2 `
+  -o "D:\React\MapLibreParticleAAR\<VERSION>\android-sdk-opengl-<VERSION>.aar" `
+  "https://pbf.jpcn.ccwu.cc/android-sdk-opengl-<VERSION>.aar?v=<NEW_VALUE>"
+```
+
+POM/module 同样使用新 `?v=` 下载。
+然后：
+
+```powershell
+Get-FileHash "D:\React\MapLibreParticleAAR\<VERSION>\android-sdk-opengl-<VERSION>.aar" -Algorithm SHA256
+```
+
+Win11 SHA256 必须与 Linux 一致。
+一致后复制三件套到：
+`C:\Users\taibe\.m2\repository\org\maplibre\gl\android-sdk-opengl\<VERSION>\`。
+再次核对 Maven Local AAR SHA256。
+## 9. Win11 源码同步与 Test Host
+
+Git sparse 工作副本：
+`D:\React\MapLibreParticleLab-Win11-SYNC\integration\react-native\MapLibreParticleRNTestHost`
+
+当前实际运行 Test Host：
+`D:\React\MapLibreParticleRNTestHost-Win11-STEP060-20260907`
+
+固定顺序：
+
+1. Win11 sparse repo `git pull --ff-only origin particle/main`；
+2. 以 Git 工作副本为来源同步本 Step 受控 Test Host 源文件到 legacy runtime 目录；
+3. 不覆盖 legacy 目录中已验证且本 Step 无关的生成环境；
+4. 若新 Step 修改 Expo plugin/nativeVersion，则同步更新当前生成 `android/build.gradle` 的对应临时版本；
+5. 保持 `app.json` landscape，并确认生成 Manifest 仍是 `android:screenOrientation="landscape"`；
+6. `05-install-and-run.ps1` 必须保留两条 reverse：`8091 -> 8091` 与 `8081 -> 8091`。
+
+Metro 固定 `8091`，不要启动第二个 Metro，也不要改成 8081。
+
+Win11 Gradle 基线：
+`C:\Users\taibe\.gradle\wrapper\dists\gradle-8.14.3-bin\cv11ve7ro1n3o1j4so8xd9n66\gradle-8.14.3\bin\gradle.bat`
+
+依赖验收必须分别检查 Bridge 与 MLRN，两者都只能解析到当前 Step 的 `<VERSION>`。
+建议在 legacy Test Host `android` 目录执行：
+
+```powershell
+$g = 'C:\Users\taibe\.gradle\wrapper\dists\gradle-8.14.3-bin\cv11ve7ro1n3o1j4so8xd9n66\gradle-8.14.3\bin\gradle.bat'
+& $g :maplibre-particle_weather-runtime-bridge:dependencyInsight --configuration debugRuntimeClasspath --dependency org.maplibre.gl:android-sdk-opengl --console=plain --no-daemon --no-watch-fs
+& $g :maplibre_maplibre-react-native:dependencyInsight --configuration debugRuntimeClasspath --dependency org.maplibre.gl:android-sdk-opengl --console=plain --no-daemon --no-watch-fs
+```
+
+两条输出必须共同出现 `org.maplibre.gl:android-sdk-opengl:<VERSION>`，且均 `BUILD SUCCESSFUL`。
+
+## 10. APK 编译边界
+
+Android APK 编译默认仍由用户手工执行；ChatGPT/RDC 不自行触发 `assembleDebug`，除非用户在当次任务中再次明确授权。
+固定命令：
+
+```powershell
+cd D:\React\MapLibreParticleRNTestHost-Win11-STEP060-20260907\android
+C:\Users\taibe\.gradle\wrapper\dists\gradle-8.14.3-bin\cv11ve7ro1n3o1j4so8xd9n66\gradle-8.14.3\bin\gradle.bat `
+  :app:assembleDebug `
+  --console=plain `
+  --no-daemon `
+  --no-watch-fs `
+  -PreactNativeArchitectures=x86_64
+```
+
+只有用户返回 `BUILD SUCCESSFUL` 后才进入安装和设备验收。
+## 11. Android 安装与运行时验收
+
+Android 测试设备：`192.168.1.146`。
+所有 ADB 命令必须显式带：`adb -s 192.168.1.146 ...`。
+
+优先使用 legacy Test Host：
+`D:\React\MapLibreParticleRNTestHost-Win11-STEP060-20260907\scripts\05-install-and-run.ps1`
+
+该脚本负责：设备检查、`8091 -> 8091`、`8081 -> 8091`、install -r、force-stop、启动 `.MainActivity`。
+安装后先确认：
+
+- Activity 为 `SCREEN_ORIENTATION_LANDSCAPE`；
+- Metro bundle 正常；
+- `WeatherRuntime attached`；
+- 无 `WEATHER_OBJECTS_NOT_READY`、JNI crash、SIGSEGV、FATAL EXCEPTION。
+
+STEP-061 的 Binary U/V 具体验收必须由正式 STEP-061 任务 MD 明确，包括提交 payload 后的 Runtime/Field Window/Timeline 预期状态。
+原则上必须证明 binary ingress 实际进入 Native/Core，而不是只验证 JS 参数接受。
+若任务要求完整控制 UI，可使用现有 `07-enable-full-validation-ui.ps1`，测试完成后必须执行 `08-restore-baseline-ui.ps1`。
+
+运行时结果应同时读取 UI result、runtime snapshot 与当前 App PID 的 logcat；不得只凭屏幕视觉判断。
+测试失败时先判断是 Host/Bridge、JNI、Core field validation、Timeline 还是 renderer，不得在 NavSea 层增加兼容逻辑掩盖上游问题。
+## 12. 临时公开文件清理
+
+Win11 AAR/POM/module 下载和 SHA 验证完成后，Linux 必须删除 `/mnt/nas/pbf` 中本 Step 临时公开的三件套。
+不得把 AAR 放进 Git。
+
+## 13. 每个 STEP 的完整顺序
+
+新窗口必须按下列顺序推进，不跳步：
+
+1. 读取本交接 MD + 实际仓库基线；
+2. 调查 STEP-061 当前源码与边界；
+3. 生成中文 STEP-061 Codex 任务 MD；
+4. 先 commit/push 任务 MD；
+5. 在 `particle-codex` 新建 `step061` window；
+6. 在该 window 启动新 Codex CLI；
+7. Codex 完成源码/文档/允许验证后退出到 shell；
+8. ChatGPT 审查真实 diff；
+9. RDC 精准 commit/push source changes；
+10. 同一 tmux window 以 `JOBS=1` 构建 AAR；
+11. Maven Local publish + Linux 双 SHA；
+12. `/mnt/nas/pbf` 临时发布；
+13. CARBON7i `curl.exe -L ?v=<new>` 下载 + SHA；
+14. Win11 Maven Local + 两条 dependencyInsight；
+15. 用户手工 APK build；
+16. ChatGPT/RDC 安装、ADB、UI/logcat 实测；
+17. 恢复 baseline validation UI；
+18. 删除 `/mnt/nas/pbf` 临时文件；
+19. 写最终 Step/验收报告/开发记录；
+20. commit/push 最终文档并核对 local/remote HEAD。
+## 14. 关键停止条件
+
+出现以下任一情况必须停止后续打包/设备流程并先定位：
+
+- Codex 修改越过 STEP-061 边界；
+- 引入 provider/network/vendor 逻辑到 MapLibre Native/Core；
+- 采用大规模 `number[]` JSON/base64 作为正式 binary field transport；
+- source review 未通过却直接 build AAR；
+- Linux build/Maven Local/Win11 SHA 不一致；
+- Bridge 与 MLRN dependencyInsight 解析到不同 AAR 或旧版本；
+- Android build 失败；
+- 设备出现 crash/JNI/SIGSEGV 或 field fail-open；
+- 未完成 Android hard gate 就提前把 STEP 标记 CLOSED/PASS。
+
+## 15. 新窗口开始语义
+
+用户在新 ChatGPT 窗口只需说明：
+“继续 MapLibreParticleLab STEP-061，先读取 `docs/40_任务/STEP-061_新窗口交接与端到端执行流程_v1.md` 并按实际仓库状态执行。”
+
+新窗口收到后应直接读取此文件和仓库，不要求用户重新复述 AAR、tmux、Win11、ADB 或 STEP-060 历史。