# 仓库协作约定

本文件适用于整个仓库，供开发者和代码助手使用。先阅读 [README.md](README.md) 与 [文档首页](docs/index.md)，再按任务进入对应子项目。子目录若新增更具体的 `AGENTS.md`，按其适用范围执行。

## 项目边界

RMIC::2026 包含 ESP32-S3 图传固件、ESP32-C3 装甲板固件和 Tauri 桌面端。它们共享部分协议代码，但不共享同一个构建目标。

| 路径 | 修改内容 | 需要注意 |
| --- | --- | --- |
| `src/`、根 `build.rs` | S3 采集、发送、重连及构建参数 | Rust `std` + ESP-IDF，默认目标为 Xtensa |
| `components/cam_wrapper/` | 相机 C/Rust FFI | 同步核对 C 结构体、绑定与缓冲所有权 |
| `components/esp32-camera/` | 本地驱动及补丁 | 保留上游结构和本地补丁说明 |
| `protocol/` | 线路编解码与帧重组 | 固件和桌面共用，保持协议兼容性 |
| `desktop/core/` | 网络、配置、密码、装甲板与槽位 | 保持独立于 UI 与 Tauri，可单独测试 |
| `desktop/src-tauri/` | 本地通道、命令、录制与维护 | 涉及文件、子进程、串口及 WebView 边界 |
| `desktop/src/` | React、TypeScript、canvas 与样式 | 复用已有组件、绘制函数和样式令牌 |
| `armor/` | C3 固件与受击规则 | 独立 workspace，目标为 RISC-V |
| `scripts/` | 构建、打包、版本和诊断 | 修改入口或输出路径时同步文档与调用方 |
| `reference/armor/` | 早期 C 版参考工程 | 默认用于核对，不作为当前实现入口 |

## 工具链与执行目录

- 根 `rust-toolchain.toml` 固定为 `esp-1.97.0.0`，根 `.cargo/config.toml` 默认目标是 `xtensa-esp32s3-espidf`，并启用 `build-std`。
- `desktop/` 使用 Rust stable，但默认 Cargo 目标仍为 `aarch64-apple-darwin`；`protocol/` 和 `armor/armor-protocol/` 也有宿主目标覆盖。换平台时显式传入实际目标。
- Windows x64 的宿主目标是 `x86_64-pc-windows-msvc`。主机检查显式使用 `+stable`、`--target` 和 `--config 'unstable.build-std=[]'`，避免继承固件配置。
- S3 默认 ESP-IDF 为 v5.5.5；装甲板原环境使用 v6.0.1。`armor/.cargo/config.toml` 含原开发机的 `IDF_PATH`，构建前核对，不假设该路径在其他机器存在。
- Cargo 根据执行目录查找 `.cargo/config.toml`；仅传 `--manifest-path` 不会自动切换到对应子项目的配置。需要依赖子项目配置时，先进入该目录。
- 固件通过 `scripts/build.ps1` 或 `scripts/build.sh` 构建，以加载 `.env` 并设置组件、分区表路径。直接执行 `cargo build` 不会自动加载 `.env`。
- 桌面前端使用 pnpm 和 `desktop/pnpm-lock.yaml`，安装时优先 `pnpm install --frozen-lockfile`。不要同时维护 npm / Yarn 锁文件。

环境准备和平台细节见[固件入门](docs/setup/firmware.md)、[客户端说明](docs/desktop/client.md)和[装甲板说明](docs/hardware/armor.md)。

## 修改方式

1. 开始前检查工作区差异，保留用户已有的修改；先定位行为所在模块，再修改对应层。
2. 沿用现有命名、格式和模块划分。代码助手只处理任务相关变更，避免顺带重排全仓库、升级依赖或改动其他平台配置。
3. 修改行为时补充能覆盖该行为的验证；纯文档或文案调整检查链接、命令、类型和显示效果即可。
4. 完成后检查差异与空白问题，说明改了什么、做了哪些验证，以及仍未验证的范围。

### 协议与实时图传

- 线路定义以 `protocol/` 为准。修改字段、头长、消息类型或版本时，同时核对固件、桌面、`scripts/udp_probe.py` 等独立探测器和[协议文档](docs/protocol/udp.md)。
- 视频帧必须按发送方和帧号隔离，重复分片不重复计数，不完整 JPEG 不进入解码和绘制。
- 保留最新帧优先、有界等待和过期清理。不要让接收线程等待视频解码、写盘或 UI 消费，也不要以无限队列掩盖拥塞。
- 修改 C 相机缓冲交接时，检查获取、归还、超时和提前返回路径，避免重复归还或泄漏。
- 用户端绑定过滤、发现列表和裁判槽位有不同职责，不要为了显示候选设备而放开用户端视频接收限制。

### 桌面端与文案

- 业务规则放在 Rust 核心，前端使用既有快照与 IPC 接口；新增设置需核对配置序列化、默认值和旧配置兼容性。
- 画面、准星、网格和命中反馈复用现有变换与绘制函数。改文案或布局后，按影响范围检查用户端、裁判端、设置和首次启动页面。
- 中文表达清楚、具体，写明状态、条件和下一步。保留术语、错误原因、数字与验证边界，避免比喻式按钮和含糊的成功提示。
- 密码限制用于防止现场误改；包内哈希校验用于检查完整性。文案不能将它们描述为不可绕过的访问控制或固件来源认证。
- 预览和演示数据始终标明为合成数据，不用演示结果替代实际网络或硬件验证。

### 硬件、配置与源码保护

- 不提交 Wi-Fi 凭据、密码哈希、个人 SDK 绝对路径或本机缓存；不要在日志和交付说明中输出 `.env` 内容。保留已有 `.env`，示例使用占位值。
- 仅做软件、文档或文案任务时，不执行烧录、擦除、写分区表或修改设备安全配置。涉及硬件任务时，按用户授权核对芯片、端口、分区与备份。
- `components/esp32-camera/target/` 是驱动源码目录，不能按构建缓存删除或忽略。清理缓存时使用明确的构建目录，相关方法见[开发与验证](docs/development/firmware.md#清理构建缓存)。
- 第三方组件的 README、许可证和本地补丁记录保留原有位置。不要把参考工程的旧实现误写成当前功能。

## 按变更选择验证

以下命令默认从仓库根目录执行，标明其他目录的除外。示例宿主为 Windows x64；其他平台用 `rustc +stable -vV` 核对 host 后替换 `--target`。

| 变更 | 至少检查 |
| --- | --- |
| 文档、链接、导航 | 文件与锚点有效，代码块闭合，命令路径正确；Mermaid 语法可解析 |
| React / TypeScript / UI 文案 | `desktop/` 下 `pnpm build`，并预览受影响页面 |
| 前端解码队列 | `desktop/` 下 `pnpm test:stream` |
| 延迟校准标记 | `desktop/` 下 `pnpm test:latency` |
| 线路编解码、帧重组 | `protocol/` 主机测试，必要时独立协议探测 |
| 桌面业务规则 | `desktop/core/` 主机测试 |
| Tauri 命令、录制、维护 | 后端编译检查和相关单元测试；录制测试需 ffmpeg / ffprobe |
| 装甲板受击规则 | `armor/armor-protocol/` 主机测试 |
| 固件发送、重连、缓冲交接 | 对应主机策略测试或 `scripts/test-latest-frame.py`；硬件表现另行实测 |
| 版本生成脚本或生成路径 | 隔离样例检查输出位置与重复生成，再运行版本一致性检查 |

### 常用主机命令

```powershell
cargo +stable test --locked --manifest-path protocol/Cargo.toml --target x86_64-pc-windows-msvc --config 'unstable.build-std=[]'
cargo +stable test --locked --manifest-path desktop/core/Cargo.toml --target x86_64-pc-windows-msvc --config 'unstable.build-std=[]'
cargo +stable test --locked --manifest-path armor/armor-protocol/Cargo.toml --target x86_64-pc-windows-msvc --config 'unstable.build-std=[]'
cargo +stable check --locked --manifest-path desktop/src-tauri/Cargo.toml --target x86_64-pc-windows-msvc --config 'unstable.build-std=[]'
```

前端命令在 `desktop/` 执行：

```sh
pnpm install --frozen-lockfile
pnpm build
pnpm test:stream
pnpm test:latency
```

浏览器预览：`pnpm dev`，打开 `http://127.0.0.1:1420/`；可用 `?preview=referee`、`?preview=first-run`、`?preview=password` 检查不同页面。预览不能验证 Tauri 原生能力。

测试通过后无需重复运行无关的大范围检查。依赖、工具链或设备条件不足时，明确记录实际执行结果和未验证项。**编译、主机测试、镜像生成不等于烧录、板上运行或硬件稳定性已验证。**

## 文档组织

- 根目录 `README.md` 介绍项目、展示架构并链接到详细文档；本文件保存仓库协作约定。子项目 README 保留简短入口。
- 除 README 和 AGENTS 外，项目说明集中到 `docs/`，按 `setup/`、`development/`、`hardware/`、`desktop/`、`protocol/`、`maintenance/`、`testing/`、`releases/`、`design/` 归类。
- 新增或迁移文档时，同步更新 `docs/index.md`、相对链接、标题锚点、脚本和代码中的引用。可复用既有主题时，优先修改原文。
- 已被实现替代或明确放弃的方案可以删除，历史从 Git 查阅；保留仍有价值的实验条件、原始数字和限定。未实现需求写入 `docs/design/` 并标明状态。
- 改写中文时保留事实、数字、命令、否定和确定程度，不将计划写成已完成，不将接收间隔写成端到端延迟。
- README 使用 GitHub 风味 Markdown：表格用于比较，折叠块放可选步骤，提示块强调实际限制，Mermaid 解释结构和流程。使用稳定基础语法，不在图表中加入脚本或外部服务依赖。

## 版本与提交

提交标题采用 Conventional Commits：`type(scope): 说明`。破坏性改动升 major，`feat` 升 minor，`fix` / `perf` 升 patch；其他类型保持语义版本，构建号由 Git 提交数计算。

版本和日志由脚本生成，在根目录执行：

```sh
node scripts/version.mjs --write
node scripts/version.mjs --check
```

不要手动修改 `version.json`、`desktop/src/lib/version.ts` 或 `docs/releases/changelog.md` / `.json`。`desktop/package.json` 和 `desktop/src-tauri/tauri.conf.json` 的版本字段也由同一脚本同步；其他字段按任务正常维护。提交或标签改变后，按发布流程重新生成；文档路径变更不得使日志重新出现在根目录。

完整规则见[版本维护](docs/development/versioning.md)。