92 lines
4.7 KiB
Markdown
92 lines
4.7 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 一并提交。
|