merge: 合入 feature/agent-linux（测试期望值修正 + 冒烟脚本纳入单测 + cargo 网络配置文档）

linux-agent/src/input.rs

@@ -242,8 +242,10 @@ mod tests {
     #[test]
     fn coordinate_scaling_covers_full_range() {
         assert_eq!(scale(0, 1920), 0);
+        // 归一化上界必须映射到 extent-1，否则指针永远到不了屏幕最右/最下
         assert_eq!(scale(65535, 1920), 1919);
-        assert_eq!(scale(32768, 1920), 960);
+        // 中点：32768 × 1919 ÷ 65535 = 959.49…，整数除法向下取整 → 959
+        assert_eq!(scale(32768, 1920), 959);
         assert_eq!(scale(12345, 0), 0); // 退化尺寸不 panic
     }
 }

scripts/linux-smoke.sh

@@ -43,6 +43,9 @@ if [ "$ready" -ne 1 ]; then
 fi
 echo "[smoke] X server 就绪：$(xdpyinfo -display "$DISPLAY_NUM" | grep -E 'dimensions' | head -1)"
 
-# 两个测试共用同一块虚拟屏与指针，必须串行
+# 先跑纯逻辑单测（键码映射 / 坐标换算），不需要 X server
+cargo test -p linux-agent --bins
+
+# 再跑端到端用例：两个用例共用同一块虚拟屏与指针，必须串行
 cargo test -p linux-agent --test smoke -- --nocapture --test-threads=1
 echo "[smoke] 通过"

构建运行手册.md

@@ -20,31 +20,34 @@
   - `rustup default stable-x86_64-pc-windows-gnu`，装到 `%USERPROFILE%\.cargo\bin`
   - MinGW-w64：`D:\mingw64\bin`（gcc 16.2.0）
   - 构建时 PATH 需同时包含上面两个目录（缺 MinGW 会在链接 openh264 的 C++ 时失败）
-- **cargo 源**：国内直连 crates.io 会超时（cargo 不读系统代理），需配置镜像。已在本机
+- **cargo 网络**：国内直连 crates.io 会超时，且 **cargo 不读 Windows 系统代理**，必须显式告诉它。
-  `%USERPROFILE%\.cargo\config.toml` 写入 USTC 源：
+  已在本机 `%USERPROFILE%\.cargo\config.toml` 写入（Clash 之类混合端口，按实际改）：
 
   ```toml
-  [source.crates-io]
+  [http]
-  replace-with = "ustc"
+  proxy = "http://127.0.0.1:7897"
-  [source.ustc]
-  registry = "sparse+https://mirrors.ustc.edu.cn/crates.io-index/"
   ```
 
+  ⚠️ **不要用国内镜像做源替换**：实测 USTC 镜像的索引 `cksum` 与其实际下发的 `.crate`
+  字节**不一致**（`nvenc 0.1.0`：索引写 `3227c3b0…`，包体实际 `ab6fde0e…`），
+  会报 `failed to verify the checksum of nvenc`；且源替换会改变 registry 身份，
+  使 `Cargo.lock` 里已有的 checksum 与全部缓存失配。**走官方源 + 代理最稳。**
+
 > 注：旧版本手册写的 `D:\wordkb\...\uurev\tools\rust` 路径已不存在，按上面重新准备工具链即可。
 
 ## 3. 构建
 
 ```bash
-export RUSTUP_HOME="D:\\wordkb\\2026-10-22-15-52-47\\uurev\\tools\\rust\\rustup"
+# Git Bash 写法：PATH 需含 rustup 的 cargo 与 MinGW-w64
-export CARGO_HOME="D:\\wordkb\\2026-10-22-15-52-47\\uurev\\tools\\rust\\cargo"
+export PATH="$USERPROFILE/.cargo/bin:/d/mingw64/bin:$PATH"
-export PATH="/d/wordkb/2026-10-22-15-52-47/uurev/tools/rust/cargo/bin:/d/wordkb/2026-10-22-15-52-47/uurev/tools/mingw64/bin:$PATH"
+cd /d/code/remote          # 换成你自己的工作目录 / worktree
-cd /d/wordkb/2026-10-22-15-52-47/mvp-remote
 cargo build --release
 ```
 
 产物：
 - 被控端 `target/release/agent.exe`
 - 主控端 `target/release/viewer.exe`
+- 编码基准（可选）`target/release/encbench.exe`
 
 ## 4. 运行（两台机器，或同机双开验证）
 
@@ -164,9 +167,15 @@ viewer.exe --addr <被控机IP> --port 47800 --code 123456
 bash scripts/linux-smoke.sh
 ```
 
-脚本自建 Xvfb 虚拟屏后跑端到端测试，覆盖：X11 采集 → openh264 编码 → QUIC 下行解帧、
+脚本自建 Xvfb 虚拟屏后跑**单测 + 端到端**两层：
-验证码认证（含**错误验证码被拒**）、Ping/Pong（含下行丢包统计字段）、静止桌面下的关键帧
+
-恢复，以及**输入注入实证**——注入鼠标移动后，从另一条 X11 连接读回指针真实坐标。
+- 单测（不需要 X server）：键码映射、坐标换算等纯逻辑；
+- 端到端：X11 采集 → openh264 编码 → QUIC 下行解帧、验证码认证（含**错误验证码被拒**）、
+  Ping/Pong（含下行丢包统计字段）、静止桌面下的关键帧恢复，以及**输入注入实证**——
+  注入鼠标移动后，从另一条 X11 连接读回指针真实坐标。
+
+> 单测那层别省：坐标换算的取整边界就是靠它才发现的（集成测试有 ±2 像素容差，
+> 期望值写错也照样绿）。
 
 > 静止关键帧那条用例做过**变异测试**：把修复退回会失败、恢复后通过，确认断言不是摆设。
 > 注意扰动量必须小（画 64x64 小方块）——整屏刷白会触发编码器场景切换自动 IDR，