MapLibreParticleLab — Codex / ChatGPT RDC 总规则

本文件是 Codex 与 ChatGPT Remote Desktop Commander（RDC）进入本仓库后的第一入口。

1. 开始工作前必须读取

任何修改、构建、Git、发布、同步或设备操作前，必须先读取：

根目录 AGENTS.md（本文件）；
根目录 PARTICLE_BASELINE.md；
docs/00_项目规范/（包括官方基线来源）；
docs/00_项目总则/README.md；
docs/00_项目总则/ 中 README 标记的全部当前有效总则；
docs/00_项目总则/当前基线与开发路线_v2.md（或 README 指定的后续当前版本）；
当前 Step / 当前任务，以及与本任务直接相关的当前设计、测试或发布文档。

不得只依赖聊天记忆、旧窗口摘要或历史 Step 直接修改仓库。

2. RDC 启动规则

ChatGPT 使用 RDC 对本仓库进行实际操作时，必须把上面的阅读步骤作为固定启动流程。RDC 本身不会自动读取 AGENTS.md，因此由 ChatGPT 在第一次写文件、执行构建、Git、发布或设备命令前主动完成。

开始实际修改前至少确认：

当前机器/设备；
仓库绝对路径；
当前 branch；
当前 HEAD；
git status；
与任务有关的当前版本号/发布坐标。

3. 冲突与事实优先级

若文档与代码/构建事实冲突，不得自行猜测或用旧规则覆盖当前实现。按以下顺序处理：

Git 当前代码与实际构建/运行结果 = 实现事实；
当前基线与项目总则 = 设计与流程意图；
当前 Step/任务 = 本轮工作合同；
历史 Step/旧验收文档 = 历史证据，不自动代表当前流程。

发现冲突时先报告并限定修改范围；除非任务明确要求，不重写历史文档来伪装一致。

4. 项目固定边界

项目目标：在 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；不得复制 Mapbox 新源码或 Windy APK 内代码。

Host/NavSea 负责 provider、HTTP、manifest、下载、缓存和业务调度；MapLibre Native 从宿主提交的 canonical/encoded field 开始负责校验、解码、Runtime Field Window 与 GPU 渲染。

5. Codex 与 RDC 的职责分工

Codex 主要负责

大规模源码修改与跨文件重构；
新功能实现、接口调整、批量工程化修改；
按 Codex 任务书完成明确范围内的代码与文档变更；
需要较长连续编辑、依赖全仓上下文的实现工作。

Codex 的核心角色是“实现者”，不作为其自身修改结果的唯一最终验收者。

RDC 主要负责

编译、链接、codegen、运行测试程序与测试命令；
AAR/APK/npm tgz 等 artifact 的构建、检查、发布与下载；
公网发布后的回读、SHA-256/版本/文件内容验证；
Win11、Linux、模拟器、ADB、Metro、安装、启动和运行态检查；
日志、进程、端口、文件系统、Git 状态与构建产物审计；
对 Codex 完成结果做独立代码/配置/文档/构建审计；
小范围、事实明确、风险可控的修正。

6. Codex → RDC 固定切换流程

默认工作流：

ChatGPT/用户先明确设计边界与任务目标；
需要大规模实现时交给 Codex；
Codex 完成任务书范围后停止，不继续承担最终环境验收；
切换到 RDC，重新读取 AGENTS.md、当前基线、Codex 交付文件和 Git diff；
RDC 做独立审计，并负责实际编译、测试、artifact、发布、下载、安装、Metro/ADB/模拟器和日志验证；
若审计发现小型明确问题，可由 RDC 直接修正并重新验证；
若发现架构性问题、跨模块大改或修改范围明显扩大，停止 RDC 扩改，重新生成/调整 Codex 任务再进入实现；
最终以 RDC 实际环境验证结果 + Git 当前代码作为验收事实。

禁止默认让 Codex 同时承担“大规模实现 + 唯一审计 + 唯一最终环境验证”三种角色。

7. 记录与收尾

每一阶段必须有 docs/50_Step记录/STEP-xxx_*.md。完成报告固定写入 docs/报告/STEP-xxx_<主题>_Codex完成报告_vN.md（仅在任务要求 Codex 完成报告时）。

修改结束必须按当前构建规范验证、更新 Step、追加 粒子开发记录.md，并明确所有未完成/阻塞。Git 提交必须 scoped，禁止把既有无关 dirty/untracked 一并提交。

8. Codex 写代码，RDC 执行编译 / 测试

本项目固定采用以下闭环，除非用户在当前任务中明确另行授权：

Codex 负责实现与修复。
- 读取当前任务、设计、源码与错误信息；
- 修改代码、测试代码、构建脚本和任务要求的文档；
- 分析 RDC 返回的编译、链接、测试、codegen、打包失败；
- 根据真实错误继续修复代码。
RDC / 普通 Terminal 负责实际编译与验证。
- CMake / Ninja / Bazel 编译；
- C++ / OpenGL / Metal 定向测试；
- codegen、链接、打包、artifact 检查；
- 其他耗时构建或机械性验证。 Codex 不应自行启动、等待或轮询这些长时间命令。
固定闭环： Codex 写代码 → Codex 停止并给出精确验证命令 → RDC 执行 → RDC 返回结果 → 若失败，Codex 分析并修复 → RDC 再验证。
失败日志只回传必要信息。
- RDC 保留完整 stdout/stderr；
- 成功时只返回 exit code、耗时和必要摘要；
- 失败时优先返回首个真实 error、相关 target、前后必要上下文和日志路径；
- 不把完整大型 build log 反复送入 Codex。
Codex 禁止行为。
- 未经用户明确授权，不得自行执行长时间编译、链接、codegen、打包或大型测试；
- 不得创建 background terminal 等待 build；
- 不得高频轮询构建状态；
- 不得为了等待编译而自行切换模型或启动第二个 Codex 实例；
- 不得把“编译未完成”当作理由持续占用高能力模型。
RDC 发现问题后的处理。
- RDC 可以直接处理范围明确、风险低、原因清楚的小问题，包括：
  - 构建命令、CMake/Bazel 配置、链接配置、平台条件、测试条件等小型工程问题；
  - 单文件或少量文件内、无需重新设计架构的小型源码修正；
  - 明确的编译错误、声明/定义不一致、include/宏条件、简单 ABI/平台兼容问题；
  - 不改变既定业务语义和总体架构的局部修复。
- RDC 修完后应立即重新编译/测试验证，不必为了这类小问题启动 Codex。
- 以下情况才交给 Codex：
  - 大规模逻辑修改；
  - 跨模块或跨层重构；
  - renderer / runtime / API 设计需要重新判断；
  - 需要新增较完整功能或大量代码；
  - 用户明确指定“这是 Codex 代码任务”。
- 一旦 RDC 判断修复范围开始扩大、需要重新设计或无法通过少量明确修改解决，应停止继续扩改，把错误证据和现状交给 Codex。
用户可见性。
- 本项目未经用户明确授权，不得使用后台/headless Codex 执行任务；
- Codex 默认运行在用户可见的 Terminal/TUI 中；
- 当前 Mac 上如需启动或恢复 Codex，必须优先使用现有 GNU Screen 会话 7445.codex；
- 不得另起隐藏的 Codex 进程或新的不可见会话，除非用户明确授权；
- 用户应能够通过该 screen 会话直接看到 Codex 的输入、输出和当前状态。
任务书冲突处理。
- 若旧任务书写有“Codex 必须执行编译/测试”，但用户未在当前任务明确重新授权，则以本节为准： Codex 只准备代码与验证命令，RDC 负责实际执行。
- 只有用户在当前任务中明确要求“由 Codex 执行某项编译/测试”时，Codex 才可执行该项。

核心原则：

Codex 负责写和改；RDC 负责跑和验；RDC 报错，再交回 Codex 修。

8.2 KiB Raw Blame History Unescape Escape