From 24fb195f98fa659f2131bbe84b51b72b0f019808 Mon Sep 17 00:00:00 2001 From: OpenAI Codex Date: Tue, 8 Sep 2026 23:02:20 +0800 Subject: [PATCH] docs: add STEP-061 new-window execution handoff --- .../STEP-061_新窗口交接与端到端执行流程_v1.md | 271 ++++++++++++++++++ 1 file changed, 271 insertions(+) create mode 100644 docs/40_任务/STEP-061_新窗口交接与端到端执行流程_v1.md diff --git a/docs/40_任务/STEP-061_新窗口交接与端到端执行流程_v1.md b/docs/40_任务/STEP-061_新窗口交接与端到端执行流程_v1.md new file mode 100644 index 000000000..23086b85f --- /dev/null +++ b/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 \ + "完整阅读并执行 ；严格遵守任务范围。" +``` + +默认使用 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//android-sdk-opengl-.aar +``` + +两个 SHA256 必须完全一致，否则停止后续 Win11 流程。 +## 8. AAR → Win11 传输固定流程 + +Linux 将新版本 AAR/POM/module 临时复制到 `/mnt/nas/pbf`，该目录对应公网根目录 `https://pbf.jpcn.ccwu.cc/`。 +只作为临时交接，Win11 验证完成后立即删除公开文件。 + +Win11 固定设备：CARBON7i。 +下载目录：`D:\React\MapLibreParticleAAR\\`。 +必须使用 `curl.exe -L`，并在 URL 后加每次不同的 `?v=` 防止 CDN/cache 命中旧产物，例如： + +```powershell +curl.exe -L --retry 5 --retry-delay 2 ` + -o "D:\React\MapLibreParticleAAR\\android-sdk-opengl-.aar" ` + "https://pbf.jpcn.ccwu.cc/android-sdk-opengl-.aar?v=" +``` + +POM/module 同样使用新 `?v=` 下载。 +然后： + +```powershell +Get-FileHash "D:\React\MapLibreParticleAAR\\android-sdk-opengl-.aar" -Algorithm SHA256 +``` + +Win11 SHA256 必须与 Linux 一致。 +一致后复制三件套到： +`C:\Users\taibe\.m2\repository\org\maplibre\gl\android-sdk-opengl\\`。 +再次核对 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 的 ``。 +建议在 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:`，且均 `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=` 下载 + 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 历史。