From 49f85db9f9692d269cb03fc9402dc566f94bd526 Mon Sep 17 00:00:00 2001
From: yu <191972707@qq.com>
Date: Fri, 23 Oct 2026 14:10:20 +0800
Subject: [PATCH 1/2] =?UTF-8?q?docs:=20=E4=BF=AE=E6=AD=A3=20cargo=20?=
 =?UTF-8?q?=E7=BD=91=E7=BB=9C=E9=85=8D=E7=BD=AE=E5=BB=BA=E8=AE=AE=EF=BC=88?=
 =?UTF-8?q?=E4=BB=A3=E7=90=86=E8=80=8C=E9=9D=9E=E9=95=9C=E5=83=8F=E6=BA=90?=
 =?UTF-8?q?=EF=BC=89+=20=E6=9B=B4=E6=96=B0=E6=9E=84=E5=BB=BA=E5=91=BD?=
 =?UTF-8?q?=E4=BB=A4=E8=B7=AF=E5=BE=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 实测 USTC 镜像索引 cksum 与下发的 .crate 字节不一致（nvenc 0.1.0），
  源替换会触发 checksum 校验失败并改变 registry 身份；改为 [http] proxy 走官方源
- 构建命令里 D:\\wordkb\\... 的失效路径替换为可用写法
- 已实测：Windows cargo build --release 通过（agent.exe/viewer.exe/encbench.exe）
  且 cargo test -p linux-agent 在容器内 2 passed
---
 构建运行手册.md | 23 +++++++++++++----------
 1 file changed, 13 insertions(+), 10 deletions(-)

diff --git a/构建运行手册.md b/构建运行手册.md
index 9d76ba0..d85b7b0 100644
--- a/构建运行手册.md
+++ b/构建运行手册.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 不读系统代理），需配置镜像。已在本机
-  `%USERPROFILE%\.cargo\config.toml` 写入 USTC 源：
+- **cargo 网络**：国内直连 crates.io 会超时，且 **cargo 不读 Windows 系统代理**，必须显式告诉它。
+  已在本机 `%USERPROFILE%\.cargo\config.toml` 写入（Clash 之类混合端口，按实际改）：
 
   ```toml
-  [source.crates-io]
-  replace-with = "ustc"
-  [source.ustc]
-  registry = "sparse+https://mirrors.ustc.edu.cn/crates.io-index/"
+  [http]
+  proxy = "http://127.0.0.1:7897"
   ```
 
+  ⚠️ **不要用国内镜像做源替换**：实测 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"
-export CARGO_HOME="D:\\wordkb\\2026-10-22-15-52-47\\uurev\\tools\\rust\\cargo"
-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/wordkb/2026-10-22-15-52-47/mvp-remote
+# Git Bash 写法：PATH 需含 rustup 的 cargo 与 MinGW-w64
+export PATH="$USERPROFILE/.cargo/bin:/d/mingw64/bin:$PATH"
+cd /d/code/remote          # 换成你自己的工作目录 / worktree
 cargo build --release
 ```
 
 产物：
 - 被控端 `target/release/agent.exe`
 - 主控端 `target/release/viewer.exe`
+- 编码基准（可选）`target/release/encbench.exe`
 
 ## 4. 运行（两台机器，或同机双开验证）
 

From bae871c78cb8b4521559621dc082f8df057c653c Mon Sep 17 00:00:00 2001
From: yu <191972707@qq.com>
Date: Fri, 23 Oct 2026 15:04:56 +0800
Subject: [PATCH 2/2] =?UTF-8?q?fix(linux-agent):=20=E4=BF=AE=E6=AD=A3?=
 =?UTF-8?q?=E5=9D=90=E6=A0=87=E6=8D=A2=E7=AE=97=E5=8D=95=E6=B5=8B=E6=9C=9F?=
 =?UTF-8?q?=E6=9C=9B=E5=80=BC=20+=20=E5=86=92=E7=83=9F=E8=84=9A=E6=9C=AC?=
 =?UTF-8?q?=E7=BA=B3=E5=85=A5=E5=8D=95=E6=B5=8B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- scale(32768,1920) 期望值应为 959（32768×1919÷65535=959.49 向下取整），
  原写成 960 —— 是**测试期望值错**，实现本身正确（0→0、65535→extents-1 均通过）；
  集成测试因带 ±2 像素容差未能暴露，是跑单测才抓到的
- scripts/linux-smoke.sh 原先只跑 --test smoke，漏掉 --bins 单测；现两层都跑
- 手册 §8.4 说明补充单测这一层及其必要性

验证：bash scripts/linux-smoke.sh → 单测 4 passed + 端到端 2 passed
---
 linux-agent/src/input.rs |  4 +++-
 scripts/linux-smoke.sh   |  5 ++++-
 构建运行手册.md    | 12 +++++++++---
 3 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/linux-agent/src/input.rs b/linux-agent/src/input.rs
index 0a77bf5..6fe4865 100644
--- a/linux-agent/src/input.rs
+++ b/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
     }
 }
diff --git a/scripts/linux-smoke.sh b/scripts/linux-smoke.sh
index 327651b..6eb2dfa 100644
--- a/scripts/linux-smoke.sh
+++ b/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] 通过"
diff --git a/构建运行手册.md b/构建运行手册.md
index d85b7b0..5a52ba9 100644
--- a/构建运行手册.md
+++ b/构建运行手册.md
@@ -167,9 +167,15 @@ viewer.exe --addr <被控机IP> --port 47800 --code 123456
 bash scripts/linux-smoke.sh
 ```
 
-脚本自建 Xvfb 虚拟屏后跑端到端测试，覆盖：X11 采集 → openh264 编码 → QUIC 下行解帧、
-验证码认证（含**错误验证码被拒**）、Ping/Pong（含下行丢包统计字段）、静止桌面下的关键帧
-恢复，以及**输入注入实证**——注入鼠标移动后，从另一条 X11 连接读回指针真实坐标。
+脚本自建 Xvfb 虚拟屏后跑**单测 + 端到端**两层：
+
+- 单测（不需要 X server）：键码映射、坐标换算等纯逻辑；
+- 端到端：X11 采集 → openh264 编码 → QUIC 下行解帧、验证码认证（含**错误验证码被拒**）、
+  Ping/Pong（含下行丢包统计字段）、静止桌面下的关键帧恢复，以及**输入注入实证**——
+  注入鼠标移动后，从另一条 X11 连接读回指针真实坐标。
+
+> 单测那层别省：坐标换算的取整边界就是靠它才发现的（集成测试有 ±2 像素容差，
+> 期望值写错也照样绿）。
 
 > 静止关键帧那条用例做过**变异测试**：把修复退回会失败、恢复后通过，确认断言不是摆设。
 > 注意扰动量必须小（画 64x64 小方块）——整屏刷白会触发编码器场景切换自动 IDR，