PRAM/simba-rmic-2026
2
0
Fork 0
Code Pull Requests Actions 4 Releases Activity
Files
6a0eb14b28270c8a7030a7de962920c90a581021
simba-rmic-2026/AGENTS.md
T
sloray 6a0eb14b28
构建客户端 / 检查（类型 + 单元测试） (push) Waiting to run
Details
构建客户端 / Linux x64（deb + AppImage） (push) Blocked by required conditions
Details
构建客户端 / Windows x64（NSIS 安装包） (push) Blocked by required conditions
Details
构建客户端 / macOS 通用（.app + .dmg） (push) Blocked by required conditions
Details
docs: 整理项目文档并统一界面表述 
将项目说明按主题集中到 docs，补齐根目录 README 和 AGENTS，移除弃用方案并保留有效测试记录与未实现提案。同步文档索引、引用及改动日志生成路径，README 增加 GitHub Markdown 导航和 Mermaid 图。

- fix(client): 统一状态与操作文案，录制和截图成功后再显示完成提示
- test(client): 按文件名核对媒体类型，避免依赖时间戳排序

验证：23 份项目文档、144 处本地引用、27 条外链、2 张 Mermaid 图；前端构建和 12 项测试；截图与录制的 4 条异步反馈路径；Windows Rust 编译检查和后端测试。后端 40 项返回成功，其中 3 项 ffmpeg 集成用例因本机缺少工具而未实际执行。
2026-10-19 11:26:26 +08:00

126 lines
9.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 仓库协作约定
本文件适用于整个仓库，供开发者和代码助手使用。先阅读 [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)。
View Git Blame Copy Permalink