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

9.8 KiB
Raw Blame History

仓库协作约定

本文件适用于整个仓库，供开发者和代码助手使用。先阅读 README.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 锁文件。

环境准备和平台细节见固件入门、客户端说明和装甲板说明。

修改方式

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

协议与实时图传

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

桌面端与文案

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

硬件、配置与源码保护

  • 不提交 Wi-Fi 凭据、密码哈希、个人 SDK 绝对路径或本机缓存；不要在日志和交付说明中输出 .env 内容。保留已有 .env，示例使用占位值。
  • 仅做软件、文档或文案任务时，不执行烧录、擦除、写分区表或修改设备安全配置。涉及硬件任务时，按用户授权核对芯片、端口、分区与备份。
  • components/esp32-camera/target/ 是驱动源码目录，不能按构建缓存删除或忽略。清理缓存时使用明确的构建目录，相关方法见开发与验证。
  • 第三方组件的 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；硬件表现另行实测
版本生成脚本或生成路径 隔离样例检查输出位置与重复生成，再运行版本一致性检查

常用主机命令

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/ 执行：

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 提交数计算。

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

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 的版本字段也由同一脚本同步；其他字段按任务正常维护。提交或标签改变后，按发布流程重新生成；文档路径变更不得使日志重新出现在根目录。

完整规则见版本维护。

View Git Blame Copy Permalink