RoboMaster 2026 超级对抗赛桌面客户端，使用 React、TypeScript 和 Tauri。
当前是可在本机完整联调的开发版本，尚未通过比赛设备验收。 操作台已接通真实本机 MQTT / V2 Protobuf，以及 UDP / HEVC 图传。正式比赛网络仍锁定。
| 功能 | 当前状态 |
|---|---|
| 比赛状态、机器人选择、视频/地图双视图、全屏 | 可用 |
| 本机 MQTT broker → Rust → V2 Protobuf → 操作台 | 已做桌面端到端验证 |
| MQTT 连接确认、broker 重启后重新订阅 | 已验证 |
| 哨兵指令 → 模拟器 → SentryCtrlResult 回执 | 成功、拒绝、超时路径已验证 |
| 异常包计数、缺失/过期字段隐藏、诊断导出 | 可用 |
| 本机 UDP HEVC 播放 | 320×180 合成样本实测约 60 FPS |
| 真实裁判系统、正式控制输入、1080p60 实机性能 | 待设备联调 |
| 雷达完整解析、地图实地标定、角色权限与全部比赛指令 | 尚未完成 |
本文描述当前入口。docs 中带历史版本号的文档保留为开发记录，不代表当前运行状态。
推荐 Windows 10/11 x64，安装：
| 工具 | 用途 |
|---|---|
| Git | 获取源码 |
| Node.js 22.12+ 或受支持的新版本，附带 npm | 前端、内置 MQTT 模拟器 |
| Rust stable，MSVC 工具链 | 编译 Tauri 后端 |
| Visual Studio Build Tools：Desktop development with C++、Windows SDK | Windows 编译与链接 |
| Microsoft Edge WebView2 Runtime | 桌面界面与 WebCodecs |
| Python 3.10+（视频模拟时需要） | 发送 HEVC 样本，无需额外 pip 包 |
安装依赖参见 Tauri 官方前置条件。 浏览器预览只需要 Git 和 Node.js；实际 MQTT TCP / UDP 必须使用桌面版。 HEVC 解码依赖当前 WebView2 和系统环境，客户端会报告不支持或配置失败。
PowerShell 检查：
node --version
npm --version
rustc --version
cargo --version
py --versiongit clone https://github.com/JFCY2718/rmuc-custom-client-ui.git
cd rmuc-custom-client-ui
npm ci已有仓库先保存自己的修改，再更新分支。使用 npm ci 安装锁文件规定的版本。 内置模拟器已经包含 broker，不需要另装 Mosquitto、Docker 或 paho-mqtt。
可选：把 Rust 缓存放到空间充足的磁盘，仅对当前终端设置：
$env:CARGO_TARGET_DIR = "D:\rmuc-build-cache\target"不设置时默认输出到 src-tauri/target。下面每个终端都要先进入项目根目录。
npm run tauri:dev该命令自动启动 Vite 和桌面程序，首次 Rust 编译较慢，默认进入演示模式。 不要同时运行多个桌面实例，避免 WebView2 数据目录和网络端口争用。
只看界面可运行 npm run dev，打开 http://localhost:5173；浏览器不能连接原生 MQTT 或图传。
- 顶部切换“视频作战 / 战术态势”，快捷键 V。
- F 切换全屏，Esc 关闭面板或退出全屏；输入框和对话框中不触发视图快捷键。
- 点击机器人列表或地图编号切换观察对象。
- 地图“红方/蓝方视角”只改变显示方向，不改变连接的己方颜色。
- “本地标记”只在本机显示；点击地图，或聚焦地图后用方向键和 Enter 放置，不发送比赛指令。
- “设置 → 进入工作台”打开原协议诊断与布局工具；进入前会清理图传和 MQTT 会话。
终端 A：启动模拟器
npm run simulator出现 READY mqtt://127.0.0.1:1883 后，broker 和数据发送均已运行。 它按 V2 Protobuf 发送比赛、基地/前哨站、后勤、当前机器人静态/动态/位置、哨兵和空中支援状态。
终端 B：启动客户端
npm run tauri:dev进入 设置 → 本机 MQTT 联调，保持默认端口 1883、红方、英雄，点击 连接本机 MQTT。 看到“MQTT 已连接”且收包数递增后关闭设置。
默认数据应为：
- 顶部“本机 MQTT”，比赛阶段“比赛进行中”。
- 红方基地 1450、蓝方基地 1234、队伍经济 250。
- 英雄 HP 480、弹量 97，热量和位置随时间变化。
- 未收到的属性显示 —；其他机器人没有下发的热量、最大血量不会沿用演示值。
动态消息不携带机器人 ID，由连接配置和 RobotStaticStatus 确定归属。 点击其他观察对象不会把收到的数据改归别人。
更换端口、队色或机器人
先“断开并返回演示”，停止模拟器（Ctrl+C），例如：
npm run simulator -- --port 1884 --team blue --robot 7客户端设置端口 1884、蓝方、哨兵，再连接。模拟器编号为 1/2/3/4/5/6/7； 蓝方发送时自动使用 101…107。己方/对方基地会投影到正确的红蓝两侧。
设置保存在本机，下次自动填入，不会自动连接。地址固定为 127.0.0.1。 地图默认 28×15 米只是本地预览换算设置，不能代替实地标定。
连接 MQTT 后，点击 指令联调：
- 选择哨兵指令，例如“防御姿态”。
- 点击“发送联调指令”，再确认发送到本机模拟器。
- 模拟器输出 COMMAND {"command_id":8}。
- 客户端显示“模拟器确认成功”。
使用 V2 的 SentryCtrlCommand / SentryCtrlResult，一次只等待一条回执。 5 秒没有回执则显示“执行结果未知”，不会自动重发。 协议没有客户端事务 ID；结果未知的同编号指令需要重新连接后再联调，避免迟到回执误匹配。 其他比赛指令、键鼠连续控制尚未接入该发送入口。
图传独立于 MQTT。桌面操作台点击 连接本地图传，另开终端：
py -3 simulator/video_sender.py --loops 100应出现仓库提供的彩条动态图像，尺寸 320×180，帧率接近 60 FPS。 发送结束后显示“视频中断”；“断开图传”释放 UDP 3334。 主视图切换不会重建解码会话。
发送自己的 Annex B HEVC 文件前查看参数：
py -3 simulator/video_sender.py --help文件需每帧有 AUD，关键帧带 VPS/SPS/PPS；codec 可在设置中调整。 当前没有捆绑 FFmpeg/原生解码回退。详见 视频运行时。
停止已有模拟器，再使用下面参数。每次更换场景前断开客户端，再重新连接。
| 场景 | 命令 | 预期 |
|---|---|---|
| 拒绝指令 | npm run simulator -- --ack reject | 模拟器拒绝 |
| 丢弃回执 | npm run simulator -- --ack drop | 5 秒后结果未知 |
| 每 10 tick 插入异常包 | npm run simulator -- --malformed-every 10 | 异常计数增加，正常遥测继续 |
| 3 秒后停止遥测但保留连接 | npm run simulator -- --pause-after 3 | 过期数值隐藏 |
| broker 重启 | Ctrl+C 停止，再运行 npm run simulator | 断线后重连、恢复订阅 |
设置面板显示收包、异常、重连和丢弃计数；导出诊断下载 JSON 报告。 重连有退避等待，最多 10 次失败后停止；此时显式断开再连接。 收包数证明传输活动，字段是否有效仍以各自更新时间为准。
| 现象 | 处理 |
|---|---|
| 连接按钮不可用 | 使用桌面版；连接期间和已连接时设置锁定 |
| 8 秒内未收到 broker 确认 | 检查模拟器是否 READY、端口是否一致；不要填比赛设备地址 |
| EADDRINUSE | 停止旧模拟器或更换端口，客户端同步修改 |
| 属性显示 — | 检查机器人身份和对应消息；未下发属性本来就未知 |
| HEVC 不支持 / 配置失败 | 检查 WebView2、系统 HEVC 能力和 codec；先用仓库样本排除码流问题 |
| 视频中断 | 检查发送进程、UDP 3334、本地地址；MQTT 正常不代表图传正常 |
| link.exe / SDK 缺失 | 安装 C++ 桌面开发及 Windows SDK，重开终端 |
| cargo / py 找不到 | 安装对应工具并重开终端，或使用 Python 完整路径 |
| 第二个窗口不出现 / exe 无法覆盖 | 关闭旧客户端后再启动或构建 |
npm run tauri:build当前生成 exe，不生成安装包：
- 默认：src-tauri/target/release/rmuc-custom-client-ui.exe
- 设置过 CARGO_TARGET_DIR：该目录下的 release/rmuc-custom-client-ui.exe
运行 exe 不需要 Vite；接收机器仍需 WebView2 和可用的 HEVC 环境。 复制前先退出旧版本。
原工作台的 official_locked 模式保持禁用网络；本机联调从操作台设置进入。 历史流程见 团队交接指南，当前能力以本文为准。
npx vitest run src/state/live/liveTelemetry.test.ts src/lib/tauri/runtime.test.ts src/protocol/official/__tests__/officialV2MessageNormalizer.test.ts
cargo test --manifest-path src-tauri/Cargo.toml mqtt_runtimeGitHub CI 执行前端格式/lint/类型/单测/构建、Rust fmt/clippy/check/test、Python 图传测试及仓库协议验证。
可复现的桌面 MQTT 冒烟：
$env:WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS = "--remote-debugging-port=9223"
npm run tauri:dev
# 在另一个项目终端，确保 Node 能找到 Playwright：
node scripts/ui/smoke-mqtt.cjs脚本自带测试 broker（仅本机 18884），测试后停止。需要独立安装的 Playwright， 可通过 NODE_PATH 指向已有安装。测试后关闭客户端和终端；普通启动不主动开启调试端口。 界面/视频脚本分别为 scripts/ui/smoke-operator.cjs 和 scripts/video/smoke-hevc.cjs。
当前无真实裁判系统硬件证据，不能宣称比赛可用。设备到位后需要：
- 校验真实 V2 抓包、阵营/机器人身份及全部所需 topic。
- 明确雷达线格式，完成地图标定与角色权限。
- 实现并验收所需比赛控制输入、指令与回执。
- 验收实际 UDP 码流、1920×1080@60 解码、延迟及长时间稳定性。
- 在明确设备配置下开放实验室网络入口，完成比赛环境验收。
官方协议参数：设备 broker 192.168.12.1:3333、客户端 IP 192.168.12.2、图传 UDP 3334。 这不表示当前版本已经开放该连接。 证据与剩余工作见 本机联调说明。
参考 ClearWei/RM26_Client （社区项目，复旦大学星云 EGA，并非官方客户端）。 快照：e291f2f65f5a5924509e4e2fe1b148ff9d4b24af。
- 原样复用赛场底图及 hero/engineer/infantry/sentry/drone 图标。
- 借鉴视频/战术双视图和地图镜像处理。
- 协议对照其 MQTT 定义与模拟器发布顺序，再以所提供的 V2.0.0 PDF 为准。
- 保留本项目 React/Tauri、MQTT runtime、视频会话和验证工具，没有迁入整套 Qt 工程。