tei/MapLibreParticleLab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f8378fd7113c4d230500f0b82902d2356907f4a9
MapLibreParticleLab/docs/40_任务/STEP-061_新窗口交接与端到端执行流程_v1.md
OpenAI Codex a5af776322
Some checks failed
validate-scripts / validate-scripts (push) Has been cancelled
Details
docs: clarify STEP-061 handoff baseline
2026-09-08 23:02:54 +08:00

12 KiB
Raw Blame History

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
  • STEP-060 closeout baseline commit：3d34ec7628d6b429d223a9022f05a9192a0a8d4d
  • 新窗口开始时必须实时查询 particle/main 的 local HEAD / remote HEAD；不得把本文件中的历史 commit 当作当前 HEAD
  • 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。 建议命令：

tmux new-window -t particle-codex -n step061 -c /mnt/sda1/MapLibreParticleLab

用户查看：

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。 已验证启动方式：

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。

cd /mnt/sda1/MapLibreParticleLab/platform/android
JOBS=1 RENDERER=opengl BUILDTYPE=Release make apackage

必须确认输出含 --max-workers=1，并最终 BUILD SUCCESSFUL。 随后在同一 window：

./gradlew :MapLibreAndroid:publishOpenglreleasePublicationToMavenLocal --console=plain

再比较 build output 与 Maven Local AAR：

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 命中旧产物，例如：

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= 下载。 然后：

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 目录执行：

$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，除非用户在当次任务中再次明确授权。 固定命令：

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 历史。

Reference in New Issue View Git Blame Copy Permalink