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 一并提交。

4.7 KiB Raw Blame History Unescape Escape