docs: 按 humanizer 重写项目文档并同步 RMIC::2026 现状

desktop/README.md

@@ -1,15 +1,15 @@
 # RMIC::2026
 
-黑龙江大学 602 实验室 · Simba Robotics 的**视野链路终端**。
-桌面端。**两种身份，两套页面，一个进程。**
+黑龙江大学 602 实验室 · Simba Robotics 的**视野链路终端**，桌面端。
+两种身份、两套页面，都在同一个进程里。
 
 | 身份 | 画面 | 血量 | 装甲板 | 绑定 |
 |---|---|---|---|---|
 | 用户端（`team`） | 一路 | **双方**（左上角自己 / 右上角对手） | 自己那块 | **要，改动需密码** |
 | 裁判端（`referee`） | 两路并排 | 双方（各自贴画面角上，**队名可改**） | 发现列表 + 槽位 | 不需要 |
 
-界面是 WebView 里的 React（画面画在 canvas 上），后端是 Rust。**它不是把旧客户端套进
-一个窗口**：网络、重组、发现、配置、密码、录制全部重写成了可单测的模块。
+界面是 WebView 里的 React（画面画在 canvas 上），后端是 Rust。它不是把旧客户端套进
+一个窗口：网络、重组、发现、配置、密码、录制全部重写成可单测的模块。
 
 > **名字与数据目录**：显示名是 `RMIC::2026`；安装包与可执行文件叫 `RMIC-2026`（Windows
 > 文件名不允许 `:`）。配置、录制、日志仍落在旧的 `cam-desktop` 目录下——这是**故意的**，
@@ -18,7 +18,7 @@
 ```text
 desktop/
   core/           cam-core：不含任何界面与 Tauri 的东西（83 个测试）
-  src-tauri/      Tauri 后端：推流、命令、录制（32 个测试）
+  src-tauri/      Tauri 后端：推流、命令、录制（40 个测试）
   src/            React 前端：两套页面 + HUD
   src/lib/        IPC 封装、WebSocket 客户端、状态存储、格式化、准星绘制、界面小节拍
   src/components/ 取景器、装甲条、命中、结算、装甲板表、队名、录制、设置抽屉、启动序列、门、提示
@@ -30,8 +30,6 @@ desktop/
 
 ## 界面：一套终端语言
 
-这一栏不是装饰说明，而是"改界面之前该知道的几件事"。
-
 ### 配色：墨黑蓝打底，只有一支红
 
 | 角色 | 值 | 用在哪 |
@@ -43,14 +41,14 @@ desktop/
 | 队伍 | `--team-0 #ff6b5e` / `--team-1 #4a9bff` | **硬件约束**：装甲板 LED 就是红与蓝 |
 
 一条硬规则：**红只给必须被看见的东西**。开关合上是白的、滑杆填充是钢灰、分段控件的选中
-记号是底沿一条 2px 线、分区编号是灰的、顶栏没有任何强调线。当红色出现时，它后面一定有一
-件真事——这就是"只高亮真正重要的信息"落到代码里的样子。
+记号是底沿一条 2px 线、分区编号是灰的、顶栏没有任何强调线。红色出现的地方，后面都有一
+件真事。
 
 队红刻意做得比强调红更暖更浅，否则两条血并列时会被误读成"系统在报警"。
 
 ### 形状：矩形，唯一的斜边给装甲条
 
-全局是矩形：没有圆角、没有切角、没有药丸、没有阴影卡片。**唯一的斜边是装甲条那排平行四边形**
+全局是矩形：没有圆角、切角、药丸，也没有阴影卡片。**唯一的斜边是装甲条那排平行四边形**
 ——它必须在一屏矩形里被一眼认成"这是血，不是别的东西"。别的元素一旦也开始斜切，那个形状
 就不再携带信息了。
 
@@ -166,7 +164,7 @@ node scripts/version.mjs --print   # 把算出来的版本打到 stdout
 
 ### 固件与客户端怎么对上
 
-同一条链贯穿到底：`git → version.json → 固件二进制 → Hello 报文 → 客户端界面`。
+同一条链：`git → version.json → 固件二进制 → Hello 报文 → 客户端界面`。
 
 板子每 2 秒广播的 `Hello` 里带着**语义化版本、构建号、以及它编译进去的线路协议号**
 （布局见 `protocol/README.md`）。客户端读出来之后：
@@ -178,6 +176,7 @@ node scripts/version.mjs --print   # 把算出来的版本打到 stdout
 
 **为什么值得占这 10 个字节**：一块烧错固件的板子，原来只表现为"没画面"，现场会去查网线、
 AP、供电。现在同一个现象会直接指向"重新烧固件"。
+
 ## 快速开始
 
 ```sh
@@ -192,7 +191,7 @@ pnpm tauri build  # 默认打包 macOS 的 .app 与 .dmg；Windows 见下文
 
 ```sh
 cd desktop/core      && cargo test    # 83
-cd desktop/src-tauri && cargo test    # 32，其中几条真的会起 ffmpeg
+cd desktop/src-tauri && cargo test    # 40，其中几条真的会起 ffmpeg
 ```
 
 ### Windows x64 构建
@@ -214,7 +213,7 @@ pnpm tauri build --target x86_64-pc-windows-msvc --bundles nsis --ci -- --locked
 
 视频录制另需可从 `PATH` 找到的 `ffmpeg`，也可以在配置的 `[recording] ffmpeg` 中指定路径；基础图传显示不依赖它。
 
-设备发现使用板卡的 Hello 广播；客户端除广播订阅外，还会按已发现设备的 IP 定向续订。Windows 开启 VPN / 虚拟网卡时，全局广播可能走虚拟接口；定向续订可避免“能发现并绑定，但始终等待画面”的情况。队伍端的绑定和画面过滤仍然生效。
+设备发现使用板卡的 Hello 广播；客户端除广播订阅外，还会按已发现设备的 IP 定向续订。Windows 开启 VPN / 虚拟网卡时，全局广播可能走虚拟接口；定向续订可避免"能发现并绑定，但始终等待画面"的情况。队伍端的绑定和画面过滤仍然生效。
 
 ### 演示模式：没有板子也能把整条链路跑起来
 
@@ -223,8 +222,8 @@ cd desktop
 CAM_DEMO=1 pnpm app
 ```
 
-它**不伪造数据给界面**，而是合成**协议数据报**，从 `Receiver::datagram` 与
-`ArmorHealthStore::datagram` 进去。也就是说演示模式跑的是同一条真实路径：
+它不伪造数据给界面，而是合成协议数据报，从 `Receiver::datagram` 与
+`ArmorHealthStore::datagram` 进去。演示模式跑的是同一条真实路径：
 
 ```text
 合成 JPEG ──分片──▶ Receiver::datagram ──重组──▶ 帧 sink ──▶ WebSocket ──▶ canvas
@@ -273,7 +272,7 @@ CAM_CONFIG=<路径>        等价于 --config <路径>
 
 ## 视频怎么进 WebView
 
-**一个只监听回环地址的 WebSocket，推二进制 JPEG。** 界面从 `stream_info` 命令拿到
+视频走一个只监听回环地址的 WebSocket，推二进制 JPEG。界面从 `stream_info` 命令拿到
 `ws://127.0.0.1:<随机端口>/?token=...`。
 
 ### 为什么不是 Tauri 的 IPC
@@ -307,8 +306,8 @@ CAM_CONFIG=<路径>        等价于 --config <路径>
 
 对抗赛里两队都用这套系统看自己小车的图传，要防止对手开第二个窗口连到另一队的板子。
 
-**关键是这件事做在接收端，不是界面里。** 广播的 Hello 里就有 MAC 派生的 `sender_id` 与
-IP，藏起来毫无意义；数据也可能已经收下并解码了，`.slint`/CSS 只控制显示。
+关键是这件事做在接收端，不是界面里。广播的 Hello 里就有 MAC 派生的 `sender_id` 与
+IP，藏起来毫无意义；数据也可能已经收下并解码了，CSS 只控制显示。
 
 | 闸门 | 管什么 | 什么时候开 |
 |---|---|---|
@@ -316,10 +315,10 @@ IP，藏起来毫无意义；数据也可能已经收下并解码了，`.slint`/
 | `discovery_all` | 是否记录**其它**板子的 Hello | 只在密码解锁后的设置界面里打开 |
 
 旧客户端把两件事绑在同一道闸门上，于是只能在"能列出候选"和"挡住对手"之间二选一，改绑
-只能靠手改配置文件。现在分开了：设置界面能列出候选摄像头（否则无从选起），但**画面不进
-来**——对手的板子即使把流推到本机端口、即使被记进发现列表，它的帧也进不了重组器。
+只能靠手改配置文件。现在分开了：设置界面能列出候选摄像头（否则无从选起），但**画面进不来**：
+对手的板子即使把流推到本机端口、即使被记进发现列表，它的帧也进不了重组器。
 
-四种情况不限制：裁判端（中立方）、debug 构建、用户端还没绑定、`--camera-id` 显式覆盖。
+`only_sender` 只在两种情况下放开：裁判端（中立方），以及用户端还没绑定摄像头。debug 构建不会放开它。
 
 ### 遥测按编译模式门控
 
@@ -329,7 +328,7 @@ IP，藏起来毫无意义；数据也可能已经收下并解码了，`.slint`/
 
 ### 这挡不住什么
 
-诚实地说：**IP 仍然通过 Hello 广播泄露。** 对手知道你的 IP 之后可以自己发一个
+**IP 仍然通过 Hello 广播泄露。** 对手知道你的 IP 之后可以自己发一个
 `Subscribe` 过来——固件会向任何订阅者推流，那道闸门在他的客户端上，不在你的。真要挡住
 需要固件侧做配对 token（首次绑定发一个令牌，固件只接受带令牌的订阅），代价是固件重启就
 失配。
@@ -339,8 +338,6 @@ IP，藏起来毫无意义；数据也可能已经收下并解码了，`.slint`/
 
 ## 密码：它挡的是谁
 
-必须说清楚，否则会被当成一把它并不是的锁。
-
 - **挡得住**：现场随手改绑定。选手想把自己的画面换到对手那块板子上，得先知道密码；围观
   的人翻不到明文（只有 Argon2id 哈希），也不能靠改配置文件把绑定改掉——改了之后界面会
   要求先解锁。**退出/关闭程序**同样要密码，因为"随手关掉"也是一种要挡的误操作。
@@ -532,7 +529,7 @@ AP、板子，而不是二十行分配代码。现在它有一个直接对着这
 
 ## 配置
 
-`~/.config/cam-desktop/config.toml`，`--config` 可改。**目录名沿用旧的 `cam-desktop`**：改名不该顺手把现场的密码哈希与绑定丢掉。要干净重来就删掉这个目录。
+`~/.config/cam-desktop/config.toml`，`--config` 可改。**目录名沿用旧的 `cam-desktop`**（原因见开头）。要干净重来就删掉这个目录。
 
 ```toml
 role = "team"
@@ -599,8 +596,8 @@ open 'http://127.0.0.1:1420/?preview=password'    # 首启的设密码
 
 ```sh
 cd desktop/core      && cargo test    # 83：重组、发现、两道闸门、帧率窗口、槽位、配置、密码、胜负判定
-cd desktop/src-tauri && cargo test    # 32：帧头布局、录制、截图、演示画面、命令行
-cd protocol          && cargo test    # 20
+cd desktop/src-tauri && cargo test    # 40：帧头布局、录制、截图、演示画面、命令行
+cd protocol          && cargo test    # 23
 ```
 
 前端解码队列测试：在 `desktop/` 运行 `pnpm test:stream`，5 项测试覆盖慢解码时保留最新帧、多路独立处理、关闭清理、坏帧恢复与设备重启。它不替代实际 WebView 的画面验证。
@@ -649,8 +646,8 @@ RUST_LOG=debug ./target/aarch64-apple-darwin/debug/cam-desktop | grep 'stream:'
   DTO，所以至少能解释清楚。
 - **`csp` 是一条收紧过的白名单**，但它是"够用"而不是"最小"：`style-src` 带
   `'unsafe-inline'`（React 的内联 `style` 属性需要它），`connect-src` 放开了整个
-  `ws://127.0.0.1:*`（端口是启动时随机分配的，写不死）。验证方式是"前端能不能连上后端"
-  ——见下面"测试"一节最后一条。
+  `ws://127.0.0.1:*`（端口是启动时随机分配的，写不死）。验证方式是"前端能不能连上后端"，
+  见"测试"一节最后一条。
 - **证书与公证**没做，`.dmg` 只在本机可用。
 - 前端已有解码队列测试；布局、实际 WebView 解码和画面显示仍需浏览器预览及真机运行验证。