From 3896c461fae8fad842721a5f4d782ad96291aadd Mon Sep 17 00:00:00 2001
From: OpenAI Codex <codex@local>
Date: Mon, 14 Sep 2026 10:26:29 +0800
Subject: [PATCH] docs: define Codex and RDC working roles

---
 AGENTS.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 85 insertions(+), 5 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index e25036d04..5f14c4c46 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,11 +1,91 @@
-# MapLibreParticleLab — Codex 总规则
+# MapLibreParticleLab — Codex / ChatGPT RDC 总规则
 
-任何修改前必须阅读 `PARTICLE_BASELINE.md`、`docs/00_项目规范/`（包括官方基线来源）、当前 Step 和当前任务。
+本文件是 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；第一阶段只用离线 fixture；不得复制 Mapbox 新源码或 Windy APK 内代码。
+固定边界：正式实现不使用 React Native/WebView/外部 Overlay；粒子模块高度隔离；官方原文件只做薄接入；Android/iOS 共用 C++ Core；WeatherColorLayer 与 RasterParticleLayer 分离；Wind=GLOBAL；Wave/Tide/Current=OCEAN_ONLY 且共用 Land/Ocean Mask；不得复制 Mapbox 新源码或 Windy APK 内代码。
 
-每一阶段必须有 `docs/50_Step记录/STEP-xxx_*.md`。完成报告固定写入 `docs/报告/STEP-xxx_<主题>_Codex完成报告_vN.md`。
+Host/NavSea 负责 provider、HTTP、manifest、下载、缓存和业务调度；MapLibre Native 从宿主提交的 canonical/encoded field 开始负责校验、解码、Runtime Field Window 与 GPU 渲染。
 
-修改结束必须按构建规范验证、更新 Step、追加 `粒子开发记录.md`、生成中文完成报告，并明确所有未完成/阻塞。
+## 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 一并提交。