155 lines
8.2 KiB
Markdown
155 lines
8.2 KiB
Markdown
# MapLibreParticleLab — Codex / ChatGPT RDC 总规则
|
||
|
||
本文件是 Codex 与 ChatGPT Remote Desktop Commander（RDC）进入本仓库后的第一入口。
|
||
|
||
## 1. 开始工作前必须读取
|
||
|
||
任何修改、构建、Git、发布、同步或设备操作前，必须先读取：
|
||
|
||
1. 根目录 `AGENTS.md`（本文件）；
|
||
2. 根目录 `PARTICLE_BASELINE.md`；
|
||
3. `docs/00_项目规范/`（包括官方基线来源）；
|
||
4. `docs/00_项目总则/README.md`；
|
||
5. `docs/00_项目总则/` 中 README 标记的全部当前有效总则；
|
||
6. `docs/00_项目总则/当前基线与开发路线_v2.md`（或 README 指定的后续当前版本）；
|
||
7. 当前 Step / 当前任务，以及与本任务直接相关的当前设计、测试或发布文档。
|
||
|
||
不得只依赖聊天记忆、旧窗口摘要或历史 Step 直接修改仓库。
|
||
|
||
## 2. RDC 启动规则
|
||
|
||
ChatGPT 使用 RDC 对本仓库进行实际操作时，必须把上面的阅读步骤作为固定启动流程。RDC 本身不会自动读取 `AGENTS.md`，因此由 ChatGPT 在第一次写文件、执行构建、Git、发布或设备命令前主动完成。
|
||
|
||
开始实际修改前至少确认：
|
||
|
||
- 当前机器/设备；
|
||
- 仓库绝对路径；
|
||
- 当前 branch；
|
||
- 当前 HEAD；
|
||
- `git status`；
|
||
- 与任务有关的当前版本号/发布坐标。
|
||
|
||
## 3. 冲突与事实优先级
|
||
|
||
若文档与代码/构建事实冲突，不得自行猜测或用旧规则覆盖当前实现。按以下顺序处理：
|
||
|
||
1. Git 当前代码与实际构建/运行结果 = 实现事实；
|
||
2. 当前基线与项目总则 = 设计与流程意图；
|
||
3. 当前 Step/任务 = 本轮工作合同；
|
||
4. 历史 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 固定切换流程
|
||
|
||
默认工作流：
|
||
|
||
1. ChatGPT/用户先明确设计边界与任务目标；
|
||
2. 需要大规模实现时交给 Codex；
|
||
3. Codex 完成任务书范围后停止，不继续承担最终环境验收；
|
||
4. 切换到 RDC，重新读取 `AGENTS.md`、当前基线、Codex 交付文件和 Git diff；
|
||
5. RDC 做独立审计，并负责实际编译、测试、artifact、发布、下载、安装、Metro/ADB/模拟器和日志验证；
|
||
6. 若审计发现小型明确问题，可由 RDC 直接修正并重新验证；
|
||
7. 若发现架构性问题、跨模块大改或修改范围明显扩大，停止 RDC 扩改，重新生成/调整 Codex 任务再进入实现；
|
||
8. 最终以 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 执行编译 / 测试
|
||
|
||
本项目固定采用以下闭环，除非用户在当前任务中明确另行授权：
|
||
|
||
1. **Codex 负责实现与修复。**
|
||
- 读取当前任务、设计、源码与错误信息；
|
||
- 修改代码、测试代码、构建脚本和任务要求的文档；
|
||
- 分析 RDC 返回的编译、链接、测试、codegen、打包失败；
|
||
- 根据真实错误继续修复代码。
|
||
|
||
2. **RDC / 普通 Terminal 负责实际编译与验证。**
|
||
- CMake / Ninja / Bazel 编译；
|
||
- C++ / OpenGL / Metal 定向测试；
|
||
- codegen、链接、打包、artifact 检查；
|
||
- 其他耗时构建或机械性验证。
|
||
Codex 不应自行启动、等待或轮询这些长时间命令。
|
||
|
||
3. **固定闭环：**
|
||
`Codex 写代码 → Codex 停止并给出精确验证命令 → RDC 执行 → RDC 返回结果 → 若失败，Codex 分析并修复 → RDC 再验证`。
|
||
|
||
4. **失败日志只回传必要信息。**
|
||
- RDC 保留完整 stdout/stderr；
|
||
- 成功时只返回 exit code、耗时和必要摘要；
|
||
- 失败时优先返回首个真实 error、相关 target、前后必要上下文和日志路径；
|
||
- 不把完整大型 build log 反复送入 Codex。
|
||
|
||
5. **Codex 禁止行为。**
|
||
- 未经用户明确授权，不得自行执行长时间编译、链接、codegen、打包或大型测试；
|
||
- 不得创建 background terminal 等待 build；
|
||
- 不得高频轮询构建状态；
|
||
- 不得为了等待编译而自行切换模型或启动第二个 Codex 实例；
|
||
- 不得把“编译未完成”当作理由持续占用高能力模型。
|
||
|
||
6. **RDC 发现问题后的处理。**
|
||
- RDC 可以直接处理范围明确、风险低、原因清楚的小问题，包括：
|
||
- 构建命令、CMake/Bazel 配置、链接配置、平台条件、测试条件等小型工程问题；
|
||
- 单文件或少量文件内、无需重新设计架构的小型源码修正；
|
||
- 明确的编译错误、声明/定义不一致、include/宏条件、简单 ABI/平台兼容问题；
|
||
- 不改变既定业务语义和总体架构的局部修复。
|
||
- RDC 修完后应立即重新编译/测试验证，不必为了这类小问题启动 Codex。
|
||
- 以下情况才交给 Codex：
|
||
- 大规模逻辑修改；
|
||
- 跨模块或跨层重构；
|
||
- renderer / runtime / API 设计需要重新判断；
|
||
- 需要新增较完整功能或大量代码；
|
||
- 用户明确指定“这是 Codex 代码任务”。
|
||
- 一旦 RDC 判断修复范围开始扩大、需要重新设计或无法通过少量明确修改解决，应停止继续扩改，把错误证据和现状交给 Codex。
|
||
|
||
7. **用户可见性。**
|
||
- 本项目未经用户明确授权，不得使用后台/headless Codex 执行任务；
|
||
- Codex 默认运行在用户可见的 Terminal/TUI 中；
|
||
- 当前 Mac 上如需启动或恢复 Codex，必须优先使用现有 GNU Screen 会话 `7445.codex`；
|
||
- 不得另起隐藏的 Codex 进程或新的不可见会话，除非用户明确授权；
|
||
- 用户应能够通过该 screen 会话直接看到 Codex 的输入、输出和当前状态。
|
||
|
||
8. **任务书冲突处理。**
|
||
- 若旧任务书写有“Codex 必须执行编译/测试”，但用户未在当前任务明确重新授权，则以本节为准：
|
||
Codex 只准备代码与验证命令，RDC 负责实际执行。
|
||
- 只有用户在当前任务中明确要求“由 Codex 执行某项编译/测试”时，Codex 才可执行该项。
|
||
|
||
核心原则：
|
||
|
||
> Codex 负责写和改；RDC 负责跑和验；RDC 报错，再交回 Codex 修。
|