test(agent): dump_stream 增加 --save，可导出裸 H.264 码流供外部解码器验证

目的
安卓主控方案的唯一高风险未知项是「agent 发出的码流能否被 MediaCodec 解码」。
要验证它，需要一份脱离 QUIC/自定义帧头的**裸 Annex-B 码流文件**，供手机端
或任何标准解码器直接读取。

改动
- 新增 --save <路径>：把各帧载荷按到达顺序拼接成 Annex-B 文件
- 存的是**载荷**而非完整帧：外部解码器只认标准 Annex-B，不认识本项目的
  长度前缀与 bincode 帧头，故不能存 encode_video_frame 的输出
- 保存时打印字节数与 IDR 数量，便于快速判断样本是否可用

不做的事
不引入独立的码流解析库，IDR 统计复用文件内已有的起始码扫描逻辑，
避免为一次性诊断工具增加依赖。

验证
cargo build --workspace 退出码 0；cargo test --workspace --exclude linux-agent 全绿。
实际使用：导出 90 帧、437823 字节、含 2 个 IDR，该文件已用于安卓 MediaCodec
兼容性验证（vivo S6 / Exynos 硬解，87/89 帧解出）。

.gitattributes

@@ -0,0 +1,15 @@
+# 统一换行符，避免跨平台踩坑
+# shell 脚本必须 LF：Windows 上若被 checkout 成 CRLF，容器/Linux 里执行会报
+# "$'\r': command not found"，或被 sed/grep 当成带 \r 的内容
+*.sh text eol=lf
+
+# Windows 侧脚本保持 CRLF
+*.ps1 text eol=crlf
+*.bat text eol=crlf
+
+# 二进制/生成物不参与换行转换
+*.exe binary
+*.dll binary
+*.png binary
+*.jpg binary
+*.ico binary

Cargo.lock

@@ -9,6 +9,7 @@ dependencies = [
  "anyhow",
  "common",
  "lz4_flex",
+ "nvenc",
  "openh264",
  "quinn",
  "rcgen",
@@ -17,6 +18,19 @@ dependencies = [
  "windows",
 ]
 
+[[package]]
+name = "agent-core"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "common",
+ "openh264",
+ "quinn",
+ "rcgen",
+ "rustls",
+ "tokio",
+]
+
 [[package]]
 name = "anyhow"
 version = "1.0.104"
@@ -44,6 +58,27 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "bitfields"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ef6e59298da389bc0649c7463856b34c6e17fe542f88939426ede4436c6b1195"
+dependencies = [
+ "bitfields-impl",
+]
+
+[[package]]
+name = "bitfields-impl"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2c044f98f86f15414668d6c8187c7e4fadab1ad2b31680f648703e0fe07c555"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+ "thiserror",
+]
+
 [[package]]
 name = "bitflags"
 version = "1.3.2"
@@ -303,6 +338,16 @@ dependencies = [
  "slab",
 ]
 
+[[package]]
+name = "gethostname"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1bd49230192a3797a9a4d6abe9b3eed6f7fa4c8a8a4947977c6f80025f92cbd8"
+dependencies = [
+ "rustix",
+ "windows-link",
+]
+
 [[package]]
 name = "getrandom"
 version = "0.2.17"
@@ -452,6 +497,19 @@ dependencies = [
  "redox_syscall 0.9.5",
 ]
 
+[[package]]
+name = "linux-agent"
+version = "0.1.0"
+dependencies = [
+ "agent-core",
+ "anyhow",
+ "common",
+ "quinn",
+ "rustls",
+ "tokio",
+ "x11rb",
+]
+
 [[package]]
 name = "linux-raw-sys"
 version = "0.12.1"
@@ -567,6 +625,15 @@ version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "521739c6d2bac4aa25192232afe6841231376b2b26d4d9fae5ecf8ca5772e441"
 
+[[package]]
+name = "nvenc"
+version = "0.1.0"
+dependencies = [
+ "bitfields",
+ "libloading",
+ "windows",
+]
+
 [[package]]
 name = "once_cell"
 version = "1.21.4"
@@ -1512,32 +1579,54 @@ checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
 
 [[package]]
 name = "windows"
-version = "0.58.0"
+version = "0.62.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dd04d41d93c4992d421894c18c8b43496aa748dd4c081bac0dc93eb0489272b6"
+checksum = "527fadee13e0c05939a6a05d5bd6eec6cd2e3dbd648b9f8e447c6518133d8580"
+dependencies = [
+ "windows-collections",
+ "windows-core",
+ "windows-future",
+ "windows-numerics",
+]
+
+[[package]]
+name = "windows-collections"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23b2d95af1a8a14a3c7367e1ed4fc9c20e0a26e79551b1454d72583c97cc6610"
 dependencies = [
  "windows-core",
- "windows-targets",
 ]
 
 [[package]]
 name = "windows-core"
-version = "0.58.0"
+version = "0.62.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6ba6d44ec8c2591c134257ce647b7ea6b20335bf6379a27dac5f1641fcf59f99"
+checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb"
 dependencies = [
  "windows-implement",
  "windows-interface",
+ "windows-link",
  "windows-result",
  "windows-strings",
- "windows-targets",
+]
+
+[[package]]
+name = "windows-future"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e1d6f90251fe18a279739e78025bd6ddc52a7e22f921070ccdc67dde84c605cb"
+dependencies = [
+ "windows-core",
+ "windows-link",
+ "windows-threading",
 ]
 
 [[package]]
 name = "windows-implement"
-version = "0.58.0"
+version = "0.60.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2bbd5b46c938e506ecbce286b6628a02171d56153ba733b6c741fc627ec9579b"
+checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -1546,9 +1635,9 @@ dependencies = [
 
 [[package]]
 name = "windows-interface"
-version = "0.58.0"
+version = "0.59.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "053c4c462dc91d3b1504c6fe5a726dd15e216ba718e84a0e46a88fbe5ded3515"
+checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -1562,22 +1651,31 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
 
 [[package]]
-name = "windows-result"
-version = "0.2.0"
+name = "windows-numerics"
+version = "0.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1d1043d8214f791817bab27572aaa8af63732e11bf84aa21a45a78d6c317ae0e"
+checksum = "6e2e40844ac143cdb44aead537bbf727de9b044e107a0f1220392177d15b0f26"
 dependencies = [
- "windows-targets",
+ "windows-core",
+ "windows-link",
+]
+
+[[package]]
+name = "windows-result"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5"
+dependencies = [
+ "windows-link",
 ]
 
 [[package]]
 name = "windows-strings"
-version = "0.1.0"
+version = "0.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4cd9b125c486025df0eabcb585e62173c6c9eddcec5d117d3b6e8c30e2ee4d10"
+checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091"
 dependencies = [
- "windows-result",
- "windows-targets",
+ "windows-link",
 ]
 
 [[package]]
@@ -1614,6 +1712,15 @@ dependencies = [
  "windows_x86_64_msvc",
 ]
 
+[[package]]
+name = "windows-threading"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3949bd5b99cafdf1c7ca86b43ca564028dfe27d66958f2470940f73d86d75b37"
+dependencies = [
+ "windows-link",
+]
+
 [[package]]
 name = "windows_aarch64_gnullvm"
 version = "0.52.6"
@@ -1673,6 +1780,23 @@ dependencies = [
  "pkg-config",
 ]
 
+[[package]]
+name = "x11rb"
+version = "0.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9993aa5be5a26815fe2c3eacfc1fde061fc1a1f094bf1ad2a18bf9c495dd7414"
+dependencies = [
+ "gethostname",
+ "rustix",
+ "x11rb-protocol",
+]
+
+[[package]]
+name = "x11rb-protocol"
+version = "0.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ea6fc2961e4ef194dcbfe56bb845534d0dc8098940c7e5c012a258bfec6701bd"
+
 [[package]]
 name = "xcursor"
 version = "0.3.11"

Cargo.toml

@@ -1,6 +1,11 @@
 [workspace]
 resolver = "2"
-members = ["common", "agent", "viewer"]
+# agent-core：平台无关会话层 + 软件编码视频管线（当前仅 linux-agent 使用）
+# linux-agent：Linux 被控端（X11 + XTest）
+members = ["common", "agent-core", "agent", "linux-agent", "viewer"]
+# 默认成员保持 Windows 三件套，`cargo build --release` 行为与改动前完全一致；
+# Linux 被控端显式构建：`cargo build --release -p linux-agent`
+default-members = ["common", "agent", "viewer"]
 
 [workspace.dependencies]
 anyhow = "1"
@@ -11,5 +16,5 @@ quinn = "0.11"
 rustls = { version = "0.23", default-features = false, features = ["ring", "std", "logging"] }
 rcgen = { version = "0.13", default-features = false, features = ["ring", "pem"] }
 lz4_flex = "0.11"
-windows = "0.58"
+windows = "0.62"
 minifb = "0.27"

README.md

@@ -27,4 +27,4 @@ agent.exe --port 47800 --code 123456
 viewer.exe --addr <被控机IP> --port 47800 --code 123456
 ```
 
-详见《构建运行手册.md》与《Git协作规范.md》。
+详见《构建运行手册.md》、《Git协作规范.md》与《打洞与信令设计.md》。

agent-core/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "agent-core"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+common = { path = "../common" }
+anyhow.workspace = true
+tokio.workspace = true
+quinn.workspace = true
+rustls.workspace = true
+rcgen.workspace = true
+openh264 = { version = "0.9.9", features = ["source"] }

agent-core/src/lib.rs

@@ -0,0 +1,478 @@
+//! 平台无关的被控端会话层：QUIC/TLS 握手、验证码认证、H.264 编码下行、输入分发。
+//!
+//! 从 `agent/`（Windows）抽出来，供 Windows 与 Linux 被控端共用，避免两端各写一份
+//! QUIC 握手/认证/丢帧逻辑造成协议漂移。平台差异只通过两个 trait 注入：
+//!
+//! - [`ScreenCapturer`]：屏幕采集（Windows = DXGI Desktop Duplication，Linux = X11）
+//! - [`InputInjector`]：输入注入（Windows = SendInput，Linux = XTest）
+//!
+//! 线格式完全复用 `common`，**不改协议**：键盘沿用 Set-1 扫描码 + extended 标志，
+//! 鼠标沿用虚拟桌面归一化坐标 0..=65535。
+
+use anyhow::Result;
+use common::{
+    encode_video_frame, h264_contains_idr, read_control, write_control, ControlMsg, InputEvent,
+    MouseButton, VideoFrameHeader,
+};
+use openh264::encoder::{
+    BitRate, Encoder, EncoderConfig, FrameRate, IntraFramePeriod, RateControlMode, UsageType,
+};
+use openh264::formats::{BgraSliceU8, YUVBuffer};
+use openh264::OpenH264API;
+use rustls::pki_types::PrivatePkcs8KeyDer;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+use tokio::sync::{mpsc, watch};
+
+/// 屏幕采集后端。
+///
+/// 语义刻意对齐 DXGI Desktop Duplication，使 Linux 侧只需实现同一套模型：
+/// `acquire()` 阻塞至多 `timeout_ms`，返回是否拿到**新**帧；`copy_frame()` 再取出像素。
+pub trait ScreenCapturer: Send {
+    /// 桌面尺寸（物理像素）
+    fn size(&self) -> (u32, u32);
+
+    /// 阻塞至多 `timeout_ms`。
+    /// `Ok(true)` = 有新帧（已拷进内部缓冲，可由 `copy_frame` 取出）；
+    /// `Ok(false)` = 超时且画面未变（静止桌面）。
+    fn acquire(&mut self, timeout_ms: u32) -> Result<bool>;
+
+    /// 取出最近一帧，BGRA 紧凑排列（已去掉 row pitch），供 openh264 直接编码。
+    fn copy_frame(&mut self) -> Result<Vec<u8>>;
+}
+
+/// 输入注入后端。实现需可在异步运行时中被多任务共享，故要求 `Send + Sync`。
+pub trait InputInjector: Send + Sync + 'static {
+    fn mouse_move(&self, x: u16, y: u16);
+    fn mouse_button(&self, b: MouseButton, down: bool);
+    fn wheel(&self, dy: i32);
+    fn key(&self, scancode: u16, extended: bool, down: bool);
+}
+
+/// 把一条协议输入事件分发到注入后端。
+pub fn dispatch_input(inj: &dyn InputInjector, ev: InputEvent) {
+    match ev {
+        InputEvent::MouseMove { x, y } => inj.mouse_move(x, y),
+        InputEvent::MouseDown(b) => inj.mouse_button(b, true),
+        InputEvent::MouseUp(b) => inj.mouse_button(b, false),
+        InputEvent::Wheel { dy } => inj.wheel(dy),
+        InputEvent::KeyDown { scancode, extended } => inj.key(scancode, extended, true),
+        InputEvent::KeyUp { scancode, extended } => inj.key(scancode, extended, false),
+    }
+}
+
+/// 会话参数
+#[derive(Debug, Clone)]
+pub struct SessionConfig {
+    pub port: u16,
+    pub code: String,
+}
+
+/// 编码档位。默认值即 Windows 现有档位，改动需两端同步评估。
+#[derive(Debug, Clone, Copy)]
+pub struct EncoderSettings {
+    pub bitrate_bps: u32,
+    pub max_fps: f32,
+    pub intra_period: u32,
+}
+
+impl Default for EncoderSettings {
+    fn default() -> Self {
+        // 关键帧周期：以**时间**为准而非固定帧数，避免帧率变化后恢复窗口漂移。
+        // 1 秒 @30fps = 30 帧。主恢复路径是 KeyFrameReq（协议 v2 后已确认生效），
+        // 自动 IDR 只是兜底；此前 300 帧 @30fps 意味着兜底窗口长达 10 秒。
+        let max_fps = 30.0f32;
+        Self {
+            bitrate_bps: 5_000_000,
+            max_fps,
+            intra_period: (max_fps as u32).max(1),
+        }
+    }
+}
+
+/// 解析 `--port` / `--code`（两端共用，保持命令行一致）
+pub fn parse_args() -> Result<(u16, String)> {
+    let mut port = 47800u16;
+    let mut code = "123456".to_string();
+    let a: Vec<String> = std::env::args().collect();
+    let mut i = 1;
+    while i + 1 < a.len() {
+        match a[i].as_str() {
+            "--port" => port = a[i + 1].parse()?,
+            "--code" => code = a[i + 1].clone(),
+            _ => {}
+        }
+        i += 2;
+    }
+    Ok((port, code))
+}
+
+fn make_encoder(enc: &EncoderSettings) -> Result<Encoder> {
+    Ok(Encoder::with_api_config(
+        OpenH264API::from_source(),
+        EncoderConfig::new()
+            .bitrate(BitRate::from_bps(enc.bitrate_bps))
+            .max_frame_rate(FrameRate::from_hz(enc.max_fps))
+            .rate_control_mode(RateControlMode::Bitrate)
+            .usage_type(UsageType::ScreenContentRealTime)
+            .intra_frame_period(IntraFramePeriod::from_num_frames(enc.intra_period)),
+    )?)
+}
+
+enum LoopEnd {
+    /// 下行通道关闭 —— 会话结束，采集线程退出
+    ChannelClosed,
+    /// 采集后端失效（Windows 的 ACCESS_LOST / X11 连接断开）—— 重建后继续
+    Rebuild,
+}
+
+/// 编码一帧并推入下行通道。返回 false 表示通道已关闭（会话结束）。
+///
+/// `seq` 由调用方持有并自增：帧序号必须覆盖**每一次实际发送**（含静止桌面重发），
+/// 不能由编码器计数（编码器只知道编码了多少帧，不知道发了多少帧）。
+fn encode_send(
+    encoder: &mut Encoder,
+    raw: &[u8],
+    (w, h): (u32, u32),
+    ts_ms: u64,
+    seq: u64,
+    tx: &watch::Sender<Option<Vec<u8>>>,
+    last_frame: &mut Option<Vec<u8>>,
+) -> bool {
+    let yuv = YUVBuffer::from_bgra8_source(BgraSliceU8::new(raw, (w as usize, h as usize)));
+    match encoder.encode(&yuv) {
+        Ok(ebs) => {
+            let payload = ebs.to_vec();
+            let header = VideoFrameHeader {
+                width: w,
+                height: h,
+                ts_ms,
+                seq,
+                keyframe: h264_contains_idr(&payload),
+            };
+            let frame = encode_video_frame(&header, &payload);
+            if tx.send(Some(frame.clone())).is_err() {
+                return false;
+            }
+            *last_frame = Some(frame);
+            true
+        }
+        Err(e) => {
+            eprintln!("[capture] encode failed: {e}");
+            true
+        }
+    }
+}
+
+/// 单次采集会话：抓帧 → 编码 → 推入 watch 单槽。
+fn capture_session(
+    cap: &mut dyn ScreenCapturer,
+    tx: &watch::Sender<Option<Vec<u8>>>,
+    keyreq: &AtomicBool,
+    enc: &EncoderSettings,
+) -> LoopEnd {
+    let mut encoder = match make_encoder(enc) {
+        Ok(e) => e,
+        Err(e) => {
+            eprintln!("[capture] encoder init failed: {e}");
+            return LoopEnd::ChannelClosed;
+        }
+    };
+
+    let (w, h) = cap.size();
+    eprintln!("[capture] started {w}x{h}");
+    let start = Instant::now();
+    let min_frame = Duration::from_secs_f32(1.0 / enc.max_fps);
+    let mut last_frame: Option<Vec<u8>> = None;
+    // 保留最近一帧裸像素：静止桌面收到关键帧请求时，仍能重编一个真关键帧
+    let mut last_raw: Option<Vec<u8>> = None;
+    let mut last_sent = Instant::now() - Duration::from_secs(10);
+    // 帧序号：覆盖每一次实际发送（含静止桌面重发），供主控端做丢帧检测
+    let mut seq: u64 = 0;
+
+    loop {
+        let iter_start = Instant::now();
+        match cap.acquire(80) {
+            Ok(true) => match cap.copy_frame() {
+                Ok(raw) => {
+                    // 主控端请求关键帧（解码异常恢复）
+                    if keyreq.swap(false, Ordering::Relaxed) {
+                        encoder.force_intra_frame();
+                    }
+                    let ts = start.elapsed().as_millis() as u64;
+                    if !encode_send(&mut encoder, &raw, (w, h), ts, seq, tx, &mut last_frame) {
+                        return LoopEnd::ChannelClosed; // 会话结束
+                    }
+                    seq = seq.wrapping_add(1);
+                    last_raw = Some(raw);
+                    last_sent = Instant::now();
+                    // 帧间隔节流到 max_fps
+                    let el = iter_start.elapsed();
+                    if el < min_frame {
+                        std::thread::sleep(min_frame - el);
+                    }
+                }
+                Err(e) => {
+                    eprintln!("[capture] frame copy failed: {e}");
+                    return LoopEnd::Rebuild;
+                }
+            },
+            Ok(false) => {
+                // 静止桌面：先看关键帧请求，再决定是否走 500ms 保活节流。
+                //
+                // ⚠️ 这里必须保证「消费了标志就一定发送」：先前写法是
+                // `if force && last_raw.is_some() { ... }`，当 force 为真但
+                // last_raw 还是 None（刚建会话、尚未抓到任何一帧）时，标志被
+                // swap 消费掉却没有发送，解码端的这次请求就永久丢失。
+                let force = keyreq.swap(false, Ordering::Relaxed);
+                let can_key = last_raw.is_some();
+                if force && !can_key {
+                    // 还没有裸帧可重编：把请求还回去，让下一轮（拿到首帧后）继续生效
+                    keyreq.store(true, Ordering::Relaxed);
+                    eprintln!("[capture] KeyFrameReq 暂存：尚无裸帧可重编");
+                    std::thread::sleep(Duration::from_millis(8));
+                } else if force {
+                    // 静止桌面下的关键帧恢复：画面没变不代表可以不给关键帧——
+                    // 解码端一旦出错，若只会收到旧 P 帧就永远恢复不了。
+                    // 关键帧请求绕过 500ms 节流：它是错误恢复路径，延迟一次 IDR
+                    // 的代价是持续黑屏，远高于多发一帧的带宽成本。
+                    encoder.force_intra_frame();
+                    let raw = last_raw.as_ref().expect("can_key 已保证");
+                    let ts = start.elapsed().as_millis() as u64;
+                    if !encode_send(&mut encoder, raw, (w, h), ts, seq, tx, &mut last_frame) {
+                        return LoopEnd::ChannelClosed;
+                    }
+                    seq = seq.wrapping_add(1);
+                    last_sent = Instant::now();
+                } else if last_sent.elapsed() > Duration::from_millis(500) && last_frame.is_some() {
+                    // 桌面静止：低频重发最后一帧（重复 P 帧，解码端画面不变）。
+                    // 帧头必须重建：直接 clone 旧帧会让 seq/ts_ms 停在上次发送时刻，
+                    // 破坏 seq 单调递增契约。
+                    let f = last_frame.as_ref().expect("上面已判断 is_some");
+                    match common::split_video_frame(f) {
+                        Ok((mut hdr, payload)) => {
+                            hdr.seq = seq;
+                            hdr.ts_ms = start.elapsed().as_millis() as u64;
+                            let frame = encode_video_frame(&hdr, payload);
+                            if tx.send(Some(frame)).is_err() {
+                                return LoopEnd::ChannelClosed;
+                            }
+                            seq = seq.wrapping_add(1);
+                            last_sent = Instant::now();
+                        }
+                        Err(e) => {
+                            // 自己产出的帧解析失败 = 编码/封装路径有 bug。
+                            // 丢弃缓存而不是每轮重复报错：静止桌面下这里会以 ~125Hz 触发。
+                            eprintln!("[capture] 静止重发时帧格式异常，丢弃缓存: {e}");
+                            last_frame = None;
+                            std::thread::sleep(Duration::from_millis(8));
+                        }
+                    }
+                } else {
+                    std::thread::sleep(Duration::from_millis(8));
+                }
+            }
+            Err(e) => {
+                eprintln!("[capture] acquire failed: {e}");
+                return LoopEnd::Rebuild;
+            }
+        }
+    }
+}
+
+/// 采集主循环：独立线程运行；后端失效时经 `factory` 重建，通道关闭时退出。
+/// 通道为 watch 单槽（latest-wins）：发送即覆盖，网络慢时不产生积压。
+pub fn run_capture_loop<F>(
+    tx: watch::Sender<Option<Vec<u8>>>,
+    keyreq: Arc<AtomicBool>,
+    mut cap: Box<dyn ScreenCapturer>,
+    mut factory: F,
+    enc: EncoderSettings,
+) where
+    F: FnMut() -> Result<Box<dyn ScreenCapturer>>,
+{
+    loop {
+        match capture_session(cap.as_mut(), &tx, keyreq.as_ref(), &enc) {
+            LoopEnd::ChannelClosed => return,
+            LoopEnd::Rebuild => {}
+        }
+        std::thread::sleep(Duration::from_millis(300));
+        loop {
+            match factory() {
+                Ok(c) => {
+                    cap = c;
+                    break;
+                }
+                Err(e) => {
+                    eprintln!("[capture] init failed: {e}, retry in 2s");
+                    std::thread::sleep(Duration::from_secs(2));
+                }
+            }
+        }
+    }
+}
+
+/// 跑一次完整的被控端会话：监听 → 认证 → 视频下行 + 输入上行。
+///
+/// `capture_factory` 可被多次调用（采集后端失效时重建），故需为 `FnMut`。
+pub async fn serve<F>(
+    cfg: SessionConfig,
+    enc: EncoderSettings,
+    mut capture_factory: F,
+    injector: Arc<dyn InputInjector>,
+) -> Result<()>
+where
+    F: FnMut() -> Result<Box<dyn ScreenCapturer>> + Send + 'static,
+{
+    rustls::crypto::ring::default_provider()
+        .install_default()
+        .ok();
+
+    // 自签名证书（MVP：客户端跳过校验；正式版改为固定公钥/账号体系）
+    let ck = rcgen::generate_simple_self_signed(vec!["localhost".into()])?;
+    let cert = ck.cert.der().clone();
+    let key = PrivatePkcs8KeyDer::from(ck.key_pair.serialize_der());
+
+    // 传输参数调优：
+    // - 收发窗口放大，避免高 RTT 下吞吐被 窗口/RTT 死锁（默认 512KB 流窗口）
+    // - 发送缓冲上限 512KB：QUIC 内部排队 ≈ 3 帧 @5Mbps，E2E 延迟天花板 ~150ms；
+    //   配合上游 latest-wins 丢帧，超量部分在进 QUIC 前就被丢弃
+    //   （与 Windows 端 agent/src/main.rs 保持一致，沿用同一次调优结论）
+    let mut transport = quinn::TransportConfig::default();
+    transport.receive_window(quinn::VarInt::from_u32(16 * 1024 * 1024));
+    transport.stream_receive_window(quinn::VarInt::from_u32(8 * 1024 * 1024));
+    transport.send_window(512 * 1024);
+    let mut server_config = quinn::ServerConfig::with_single_cert(vec![cert], key.into())?;
+    server_config.transport_config(Arc::new(transport));
+
+    let endpoint = quinn::Endpoint::server(server_config, format!("0.0.0.0:{}", cfg.port).parse()?)?;
+    println!(
+        "[agent] listening 0.0.0.0:{}, verify code = {}",
+        cfg.port, cfg.code
+    );
+
+    let conn = endpoint
+        .accept()
+        .await
+        .ok_or_else(|| anyhow::anyhow!("endpoint closed"))?
+        .await?;
+    println!("[agent] peer connected: {}", conn.remote_address());
+
+    // 流 1：认证 + 视频下行
+    let (mut send, mut recv) = conn.accept_bi().await?;
+
+    let first = read_control(&mut recv).await?;
+    // 先校验版本，再校验验证码：版本不一致时字段布局可能不同，验证码的解析结果不可信
+    let auth_err: Option<String> = match &first {
+        ControlMsg::Auth {
+            code: c,
+            proto_version,
+        } => {
+            if *proto_version != common::PROTO_VERSION {
+                Some(format!(
+                    "protocol version mismatch: client={proto_version}, server={}",
+                    common::PROTO_VERSION
+                ))
+            } else if *c != cfg.code {
+                Some("bad code".into())
+            } else {
+                None
+            }
+        }
+        other => Some(format!("expected Auth, got {other:?}")),
+    };
+    if let Some(msg) = auth_err {
+        write_control(&mut send, &ControlMsg::AuthFail(msg.clone())).await?;
+        send.finish()?;
+        // 必须等对端读到 AuthFail 并挂断再退出：直接 return 会让进程带走 QUIC
+        // 缓冲区里尚未发出的数据，客户端只会看到 "connection lost" 而不是 AuthFail
+        let _ = tokio::time::timeout(Duration::from_secs(5), conn.closed()).await;
+        anyhow::bail!(msg);
+    }
+
+    // 采集后端先建一次：既拿桌面尺寸回给主控端，也避免白建一个 duplication 只为读尺寸
+    let first_cap = capture_factory()?;
+    let (w, h) = first_cap.size();
+    write_control(
+        &mut send,
+        &ControlMsg::AuthOk {
+            width: w,
+            height: h,
+            proto_version: common::PROTO_VERSION,
+        },
+    )
+    .await?;
+    println!("[agent] auth ok, desktop {w}x{h}");
+
+    // 流 2：键鼠输入 + 控制上行（与视频分离，避免被视频积压阻塞）
+    let (mut isend, mut irecv) = conn.accept_bi().await?;
+
+    // 采集线程 → 视频帧（watch 单槽：新帧覆盖旧帧，latest-wins）
+    let (tx, mut frames_rx) = watch::channel::<Option<Vec<u8>>>(None);
+    let keyreq = Arc::new(AtomicBool::new(false));
+    let keyreq_capture = keyreq.clone();
+    let enc_settings = enc;
+    std::thread::spawn(move || {
+        run_capture_loop(tx, keyreq_capture, first_cap, capture_factory, enc_settings)
+    });
+
+    // 上行控制消息（Pong）经通道交给主循环写流 2，避免多任务争抢
+    let (ctl_tx, mut ctl_rx) = mpsc::unbounded_channel::<ControlMsg>();
+    let t0 = Instant::now();
+
+    // 读循环（流 2）：输入事件 + Ping；Pong 附带**视频下行方向**的 QUIC 丢包统计
+    // （conn.stats().path 统计的是本端发送方向，被控端的发送方向正是视频下行）
+    let keyreq_reader = keyreq.clone();
+    let conn_stats = conn.clone();
+    let reader = tokio::spawn(async move {
+        loop {
+            match read_control(&mut irecv).await {
+                Ok(ControlMsg::Input(ev)) => dispatch_input(injector.as_ref(), ev),
+                Ok(ControlMsg::KeyFrameReq) => {
+                    keyreq_reader.store(true, Ordering::Relaxed);
+                }
+                Ok(ControlMsg::Ping(t)) => {
+                    let agent_ts = t0.elapsed().as_millis() as u64;
+                    let p = conn_stats.stats().path;
+                    let _ = ctl_tx.send(ControlMsg::Pong {
+                        t,
+                        agent_ts,
+                        lost: p.lost_packets,
+                        sent: p.sent_packets,
+                    });
+                }
+                Ok(_) => {}
+                Err(_) => break,
+            }
+        }
+    });
+
+    loop {
+        tokio::select! {
+            changed = frames_rx.changed() => {
+                if changed.is_err() {
+                    break; // 采集线程退出
+                }
+                if let Some(data) = frames_rx.borrow().clone() {
+                    if send.write_all(&data).await.is_err() {
+                        break;
+                    }
+                }
+            }
+            ctl = ctl_rx.recv() => {
+                match ctl {
+                    Some(m) => {
+                        if write_control(&mut isend, &m).await.is_err() {
+                            break;
+                        }
+                    }
+                    None => break,
+                }
+            }
+        }
+    }
+    reader.abort();
+    println!("[agent] session closed");
+    Ok(())
+}

agent/Cargo.toml

@@ -12,6 +12,10 @@ rustls.workspace = true
 rcgen.workspace = true
 lz4_flex.workspace = true
 openh264 = { version = "0.9.9", features = ["source"] }
+# 上游 nvenc 0.1.0 的 encode_picture 只设 picture_type=IDR、不置 FORCEIDR 标志，
+# 导致运行期 KeyFrameReq 被编码器静默忽略（实测输出 NAL type=1 而非 5）。
+# vendor 版本补上了该标志，见 vendor/nvenc/src/safe/encoder.rs 的「本项目补丁」注释。
+nvenc = { path = "../vendor/nvenc" }
 windows = { workspace = true, features = [
     "Win32_Foundation",
     "Win32_Graphics_Direct3D",

agent/src/bin/dump_stream.rs

@@ -0,0 +1,316 @@
+//! 临时诊断工具：抓 agent 下发的码流，逐帧打印 NAL 结构并试解码。
+//!
+//! 目的：定位「首帧能解、之后连续 decode failed」的根因，不靠猜。
+//!
+//! 用法：
+//!   cargo run --release -p agent --bin dump_stream -- --port 47805 --code t
+//!   cargo run --release -p agent --bin dump_stream -- --port 47805 --code t --skip-at 2
+//!
+//! `--skip-at N`：模拟主控端的「积压跳帧」行为——第 N 帧读出但不喂给解码器，
+//! 用来验证「跳帧是否直接导致后续所有 P 帧解不出来」。
+
+use anyhow::{bail, Result};
+use common::{read_control, read_video_frame, write_control, ControlMsg};
+use openh264::decoder::Decoder;
+use rustls::client::danger::{HandshakeSignatureValid, ServerCertVerified, ServerCertVerifier};
+use rustls::pki_types::{CertificateDer, ServerName, UnixTime};
+use rustls::{DigitallySignedStruct, SignatureScheme};
+use std::net::ToSocketAddrs;
+use std::sync::Arc;
+use std::time::Duration;
+
+#[derive(Debug)]
+struct SkipVerify;
+impl ServerCertVerifier for SkipVerify {
+    fn verify_server_cert(
+        &self,
+        _e: &CertificateDer<'_>,
+        _i: &[CertificateDer<'_>],
+        _s: &ServerName<'_>,
+        _o: &[u8],
+        _n: UnixTime,
+    ) -> Result<ServerCertVerified, rustls::Error> {
+        Ok(ServerCertVerified::assertion())
+    }
+    fn verify_tls12_signature(
+        &self,
+        _m: &[u8],
+        _c: &CertificateDer<'_>,
+        _d: &DigitallySignedStruct,
+    ) -> Result<HandshakeSignatureValid, rustls::Error> {
+        Ok(HandshakeSignatureValid::assertion())
+    }
+    fn verify_tls13_signature(
+        &self,
+        _m: &[u8],
+        _c: &CertificateDer<'_>,
+        _d: &DigitallySignedStruct,
+    ) -> Result<HandshakeSignatureValid, rustls::Error> {
+        Ok(HandshakeSignatureValid::assertion())
+    }
+    fn supported_verify_schemes(&self) -> Vec<SignatureScheme> {
+        vec![
+            SignatureScheme::RSA_PKCS1_SHA256,
+            SignatureScheme::ECDSA_NISTP256_SHA256,
+            SignatureScheme::ED25519,
+            SignatureScheme::RSA_PSS_SHA256,
+        ]
+    }
+}
+
+/// 扫 Annex-B 起始码，返回 NAL 类型列表（如 [7, 8, 5]）
+fn nal_types(payload: &[u8]) -> Vec<u8> {
+    let mut out = Vec::new();
+    let mut i = 0usize;
+    while i + 3 < payload.len() {
+        let sc = if payload[i..].starts_with(&[0, 0, 0, 1]) {
+            4
+        } else if payload[i..].starts_with(&[0, 0, 1]) {
+            3
+        } else {
+            i += 1;
+            continue;
+        };
+        match payload.get(i + sc) {
+            Some(&b) => {
+                out.push(b & 0x1F);
+                i += sc + 1;
+            }
+            None => break,
+        }
+    }
+    out
+}
+
+fn describe(types: &[u8]) -> String {
+    let has = |t: u8| types.contains(&t);
+    let mut s = String::new();
+    if has(7) {
+        s.push_str("SPS ");
+    }
+    if has(8) {
+        s.push_str("PPS ");
+    }
+    if has(5) {
+        s.push_str("IDR ");
+    }
+    if has(1) {
+        s.push_str("P ");
+    }
+    if has(6) {
+        s.push_str("SEI ");
+    }
+    if s.is_empty() {
+        s.push_str("(未知)");
+    }
+    format!("{}[{}]", s.trim(), types.len())
+}
+
+fn arg(name: &str) -> Option<String> {
+    let a: Vec<String> = std::env::args().collect();
+    a.iter()
+        .position(|x| x == name)
+        .and_then(|i| a.get(i + 1))
+        .cloned()
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    rustls::crypto::ring::default_provider()
+        .install_default()
+        .ok();
+
+    let port: u16 = arg("--port")
+        .map(|s| s.parse())
+        .transpose()?
+        .unwrap_or(47800);
+    let code = arg("--code").unwrap_or_else(|| "123456".into());
+    let skip_at: Option<usize> = arg("--skip-at").map(|s| s.parse()).transpose()?;
+    let total: usize = arg("--frames")
+        .map(|s| s.parse())
+        .transpose()?
+        .unwrap_or(30);
+    // --save <路径>：把**裸 H.264 码流**（各帧载荷按到达顺序直接拼接）
+    // 写成 Annex-B 文件，供安卓 MediaCodec 等外部解码器验证兼容性。
+    // 注意存的是载荷而非完整帧（不含自定义帧头），因为外部解码器只认标准 Annex-B。
+    let save_path = arg("--save");
+
+    let tls = rustls::ClientConfig::builder()
+        .dangerous()
+        .with_custom_certificate_verifier(Arc::new(SkipVerify))
+        .with_no_client_auth();
+    let qc: quinn::crypto::rustls::QuicClientConfig = Arc::new(tls).try_into()?;
+    let mut transport = quinn::TransportConfig::default();
+    transport.receive_window(quinn::VarInt::from_u32(16 * 1024 * 1024));
+    transport.stream_receive_window(quinn::VarInt::from_u32(8 * 1024 * 1024));
+    let mut client_config = quinn::ClientConfig::new(Arc::new(qc));
+    client_config.transport_config(Arc::new(transport));
+    let mut endpoint = quinn::Endpoint::client("0.0.0.0:0".parse()?)?;
+    endpoint.set_default_client_config(client_config);
+
+    let addr = ("127.0.0.1", port)
+        .to_socket_addrs()?
+        .next()
+        .ok_or_else(|| anyhow::anyhow!("解析失败"))?;
+    let conn = endpoint.connect(addr, "localhost")?.await?;
+    println!("[dump] connected");
+
+    let (mut send, mut recv) = conn.open_bi().await?;
+    write_control(
+        &mut send,
+        &ControlMsg::Auth {
+            code,
+            proto_version: common::PROTO_VERSION,
+        },
+    )
+    .await?;
+    match read_control(&mut recv).await? {
+        ControlMsg::AuthOk {
+            width,
+            height,
+            proto_version,
+        } => println!("[dump] auth ok {width}x{height} proto={proto_version}"),
+        other => bail!("认证失败: {other:?}"),
+    }
+
+    let (mut isend, _irecv) = conn.open_bi().await?;
+
+    // 入会先请求一次 IDR，和 viewer 行为一致。
+    // 注意：KeyFrameReq 必须走**流 2**（isend），agent 的读循环只监听流 2。
+    write_control(&mut isend, &ControlMsg::KeyFrameReq).await?;
+
+    let mut decoder = Decoder::new()?;
+    let mut sent_kfreq = false;
+    // 累积裸码流，用于 --save
+    let mut saved: Vec<u8> = Vec::new();
+
+    println!("\n序号 seq  kf  载荷字节  NAL 结构        解码结果");
+    println!("{}", "-".repeat(72));
+
+    for i in 0..total {
+        let (hdr, payload) = match tokio::time::timeout(
+            Duration::from_secs(10),
+            read_video_frame(&mut recv),
+        )
+        .await
+        {
+            Ok(r) => r?,
+            Err(_) => {
+                println!("[{i}] 读帧超时（桌面可能完全静止）");
+                break;
+            }
+        };
+
+        let types = nal_types(&payload);
+        let is_idr = types.contains(&5);
+
+        // 需要在 save 里也保留这一帧时，先记录到缓冲
+        if save_path.is_some() {
+            saved.extend_from_slice(&payload);
+        }
+
+        // 交叉校验：帧头 keyframe 标志必须与码流实际 NAL 类型一致。
+        // 这条不一致意味着时间戳/序号契约或编码器标志有 bug，比画面花屏更难排查。
+        if hdr.keyframe != is_idr {
+            println!(
+                "      ⚠️ 帧头 keyframe={} 但码流实际 IDR={}（seq={}）",
+                hdr.keyframe, is_idr, hdr.seq
+            );
+        }
+
+        // 模拟主控端积压跳帧：读出但不解码
+        if Some(i) == skip_at {
+            println!(
+                "[{i:2}] {:3}  {:<5} {:8}  {:<14}  ⏭ 跳过解码（模拟积压跳帧）",
+                hdr.seq,
+                hdr.keyframe,
+                payload.len(),
+                describe(&types)
+            );
+            continue;
+        }
+
+        let res = match decoder.decode(&payload) {
+            Ok(Some(_)) => "✅ 解出画面".to_string(),
+            Ok(None) => "○ 无输出（缓冲中）".to_string(),
+            Err(e) => format!("❌ {e}"),
+        };
+
+        println!(
+            "[{i:2}] {:3}  {:<5} {:8}  {:<14}  {}",
+            hdr.seq,
+            hdr.keyframe,
+            payload.len(),
+            describe(&types),
+            res
+        );
+
+        // 和 viewer 一样：解码失败就请求关键帧
+        if res.starts_with('❌') && !sent_kfreq {
+            sent_kfreq = true;
+            write_control(&mut isend, &ControlMsg::KeyFrameReq).await?;
+            println!("      ↑ 已发 KeyFrameReq");
+        }
+    }
+
+    // 诊断：静止桌面下再请求一次关键帧，看是否真能拿到 IDR
+    println!("\n[dump] 再发一次 KeyFrameReq，观察 10 帧…");
+    write_control(&mut isend, &ControlMsg::KeyFrameReq).await?;
+    for i in 0..10 {
+        match tokio::time::timeout(Duration::from_secs(5), read_video_frame(&mut recv)).await {
+            Ok(Ok((hdr, payload))) => {
+                let types = nal_types(&payload);
+                println!(
+                    "[k{i:2}] seq={:3} kf={:<5} {:6}B {}",
+                    hdr.seq,
+                    hdr.keyframe,
+                    payload.len(),
+                    describe(&types)
+                );
+                if types.contains(&5) {
+                    println!("      ↑ 收到 IDR");
+                }
+            }
+            _ => {
+                println!("[k{i:2}] 超时/流关闭");
+                break;
+            }
+        }
+    }
+
+    // 导出裸码流文件（Annex-B 拼接），供外部解码器验证
+    if let Some(p) = save_path.as_ref() {
+        std::fs::write(p, &saved)?;
+        let idr_cnt = {
+            // 粗略统计 IDR 数量：扫起始码后的 NAL 类型
+            let mut n = 0;
+            let mut i = 0usize;
+            while i + 3 < saved.len() {
+                let sc = if saved[i..].starts_with(&[0, 0, 0, 1]) {
+                    4
+                } else if saved[i..].starts_with(&[0, 0, 1]) {
+                    3
+                } else {
+                    i += 1;
+                    continue;
+                };
+                match saved.get(i + sc) {
+                    Some(&b) if b & 0x1F == 5 => {
+                        n += 1;
+                        i += sc + 1;
+                    }
+                    Some(_) => i += sc + 1,
+                    None => break,
+                }
+            }
+            n
+        };
+        println!(
+            "\n[dump] 已保存裸码流: {p}（{} 字节，含 {idr_cnt} 个 IDR）",
+            saved.len()
+        );
+    }
+
+    let _ = conn.close(0u32.into(), b"done");
+    Ok(())
+}

agent/src/bin/encbench.rs

@@ -0,0 +1,59 @@
+//! 编码基准：1080p 噪声帧（最恶劣压缩工况）对比单线程与 4 线程 openh264。
+//! 运行：cargo run --release -p agent --bin encbench
+
+use openh264::encoder::{
+    BitRate, Encoder, EncoderConfig, FrameRate, IntraFramePeriod, RateControlMode, UsageType,
+};
+use openh264::formats::{BgraSliceU8, YUVBuffer};
+use openh264::OpenH264API;
+use std::time::Instant;
+
+fn bench(threads: u16, frames: usize) -> f64 {
+    let mut enc = Encoder::with_api_config(
+        OpenH264API::from_source(),
+        EncoderConfig::new()
+            .bitrate(BitRate::from_bps(5_000_000))
+            .max_frame_rate(FrameRate::from_hz(30.0))
+            .rate_control_mode(RateControlMode::Bitrate)
+            .usage_type(UsageType::ScreenContentRealTime)
+            .intra_frame_period(IntraFramePeriod::from_num_frames(300))
+            .num_threads(threads),
+    )
+    .expect("encoder");
+
+    // 预生成 10 张不同噪声帧轮换（保证每帧 P 帧都真实编码，避免运动估计空转）
+    let mut frames_in = Vec::with_capacity(10);
+    for f in 0..10u32 {
+        let mut frame = vec![0u8; 1920 * 1080 * 4];
+        let mut seed = 12345u32.wrapping_add(f * 7919);
+        for px in frame.chunks_exact_mut(4) {
+            seed = seed.wrapping_mul(1103515245).wrapping_add(12345);
+            px.copy_from_slice(&seed.to_le_bytes());
+        }
+        frames_in.push(YUVBuffer::from_bgra8_source(BgraSliceU8::new(&frame, (1920, 1080))));
+    }
+
+    // 预热 5 帧（首帧 IDR、线程池初始化）
+    for (i, y) in frames_in.iter().enumerate().take(5) {
+        let _ = enc.encode(y).unwrap_or_else(|_| panic!("frame {i}"));
+    }
+    let t = Instant::now();
+    for (i, y) in frames_in.iter().cycle().take(frames).enumerate() {
+        let _ = enc.encode(y).unwrap_or_else(|_| panic!("frame {i}"));
+    }
+    t.elapsed().as_millis() as f64 / frames as f64
+}
+
+fn main() {
+    println!("1080p 噪声帧编码基准（含 BGRA→YUV 转换）");
+    let t = Instant::now();
+    let _ = YUVBuffer::from_bgra8_source(BgraSliceU8::new(
+        &vec![7u8; 1920 * 1080 * 4],
+        (1920, 1080),
+    ));
+    println!("BGRA→YUV 转换: {}ms/帧", t.elapsed().as_millis());
+    let s = bench(1, 20);
+    println!("单线程: {s:.1}ms/帧 → {}fps", (1000.0 / s) as u32);
+    let m = bench(4, 20);
+    println!("4 线程: {m:.1}ms/帧 → {}fps", (1000.0 / m) as u32);
+}

agent/src/capture.rs

@@ -1,9 +1,17 @@
 //! DXGI Desktop Duplication 采集（Windows 8+）。
-//! 帧处理：BGRA → openh264 H.264 编码（屏幕内容实时档，5Mbps）→ 线格式。
+//! 编码器自动选择：NVENC 硬编（N 卡：GPU 内 BGRA→H.264 零转换零拷贝直通）
+//! → openh264 软编兜底（无 N 卡/驱动异常时自动启用）。
 //! 支持主控端 KeyFrameReq 强制关键帧（解码异常恢复）。
 
 use anyhow::{anyhow, Result};
-use common::{encode_video_frame, VideoFrameHeader};
+use common::{encode_video_frame, h264_contains_idr, VideoFrameHeader};
+use nvenc::bitstream::BitStream;
+use nvenc::encoder::RegisteredResource;
+use nvenc::session::{InitParams, Session};
+use nvenc::sys::enums::{
+    NVencBufferFormat, NVencPicStruct, NVencPicType, NVencParamsRcMode, NVencTuningInfo,
+};
+use nvenc::sys::guids::{NV_ENC_CODEC_H264_GUID, NV_ENC_PRESET_P3_GUID};
 use openh264::encoder::{
     BitRate, Encoder, EncoderConfig, FrameRate, IntraFramePeriod, RateControlMode, UsageType,
 };
@@ -19,8 +27,9 @@ use windows::Win32::Graphics::Direct3D::{
 };
 use windows::Win32::Graphics::Direct3D11::{
     D3D11CreateDevice, ID3D11Device, ID3D11DeviceContext, ID3D11Resource, ID3D11Texture2D,
-    D3D11_CREATE_DEVICE_FLAG, D3D11_CPU_ACCESS_READ, D3D11_MAP, D3D11_MAP_READ,
-    D3D11_MAPPED_SUBRESOURCE, D3D11_SDK_VERSION, D3D11_TEXTURE2D_DESC, D3D11_USAGE_STAGING,
+    D3D11_BIND_RENDER_TARGET, D3D11_BIND_SHADER_RESOURCE, D3D11_CREATE_DEVICE_FLAG,
+    D3D11_CPU_ACCESS_READ, D3D11_MAP_READ, D3D11_MAPPED_SUBRESOURCE,
+    D3D11_SDK_VERSION, D3D11_TEXTURE2D_DESC, D3D11_USAGE_DEFAULT, D3D11_USAGE_STAGING,
 };
 use windows::Win32::Graphics::Dxgi::Common::{DXGI_FORMAT_B8G8R8A8_UNORM, DXGI_SAMPLE_DESC};
 use windows::Win32::Graphics::Dxgi::{
@@ -30,10 +39,24 @@ use windows::Win32::Graphics::Dxgi::{
 
 use std::time::{Duration, Instant};
 
+/// 周期 IDR 的帧间隔（兜底恢复点）。
+///
+/// 两个编码器共用同一常量，避免 NVENC 与软编的恢复窗口不一致——此前分别是
+/// 240 帧@60fps=4s 与 300 帧@60fps=5s，而 Linux 端又是 300 帧@30fps=10s。
+///
+/// 取值理由：**主恢复路径是 KeyFrameReq，不是自动 IDR**（协议 v2 后已确认请求
+/// 真正生效，见 vendor/nvenc 的 FORCEIDR 补丁）。自动 IDR 只用于兜底
+/// 「请求连续丢失」这种极端情况。60 帧 @60fps = 1 秒，既足够兜底，
+/// 又不会因过密的整帧内编码抬高码率。
+pub const INTRA_PERIOD_FRAMES: u32 = 60;
+
 pub struct Duplication {
-    _device: ID3D11Device,
+    pub device: ID3D11Device,
     context: ID3D11DeviceContext,
     staging_res: ID3D11Resource,
+    /// GPU 内中间纹理（NVENC 注册目标；DEFAULT usage，BGRA 与采集一致）
+    gpu_res: ID3D11Resource,
+    gpu_tex: ID3D11Texture2D,
     dup: IDXGIOutputDuplication,
     pub width: u32,
     pub height: u32,
@@ -47,13 +70,13 @@ impl Duplication {
             D3D11CreateDevice(
                 None,
                 D3D_DRIVER_TYPE_HARDWARE,
-                HMODULE::default(),
+                HMODULE(std::ptr::null_mut()),
                 D3D11_CREATE_DEVICE_FLAG(0),
                 Some(&[D3D_FEATURE_LEVEL_11_0]),
                 D3D11_SDK_VERSION,
-                Some(&mut device),
+                Some(&raw mut device),
                 None,
-                Some(&mut context),
+                Some(&raw mut context),
             )
             .map_err(|e| anyhow!("D3D11CreateDevice failed: {e}"))?;
             let device = device.ok_or_else(|| anyhow!("no d3d device"))?;
@@ -73,6 +96,7 @@ impl Duplication {
             let (width, height) = (desc.ModeDesc.Width, desc.ModeDesc.Height);
             anyhow::ensure!(width > 0 && height > 0, "bad desktop size");
 
+            // staging：软编路径 Map 读内存
             let sdesc = D3D11_TEXTURE2D_DESC {
                 Width: width,
                 Height: height,
@@ -95,10 +119,26 @@ impl Duplication {
             let staging = staging_opt.ok_or_else(|| anyhow!("no staging texture"))?;
             let staging_res: ID3D11Resource = staging.cast()?;
 
+            // GPU 中间纹理：NVENC 路径的注册目标（DEFAULT usage，GPU 可读）
+            let gdesc = D3D11_TEXTURE2D_DESC {
+                Usage: D3D11_USAGE_DEFAULT,
+                BindFlags: (D3D11_BIND_RENDER_TARGET.0 | D3D11_BIND_SHADER_RESOURCE.0) as u32,
+                CPUAccessFlags: 0,
+                ..sdesc
+            };
+            let mut gpu_opt: Option<ID3D11Texture2D> = None;
+            device
+                .CreateTexture2D(&gdesc, None, Some(&mut gpu_opt))
+                .map_err(|e| anyhow!("CreateTexture2D(gpu) failed: {e}"))?;
+            let gpu_tex = gpu_opt.ok_or_else(|| anyhow!("no gpu texture"))?;
+            let gpu_res: ID3D11Resource = gpu_tex.cast()?;
+
             Ok(Self {
-                _device: device,
+                device,
                 context,
                 staging_res,
+                gpu_res,
+                gpu_tex,
                 dup,
                 width,
                 height,
@@ -106,7 +146,8 @@ impl Duplication {
         }
     }
 
-    /// true=拿到新帧并已复制到 staging；false=超时无更新
+    /// true=拿到新帧并已复制；false=超时无更新。
+    /// 同时复制到 staging（软编读内存）与 GPU 中间纹理（NVENC 注册输入）。
     pub fn acquire(&mut self, timeout_ms: u32) -> Result<bool> {
         unsafe {
             let mut info = DXGI_OUTDUPL_FRAME_INFO::default();
@@ -116,6 +157,7 @@ impl Duplication {
                     let res = resource.ok_or_else(|| anyhow!("no desktop resource"))?;
                     let src: ID3D11Resource = res.cast()?;
                     self.context.CopyResource(&self.staging_res, &src);
+                    self.context.CopyResource(&self.gpu_res, &src);
                     let _ = self.dup.ReleaseFrame();
                     Ok(true)
                 }
@@ -125,8 +167,8 @@ impl Duplication {
         }
     }
 
-    /// 把 staging 纹理映射到内存并去掉行间距
-    pub fn copy_frame(&mut self) -> Result<Vec<u8>> {
+    /// 在 staging 映射窗口内执行回调（软编路径）。回调参数 = (像素数据, 行距)。
+    pub fn with_mapped<R>(&mut self, f: impl FnOnce(&[u8], usize) -> R) -> Result<R> {
         unsafe {
             let mut mapped = D3D11_MAPPED_SUBRESOURCE::default();
             self.context
@@ -135,16 +177,115 @@ impl Duplication {
             let (w, h) = (self.width as usize, self.height as usize);
             let pitch = mapped.RowPitch as usize;
             let src = std::slice::from_raw_parts(mapped.pData as *const u8, pitch * h);
-            let mut out = Vec::with_capacity(w * h * 4);
-            for row in 0..h {
-                out.extend_from_slice(&src[row * pitch..row * pitch + w * 4]);
-            }
+            let r = f(src, pitch);
             self.context.Unmap(&self.staging_res, 0);
-            Ok(out)
+            Ok(r)
         }
     }
 }
 
+/// NVENC 硬编封装：H.264 High、CBR 码率控制、UltraLowLatency 调优、无 B 帧。
+/// 输入 = 注册的 GPU 纹理（BGRA 与 DXGI 采集字节序一致，零转换）。
+struct NvencEncoder {
+    encoder: nvenc::encoder::Encoder,
+    registered: RegisteredResource,
+    bitstream: BitStream,
+    frame_count: usize,
+}
+
+impl NvencEncoder {
+    fn new(dup: &mut Duplication, bitrate_bps: u32) -> Result<Self> {
+        // 打开会话（无 N 卡 / 驱动不含编码库时在此失败）
+        let session: Session<_> = Session::open_dx(&dup.device)
+            .map_err(|e| anyhow!("open_dx: {e:?}"))?;
+        let codecs = session
+            .get_encode_codecs()
+            .map_err(|e| anyhow!("codecs: {e:?}"))?;
+        anyhow::ensure!(codecs.contains(&NV_ENC_CODEC_H264_GUID), "NVENC no H264 codec");
+        let (session, mut config) = session
+            .get_encode_preset_config_ex(
+                NV_ENC_CODEC_H264_GUID,
+                NV_ENC_PRESET_P3_GUID,
+                NVencTuningInfo::UltraLowLatency,
+            )
+            .map_err(|e| anyhow!("preset_config: {e:?}"))?;
+        // CBR 桌面实时档：码率恒定，延迟可预测（对标 UU 3.2Mbps@60fps）
+        config.preset_cfg.rc_params.rate_control_mode = NVencParamsRcMode::CBR;
+        config.preset_cfg.rc_params.average_bit_rate = bitrate_bps;
+        // 周期 IDR 是**兜底恢复点**，不是主恢复路径——主路径是 KeyFrameReq
+        // （协议 v2 后已确认真正生效，见 vendor/nvenc 的 FORCEIDR 补丁）。
+        //
+        // 取值权衡：GOP 越短，丢帧后自动恢复越快，但每次 IDR 都是整帧内编码，
+        // 码率开销显著（1080p 桌面 IDR 通常数倍于 P 帧）。
+        // 60 帧 @60fps = 1s：既覆盖「KeyFrameReq 连续丢失」这种极端情况，
+        // 又把兜底窗口压到 1 秒以内。原先 240 帧 = 4s，在请求已可靠的前提下
+        // 只会让受害时长无谓地长 4 倍。
+        config.preset_cfg.gop_len = INTRA_PERIOD_FRAMES;
+        config.preset_cfg.frame_interval_p = 1; // 无 B 帧
+
+        let init = InitParams {
+            encode_guid: NV_ENC_CODEC_H264_GUID,
+            preset_guid: NV_ENC_PRESET_P3_GUID,
+            resolution: [dup.width, dup.height],
+            aspect_ratio: [dup.width, dup.height],
+            frame_rate: [60, 1],
+            tuning_info: NVencTuningInfo::UltraLowLatency,
+            buffer_format: NVencBufferFormat::ARGB,
+            encode_config: &mut config.preset_cfg,
+            enable_ptd: true,
+            max_encoder_resolution: [dup.width, dup.height],
+        };
+        let encoder = session
+            .init_encoder(init)
+            .map_err(|e| anyhow!("init_encoder: {e:?}"))?;
+        let registered = encoder
+            .register_resource_dx11(&dup.gpu_tex, NVencBufferFormat::ARGB, 0)
+            .map_err(|e| anyhow!("register_resource: {e:?}"))?;
+        let bitstream = encoder
+            .create_bitstream_buffer()
+            .map_err(|e| anyhow!("bitstream: {e:?}"))?;
+        Ok(Self {
+            encoder,
+            registered,
+            bitstream,
+            frame_count: 0,
+        })
+    }
+
+    /// 编码当前 GPU 纹理内容，返回 Annex B H.264 码流。
+    fn encode(&mut self, force_idr: bool, ts_ms: u64) -> Result<Vec<u8>> {
+        // 首帧强制 IDR：解码端从任意时刻接入，没有 IDR 无法解出后续 P 帧
+        let ty = if force_idr || self.frame_count == 0 {
+            NVencPicType::IDR
+        } else {
+            NVencPicType::P
+        };
+        self.encoder.encode_picture(
+            &self.registered,
+            &self.bitstream,
+            self.frame_count,
+            ts_ms,
+            NVencBufferFormat::ARGB,
+            NVencPicStruct::Frame,
+            ty,
+            None,
+        )
+        .map_err(|e| anyhow!("encode_picture: {e:?}"))?;
+        self.frame_count += 1;
+        // 同步读出码流（NVENC 单帧编码 1-3ms，阻塞等待可接受）
+        let lock = self
+            .bitstream
+            .try_lock(true)
+            .map_err(|e| anyhow!("bitstream lock: {e:?}"))?;
+        let out = lock.as_slice().to_vec();
+        drop(lock);
+        if out.is_empty() {
+            anyhow::bail!("nvenc empty bitstream");
+        }
+        Ok(out)
+    }
+}
+
 #[allow(dead_code)]
 pub fn desktop_size() -> Result<(u32, u32)> {
     let d = Duplication::new()?;
@@ -153,7 +294,8 @@ pub fn desktop_size() -> Result<(u32, u32)> {
 
 /// 采集主循环：独立线程运行；连接断开（通道关闭）时退出。
 /// 通道为 watch 单槽（latest-wins）：发送即覆盖，网络慢时不产生积压。
-pub fn run(tx: Sender<Option<Vec<u8>>>, keyreq: Arc<AtomicBool>) {
+/// congestion：发送侧 write 超时置位 → 跳过当前帧（不编码不发送），注入率自适应降速。
+pub fn run(tx: Sender<Option<Vec<u8>>>, keyreq: Arc<AtomicBool>, congestion: Arc<AtomicBool>) {
     let start = Instant::now();
     loop {
         let mut dup = match Duplication::new() {
@@ -169,78 +311,259 @@ pub fn run(tx: Sender<Option<Vec<u8>>>, keyreq: Arc<AtomicBool>) {
             dup.width, dup.height
         );
 
-        // H.264 编码器：屏幕内容实时档 + 码率控制（对标 UU：3.2Mbps@60fps）
-        let mut encoder = match Encoder::with_api_config(
-            OpenH264API::from_source(),
-            EncoderConfig::new()
-                .bitrate(BitRate::from_bps(5_000_000))
-                .max_frame_rate(FrameRate::from_hz(30.0))
-                .rate_control_mode(RateControlMode::Bitrate)
-                .usage_type(UsageType::ScreenContentRealTime)
-                .intra_frame_period(IntraFramePeriod::from_num_frames(300)),
-        ) {
-            Ok(e) => e,
+        // ---- 编码器自动选择：NVENC 硬编优先，失败落回 openh264 软编 ----
+        enum EncoderKind {
+            Nvenc(Box<NvencEncoder>),
+            Soft(Box<openh264::encoder::Encoder>),
+        }
+        let mut encoder: EncoderKind = match NvencEncoder::new(&mut dup, 5_000_000) {
+            Ok(nv) => {
+                eprintln!("[capture] encoder = NVENC hardware (CBR 5Mbps@60fps, ARGB direct)");
+                EncoderKind::Nvenc(Box::new(nv))
+            }
             Err(e) => {
-                eprintln!("[capture] encoder init failed: {e}");
-                return;
+                eprintln!("[capture] NVENC unavailable ({e}); fallback to openh264 software");
+                match Encoder::with_api_config(
+                    OpenH264API::from_source(),
+                    EncoderConfig::new()
+                        .bitrate(BitRate::from_bps(5_000_000))
+                        .max_frame_rate(FrameRate::from_hz(60.0))
+                        .rate_control_mode(RateControlMode::Bitrate)
+                        .usage_type(UsageType::ScreenContentRealTime)
+                        .intra_frame_period(IntraFramePeriod::from_num_frames(
+                            INTRA_PERIOD_FRAMES,
+                        ))
+                        .num_threads(4),
+                ) {
+                    Ok(e) => {
+                        eprintln!("[capture] encoder = openh264 software (5Mbps@60fps, 4T)");
+                        EncoderKind::Soft(Box::new(e))
+                    }
+                    Err(e) => {
+                        eprintln!("[capture] encoder init failed: {e}");
+                        return;
+                    }
+                }
             }
         };
 
-        let mut last_frame: Option<Vec<u8>> = None;
+        // 最近一帧的**裸载荷**与关键帧标志：静止重发时要用它们重建帧头，
+        // 不能直接重发整帧（那样 seq/ts_ms 会停在上次发送时刻）
+        let mut last_payload: Option<Vec<u8>> = None;
+        let mut last_kf = false;
         let mut last_sent = Instant::now() - Duration::from_secs(10);
-        let min_frame = Duration::from_millis(33); // 30fps 上限
+        let min_frame = Duration::from_millis(16); // 60fps 上限
+        let mut scratch: Vec<u8> = Vec::new(); // 软编：行距不连续时的复用缓冲
+        // 帧序号：每发一帧 +1（含静止桌面的重复帧），供主控端做丢帧检测
+        let mut seq: u64 = 0;
+        // 编码耗时统计（每 120 帧输出一次均值，ms）
+        let mut stat_frames = 0u64;
+        let mut stat_convert_ms = 0u64;
+        let mut stat_encode_ms = 0u64;
+        let mut stat_skipped = 0u64; // 拥塞跳帧计数
+
+        // `$kf` 由调用点显式给出：NVENC 路径知道 `force_key`，软编路径同理。
+        // 不要在这里猜——首帧和 KeyFrameReq 都会产生 IDR，猜错会让解码端错过重同步点。
+        macro_rules! emit {
+            ($payload:expr, $kf:expr) => {{
+                let header = VideoFrameHeader {
+                    width: dup.width,
+                    height: dup.height,
+                    ts_ms: start.elapsed().as_millis() as u64,
+                    seq,
+                    keyframe: $kf,
+                };
+                let payload_vec: Vec<u8> = $payload;
+                let frame = encode_video_frame(&header, &payload_vec);
+                if tx.send(Some(frame.clone())).is_err() {
+                    return; // 会话结束
+                }
+                last_payload = Some(payload_vec);
+                last_kf = $kf;
+                last_sent = Instant::now();
+                seq = seq.wrapping_add(1);
+                stat_frames += 1;
+            }};
+        }
+
         loop {
             let iter_start = Instant::now();
             match dup.acquire(80) {
-                Ok(true) => match dup.copy_frame() {
-                    Ok(raw) => {
-                        // 主控端请求关键帧（解码异常恢复）
-                        if keyreq.swap(false, Ordering::Relaxed) {
-                            encoder.force_intra_frame();
-                        }
-                        let header = VideoFrameHeader {
-                            width: dup.width,
-                            height: dup.height,
-                            ts_ms: start.elapsed().as_millis() as u64,
-                        };
-                        let yuv = YUVBuffer::from_bgra8_source(BgraSliceU8::new(
-                            &raw,
-                            (dup.width as usize, dup.height as usize),
-                        ));
-                        match encoder.encode(&yuv) {
-                            Ok(ebs) => {
-                                let payload = ebs.to_vec();
-                                let frame = encode_video_frame(&header, &payload);
-                                if tx.send(Some(frame.clone())).is_err() {
-                                    return; // 会话结束
-                                }
-                                last_frame = Some(frame);
-                                last_sent = Instant::now();
-                            }
-                            Err(e) => {
-                                eprintln!("[capture] encode failed: {e}");
-                            }
-                        }
-                        // 帧间隔节流到 ~30fps
+                Ok(true) => {
+                    // 拥塞反馈：发送侧排队深 → 跳过本帧（NVENC 少输入一帧，参考链连续；
+                    // 解码端收到的帧序 = 编码端实际输出序，无花屏风险）
+                    //
+                    // ⚠️ 必须放在消费 keyreq **之前**：先前顺序是「先 swap 再判断拥塞」，
+                    // 一旦本帧因拥塞被跳过，已消费的 KeyFrameReq 就随 continue 一起丢失，
+                    // 解码端等不到 IDR（与下方静止分支同源的缺陷）。
+                    if congestion.swap(false, Ordering::Relaxed) {
+                        stat_skipped += 1;
                         let el = iter_start.elapsed();
                         if el < min_frame {
                             std::thread::sleep(min_frame - el);
                         }
+                        continue;
                     }
-                    Err(e) => {
-                        eprintln!("[capture] frame copy failed: {e}");
-                        break; // 重建 duplication
-                    }
-                },
-                Ok(false) => {
-                    // 桌面静止：低频重发最后一帧（重复 P 帧，解码端画面不变）
-                    if last_sent.elapsed() > Duration::from_millis(500) {
-                        if let Some(f) = last_frame.as_ref() {
-                            if tx.send(Some(f.clone())).is_err() {
-                                return;
+                    // 主控端请求关键帧（解码异常恢复）。走到这里一定会编码，
+                    // 因此可以安全地消费标志。
+                    let force_key = keyreq.swap(false, Ordering::Relaxed);
+                    match &mut encoder {
+                        EncoderKind::Nvenc(enc) => {
+                            let enc_start = Instant::now();
+                            let r = enc.encode(force_key, start.elapsed().as_millis() as u64);
+                            stat_encode_ms += enc_start.elapsed().as_millis() as u64;
+                            match r {
+                                Ok(payload) => {
+                                    let kf = h264_contains_idr(&payload);
+                                    emit!(payload, kf)
+                                }
+                                Err(e) => eprintln!("[capture] nvenc encode failed: {e}"),
                             }
-                            last_sent = Instant::now();
                         }
+                        EncoderKind::Soft(enc) => {
+                            if force_key {
+                                enc.force_intra_frame();
+                            }
+                            // 映射窗口内直接做 BGRA→YUV（行距连续时零拷贝，否则复用 scratch）
+                            let conv_start = Instant::now();
+                            let dims = (dup.width as usize, dup.height as usize);
+                            let conv = dup.with_mapped(|src, pitch| {
+                                if pitch == dims.0 * 4 {
+                                    YUVBuffer::from_bgra8_source(BgraSliceU8::new(src, dims))
+                                } else {
+                                    scratch.resize(dims.0 * dims.1 * 4, 0);
+                                    for (row, dst) in
+                                        scratch.chunks_exact_mut(dims.0 * 4).enumerate()
+                                    {
+                                        dst.copy_from_slice(
+                                            &src[row * pitch..row * pitch + dims.0 * 4],
+                                        );
+                                    }
+                                    YUVBuffer::from_bgra8_source(BgraSliceU8::new(&scratch, dims))
+                                }
+                            });
+                            match conv {
+                                Ok(yuv) => {
+                                    stat_convert_ms +=
+                                        conv_start.elapsed().as_millis() as u64;
+                                    let enc_start = Instant::now();
+                                    let r = enc.encode(&yuv);
+                                    stat_encode_ms += enc_start.elapsed().as_millis() as u64;
+                                    match r {
+                                        Ok(ebs) => {
+                                            let payload = ebs.to_vec();
+                                            let kf = h264_contains_idr(&payload);
+                                            emit!(payload, kf)
+                                        }
+                                        Err(e) => {
+                                            eprintln!("[capture] encode failed: {e}");
+                                        }
+                                    }
+                                }
+                                Err(e) => {
+                                    eprintln!("[capture] frame convert failed: {e}");
+                                    break;
+                                }
+                            }
+                        }
+                    }
+                    if stat_frames > 0 && stat_frames % 120 == 0 {
+                        eprintln!(
+                            "[capture] avg convert {}ms, encode {}ms/frame, skipped {} (last 120)",
+                            stat_convert_ms / 120,
+                            stat_encode_ms / 120,
+                            stat_skipped
+                        );
+                        stat_convert_ms = 0;
+                        stat_encode_ms = 0;
+                        stat_skipped = 0;
+                    }
+                    // 帧间隔节流到 ~60fps
+                    let el = iter_start.elapsed();
+                    if el < min_frame {
+                        std::thread::sleep(min_frame - el);
+                    }
+                }
+                Ok(false) => {
+                    // 桌面静止：低频重发（丢包后恢复 + 会话保活）。
+                    //
+                    // ⚠️ 这里曾有三个缺陷，全部围绕「KeyFrameReq 被静默丢弃」：
+                    // 1. `swap` 写在时间闸**外面**：请求若落在距上次发送 500ms 之内，
+                    //    标志已被消费但分支不进入，该次请求直接丢失（手册 §6.1 第 3 条）。
+                    // 2. 软编分支只重发旧码流、不看 force_key：永远吐不出 IDR（手册 §6.1 第 2 条）。
+                    // 3. NVENC 分支虽然把 force_key 传给了编码器，但受第 1 条限制。
+                    //
+                    // 现在的语义：**关键帧请求绕过 500ms 节流**——它是错误恢复路径，
+                    // 延迟一次 IDR 的代价是解码端持续黑屏，远高于多发一帧的带宽成本。
+                    let force_key = keyreq.swap(false, Ordering::Relaxed);
+                    let due = force_key || last_sent.elapsed() > Duration::from_millis(500);
+                    if due {
+                        match &mut encoder {
+                            EncoderKind::Nvenc(enc) => {
+                                // 重编当前 GPU 帧（内容未变，输出极小；force_key 时为 IDR）
+                                let r = enc.encode(force_key, start.elapsed().as_millis() as u64);
+                                match r {
+                                    Ok(payload) => {
+                                        let kf = h264_contains_idr(&payload);
+                                        emit!(payload, kf)
+                                    }
+                                    Err(e) => {
+                                        eprintln!("[capture] nvenc idle encode failed: {e}")
+                                    }
+                                }
+                            }
+                            EncoderKind::Soft(enc) => {
+                                // 软编：静止桌面没有新像素可编，只能重发最近一帧。
+                                // 但 force_key 时必须真的重编出 IDR —— 重发旧 P 帧对
+                                // 已经解不动的解码端毫无帮助。
+                                //
+                                // 裸像素来源：staging 纹理里仍是上一帧内容（DXGI 只在
+                                // 有新帧时覆盖），重新 Map 一次即可，不必每帧额外拷 14MB。
+                                if force_key {
+                                    enc.force_intra_frame();
+                                    let dims = (dup.width as usize, dup.height as usize);
+                                    let conv = dup.with_mapped(|src, pitch| {
+                                        if pitch == dims.0 * 4 {
+                                            YUVBuffer::from_bgra8_source(BgraSliceU8::new(
+                                                src, dims,
+                                            ))
+                                        } else {
+                                            scratch.resize(dims.0 * dims.1 * 4, 0);
+                                            for (row, dst) in
+                                                scratch.chunks_exact_mut(dims.0 * 4).enumerate()
+                                            {
+                                                dst.copy_from_slice(
+                                                    &src[row * pitch..row * pitch + dims.0 * 4],
+                                                );
+                                            }
+                                            YUVBuffer::from_bgra8_source(BgraSliceU8::new(
+                                                &scratch, dims,
+                                            ))
+                                        }
+                                    });
+                                    match conv {
+                                        Ok(yuv) => match enc.encode(&yuv) {
+                                            Ok(ebs) => {
+                                                let payload = ebs.to_vec();
+                                                let kf = h264_contains_idr(&payload);
+                                                emit!(payload, kf)
+                                            }
+                                            Err(e) => eprintln!(
+                                                "[capture] idle keyframe encode failed: {e}"
+                                            ),
+                                        },
+                                        Err(e) => {
+                                            eprintln!("[capture] idle keyframe convert failed: {e}")
+                                        }
+                                    }
+                                } else if let Some(p) = last_payload.as_ref() {
+                                    // 非关键帧的保活重发：复用载荷但重建帧头（seq 必须递增）
+                                    let kf = last_kf;
+                                    emit!(p.clone(), kf)
+                                }
+                            }
+                        }
+                        last_sent = Instant::now();
                     } else {
                         std::thread::sleep(Duration::from_millis(8));
                     }

agent/src/main.rs

@@ -43,12 +43,13 @@ async fn main() -> Result<()> {
 
     // 传输参数调优：
     // - 收发窗口放大，避免高 RTT 下吞吐被 窗口/RTT 死锁（默认 512KB 流窗口）
-    // - 发送缓冲上限 2MB：QUIC 内部排队有界（约 1 帧多），配合上游 latest-wins 丢帧
-    //   把端到端排队延迟压在 ~0.4s 内
+    // - 发送缓冲上限 64KB：QUIC 内部排队硬上限（实测 WiFi ~3Mbps 吞吐 → E2E ≤ ~170ms；
+    //   突发吞吐 = 64KB/7ms ≈ 72Mbps，不限制带宽）。注意此窗口为连接级，流 2 输入/Ping
+    //   数据量极小不受影响。配合下方拥塞反馈跳帧，把排队压在数帧以内
     let mut transport = quinn::TransportConfig::default();
     transport.receive_window(quinn::VarInt::from_u32(16 * 1024 * 1024));
     transport.stream_receive_window(quinn::VarInt::from_u32(8 * 1024 * 1024));
-    transport.send_window(2 * 1024 * 1024);
+    transport.send_window(64 * 1024);
     let mut server_config = quinn::ServerConfig::with_single_cert(vec![cert], key.into())?;
     server_config.transport_config(Arc::new(transport));
 
@@ -68,16 +69,42 @@ async fn main() -> Result<()> {
     // 流 1：认证 + 视频下行
     let (mut send, mut recv) = conn.accept_bi().await?;
 
-    // 认证
+    // 认证：先校验版本，再校验验证码。
+    // 顺序刻意如此——版本不一致时字段布局可能不同，验证码的解析结果不可信。
     let first = read_control(&mut recv).await?;
-    let code_ok = matches!(&first, ControlMsg::Auth { code: c } if *c == code);
-    if !code_ok {
-        write_control(&mut send, &ControlMsg::AuthFail("bad code".into())).await?;
+    let auth_err: Option<String> = match &first {
+        ControlMsg::Auth {
+            code: c,
+            proto_version,
+        } => {
+            if *proto_version != common::PROTO_VERSION {
+                Some(format!(
+                    "protocol version mismatch: client={proto_version}, server={}",
+                    common::PROTO_VERSION
+                ))
+            } else if *c != code {
+                Some("bad code".into())
+            } else {
+                None
+            }
+        }
+        other => Some(format!("expected Auth, got {other:?}")),
+    };
+    if let Some(msg) = auth_err {
+        write_control(&mut send, &ControlMsg::AuthFail(msg.clone())).await?;
         send.finish()?;
-        anyhow::bail!("auth failed");
+        anyhow::bail!(msg);
     }
     let (w, h) = capture::desktop_size()?;
-    write_control(&mut send, &ControlMsg::AuthOk { width: w, height: h }).await?;
+    write_control(
+        &mut send,
+        &ControlMsg::AuthOk {
+            width: w,
+            height: h,
+            proto_version: common::PROTO_VERSION,
+        },
+    )
+    .await?;
     println!("[agent] auth ok, desktop {w}x{h}");
 
     // 流 2：键鼠输入 + 控制上行（与视频分离，避免被视频积压阻塞）
@@ -87,7 +114,10 @@ async fn main() -> Result<()> {
     let (tx, mut frames_rx) = watch::channel::<Option<Vec<u8>>>(None);
     let keyreq = Arc::new(AtomicBool::new(false));
     let keyreq_capture = keyreq.clone();
-    std::thread::spawn(move || capture::run(tx, keyreq_capture));
+    // 拥塞反馈标志：发送侧 write 超过单帧预算(20ms) → 置位，采集线程跳帧降注入率
+    let congestion = Arc::new(AtomicBool::new(false));
+    let congestion_capture = congestion.clone();
+    std::thread::spawn(move || capture::run(tx, keyreq_capture, congestion_capture));
 
     // 上行控制消息（Pong）经通道交给主循环写流 2，避免多任务争抢
     let (ctl_tx, mut ctl_rx) = mpsc::unbounded_channel::<ControlMsg>();
@@ -127,7 +157,14 @@ async fn main() -> Result<()> {
                     break; // 采集线程退出
                 }
                 if let Some(data) = frames_rx.borrow().clone() {
-                    if send.write_all(&data).await.is_err() {
+                    let wt = std::time::Instant::now();
+                    let ok = send.write_all(&data).await.is_ok();
+                    // write 耗时 > 单帧预算(16.7ms 的 1.2 倍) → QUIC 窗口排队深，
+                    // 通知采集线程跳帧，把注入率降到网络实际吞吐水平
+                    if wt.elapsed() > std::time::Duration::from_millis(20) {
+                        congestion.store(true, Ordering::Relaxed);
+                    }
+                    if !ok {
                         break;
                     }
                 }

common/src/lib.rs

@@ -1,15 +1,35 @@
 //! 通用协议与帧封装：控制消息（bincode + 长度前缀）与视频帧格式。
 
+/// P2P 打洞信令协议（信令通道专用，不含中继；三端共享契约）
+pub mod signaling;
+
 use anyhow::Result;
 use serde::{Deserialize, Serialize};
 use tokio::io::{AsyncReadExt, AsyncWriteExt};
 
+/// 媒体/控制协议版本。
+///
+/// **改动规则**：任何对 `ControlMsg` 或 `VideoFrameHeader` 字段的增删改都必须递增此值。
+/// 理由：线格式是 bincode（按位置编码，无字段名），新增字段会让旧端解析失败或错位，
+/// 且失败方式可能是静默的错误数据而非明确报错。递增后由 `Auth` 握手显式拒绝旧端，
+/// 把"连上了但行为诡异"变成"连不上且提示升级"。
+///
+/// - v1：初版（无版本字段，隐式）
+/// - v2：`Auth`/`AuthOk` 携带版本；帧头增加 `seq`/`keyframe`
+pub const PROTO_VERSION: u16 = 2;
+
 /// 控制通道消息（双向）
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub enum ControlMsg {
-    /// 主控端认证（临时验证码，MVP 明文走 QUIC-TLS 加密通道）
-    Auth { code: String },
-    AuthOk { width: u32, height: u32 },
+    /// 主控端认证（临时验证码，MVP 明文走 QUIC-TLS 加密通道）。
+    /// `proto_version` 必须等于 [`PROTO_VERSION`]，否则被控端回 `AuthFail` 并拒绝。
+    Auth { code: String, proto_version: u16 },
+    /// 认证通过。`proto_version` 回显被控端的版本，供主控端确认双方一致。
+    AuthOk {
+        width: u32,
+        height: u32,
+        proto_version: u16,
+    },
     AuthFail(String),
     KeyFrameReq,
     Ping(u64),
@@ -39,12 +59,22 @@ pub enum InputEvent {
     KeyUp { scancode: u16, extended: bool },
 }
 
-/// 视频帧头（载荷为 LZ4 压缩的 BGRA 像素，按行紧凑排列）
+/// 视频帧头。载荷为 H.264 Annex-B 码流（含 00 00 00 01 起始码）。
+///
+/// 字段语义：
+/// - `width` / `height`：被控端桌面尺寸（逻辑尺寸，非编码对齐后的尺寸）
+/// - `ts_ms`：被控端采集时刻（被控时钟），配合 Ping/Pong 估计的时钟偏移算端到端延迟
+/// - `seq`：帧序号，从 0 单调递增，每发一帧 +1（含静止桌面的重复帧）。
+///   用于丢帧检测与弱网统计；注意它统计的是"发送序"，不是"显示序"
+/// - `keyframe`：本帧是否 IDR。解码端（尤其 MediaCodec）需要它决定是否重置解码器，
+///   不必再自己扫 NAL 起始码判断
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct VideoFrameHeader {
     pub width: u32,
     pub height: u32,
     pub ts_ms: u64,
+    pub seq: u64,
+    pub keyframe: bool,
 }
 
 async fn read_u32le<R: AsyncReadExt + Unpin>(r: &mut R) -> Result<u32> {
@@ -78,7 +108,9 @@ pub async fn read_control<R: AsyncReadExt + Unpin>(r: &mut R) -> Result<ControlM
     Ok(bincode::deserialize(&buf)?)
 }
 
-/// 编码视频帧：[总长 u32][头长 u32][bincode 头][LZ4 载荷]
+/// 编码视频帧：[总长 u32][头长 u32][bincode 头][H.264 载荷]
+///
+/// `总长` 不含自身这 4 字节，等于 `4 + 头长 + 载荷长`。
 pub fn encode_video_frame(header: &VideoFrameHeader, payload: &[u8]) -> Vec<u8> {
     let hb = bincode::serialize(header).expect("serialize header");
     let total = 4 + hb.len() + payload.len();
@@ -90,14 +122,292 @@ pub fn encode_video_frame(header: &VideoFrameHeader, payload: &[u8]) -> Vec<u8>
     out
 }
 
+/// 单帧总长上限（256 MiB）。超过即视为协议错误或恶意输入。
+const MAX_VIDEO_FRAME: usize = 256 << 20;
+
+/// 判断一段 Annex-B H.264 码流里是否含 IDR 片（NAL 类型 5）。
+///
+/// 用途：填充 [`VideoFrameHeader::keyframe`]。
+/// 为什么不问编码器要这个标志——NVENC 与 openh264 的 API 都能间接推出，
+/// 但两者规则不同（首帧强制、`force_intra_frame`、GOP 自动 IDR 交织），
+/// 而**实际输出**是唯一可信来源。直接看码流，两种编码器一套逻辑。
+///
+/// 只识别 3/4 字节起始码；`start-code emulation prevention` 由编码器保证，
+/// 因此不会在 SPS/PPS 载荷里误判出起始码。
+pub fn h264_contains_idr(payload: &[u8]) -> bool {
+    let mut i = 0usize;
+    while i + 3 < payload.len() {
+        let sc = if payload[i..].starts_with(&[0, 0, 0, 1]) {
+            4
+        } else if payload[i..].starts_with(&[0, 0, 1]) {
+            3
+        } else {
+            i += 1;
+            continue;
+        };
+        match payload.get(i + sc) {
+            // nal_unit_type 占首字节低 5 位
+            Some(&b) if b & 0x1F == 5 => return true,
+            Some(_) => i += sc + 1,
+            None => break,
+        }
+    }
+    false
+}
+
+/// 读一个视频帧。
+///
+/// 对端数据一律视为不可信输入：`total` 与 `hlen` 都必须做**上下界**校验，
+/// 否则构造一个 `total < 4` 的帧就能让接收端在切片处 panic（进程级拒绝服务）。
 pub async fn read_video_frame<R: AsyncReadExt + Unpin>(
     r: &mut R,
 ) -> Result<(VideoFrameHeader, Vec<u8>)> {
     let total = read_u32le(r).await? as usize;
-    anyhow::ensure!(total < 256 << 20, "video frame too large: {total}");
+    // 下界：至少要容得下「头长字段(4) + 一个非空的 bincode 头」。
+    // 上界：防止对端声明超大长度导致巨量分配。
+    anyhow::ensure!(
+        (4..MAX_VIDEO_FRAME).contains(&total),
+        "video frame length out of range: {total}"
+    );
+
     let mut buf = vec![0u8; total];
     r.read_exact(&mut buf).await?;
-    let hlen = u32::from_le_bytes(buf[0..4].try_into().unwrap()) as usize;
+
+    let hlen = u32::from_le_bytes(buf[0..4].try_into().expect("已校验 total >= 4")) as usize;
+    // hlen 必须落在 [1, total-4] 内：0 无法反序列化，超出则切片越界
+    anyhow::ensure!(
+        hlen > 0 && hlen <= total - 4,
+        "video header length invalid: hlen={hlen}, total={total}"
+    );
+
     let header: VideoFrameHeader = bincode::deserialize(&buf[4..4 + hlen])?;
     Ok((header, buf[4 + hlen..].to_vec()))
 }
+
+/// 把一个已编码的完整帧拆回 `(帧头, 载荷)`。
+///
+/// 用途：静止桌面重发时，被控端需要复用上一帧的**载荷**但重建**帧头**
+/// （`seq` 必须递增、`ts_ms` 必须是本次发送时刻）。直接 `clone` 整个帧会让
+/// 这两个字段停在上一次发送的时刻，破坏 `seq` 单调递增契约。
+///
+/// 只接受本模块 [`encode_video_frame`] 产出的字节；格式不符返回 `Err`。
+pub fn split_video_frame(frame: &[u8]) -> Result<(VideoFrameHeader, &[u8])> {
+    anyhow::ensure!(frame.len() >= 8, "frame too short: {}", frame.len());
+    let hlen = u32::from_le_bytes(frame[4..8].try_into().expect("已校验 len >= 8")) as usize;
+    anyhow::ensure!(
+        hlen > 0 && hlen <= frame.len() - 8,
+        "header length invalid: hlen={hlen}, len={}",
+        frame.len()
+    );
+    let header: VideoFrameHeader = bincode::deserialize(&frame[8..8 + hlen])?;
+    Ok((header, &frame[8 + hlen..]))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tokio::io::duplex;
+
+    fn hdr(seq: u64, keyframe: bool) -> VideoFrameHeader {
+        VideoFrameHeader {
+            width: 1920,
+            height: 1080,
+            ts_ms: 12345,
+            seq,
+            keyframe,
+        }
+    }
+
+    // ---- 控制消息 ----
+
+    #[test]
+    fn control_roundtrip_preserves_version() {
+        let m = ControlMsg::Auth {
+            code: "123456".into(),
+            proto_version: PROTO_VERSION,
+        };
+        let bytes = encode_control(&m);
+        // 长度前缀 + 载荷
+        let len = u32::from_le_bytes(bytes[0..4].try_into().unwrap()) as usize;
+        assert_eq!(len, bytes.len() - 4);
+        let back: ControlMsg = bincode::deserialize(&bytes[4..]).unwrap();
+        match back {
+            ControlMsg::Auth { code, proto_version } => {
+                assert_eq!(code, "123456");
+                assert_eq!(proto_version, PROTO_VERSION);
+            }
+            other => panic!("期望 Auth，实际 {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn control_write_read_roundtrip() {
+        let (mut a, mut b) = duplex(64 * 1024);
+        let msgs = [
+            ControlMsg::Auth {
+                code: "x".into(),
+                proto_version: PROTO_VERSION,
+            },
+            ControlMsg::AuthOk {
+                width: 800,
+                height: 600,
+                proto_version: PROTO_VERSION,
+            },
+            ControlMsg::KeyFrameReq,
+            ControlMsg::Ping(42),
+            ControlMsg::Pong {
+                t: 1,
+                agent_ts: 2,
+                lost: 3,
+                sent: 4,
+            },
+        ];
+        for m in &msgs {
+            write_control(&mut a, m).await.unwrap();
+            let got = read_control(&mut b).await.unwrap();
+            assert_eq!(format!("{got:?}"), format!("{m:?}"));
+        }
+    }
+
+    // ---- 视频帧头 ----
+
+    #[test]
+    fn video_header_roundtrip_keeps_seq_and_keyframe() {
+        for (seq, kf) in [(0u64, true), (1, false), (u64::MAX, false)] {
+            let h = hdr(seq, kf);
+            let payload = b"\x00\x00\x00\x01\x65fake-nal";
+            let bytes = encode_video_frame(&h, payload);
+
+            let total = u32::from_le_bytes(bytes[0..4].try_into().unwrap()) as usize;
+            assert_eq!(total, bytes.len() - 4, "总长字段应不含自身");
+
+            let hlen = u32::from_le_bytes(bytes[4..8].try_into().unwrap()) as usize;
+            let back: VideoFrameHeader = bincode::deserialize(&bytes[8..8 + hlen]).unwrap();
+            assert_eq!(back.seq, seq);
+            assert_eq!(back.keyframe, kf);
+            assert_eq!(&bytes[8 + hlen..], payload);
+        }
+    }
+
+    #[tokio::test]
+    async fn video_frame_write_read_roundtrip() {
+        let (mut a, mut b) = duplex(256 * 1024);
+        let h = hdr(7, true);
+        let payload = vec![0xABu8; 4096];
+        let bytes = encode_video_frame(&h, &payload);
+        tokio::io::AsyncWriteExt::write_all(&mut a, &bytes).await.unwrap();
+
+        let (h2, p2) = read_video_frame(&mut b).await.unwrap();
+        assert_eq!(h2.seq, 7);
+        assert!(h2.keyframe);
+        assert_eq!((h2.width, h2.height), (1920, 1080));
+        assert_eq!(p2, payload);
+    }
+
+    // ---- 不可信输入（P3 的核心回归） ----
+
+    /// `total < 4` 必须报错而不是 panic：旧实现在这里 `buf[0..4]` 会越界 panic。
+    #[tokio::test]
+    async fn rejects_total_below_minimum() {
+        for total in [0u32, 1, 3] {
+            let (mut a, mut b) = duplex(64);
+            tokio::io::AsyncWriteExt::write_all(&mut a, &total.to_le_bytes())
+                .await
+                .unwrap();
+            let err = read_video_frame(&mut b).await.unwrap_err().to_string();
+            assert!(
+                err.contains("out of range"),
+                "total={total} 应被拒绝，实际错误: {err}"
+            );
+        }
+    }
+
+    /// `total == 4` 但没有头数据：hlen 读出来是 0，必须拒绝。
+    #[tokio::test]
+    async fn rejects_zero_header_length() {
+        let (mut a, mut b) = duplex(64);
+        let mut bytes = 4u32.to_le_bytes().to_vec();
+        bytes.extend_from_slice(&0u32.to_le_bytes());
+        tokio::io::AsyncWriteExt::write_all(&mut a, &bytes)
+            .await
+            .unwrap();
+        let err = read_video_frame(&mut b).await.unwrap_err().to_string();
+        assert!(err.contains("header length invalid"), "实际错误: {err}");
+    }
+
+    /// hlen 声明超过 total-4：旧实现会切片越界 panic。
+    #[tokio::test]
+    async fn rejects_header_length_beyond_frame() {
+        let (mut a, mut b) = duplex(64);
+        // total = 8 → body 必须正好 8 字节（hlen 字段 4 + 4 字节填充）
+        let mut bytes = 8u32.to_le_bytes().to_vec();
+        bytes.extend_from_slice(&999u32.to_le_bytes()); // hlen = 999 > total-4 = 4
+        bytes.extend_from_slice(&[0u8; 4]);
+        tokio::io::AsyncWriteExt::write_all(&mut a, &bytes)
+            .await
+            .unwrap();
+        let err = read_video_frame(&mut b).await.unwrap_err().to_string();
+        assert!(err.contains("header length invalid"), "实际错误: {err}");
+    }
+
+    /// 超过 256 MiB 上限必须在**分配前**拒绝，不能先 vec! 再检查。
+    #[tokio::test]
+    async fn rejects_oversized_frame_without_allocating() {
+        let (mut a, mut b) = duplex(64);
+        let total = (MAX_VIDEO_FRAME as u32) + 1;
+        tokio::io::AsyncWriteExt::write_all(&mut a, &total.to_le_bytes())
+            .await
+            .unwrap();
+        let err = read_video_frame(&mut b).await.unwrap_err().to_string();
+        assert!(err.contains("out of range"), "实际错误: {err}");
+    }
+
+    /// 头部字节损坏（非合法 bincode）应返回 Err 而非 panic。
+    #[tokio::test]
+    async fn rejects_corrupt_header_bytes() {
+        let (mut a, mut b) = duplex(64);
+        let garbage = [0xFFu8; 8];
+        let total = (4 + garbage.len()) as u32;
+        let mut bytes = total.to_le_bytes().to_vec();
+        bytes.extend_from_slice(&(garbage.len() as u32).to_le_bytes());
+        bytes.extend_from_slice(&garbage);
+        tokio::io::AsyncWriteExt::write_all(&mut a, &bytes)
+            .await
+            .unwrap();
+        assert!(read_video_frame(&mut b).await.is_err());
+    }
+
+    // ---- IDR 识别（P2 的 keyframe 标志来源） ----
+
+    #[test]
+    fn detects_idr_in_annex_b() {
+        // SPS(7) + PPS(8) + IDR 片(5)，4 字节起始码
+        let idr = [
+            0, 0, 0, 1, 0x67, 0xAA, // SPS
+            0, 0, 0, 1, 0x68, 0xBB, // PPS
+            0, 0, 0, 1, 0x65, 0xCC, // IDR
+        ];
+        assert!(h264_contains_idr(&idr));
+
+        // 3 字节起始码也应识别
+        let idr3 = [0, 0, 1, 0x65, 0xCC];
+        assert!(h264_contains_idr(&idr3));
+    }
+
+    #[test]
+    fn rejects_non_idr_payloads() {
+        // 纯 P 片（NAL 类型 1）
+        let p_frame = [0, 0, 0, 1, 0x41, 0xDD];
+        assert!(!h264_contains_idr(&p_frame));
+
+        // 只有 SPS/PPS，没有片（关键帧边界可能落在下一个包，此时不应谎报 keyframe）
+        let params_only = [
+            0, 0, 0, 1, 0x67, 0xAA,
+            0, 0, 0, 1, 0x68, 0xBB,
+        ];
+        assert!(!h264_contains_idr(&params_only));
+
+        assert!(!h264_contains_idr(&[]));
+        assert!(!h264_contains_idr(&[0, 0, 1])); // 起始码后无 NAL 字节
+    }
+}

common/src/signaling.rs

@@ -0,0 +1,757 @@
+//! P2P 打洞信令协议（`common/` 契约，agent / viewer / 信令服务三端共享）。
+//!
+//! ## 职责边界（重要，改动前必读）
+//! - **信令服务器只做两件事**：① 把双方的外部视角（公网映射地址 + NAT 行为）拼起来回推给对端；
+//!   ② 下发同步打洞计划，让双方在同一绝对时刻开始发包。建连完成后信令与本次会话再无关系，
+//!   不承载任何媒体流量。
+//! - **本协议不含中继**（无 relay / TURN 消息）。打洞失败就是失败，因此必须把原因讲清楚
+//!   （见 [`PunchFailReason::user_hint`]），不允许让用户停在"连接中"。
+//! - 会话建立后走 QUIC：**不要**再用 viewer 现有的 `SkipVerify`，改用
+//!   [`EndpointInfo::cert_fingerprint`] 做公钥钉扎。
+//!
+//! ## 线格式
+//! 类型只依赖 `serde`，不绑定具体编码。建议信令走 WSS/443（最容易穿过企业防火墙），
+//! 编码用 JSON 便于抓包排查；本模块单元测试用 bincode 做往返校验，两者不冲突。
+//!
+//! ## 一次会话的时序
+//! ```text
+//!   agent                      信令服务器                      viewer
+//!     |-- Register(info) ------->|<------- Register(info) -----|
+//!     |<-- Registered(observed) -|------ Registered(observed) ->|
+//!     |<-- PeerReady(peer info) -|------ PeerReady(peer info) -->|
+//!     |<-- PunchPlan(start_in) --|------ PunchPlan(start_in) --->|
+//!     |      （双方同时向对端候选列表发包，多轮）                 |
+//!     |<========= 打通：UDP 直连 → QUIC 握手 + 证书钉扎 =========>|
+//!     |--- PunchReport(Connected) ->|<---- PunchReport ----------|
+//! ```
+
+use serde::{Deserialize, Serialize};
+use std::net::{IpAddr, SocketAddr};
+
+// ---------------------------------------------------------------------------
+// 常量
+// ---------------------------------------------------------------------------
+
+/// 信令协议版本。双方不一致时服务器应拒绝并提示升级，不要尝试兼容旧版。
+pub const SIGNALING_VERSION: u16 = 1;
+
+/// 打洞用的 UDP 端口，与 agent 当前监听端口一致。
+/// 固定端口对两件事有直接好处：NAT 端口预测、以及用户手动做端口转发。
+pub const PUNCH_UDP_PORT: u16 = 47800;
+
+/// 信令默认端口。走 WSS/443 是因为企业防火墙通常只放行 80/443。
+pub const SIGNALING_DEFAULT_PORT: u16 = 443;
+
+/// 单次打洞的默认轮数。
+pub const PUNCH_DEFAULT_ROUNDS: u8 = 3;
+
+/// 打洞轮间隔（毫秒）。太短来不及让 NAT 建立映射，太长用户等不及。
+pub const PUNCH_ROUND_INTERVAL_MS: u16 = 200;
+
+/// 候选地址数量上限（含预测端口）。超出即截断，防止滥用与报文膨胀。
+pub const MAX_CANDIDATES: usize = 32;
+
+/// NAT 绑定保活周期的下限/上限（秒）。
+pub const KEEPALIVE_MIN_S: u16 = 5;
+pub const KEEPALIVE_MAX_S: u16 = 60;
+
+/// 未测出 NAT 绑定超时时的保活默认值（秒）。家用 NAT 的 UDP 映射普遍 30s 左右超时。
+pub const KEEPALIVE_DEFAULT_S: u16 = 15;
+
+// ---------------------------------------------------------------------------
+// 基础类型
+// ---------------------------------------------------------------------------
+
+/// 端点角色。打洞成功后 agent 作为 QUIC server，viewer 主动 connect。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum Role {
+    /// 被控端
+    Agent,
+    /// 主控端
+    Viewer,
+}
+
+impl Role {
+    pub fn peer(self) -> Role {
+        match self {
+            Role::Agent => Role::Viewer,
+            Role::Viewer => Role::Agent,
+        }
+    }
+}
+
+/// 候选地址的来源，决定打洞优先级。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum CandidateKind {
+    /// 本机网卡地址（同局域网直连用，最省事）
+    Host,
+    /// 经 UPnP / NAT-PMP / PCP 主动申请的端口映射（把对称 NAT 变成可直连）
+    Upnp,
+    /// 信令服务器观察到的公网映射（等价于一次 STUN binding，server-reflexive）
+    Reflexive,
+    /// 按 NAT 端口分配规律预测出的端口
+    Predicted,
+}
+
+/// 一个候选地址。IPv6 有公网地址时基本等同直连，因此固定排在 IPv4 之前。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Candidate {
+    pub addr: SocketAddr,
+    pub kind: CandidateKind,
+}
+
+impl Candidate {
+    pub fn new(addr: SocketAddr, kind: CandidateKind) -> Self {
+        Self { addr, kind }
+    }
+
+    pub fn is_ipv6(&self) -> bool {
+        self.addr.is_ipv6()
+    }
+
+    /// 打分越高越先打。IPv6（+100）> UPnP 显式映射 > 本机地址 > 公网反射 > 端口预测。
+    pub fn score(&self) -> u16 {
+        let base = match self.kind {
+            CandidateKind::Upnp => 90,
+            CandidateKind::Host => 80,
+            CandidateKind::Reflexive => 60,
+            CandidateKind::Predicted => 40,
+        };
+        if self.is_ipv6() {
+            base + 100
+        } else {
+            base
+        }
+    }
+}
+
+/// 按优先级从高到低排序（`sort_by` 是稳定排序，同分保持调用方给出的顺序）。
+pub fn sort_candidates(v: &mut [Candidate]) {
+    v.sort_by(|a, b| b.score().cmp(&a.score()));
+}
+
+/// 清洗对端送来的候选列表：丢弃端口 0、按地址去重、截断到 [`MAX_CANDIDATES`]。
+///
+/// 对端数据一律视为不可信输入；打洞阶段每个候选都会产生实际发包，必须设上限。
+pub fn sanitize_candidates(v: Vec<Candidate>) -> Vec<Candidate> {
+    let mut out: Vec<Candidate> = Vec::with_capacity(v.len().min(MAX_CANDIDATES));
+    for c in v {
+        if c.addr.port() == 0 {
+            continue;
+        }
+        if out.iter().any(|e| e.addr == c.addr) {
+            continue;
+        }
+        if out.len() == MAX_CANDIDATES {
+            break;
+        }
+        out.push(c);
+    }
+    out
+}
+
+// ---------------------------------------------------------------------------
+// NAT 画像与诊断
+// ---------------------------------------------------------------------------
+
+/// RFC 4787 §4.1 映射行为：同一个内网 socket 的公网端口是否随目标变化。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum MappingBehavior {
+    /// 端点无关（full cone / restricted cone）：打洞最理想
+    EndpointIndependent,
+    /// 地址相关
+    AddressDependent,
+    /// 地址+端口相关（即"对称 NAT"）
+    AddressAndPortDependent,
+    Unknown,
+}
+
+/// RFC 4787 §5.1 过滤行为：外部包能否进得来。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum FilteringBehavior {
+    EndpointIndependent,
+    AddressDependent,
+    AddressAndPortDependent,
+    Unknown,
+}
+
+/// 公网端口分配规律，决定端口预测是否可用。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum PortAllocation {
+    /// 保持内网端口
+    Preserved,
+    /// 递增分配（可预测，端口预测值得一试）
+    Sequential,
+    /// 随机（端口预测无效）
+    Random,
+    Unknown,
+}
+
+/// NAT 行为画像。信令握手阶段顺带测出，用于：① 决定打洞策略；② 失败时给用户解释。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub struct NatProfile {
+    pub mapping: MappingBehavior,
+    pub filtering: FilteringBehavior,
+    pub allocation: PortAllocation,
+    /// NAT 绑定超时（秒）。未测出为 `None`，此时用 [`KEEPALIVE_DEFAULT_S`]。
+    pub binding_timeout_s: Option<u16>,
+    /// 是否支持 hairpinning（同一 NAT 内的两端可互连）
+    pub hairpinning: bool,
+}
+
+impl Default for NatProfile {
+    fn default() -> Self {
+        Self {
+            mapping: MappingBehavior::Unknown,
+            filtering: FilteringBehavior::Unknown,
+            allocation: PortAllocation::Unknown,
+            binding_timeout_s: None,
+            hairpinning: false,
+        }
+    }
+}
+
+/// 打洞前景评估，直接用于 UI 提示与"是否值得继续重试"的决策。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum PunchOutlook {
+    /// 锥形 NAT 或公网 IPv6，基本必成
+    Likely,
+    /// 需要多轮重试 / 端口预测，可能成
+    Possible,
+    /// 对称 NAT 且端口不可预测，通常打不通
+    Unlikely,
+    /// 运营商级 NAT（CGNAT），无中继方案下无解 —— 不必浪费多轮打洞
+    Hopeless,
+}
+
+/// 运营商级 NAT 判定：RFC 6598 共享地址空间 `100.64.0.0/10`。
+///
+/// 命中即无中继不可达，应立刻给出"换网络"提示，而不是让用户等完所有打洞轮次。
+pub fn is_cgnat(observed: IpAddr) -> bool {
+    match observed {
+        IpAddr::V4(v4) => {
+            let o = v4.octets();
+            o[0] == 100 && (64..=127).contains(&o[1])
+        }
+        IpAddr::V6(_) => false,
+    }
+}
+
+/// 综合 NAT 画像与观察到的公网地址，评估打洞前景。
+///
+/// `observed_public` 是信令服务器看到的本端公网映射（IPv6 时即本机全局地址）。
+pub fn punch_outlook(nat: &NatProfile, observed_public: IpAddr) -> PunchOutlook {
+    // IPv6 没有 NAT 可言，只要双方都有公网 v6 就是真直连。
+    if observed_public.is_ipv6() {
+        return PunchOutlook::Likely;
+    }
+    if is_cgnat(observed_public) {
+        return PunchOutlook::Hopeless;
+    }
+    match nat.mapping {
+        MappingBehavior::EndpointIndependent => PunchOutlook::Likely,
+        MappingBehavior::AddressDependent => PunchOutlook::Possible,
+        MappingBehavior::AddressAndPortDependent => match nat.allocation {
+            // 对称 NAT 但端口可预测 → 端口预测 + 多轮重试仍有机会
+            PortAllocation::Sequential | PortAllocation::Preserved => PunchOutlook::Possible,
+            PortAllocation::Random | PortAllocation::Unknown => PunchOutlook::Unlikely,
+        },
+        // 测不出来就按"可能"处理，先试再说
+        MappingBehavior::Unknown => PunchOutlook::Possible,
+    }
+}
+
+/// 双方协商保活周期（秒）：取双方绑定超时的较小值再折半，并夹在
+/// [`KEEPALIVE_MIN_S`]..=[`KEEPALIVE_MAX_S`] 之间。
+///
+/// 洞是靠出站包维持的，超时后会静默关闭 —— 表现为"连上了一会儿就断"。
+pub fn keepalive_secs(mine: &NatProfile, theirs: &NatProfile) -> u16 {
+    let t = match (mine.binding_timeout_s, theirs.binding_timeout_s) {
+        (Some(a), Some(b)) => a.min(b),
+        (Some(a), None) => a,
+        (None, Some(b)) => b,
+        (None, None) => KEEPALIVE_DEFAULT_S,
+    };
+    (t / 2).clamp(KEEPALIVE_MIN_S, KEEPALIVE_MAX_S)
+}
+
+/// 服务器侧计算某个客户端的打洞启动延迟（相对 PunchPlan 送达时刻）。
+///
+/// 两侧 RTT 不同：若下发同一个延迟，RTT 大的一方会晚发包，洞就打不上。
+/// 以双方最大 RTT 为基准、减去自身 RTT 的一半，即可在**不做时钟同步**的前提下
+/// 让两侧的绝对开打时刻对齐（误差约等于单程抖动）。
+///
+/// ```text
+/// start_in_ms = max_rtt_ms / 2 + margin_ms - own_rtt_ms / 2
+/// ```
+pub fn punch_start_delay_ms(own_rtt_ms: u16, max_rtt_ms: u16, margin_ms: u16) -> u16 {
+    let base = max_rtt_ms as u32 / 2 + margin_ms as u32;
+    let own_half = own_rtt_ms as u32 / 2;
+    base.saturating_sub(own_half).min(u16::MAX as u32) as u16
+}
+
+// ---------------------------------------------------------------------------
+// 证书指纹（替代 viewer 现有的 SkipVerify）
+// ---------------------------------------------------------------------------
+
+/// 自签证书公钥指纹（SHA-256 的 32 字节裸值）。
+///
+/// agent 生成自签证书后把指纹经信令发布，viewer 用它对 QUIC 连接做**公钥钉扎**，
+/// 从而去掉 `viewer/src/main.rs` 里的 `SkipVerify`（公网环境不可接受）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub struct CertFingerprint(pub [u8; 32]);
+
+impl CertFingerprint {
+    /// 小写十六进制（64 字符）
+    pub fn to_hex(&self) -> String {
+        self.0.iter().map(|b| format!("{b:02x}")).collect()
+    }
+
+    /// 解析 64 字符十六进制；长度不符或含非十六进制字符返回 `None`。
+    pub fn from_hex(s: &str) -> Option<Self> {
+        let s = s.trim();
+        if s.len() != 64 {
+            return None;
+        }
+        let mut out = [0u8; 32];
+        for (i, chunk) in s.as_bytes().chunks(2).enumerate() {
+            let hi = (chunk[0] as char).to_digit(16)?;
+            let lo = (chunk[1] as char).to_digit(16)?;
+            out[i] = (hi * 16 + lo) as u8;
+        }
+        Some(Self(out))
+    }
+}
+
+impl std::fmt::Display for CertFingerprint {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.to_hex())
+    }
+}
+
+// ---------------------------------------------------------------------------
+// 端点信息与消息
+// ---------------------------------------------------------------------------
+
+/// 连通性相关的能力标志。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+pub struct Capabilities {
+    /// 已成功获得 UPnP / NAT-PMP / PCP 端口映射
+    pub upnp_mapped: bool,
+    /// 本机具备可用 IPv6 出口
+    pub ipv6_available: bool,
+}
+
+/// 一个端点的完整连通性描述，随 Register / PeerReady 交换。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct EndpointInfo {
+    pub role: Role,
+    /// 本端打洞用的 UDP 监听端口（通常等于 [`PUNCH_UDP_PORT`]）
+    pub port: u16,
+    /// 候选地址，发送前请用 [`sort_candidates`] 排好序
+    pub candidates: Vec<Candidate>,
+    pub nat: NatProfile,
+    /// QUIC 证书公钥指纹，供对端钉扎
+    pub cert_fingerprint: CertFingerprint,
+    pub caps: Capabilities,
+}
+
+/// 打洞失败原因。**无中继方案的用户体验下限就在这里** —— 每种原因都要能翻译成
+/// 用户能照做的一句话，见 [`PunchFailReason::user_hint`]。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum PunchFailReason {
+    /// 所有候选都无回包（最常见：双方都是地址+端口相关型 NAT）
+    NoCandidateReachable,
+    /// 双方均为对称 NAT 且端口不可预测
+    SymmetricNat,
+    /// 运营商级 NAT（100.64/10）
+    Cgnat,
+    /// 本机 UDP 出站被策略封锁（企业防火墙常见）
+    UdpBlocked,
+    /// 对端提前退出
+    PeerAborted,
+    /// 超时未收到任何回包
+    Timeout,
+}
+
+impl PunchFailReason {
+    /// 面向用户的中文处置建议。不要吞掉这个信息 —— 用户看不到原因就只会认为"这软件连不上"。
+    pub fn user_hint(self) -> &'static str {
+        match self {
+            PunchFailReason::NoCandidateReachable => {
+                "双方网络都无法直接互通。请在被控端路由器开启 UPnP 后重试，或双方改用 IPv6 网络。"
+            }
+            PunchFailReason::SymmetricNat => {
+                "当前网络是对称型 NAT，无法直连。请在被控端路由器开启 UPnP，或更换网络后重试。"
+            }
+            PunchFailReason::Cgnat => {
+                "当前处于运营商级 NAT（大内网），无法直连。请改用 IPv6 网络，或换一条能拿到公网地址的线路。"
+            }
+            PunchFailReason::UdpBlocked => {
+                "当前网络的防火墙拦截了 UDP 出站。请更换网络（如切换手机热点）后重试。"
+            }
+            PunchFailReason::PeerAborted => "对端已取消本次连接。",
+            PunchFailReason::Timeout => "连接超时，可能是网络波动。请重试一次。",
+        }
+    }
+}
+
+/// 打洞结果。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum PunchOutcome {
+    /// 打通：`peer` 为真正生效的对端地址，`rtt_ms` 为实测往返
+    Connected { peer: SocketAddr, rtt_ms: u16 },
+    Failed { reason: PunchFailReason },
+}
+
+impl PunchOutcome {
+    pub fn is_connected(&self) -> bool {
+        matches!(self, PunchOutcome::Connected { .. })
+    }
+
+    /// 已连通返回 `None`，失败返回给用户看的建议。
+    pub fn user_hint(&self) -> Option<&'static str> {
+        match self {
+            PunchOutcome::Connected { .. } => None,
+            PunchOutcome::Failed { reason } => Some(reason.user_hint()),
+        }
+    }
+}
+
+/// 信令层错误码。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum SignalError {
+    /// [`SIGNALING_VERSION`] 不匹配（客户端需升级）
+    VersionMismatch,
+    /// 验证码错误或已过期
+    BadAuth,
+    SessionNotFound,
+    PeerOffline,
+    /// 候选地址数量超限
+    TooManyCandidates,
+    RateLimited,
+    Internal,
+}
+
+/// 客户端 → 信令服务器。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ClientMsg {
+    /// 注册并等待对端。`auth` 必须是一次性验证码（不是 MVP 里的固定 123456）。
+    Register {
+        version: u16,
+        /// 会话/设备标识；服务器据此配对两端
+        session: String,
+        auth: String,
+        info: EndpointInfo,
+    },
+    /// 候选变化补报：UPnP 映射稍后才成功、或网卡地址变化时用。
+    UpdateCandidates {
+        session: String,
+        candidates: Vec<Candidate>,
+        nat: NatProfile,
+    },
+    /// 打洞结果回报。服务器可据此记录有效路径、统计成功率。
+    PunchReport {
+        session: String,
+        plan_id: u32,
+        outcome: PunchOutcome,
+    },
+    /// 保活：维持信令长连接，同时刷新本端 NAT 绑定。
+    Keepalive { session: String },
+    Bye {
+        session: String,
+        reason: String,
+    },
+}
+
+/// 信令服务器 → 客户端。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ServerMsg {
+    /// 注册成功。`observed` 是服务器看到的本端公网映射，等价于一次 STUN binding；
+    /// `rtt_ms` 供打洞计划做时间对齐（见 [`punch_start_delay_ms`]）。
+    Registered {
+        session: String,
+        observed: SocketAddr,
+        /// 对端是否已在场。`false` 时应等待 [`ServerMsg::PeerReady`]。
+        peer_present: bool,
+        rtt_ms: u16,
+    },
+    /// 对端已就绪，附带其候选地址、NAT 画像与证书指纹。
+    PeerReady {
+        peer: EndpointInfo,
+        peer_observed: SocketAddr,
+        /// 打洞前景，可直接显示给用户（"很可能直连成功" / "当前网络可能无法直连"）
+        outlook: PunchOutlook,
+    },
+    /// 同步打洞计划。
+    ///
+    /// `start_in_ms` 是**相对本消息**的延迟，服务器对两侧下发不同的值以使双方在同一
+    /// 绝对时刻开打 —— 因此本协议不要求两端时钟同步。
+    PunchPlan {
+        plan_id: u32,
+        start_in_ms: u16,
+        rounds: u8,
+        round_interval_ms: u16,
+        /// 对端候选（已排序、已清洗）；本端需对其中每个地址发包
+        peer_candidates: Vec<Candidate>,
+    },
+    /// 打洞结果确认（用于 UI 显示"直连成功，RTT xx ms"）。
+    PunchAck { plan_id: u32, outcome: PunchOutcome },
+    Error { code: SignalError, message: String },
+}
+
+// ---------------------------------------------------------------------------
+// 测试
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn fp(byte: u8) -> CertFingerprint {
+        CertFingerprint([byte; 32])
+    }
+
+    fn info(role: Role) -> EndpointInfo {
+        let mut candidates = vec![
+            Candidate::new("1.2.3.4:47800".parse().unwrap(), CandidateKind::Reflexive),
+            Candidate::new("[2001:db8::1]:47800".parse().unwrap(), CandidateKind::Host),
+            Candidate::new("192.168.1.5:47800".parse().unwrap(), CandidateKind::Upnp),
+        ];
+        sort_candidates(&mut candidates);
+        EndpointInfo {
+            role,
+            port: PUNCH_UDP_PORT,
+            candidates,
+            nat: NatProfile {
+                mapping: MappingBehavior::AddressDependent,
+                filtering: FilteringBehavior::AddressAndPortDependent,
+                allocation: PortAllocation::Sequential,
+                binding_timeout_s: Some(30),
+                hairpinning: false,
+            },
+            cert_fingerprint: fp(0xab),
+            caps: Capabilities {
+                upnp_mapped: true,
+                ipv6_available: true,
+            },
+        }
+    }
+
+    fn client_msgs() -> Vec<ClientMsg> {
+        vec![
+            ClientMsg::Register {
+                version: SIGNALING_VERSION,
+                session: "dev-1".into(),
+                auth: "0f3a91".into(),
+                info: info(Role::Agent),
+            },
+            ClientMsg::UpdateCandidates {
+                session: "dev-1".into(),
+                candidates: vec![Candidate::new(
+                    "5.6.7.8:47800".parse().unwrap(),
+                    CandidateKind::Predicted,
+                )],
+                nat: NatProfile::default(),
+            },
+            ClientMsg::PunchReport {
+                session: "dev-1".into(),
+                plan_id: 7,
+                outcome: PunchOutcome::Connected {
+                    peer: "9.9.9.9:47800".parse().unwrap(),
+                    rtt_ms: 42,
+                },
+            },
+            ClientMsg::PunchReport {
+                session: "dev-1".into(),
+                plan_id: 8,
+                outcome: PunchOutcome::Failed {
+                    reason: PunchFailReason::Cgnat,
+                },
+            },
+            ClientMsg::Keepalive {
+                session: "dev-1".into(),
+            },
+            ClientMsg::Bye {
+                session: "dev-1".into(),
+                reason: "user quit".into(),
+            },
+        ]
+    }
+
+    fn server_msgs() -> Vec<ServerMsg> {
+        vec![
+            ServerMsg::Registered {
+                session: "dev-1".into(),
+                observed: "203.0.113.9:51234".parse().unwrap(),
+                peer_present: true,
+                rtt_ms: 38,
+            },
+            ServerMsg::PeerReady {
+                peer: info(Role::Viewer),
+                peer_observed: "203.0.113.10:51235".parse().unwrap(),
+                outlook: PunchOutlook::Likely,
+            },
+            ServerMsg::PunchPlan {
+                plan_id: 9,
+                start_in_ms: 130,
+                rounds: PUNCH_DEFAULT_ROUNDS,
+                round_interval_ms: PUNCH_ROUND_INTERVAL_MS,
+                peer_candidates: info(Role::Viewer).candidates,
+            },
+            ServerMsg::PunchAck {
+                plan_id: 9,
+                outcome: PunchOutcome::Failed {
+                    reason: PunchFailReason::SymmetricNat,
+                },
+            },
+            ServerMsg::Error {
+                code: SignalError::VersionMismatch,
+                message: "server expects v1".into(),
+            },
+        ]
+    }
+
+    #[test]
+    fn bincode_roundtrip_client_msgs() {
+        for m in client_msgs() {
+            let bytes = bincode::serialize(&m).expect("serialize");
+            let back: ClientMsg = bincode::deserialize(&bytes).expect("deserialize");
+            assert_eq!(m, back);
+        }
+    }
+
+    #[test]
+    fn bincode_roundtrip_server_msgs() {
+        for m in server_msgs() {
+            let bytes = bincode::serialize(&m).expect("serialize");
+            let back: ServerMsg = bincode::deserialize(&bytes).expect("deserialize");
+            assert_eq!(m, back);
+        }
+    }
+
+    #[test]
+    fn candidates_sorted_ipv6_first_then_upnp() {
+        let mut v = vec![
+            Candidate::new("1.2.3.4:47800".parse().unwrap(), CandidateKind::Reflexive),
+            Candidate::new("[2001:db8::1]:47800".parse().unwrap(), CandidateKind::Host),
+            Candidate::new("192.168.1.5:47800".parse().unwrap(), CandidateKind::Upnp),
+        ];
+        sort_candidates(&mut v);
+        assert!(v[0].is_ipv6(), "IPv6 候选必须排第一");
+        assert_eq!(v[1].kind, CandidateKind::Upnp);
+        assert_eq!(v[2].kind, CandidateKind::Reflexive);
+    }
+
+    #[test]
+    fn sanitize_dedups_and_bounds() {
+        let dup = Candidate::new("1.2.3.4:47800".parse().unwrap(), CandidateKind::Host);
+        let zero_port = Candidate::new("1.2.3.4:0".parse().unwrap(), CandidateKind::Host);
+        let mut v = vec![dup, dup, zero_port];
+        v.extend((0..MAX_CANDIDATES + 5).map(|i| {
+            Candidate::new(
+                format!("10.0.{}.{}:47800", i / 250, i % 250).parse().unwrap(),
+                CandidateKind::Predicted,
+            )
+        }));
+        let out = sanitize_candidates(v);
+        assert_eq!(out.len(), MAX_CANDIDATES);
+        assert!(out.iter().all(|c| c.addr.port() != 0));
+        let mut addrs: Vec<_> = out.iter().map(|c| c.addr).collect();
+        addrs.sort();
+        addrs.dedup();
+        assert_eq!(addrs.len(), out.len());
+    }
+
+    #[test]
+    fn outlook_covers_ipv6_cgnat_and_symmetric() {
+        let v6: IpAddr = "2001:db8::1".parse().unwrap();
+        let public: IpAddr = "203.0.113.9".parse().unwrap();
+        let cgnat: IpAddr = "100.64.1.1".parse().unwrap();
+
+        let mut nat = NatProfile::default();
+        assert_eq!(punch_outlook(&nat, v6), PunchOutlook::Likely);
+        assert_eq!(punch_outlook(&nat, cgnat), PunchOutlook::Hopeless);
+        assert!(is_cgnat("100.127.255.254".parse().unwrap()));
+        assert!(!is_cgnat("100.128.0.1".parse().unwrap()));
+
+        nat.mapping = MappingBehavior::EndpointIndependent;
+        assert_eq!(punch_outlook(&nat, public), PunchOutlook::Likely);
+
+        nat.mapping = MappingBehavior::AddressAndPortDependent;
+        nat.allocation = PortAllocation::Sequential;
+        assert_eq!(punch_outlook(&nat, public), PunchOutlook::Possible);
+
+        nat.allocation = PortAllocation::Random;
+        assert_eq!(punch_outlook(&nat, public), PunchOutlook::Unlikely);
+    }
+
+    #[test]
+    fn keepalive_halves_binding_timeout_and_clamps() {
+        let a = NatProfile {
+            binding_timeout_s: Some(30),
+            ..Default::default()
+        };
+        let b = NatProfile {
+            binding_timeout_s: Some(20),
+            ..Default::default()
+        };
+        assert_eq!(keepalive_secs(&a, &b), 10);
+        assert_eq!(keepalive_secs(&NatProfile::default(), &NatProfile::default()), 7);
+        let short = NatProfile {
+            binding_timeout_s: Some(4),
+            ..Default::default()
+        };
+        assert_eq!(keepalive_secs(&short, &short), KEEPALIVE_MIN_S);
+        let long = NatProfile {
+            binding_timeout_s: Some(600),
+            ..Default::default()
+        };
+        assert_eq!(keepalive_secs(&long, &long), KEEPALIVE_MAX_S);
+    }
+
+    #[test]
+    fn punch_start_delay_aligns_absolute_time() {
+        // RTT 大的一方应该更早出发，使两侧绝对开打时刻一致。
+        let slow = punch_start_delay_ms(200, 200, 100);
+        let fast = punch_start_delay_ms(20, 200, 100);
+        assert_eq!(slow, 100);
+        assert_eq!(fast, 190);
+        assert!(fast > slow);
+    }
+
+    #[test]
+    fn cert_fingerprint_hex_roundtrip() {
+        let f = fp(0x0f);
+        let hex = f.to_hex();
+        assert_eq!(hex.len(), 64);
+        assert_eq!(CertFingerprint::from_hex(&hex), Some(f));
+        assert_eq!(CertFingerprint::from_hex(&hex.to_uppercase()), Some(f));
+        assert_eq!(CertFingerprint::from_hex("00"), None);
+        assert_eq!(CertFingerprint::from_hex(&"z".repeat(64)), None);
+    }
+
+    #[test]
+    fn fail_reasons_all_have_user_hints() {
+        let all = [
+            PunchFailReason::NoCandidateReachable,
+            PunchFailReason::SymmetricNat,
+            PunchFailReason::Cgnat,
+            PunchFailReason::UdpBlocked,
+            PunchFailReason::PeerAborted,
+            PunchFailReason::Timeout,
+        ];
+        for r in all {
+            assert!(!r.user_hint().is_empty());
+            let o = PunchOutcome::Failed { reason: r };
+            assert!(!o.is_connected());
+            assert!(o.user_hint().is_some());
+        }
+        let ok = PunchOutcome::Connected {
+            peer: "1.2.3.4:47800".parse().unwrap(),
+            rtt_ms: 30,
+        };
+        assert!(ok.is_connected());
+        assert!(ok.user_hint().is_none());
+    }
+}

linux-agent/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "linux-agent"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+agent-core = { path = "../agent-core" }
+common = { path = "../common" }
+anyhow.workspace = true
+tokio.workspace = true
+x11rb = { version = "0.13", features = ["xtest"] }
+
+[dev-dependencies]
+# 冒烟测试里要扮演主控端，自己发起 QUIC/TLS 连接
+quinn.workspace = true
+rustls.workspace = true

linux-agent/src/capture.rs

@@ -0,0 +1,147 @@
+//! X11 屏幕采集。
+//!
+//! MVP 走核心协议 `GetImage`：零扩展依赖、零 unsafe，先把「采集 → 编码 → QUIC」整条链路打通。
+//! 变更检测用整帧字节比较，桌面静止时不上行视频（省掉编码开销）。
+//!
+//! 二期优化锚点（已在 `ScreenCapturer` 语义内预留，无需改 agent-core）：
+//! 1. **MIT-SHM**：共享内存替代 `GetImage` 的 socket 传输，省掉 X server 一次全画布拷贝；
+//! 2. **XDamage**：只取变化矩形 + 只编码脏区，静止时零拷贝。
+
+use agent_core::ScreenCapturer;
+use anyhow::{anyhow, Result};
+use std::time::{Duration, Instant};
+use x11rb::connection::Connection;
+use x11rb::protocol::xproto::{ConnectionExt as _, ImageFormat, VisualClass, Window};
+use x11rb::rust_connection::RustConnection;
+
+/// 帧节流上限，与 agent-core 默认编码档位（30fps）对齐
+const FRAME_INTERVAL: Duration = Duration::from_millis(33);
+
+pub struct X11Capturer {
+    conn: RustConnection,
+    root: Window,
+    width: u16,
+    height: u16,
+    /// 最近一帧 BGRA（既是变更检测基线，也是 copy_frame 的数据源）
+    last: Vec<u8>,
+    last_capture: Option<Instant>,
+}
+
+impl X11Capturer {
+    pub fn new() -> Result<Self> {
+        let (conn, screen_num) = x11rb::connect(None).map_err(|e| {
+            anyhow!(
+                "连接 X11 失败（DISPLAY={:?}）: {e}",
+                std::env::var("DISPLAY").ok()
+            )
+        })?;
+
+        // 先把需要的屏幕参数拷出来：随后 conn 要被移进结构体，不能再持有对它的借用
+        let (root, width, height, depth, visual_class, bpp) = {
+            let setup = conn.setup();
+            let screen = &setup.roots[screen_num];
+
+            // bits_per_pixel 不在 visual 上，而在 Setup 的 pixmap_formats 里（按 depth 索引）
+            let fmt = setup
+                .pixmap_formats
+                .iter()
+                .find(|f| f.depth == screen.root_depth)
+                .ok_or_else(|| anyhow!("找不到 depth={} 对应的像素格式", screen.root_depth))?;
+
+            let visual_class = screen
+                .allowed_depths
+                .iter()
+                .flat_map(|d| d.visuals.iter())
+                .find(|v| v.visual_id == screen.root_visual)
+                .map(|v| v.class)
+                .ok_or_else(|| anyhow!("找不到 root visual"))?;
+
+            (
+                screen.root,
+                screen.width_in_pixels,
+                screen.height_in_pixels,
+                screen.root_depth,
+                visual_class,
+                fmt.bits_per_pixel,
+            )
+        };
+
+        anyhow::ensure!(width > 0 && height > 0, "屏幕尺寸异常 {width}x{height}");
+        anyhow::ensure!(
+            bpp == 32,
+            "当前仅支持 32bpp 真彩采集（depth={depth}，实际 {bpp}bpp）"
+        );
+        // BGRA 字节序假设只在 TrueColor 下成立
+        anyhow::ensure!(
+            visual_class == VisualClass::TRUE_COLOR,
+            "当前仅支持 TrueColor 视觉（实际 {visual_class:?}）"
+        );
+
+        println!("[capture] X11 screen {width}x{height}, depth={depth}, {bpp}bpp");
+
+        Ok(Self {
+            conn,
+            root,
+            width,
+            height,
+            last: Vec::new(),
+            last_capture: None,
+        })
+    }
+
+    /// 抓一帧整屏到 `last`，返回画面是否发生变化
+    fn grab(&mut self) -> Result<bool> {
+        let reply = self
+            .conn
+            .get_image(
+                ImageFormat::Z_PIXMAP,
+                self.root,
+                0,
+                0,
+                self.width,
+                self.height,
+                !0,
+            )
+            .map_err(|e| anyhow!("get_image 请求失败: {e}"))?
+            .reply()
+            .map_err(|e| anyhow!("get_image 应答失败: {e}"))?;
+
+        let expect = self.width as usize * self.height as usize * 4;
+        anyhow::ensure!(
+            reply.data.len() == expect,
+            "帧数据长度异常：期望 {expect} 字节，实际 {}",
+            reply.data.len()
+        );
+
+        let changed = reply.data != self.last;
+        if changed {
+            self.last = reply.data;
+        }
+        Ok(changed)
+    }
+}
+
+impl ScreenCapturer for X11Capturer {
+    fn size(&self) -> (u32, u32) {
+        (self.width as u32, self.height as u32)
+    }
+
+    /// X11 核心协议没有「阻塞至新帧」语义，故这里按帧槽节流后主动抓帧：
+    /// 睡到下一个 1/30s 槽位 → 抓帧 → 与上一帧逐字节比较。
+    /// 因此 `timeout_ms` 在 Linux 实现中被忽略（agent-core 的 min_frame 节流也随之自然满足）。
+    fn acquire(&mut self, _timeout_ms: u32) -> Result<bool> {
+        if let Some(t) = self.last_capture {
+            let elapsed = t.elapsed();
+            if elapsed < FRAME_INTERVAL {
+                std::thread::sleep(FRAME_INTERVAL - elapsed);
+            }
+        }
+        self.last_capture = Some(Instant::now());
+        self.grab()
+    }
+
+    fn copy_frame(&mut self) -> Result<Vec<u8>> {
+        anyhow::ensure!(!self.last.is_empty(), "尚无帧数据可拷贝");
+        Ok(self.last.clone())
+    }
+}

linux-agent/src/input.rs

@@ -0,0 +1,251 @@
+//! X11 输入注入：XTest 扩展（Xorg / XWayland / Xvfb 均支持）。
+//!
+//! **键码映射是本模块的关键**：协议里键盘沿用 Windows 口味的 PS/2 Set-1 扫描码，
+//! 而 X11 要的是 keycode，两套编号并非处处等价：
+//! - 主键区：`keycode = scancode + 8`（evdev 偏移），已逐键核对；
+//! - E0 扩展键：两条链路编号**完全不同**（如方向键 Set-1 是 0x48，evdev 侧 X11 keycode 是 111），必须查表。
+//!
+//! 鼠标沿用虚拟桌面归一化坐标 0..=65535：X11 根窗口天然横跨全部显示器，
+//! 与 Windows 的 `MOUSEEVENTF_VIRTUALDESK` 语义一致，故映射到根窗口像素即可。
+
+use agent_core::InputInjector;
+use anyhow::{anyhow, Result};
+use common::MouseButton;
+use std::sync::Mutex;
+use x11rb::connection::Connection;
+use x11rb::protocol::xproto::{ConnectionExt as _, Window};
+use x11rb::protocol::xtest::ConnectionExt as _;
+use x11rb::rust_connection::RustConnection;
+
+// X11 核心事件码（协议固定值）
+const KEY_PRESS: u8 = 2;
+const KEY_RELEASE: u8 = 3;
+const BUTTON_PRESS: u8 = 4;
+const BUTTON_RELEASE: u8 = 5;
+const MOTION_NOTIFY: u8 = 6;
+
+// X11 按钮编号：1=左 2=中 3=右 4=滚轮上 5=滚轮下
+const BTN_LEFT: u8 = 1;
+const BTN_MIDDLE: u8 = 2;
+const BTN_RIGHT: u8 = 3;
+const BTN_WHEEL_UP: u8 = 4;
+const BTN_WHEEL_DOWN: u8 = 5;
+
+/// Windows 滚轮一格 = 120（协议沿用该语义）
+const WHEEL_DELTA: i32 = 120;
+
+/// 单次滚轮最多合成的格数，防止异常值刷爆事件队列
+const WHEEL_MAX_CLICKS: i32 = 20;
+
+pub struct X11Injector {
+    /// `Mutex` 只为满足 `InputInjector: Sync`（X11 连接本身非 Sync），无竞争
+    conn: Mutex<RustConnection>,
+    root: Window,
+    width: i32,
+    height: i32,
+}
+
+impl X11Injector {
+    pub fn new() -> Result<Self> {
+        let (conn, screen_num) = x11rb::connect(None).map_err(|e| {
+            anyhow!(
+                "连接 X11 失败（DISPLAY={:?}）: {e}",
+                std::env::var("DISPLAY").ok()
+            )
+        })?;
+
+        // XTest 缺失就没有注入能力，启动即失败好过连上后才报错
+        let ext = conn
+            .query_extension(b"XTEST")
+            .map_err(|e| anyhow!("查询 XTEST 扩展失败: {e}"))?
+            .reply()
+            .map_err(|e| anyhow!("查询 XTEST 扩展应答失败: {e}"))?;
+        anyhow::ensure!(ext.present, "X server 未提供 XTEST 扩展，无法注入输入");
+
+        // 先拷出参数，避免借用 conn 的同时又把它移进结构体
+        let (root, width, height) = {
+            let screen = &conn.setup().roots[screen_num];
+            (
+                screen.root,
+                screen.width_in_pixels as i32,
+                screen.height_in_pixels as i32,
+            )
+        };
+        println!("[input] XTEST ready, root {width}x{height}");
+
+        Ok(Self {
+            conn: Mutex::new(conn),
+            root,
+            width,
+            height,
+        })
+    }
+
+    fn fake(&self, type_: u8, detail: u8, x: i32, y: i32) {
+        let conn = match self.conn.lock() {
+            Ok(c) => c,
+            Err(poisoned) => poisoned.into_inner(),
+        };
+        if let Err(e) = conn.xtest_fake_input(
+            type_,
+            detail,
+            0,
+            self.root,
+            x as i16,
+            y as i16,
+            0, // deviceid：0 = 核心设备
+        ) {
+            eprintln!("[input] xtest_fake_input 失败: {e}");
+            return;
+        }
+        let _ = conn.flush();
+    }
+
+    fn click(&self, button: u8) {
+        self.fake(BUTTON_PRESS, button, 0, 0);
+        self.fake(BUTTON_RELEASE, button, 0, 0);
+    }
+}
+
+impl InputInjector for X11Injector {
+    fn mouse_move(&self, x: u16, y: u16) {
+        // detail=0 → 绝对坐标
+        let px = scale(x, self.width);
+        let py = scale(y, self.height);
+        self.fake(MOTION_NOTIFY, 0, px, py);
+    }
+
+    fn mouse_button(&self, b: MouseButton, down: bool) {
+        let button = match b {
+            MouseButton::Left => BTN_LEFT,
+            MouseButton::Middle => BTN_MIDDLE,
+            MouseButton::Right => BTN_RIGHT,
+        };
+        self.fake(
+            if down { BUTTON_PRESS } else { BUTTON_RELEASE },
+            button,
+            0,
+            0,
+        );
+    }
+
+    fn wheel(&self, dy: i32) {
+        // 协议沿用 Windows 语义：dy > 0 向上滚，一格 = 120
+        if dy == 0 {
+            return;
+        }
+        let clicks = (dy.abs() / WHEEL_DELTA).clamp(1, WHEEL_MAX_CLICKS);
+        let button = if dy > 0 { BTN_WHEEL_UP } else { BTN_WHEEL_DOWN };
+        for _ in 0..clicks {
+            self.click(button);
+        }
+    }
+
+    fn key(&self, scancode: u16, extended: bool, down: bool) {
+        let Some(keycode) = keycode_of(scancode, extended) else {
+            eprintln!("[input] 未映射的扫描码 scancode=0x{scancode:02X} extended={extended}");
+            return;
+        };
+        self.fake(
+            if down { KEY_PRESS } else { KEY_RELEASE },
+            keycode,
+            0,
+            0,
+        );
+    }
+}
+
+/// 虚拟桌面归一化坐标（0..=65535）→ 根窗口像素坐标
+fn scale(v: u16, extent: i32) -> i32 {
+    if extent <= 1 {
+        return 0;
+    }
+    ((v as i64 * (extent as i64 - 1)) / 65535) as i32
+}
+
+/// PS/2 Set-1 扫描码 → X11 keycode。
+///
+/// 非扩展键恒为 `scancode + 8`（当前 viewer 的 keymap 只发该区间内的键）；
+/// E0 扩展键查表，编号与主键区规则无关。
+fn keycode_of(scancode: u16, extended: bool) -> Option<u8> {
+    if extended {
+        // 已按 Xorg evdev 标准 keycode 分配核对
+        let kc = match scancode {
+            0x1C => 104, // 小键盘 Enter
+            0x1D => 105, // 右 Ctrl
+            0x35 => 106, // 小键盘 /
+            0x37 => 107, // PrintScreen
+            0x38 => 108, // 右 Alt
+            0x47 => 110, // Home
+            0x48 => 111, // ↑
+            0x49 => 112, // PageUp
+            0x4B => 113, // ←
+            0x4D => 114, // →
+            0x4F => 115, // End
+            0x50 => 116, // ↓
+            0x51 => 117, // PageDown
+            0x52 => 118, // Insert
+            0x53 => 119, // Delete
+            0x5B => 133, // 左 Super(Win)
+            0x5C => 134, // 右 Super(Win)
+            0x5D => 135, // Menu
+            _ => return None,
+        };
+        Some(kc)
+    } else {
+        // 0x01..=0x53 主键区，以及 0x57/0x58 的 F11/F12；其余为 Set-1 未定义位
+        match scancode {
+            0x01..=0x53 | 0x57 | 0x58 => Some((scancode + 8) as u8),
+            _ => None,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn main_block_uses_evdev_offset() {
+        assert_eq!(keycode_of(0x1E, false), Some(38)); // A
+        assert_eq!(keycode_of(0x02, false), Some(10)); // 1
+        assert_eq!(keycode_of(0x39, false), Some(65)); // Space
+        assert_eq!(keycode_of(0x1C, false), Some(36)); // Enter
+        assert_eq!(keycode_of(0x1D, false), Some(37)); // 左 Ctrl
+        assert_eq!(keycode_of(0x2A, false), Some(50)); // 左 Shift
+        assert_eq!(keycode_of(0x58, false), Some(96)); // F12
+    }
+
+    #[test]
+    fn extended_keys_are_not_offset() {
+        // 若误用 +8 规则，方向键会落到小键盘区（0x48+8=80=KP_8），这正是要防的坑
+        assert_eq!(keycode_of(0x48, true), Some(111)); // ↑
+        assert_ne!(keycode_of(0x48, true), Some(0x48 + 8));
+        assert_eq!(keycode_of(0x50, true), Some(116)); // ↓
+        assert_eq!(keycode_of(0x4B, true), Some(113)); // ←
+        assert_eq!(keycode_of(0x4D, true), Some(114)); // →
+        assert_eq!(keycode_of(0x47, true), Some(110)); // Home
+        assert_eq!(keycode_of(0x4F, true), Some(115)); // End
+        assert_eq!(keycode_of(0x49, true), Some(112)); // PageUp
+        assert_eq!(keycode_of(0x51, true), Some(117)); // PageDown
+        assert_eq!(keycode_of(0x53, true), Some(119)); // Delete
+        assert_eq!(keycode_of(0x5B, true), Some(133)); // 左 Super
+    }
+
+    #[test]
+    fn undefined_scancodes_are_rejected() {
+        assert_eq!(keycode_of(0x54, false), None);
+        assert_eq!(keycode_of(0x7F, false), None);
+        assert_eq!(keycode_of(0x99, true), None);
+    }
+
+    #[test]
+    fn coordinate_scaling_covers_full_range() {
+        assert_eq!(scale(0, 1920), 0);
+        // 归一化上界必须映射到 extent-1，否则指针永远到不了屏幕最右/最下
+        assert_eq!(scale(65535, 1920), 1919);
+        // 中点：32768 × 1919 ÷ 65535 = 959.49…，整数除法向下取整 → 959
+        assert_eq!(scale(32768, 1920), 959);
+        assert_eq!(scale(12345, 0), 0); // 退化尺寸不 panic
+    }
+}

linux-agent/src/main.rs

@@ -0,0 +1,31 @@
+//! Linux 被控端：X11 采集 + XTest 注入；会话层（QUIC/认证/编码/丢帧）复用 `agent-core`。
+//!
+//! 与 Windows 端的差异仅在这两个模块里，线格式与主控端完全一致，viewer 不需要任何改动。
+//! 依赖 `DISPLAY` 环境变量（Xorg / XWayland 均可）。
+
+mod capture;
+mod input;
+
+use agent_core::{parse_args, serve, EncoderSettings, InputInjector, ScreenCapturer, SessionConfig};
+use anyhow::Result;
+use std::sync::Arc;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let (port, code) = parse_args()?;
+
+    let display = std::env::var("DISPLAY").unwrap_or_else(|_| "(未设置)".to_string());
+    println!("[linux-agent] DISPLAY={display}");
+
+    // 注入端连接常驻（启动即校验 XTEST 扩展是否可用，缺了就直接报错退出）
+    let injector: Arc<dyn InputInjector> = Arc::new(input::X11Injector::new()?);
+
+    serve(
+        SessionConfig { port, code },
+        EncoderSettings::default(),
+        // 采集端可被重建（X11 连接断开等），故用工厂闭包
+        || Ok(Box::new(capture::X11Capturer::new()?) as Box<dyn ScreenCapturer>),
+        injector,
+    )
+    .await
+}

linux-agent/tests/smoke.rs

@@ -0,0 +1,447 @@
+//! Linux 被控端端到端冒烟测试。
+//!
+//! 需要 X server（Xvfb 即可），通过 `DISPLAY` 指定；推荐用 `scripts/linux-smoke.sh` 一键跑。
+//!
+//! 覆盖链路：X11 采集 → openh264 编码 → QUIC/TLS 下行 → 主控端解帧；
+//! 外加验证码认证、Ping/Pong、关键帧请求，以及**输入注入的实证断言**
+//! （注入鼠标移动后，从另一条 X11 连接查询指针真实落点，而不是只看进程没崩）。
+
+use anyhow::{bail, Context, Result};
+use common::{read_control, read_video_frame, write_control, ControlMsg, InputEvent};
+use rustls::client::danger::{HandshakeSignatureValid, ServerCertVerified, ServerCertVerifier};
+use rustls::pki_types::{CertificateDer, ServerName, UnixTime};
+use rustls::{DigitallySignedStruct, SignatureScheme};
+use std::io::{BufRead, BufReader};
+use std::net::{TcpListener, ToSocketAddrs};
+use std::process::{Child, Command, Stdio};
+use std::sync::{mpsc, Arc};
+use std::time::{Duration, Instant};
+use x11rb::connection::Connection;
+use x11rb::protocol::xproto::{ConnectionExt as _, Window};
+use x11rb::rust_connection::RustConnection;
+
+/// 与 viewer 一致：MVP 阶段跳过自签名证书校验
+#[derive(Debug)]
+struct SkipVerify;
+
+impl ServerCertVerifier for SkipVerify {
+    fn verify_server_cert(
+        &self,
+        _end_entity: &CertificateDer<'_>,
+        _intermediates: &[CertificateDer<'_>],
+        _server_name: &ServerName<'_>,
+        _ocsp_response: &[u8],
+        _now: UnixTime,
+    ) -> Result<ServerCertVerified, rustls::Error> {
+        Ok(ServerCertVerified::assertion())
+    }
+    fn verify_tls12_signature(
+        &self,
+        _message: &[u8],
+        _certificate: &CertificateDer<'_>,
+        _dss: &DigitallySignedStruct,
+    ) -> Result<HandshakeSignatureValid, rustls::Error> {
+        Ok(HandshakeSignatureValid::assertion())
+    }
+    fn verify_tls13_signature(
+        &self,
+        _message: &[u8],
+        _certificate: &CertificateDer<'_>,
+        _dss: &DigitallySignedStruct,
+    ) -> Result<HandshakeSignatureValid, rustls::Error> {
+        Ok(HandshakeSignatureValid::assertion())
+    }
+    fn supported_verify_schemes(&self) -> Vec<SignatureScheme> {
+        vec![
+            SignatureScheme::RSA_PKCS1_SHA256,
+            SignatureScheme::ECDSA_NISTP256_SHA256,
+            SignatureScheme::ED25519,
+            SignatureScheme::RSA_PSS_SHA256,
+        ]
+    }
+}
+
+/// 被测进程的 RAII 句柄：测试无论成功失败都会收尸
+struct AgentProc {
+    child: Child,
+}
+
+impl Drop for AgentProc {
+    fn drop(&mut self) {
+        let _ = self.child.kill();
+        let _ = self.child.wait();
+    }
+}
+
+fn expected_screen() -> (u32, u32) {
+    let s = std::env::var("SMOKE_SCREEN").unwrap_or_else(|_| "1280x720".to_string());
+    let (w, h) = s
+        .split_once('x')
+        .unwrap_or_else(|| panic!("SMOKE_SCREEN 需形如 1280x720，实际 {s:?}"));
+    (w.parse().expect("宽"), h.parse().expect("高"))
+}
+
+fn free_port() -> Result<u16> {
+    let l = TcpListener::bind("127.0.0.1:0")?;
+    Ok(l.local_addr()?.port())
+}
+
+fn spawn_agent(port: u16, code: &str) -> Result<AgentProc> {
+    let mut child = Command::new(env!("CARGO_BIN_EXE_linux-agent"))
+        .args(["--port", &port.to_string(), "--code", code])
+        .stdout(Stdio::piped())
+        .stderr(Stdio::inherit())
+        .spawn()
+        .context("启动 linux-agent 失败")?;
+
+    let stdout = child.stdout.take().expect("stdout 已 piped");
+    let (tx, rx) = mpsc::channel();
+    std::thread::spawn(move || {
+        for line in BufReader::new(stdout).lines().map_while(|l| l.ok()) {
+            println!("[agent] {line}");
+            let _ = tx.send(line);
+        }
+    });
+
+    // 等 QUIC 端口就绪
+    let deadline = Instant::now() + Duration::from_secs(30);
+    loop {
+        let left = deadline.saturating_duration_since(Instant::now());
+        if left.is_zero() {
+            bail!("等待 agent 监听超时（DISPLAY 是否已设置？）");
+        }
+        match rx.recv_timeout(left) {
+            Ok(line) if line.contains("listening") => return Ok(AgentProc { child }),
+            Ok(_) => continue,
+            Err(_) => bail!("等待 agent 监听超时，进程可能已退出"),
+        }
+    }
+}
+
+async fn connect(port: u16) -> Result<(quinn::Endpoint, quinn::Connection)> {
+    let tls = rustls::ClientConfig::builder()
+        .dangerous()
+        .with_custom_certificate_verifier(Arc::new(SkipVerify))
+        .with_no_client_auth();
+    let qc: quinn::crypto::rustls::QuicClientConfig = Arc::new(tls).try_into()?;
+
+    let mut transport = quinn::TransportConfig::default();
+    transport.receive_window(quinn::VarInt::from_u32(16 * 1024 * 1024));
+    transport.stream_receive_window(quinn::VarInt::from_u32(8 * 1024 * 1024));
+
+    let mut client_config = quinn::ClientConfig::new(Arc::new(qc));
+    client_config.transport_config(Arc::new(transport));
+
+    let mut endpoint = quinn::Endpoint::client("0.0.0.0:0".parse()?)?;
+    endpoint.set_default_client_config(client_config);
+
+    let addr = ("127.0.0.1", port)
+        .to_socket_addrs()?
+        .next()
+        .ok_or_else(|| anyhow::anyhow!("地址解析失败"))?;
+    let conn = endpoint.connect(addr, "localhost")?.await?;
+    // endpoint 必须与 conn 同生命周期，故一并返回
+    Ok((endpoint, conn))
+}
+
+fn has_start_code(payload: &[u8]) -> bool {
+    let head = &payload[..payload.len().min(64)];
+    head.windows(4).any(|w| w == [0, 0, 0, 1]) || head.windows(3).any(|w| w == [0, 0, 1])
+}
+
+/// H.264 NAL 类型：5 = IDR 片（关键帧）
+const NAL_IDR: u8 = 5;
+
+/// 按 Annex-B 起始码扫描，判断载荷里是否含指定类型的 NAL
+fn contains_nal(payload: &[u8], nal_type: u8) -> bool {
+    let mut i = 0usize;
+    while i + 3 <= payload.len() {
+        let sc_len = if payload[i..].starts_with(&[0, 0, 0, 1]) {
+            4
+        } else if payload[i..].starts_with(&[0, 0, 1]) {
+            3
+        } else {
+            i += 1;
+            continue;
+        };
+        if i + sc_len >= payload.len() {
+            return false;
+        }
+        if payload[i + sc_len] & 0x1F == nal_type {
+            return true;
+        }
+        i += sc_len + 1;
+    }
+    false
+}
+
+/// 在根窗口左上角画一个**小**矩形，制造一次细微画面变化。
+///
+/// 刻意不用「整屏刷白」那类大变化：大变化会触发编码器的场景切换自动 IDR，
+/// 于是「重发旧帧」和「真重编关键帧」拿到同样的字节，用例就失去区分度了。
+fn perturb_screen(conn: &RustConnection, root: Window) -> Result<()> {
+    use x11rb::protocol::xproto::{CreateGCAux, Rectangle};
+    let gc = conn.generate_id()?;
+    conn.create_gc(
+        gc,
+        root,
+        &CreateGCAux::new().foreground(0x00FF_FFFF).graphics_exposures(0),
+    )?;
+    conn.poly_fill_rectangle(
+        root,
+        gc,
+        &[Rectangle {
+            x: 32,
+            y: 32,
+            width: 64,
+            height: 64,
+        }],
+    )?;
+    conn.free_gc(gc)?;
+    conn.flush()?;
+    println!("[smoke] 已扰动屏幕（根窗口画 64x64 白块）");
+    Ok(())
+}
+
+/// 读帧直到拿到一个非关键帧（跳过静止桌面的低频重发），返回该帧载荷
+async fn read_until_p_frame(recv: &mut quinn::RecvStream, timeout: Duration) -> Result<Vec<u8>> {
+    let deadline = Instant::now() + timeout;
+    while Instant::now() < deadline {
+        let (_h, p) = tokio::time::timeout(Duration::from_secs(5), read_video_frame(recv))
+            .await
+            .context("等待扰动帧超时")??;
+        if !contains_nal(&p, NAL_IDR) {
+            return Ok(p);
+        }
+    }
+    bail!("扰动后未拿到非关键帧，用例前置条件不成立（扰动量是否太大？）")
+}
+
+/// 请求关键帧后，容错地等待一个 IDR：期间允许出现静止桌面的 P 帧重发。
+/// 返回是否在超时内拿到 IDR。
+async fn wait_for_idr(recv: &mut quinn::RecvStream, timeout: Duration) -> Result<bool> {
+    let deadline = Instant::now() + timeout;
+    while Instant::now() < deadline {
+        match tokio::time::timeout(Duration::from_secs(2), read_video_frame(recv)).await {
+            Ok(Ok((_h, p))) => {
+                if contains_nal(&p, NAL_IDR) {
+                    return Ok(true);
+                }
+            }
+            _ => break,
+        }
+    }
+    Ok(false)
+}
+
+/// 归一化坐标 → 根窗口像素（与 linux-agent/src/input.rs 的 scale 完全一致）
+fn scale(v: u16, extent: u32) -> i16 {
+    if extent <= 1 {
+        return 0;
+    }
+    ((v as i64 * (extent as i64 - 1)) / 65535) as i16
+}
+
+fn open_display() -> Result<(RustConnection, Window)> {
+    let (conn, screen_num) = x11rb::connect(None)
+        .map_err(|e| anyhow::anyhow!("连接 X11 失败（DISPLAY 是否已设置？）: {e}"))?;
+    let root = conn.setup().roots[screen_num].root;
+    Ok((conn, root))
+}
+
+fn pointer_position(conn: &RustConnection, root: Window) -> Result<(i16, i16)> {
+    let r = conn.query_pointer(root)?.reply()?;
+    Ok((r.root_x, r.root_y))
+}
+
+fn wait_pointer(
+    conn: &RustConnection,
+    root: Window,
+    want: (i16, i16),
+    timeout: Duration,
+) -> Result<(i16, i16)> {
+    let deadline = Instant::now() + timeout;
+    let mut last = pointer_position(conn, root)?;
+    while Instant::now() < deadline {
+        last = pointer_position(conn, root)?;
+        if (last.0 - want.0).abs() <= 2 && (last.1 - want.1).abs() <= 2 {
+            return Ok(last);
+        }
+        std::thread::sleep(Duration::from_millis(50));
+    }
+    Ok(last)
+}
+
+#[tokio::test]
+async fn end_to_end_capture_encode_transport_input() -> Result<()> {
+    rustls::crypto::ring::default_provider()
+        .install_default()
+        .ok();
+
+    let (sw, sh) = expected_screen();
+    let port = free_port()?;
+    let _agent = spawn_agent(port, "smoke-code")?;
+    let (_endpoint, conn) = connect(port).await?;
+
+    // 流 1：认证，并核对被控端上报的桌面尺寸就是 Xvfb 的尺寸
+    let (mut send, mut recv) = conn.open_bi().await?;
+    write_control(
+        &mut send,
+        &ControlMsg::Auth {
+            code: "smoke-code".into(),
+            proto_version: common::PROTO_VERSION,
+        },
+    )
+    .await?;
+    match read_control(&mut recv).await? {
+        ControlMsg::AuthOk {
+            width,
+            height,
+            proto_version,
+        } => {
+            assert_eq!(proto_version, common::PROTO_VERSION, "被控端协议版本不符");
+            assert_eq!(
+                (width, height),
+                (sw, sh),
+                "agent 上报桌面尺寸与实际屏幕不符"
+            );
+        }
+        other => bail!("认证应成功，却收到 {other:?}"),
+    }
+
+    // 流 2：输入 + 控制
+    let (mut isend, mut irecv) = conn.open_bi().await?;
+
+    // Ping/Pong（延迟测量通道 + 下行丢包统计）
+    write_control(&mut isend, &ControlMsg::Ping(4242)).await?;
+    match read_control(&mut irecv).await? {
+        ControlMsg::Pong {
+            t,
+            agent_ts,
+            lost,
+            sent,
+        } => {
+            assert_eq!(t, 4242, "Pong 回显的时间戳不一致");
+            assert!(sent > 0, "下行发包计数应大于 0（视频流已在发）");
+            println!("[smoke] Pong 收到，agent_ts={agent_ts}，下行 sent={sent} lost={lost}");
+        }
+        other => bail!("期望 Pong，收到 {other:?}"),
+    }
+
+    // 首帧：证明采集 + 编码 + 线格式整条链路通了
+    let (h1, p1) = tokio::time::timeout(Duration::from_secs(15), read_video_frame(&mut recv))
+        .await
+        .context("等待首个视频帧超时")??;
+    assert_eq!((h1.width, h1.height), (sw, sh), "视频帧头尺寸不符");
+    assert!(!p1.is_empty(), "视频载荷为空");
+    println!(
+        "[smoke] 首帧 {}x{} ts={} 编码后 {} 字节，头部 {:02X?}",
+        h1.width,
+        h1.height,
+        h1.ts_ms,
+        p1.len(),
+        &p1[..p1.len().min(12)]
+    );
+    assert!(
+        has_start_code(&p1),
+        "载荷不像 H.264（前 16 字节 {:02X?}）",
+        &p1[..p1.len().min(16)]
+    );
+
+    // 关键帧恢复：先在**静止**桌面上请求关键帧。
+    // 为了有区分度，先扰动一下屏幕，让缓存里落入一个非关键帧（P 帧），否则
+    // 「重发旧帧」和「真重编关键帧」两种行为拿到的字节是一样的，测不出来。
+    let (probe, root) = open_display()?;
+    perturb_screen(&probe, root)?;
+    let pp = read_until_p_frame(&mut recv, Duration::from_secs(10)).await?;
+    println!(
+        "[smoke] 扰动帧 {} 字节，头部 {:02X?}（应为 P 帧，无 IDR）",
+        pp.len(),
+        &pp[..pp.len().min(12)]
+    );
+    // 前置条件自检：没有这一步，用例可能因为「扰动本身产生了 IDR」而虚假通过
+    assert!(
+        !contains_nal(&pp, NAL_IDR),
+        "扰动帧仍是 IDR，本用例无法区分重发旧帧与真重编关键帧"
+    );
+    tokio::time::sleep(Duration::from_millis(800)).await; // 等画面重新静止
+
+    write_control(&mut isend, &ControlMsg::KeyFrameReq).await?;
+    assert!(
+        wait_for_idr(&mut recv, Duration::from_secs(3)).await?,
+        "静止桌面请求关键帧后 3s 内未收到 IDR：解码端一旦出错将永远无法恢复"
+    );
+    println!("[smoke] 静止桌面请求关键帧 → 收到 IDR");
+
+    // 输入注入实证：注入到屏幕中心，再从独立 X11 连接查询指针真实落点
+    let before = pointer_position(&probe, root)?;
+    write_control(
+        &mut isend,
+        &ControlMsg::Input(InputEvent::MouseMove {
+            x: 32768,
+            y: 32768,
+        }),
+    )
+    .await?;
+    let want = (scale(32768, sw), scale(32768, sh));
+    let got = wait_pointer(&probe, root, want, Duration::from_secs(5))?;
+    println!("[smoke] 指针 {before:?} → {got:?}（期望 ≈{want:?}）");
+    assert!(
+        (got.0 - want.0).abs() <= 2 && (got.1 - want.1).abs() <= 2,
+        "XTest 注入未生效：期望指针 ≈{want:?}，实际 {got:?}"
+    );
+
+    // 键盘：链路不得因此崩溃（无窗口可断言落点）
+    write_control(
+        &mut isend,
+        &ControlMsg::Input(InputEvent::KeyDown {
+            scancode: 0x1E,
+            extended: false,
+        }),
+    )
+    .await?;
+    write_control(
+        &mut isend,
+        &ControlMsg::Input(InputEvent::KeyUp {
+            scancode: 0x1E,
+            extended: false,
+        }),
+    )
+    .await?;
+
+    tokio::time::sleep(Duration::from_millis(300)).await;
+    assert!(
+        conn.close_reason().is_none(),
+        "会话被意外关闭：{:?}",
+        conn.close_reason()
+    );
+
+    println!("[smoke] 全部断言通过");
+    Ok(())
+}
+
+#[tokio::test]
+async fn rejects_wrong_verification_code() -> Result<()> {
+    rustls::crypto::ring::default_provider()
+        .install_default()
+        .ok();
+
+    let port = free_port()?;
+    let _agent = spawn_agent(port, "right-code")?;
+    let (_endpoint, conn) = connect(port).await?;
+
+    let (mut send, mut recv) = conn.open_bi().await?;
+    write_control(
+        &mut send,
+        &ControlMsg::Auth {
+            code: "wrong-code".into(),
+            proto_version: common::PROTO_VERSION,
+        },
+    )
+    .await?;
+
+    match read_control(&mut recv).await? {
+        ControlMsg::AuthFail(_) => Ok(()),
+        other => bail!("错误验证码竟被接受：{other:?}"),
+    }
+}

scripts/linux-smoke.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Linux 被控端冒烟测试一键脚本：自建 Xvfb 虚拟显示 → 跑端到端测试 → 收摊。
+#
+# 用法（容器内或任意有 Xvfb 的 Linux）：
+#   bash scripts/linux-smoke.sh
+# 可用环境变量覆盖：
+#   SMOKE_SCREEN=1920x1080   虚拟屏分辨率（默认 1280x720）
+#   SMOKE_DISPLAY=:99        X display 编号（默认 :99）
+set -euo pipefail
+
+SCREEN="${SMOKE_SCREEN:-1280x720}"
+DISPLAY_NUM="${SMOKE_DISPLAY:-:99}"
+
+export DISPLAY="$DISPLAY_NUM"
+export SMOKE_SCREEN="$SCREEN"
+
+XVFB_PID=""
+cleanup() {
+  if [ -n "$XVFB_PID" ]; then
+    kill "$XVFB_PID" 2>/dev/null || true
+    wait "$XVFB_PID" 2>/dev/null || true
+  fi
+}
+trap cleanup EXIT
+
+echo "[smoke] 启动 Xvfb $DISPLAY_NUM (${SCREEN}x24)"
+Xvfb "$DISPLAY_NUM" -screen 0 "${SCREEN}x24" -nolisten tcp >/tmp/xvfb.log 2>&1 &
+XVFB_PID=$!
+
+ready=0
+for _ in $(seq 1 50); do
+  if xdpyinfo -display "$DISPLAY_NUM" >/dev/null 2>&1; then
+    ready=1
+    break
+  fi
+  sleep 0.2
+done
+
+if [ "$ready" -ne 1 ]; then
+  echo "[smoke] Xvfb 启动失败，日志："
+  cat /tmp/xvfb.log 2>/dev/null || true
+  exit 1
+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] 通过"

tools/punch_probe.py

@@ -0,0 +1,365 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""UDP 打洞探针 —— 两台不同网络的机器各跑一个，用来摸清你们线路的底牌。
+
+回答四个问题：
+  1. 这条线路的 NAT 能不能打洞？
+  2. 要几轮才能打通？（轮数越少说明 NAT 越宽松）
+  3. 对方的源端口有没有被 NAT 改写？（判断是不是对称 NAT）
+  4. 有没有公网 IPv6？IPv6 直连通不通？
+
+用法
+----
+A 机（假设公网 1.2.3.4）:
+    py punch_probe.py --peer 2.3.4.5:47800
+
+B 机（假设公网 2.3.4.5）:
+    py punch_probe.py --peer 1.2.3.4:47800
+
+IPv6（双方都有公网 v6 时）:
+    py punch_probe.py --peer [2408:8207:1234::1]:47800
+
+先查自己的公网映射（走 STUN，不需要对方）:
+    py punch_probe.py --stun
+
+被动监听（不发包，只看能不能收到对方打进来的包）:
+    py punch_probe.py
+
+说明
+----
+- 两台机器必须**同时**启动，脚本靠「双方同时向对方发包」来穿透 NAT。
+- 先各自查公网 IP（浏览器搜 "my ip" 或 --stun），再互相填。
+- 只依赖 Python 标准库。
+"""
+
+import argparse
+import socket
+import struct
+import sys
+import threading
+import time
+
+MAGIC = b"PUNCHv1|"
+
+
+# ---------------------------------------------------------------- 地址解析
+
+def parse_addr(s):
+    """解析 'ip:port' 或 '[v6]:port' -> (host, port, family)"""
+    s = s.strip()
+    if s.startswith("["):
+        end = s.index("]")
+        host = s[1:end]
+        port = int(s[end + 2:])
+        return host, port, socket.AF_INET6
+    host, _, p = s.rpartition(":")
+    return host, int(p), socket.AF_INET
+
+
+def fmt_addr(sockaddr):
+    host, port = sockaddr[0], sockaddr[1]
+    if ":" in host:
+        return "[%s]:%d" % (host, port)
+    return "%s:%d" % (host, port)
+
+
+# ---------------------------------------------------------------- STUN
+
+def stun_mapped(server="stun.l.google.com", port=19302, timeout=3.0, sock=None):
+    """最小 STUN Binding 请求，返回 (ip, port)；失败返回 None。
+
+    sock 不为 None 时复用它（用来测「同一个本地端口对另一个目标」的映射端口，
+    这是判断 NAT 是不是对称型的关键）。
+    """
+    txid = b"\x5a" * 12
+    req = struct.pack(">HHI12s", 0x0001, 0, 0x2112A442, txid)
+    try:
+        infos = socket.getaddrinfo(server, port, 0, socket.SOCK_DGRAM)
+    except OSError:
+        return None
+    fam, sockaddr = infos[0][0], infos[0][4]
+    own = sock is None
+    s = socket.socket(fam, socket.SOCK_DGRAM) if own else sock
+    s.settimeout(timeout)
+    try:
+        s.sendto(req, sockaddr)
+        data, _ = s.recvfrom(2048)
+    except OSError:
+        return None
+    finally:
+        if own:
+            s.close()
+
+    if len(data) < 20:
+        return None
+    off = 20
+    while off + 4 <= len(data):
+        atype, alen = struct.unpack(">HH", data[off:off + 4])
+        val = data[off + 4:off + 4 + alen]
+        if atype == 0x0020 and len(val) >= 8:          # XOR-MAPPED-ADDRESS
+            famv = val[1]
+            xport = struct.unpack(">H", val[2:4])[0] ^ 0x2112
+            if famv == 0x01 and len(val) >= 8:
+                ip = bytes(a ^ b for a, b in zip(val[4:8], b"\x21\x12\xA4\x42"))
+                return socket.inet_ntoa(ip), xport
+            if famv == 0x02 and len(val) >= 20:
+                mask = b"\x21\x12\xA4\x42" + txid
+                ip = bytes(a ^ b for a, b in zip(val[4:20], mask))
+                return socket.inet_ntop(socket.AF_INET6, ip), xport
+        off += 4 + alen + ((4 - alen % 4) % 4)
+    return None
+
+
+# ---------------------------------------------------------------- 信令
+
+def discover_peer(sock, server, room, timeout=60.0):
+    """注册到房间，等服务器回推对方的公网地址。
+
+    注意：这里**复用同一个 socket**——服务器看到的源地址，就是 NAT 为
+    「本机 → 服务器」这条流分配的映射。对锥形 NAT 而言，它与「本机 → 对端」
+    的映射相同，所以拿它去打洞是有效的；对对称 NAT 则不同，打不通属预期。
+    """
+    host, port = server[0], server[1]
+    deadline = time.time() + timeout
+    last_send = 0.0
+    while time.time() < deadline:
+        now = time.time()
+        if now - last_send > 1.0:
+            try:
+                sock.sendto(b"REGISTER|" + room.encode("utf-8"), (host, port))
+            except OSError as e:
+                print("  注册发送失败：%s" % e)
+                return None
+            last_send = now
+        try:
+            data, _src = sock.recvfrom(2048)
+        except socket.timeout:
+            continue
+        except ConnectionResetError:
+            continue
+        except OSError as e:
+            if getattr(e, "winerror", None) == 10054:
+                continue
+            return None
+        txt = data.decode("utf-8", "replace").strip()
+        if txt.startswith("PEER|"):
+            h, p, _f = parse_addr(txt[5:])
+            return (h, p)
+    return None
+
+
+# ---------------------------------------------------------------- 主逻辑
+
+class Probe:
+    def __init__(self, bind_host, port, family):
+        self.sock = socket.socket(family, socket.SOCK_DGRAM)
+        self.sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        if family == socket.AF_INET6:
+            try:
+                self.sock.setsockopt(socket.IPPROTO_IPV6, socket.IPV6_V6ONLY, 1)
+            except OSError:
+                pass
+        self.sock.bind((bind_host, port))
+        self.sock.settimeout(0.2)
+        # Windows 特有坑：曾经发过包给对方，但对方端口没开 → 会收到 ICMP 端口不可达，
+        # 之后下一次 recv 直接抛 WSAECONNRESET(10054)。不打这个 ioctl，
+        # 接收循环会被"自己之前的失败发送"打断，之后再也收不到包。
+        # （Rust 实现同样要处理：tokio recv 返回 ConnectionReset 时不能退出循环）
+        if sys.platform == "win32":
+            try:
+                self.sock.ioctl(socket.SIO_UDP_CONNRESET, False)
+            except (AttributeError, OSError):
+                pass
+        self.port = self.sock.getsockname()[1]
+        self.stop = threading.Event()
+        self.first_src = None
+        self.packets = 0
+        self.junk = 0
+
+    def receiver(self, ignore=()):
+        """接收线程。
+
+        只认「以 MAGIC 开头」且「来自对端而非信令服务器」的包。
+        信令服务器的 PEER/WAIT 回复绝不能算作打通——否则客户端反复注册引来的
+        回复会造成假阳性（已踩过：把服务器的 PEER 回复误判成打洞成功）。
+        """
+        while not self.stop.is_set():
+            try:
+                data, src = self.sock.recvfrom(2048)
+            except socket.timeout:
+                continue
+            except ConnectionResetError:
+                # ICMP 端口不可达留下的错误，忽略并继续收（绝不能 break）
+                continue
+            except OSError as e:
+                if getattr(e, "winerror", None) == 10054:
+                    continue
+                break
+
+            # ---- 过滤：非打洞包一律丢弃
+            if not data.startswith(MAGIC) or (ignore and src[:2] in ignore):
+                self.junk += 1
+                continue
+
+            if self.first_src is None:
+                self.first_src = src
+                print("\n  ✅ 收到对方的包！")
+                print("     对方源地址（NAT 之后）= %s" % fmt_addr(src))
+                if src[1] != self.port:
+                    print("     对方源端口 = %d（本机端口 %d）；若双方约定端口相同，"
+                          "说明 NAT 改写了端口" % (src[1], self.port))
+                else:
+                    print("     对方源端口与约定端口一致 → NAT 保留了端口")
+            self.packets += 1
+            if self.packets <= 3:
+                print("     [%s] 收到 %d 字节" % (fmt_addr(src), len(data)))
+
+    def send_rounds(self, peer_sockaddr, rounds, interval):
+        for i in range(1, rounds + 1):
+            if self.stop.is_set():
+                return
+            payload = MAGIC + struct.pack(">d", time.time())
+            try:
+                self.sock.sendto(payload, peer_sockaddr)
+            except OSError as e:
+                print("  发送失败：%s" % e)
+                return
+            if i == 1 or i % 5 == 0 or self.first_src is not None:
+                mark = "✅" if self.first_src is not None else "  "
+                print("  %s 第 %2d/%d 轮已发出" % (mark, i, rounds))
+            if self.first_src is not None:
+                return
+            time.sleep(interval)
+
+
+def main():
+    ap = argparse.ArgumentParser(add_help=True, description="UDP 打洞探针")
+    ap.add_argument("--peer", help="对方地址 ip:port 或 [v6]:port；不给则只被动监听")
+    ap.add_argument("--port", type=int, default=47800, help="本地端口（默认 47800）")
+    ap.add_argument("--rounds", type=int, default=25, help="发包轮数（默认 25）")
+    ap.add_argument("--interval", type=float, default=0.2, help="轮间隔秒（默认 0.2）")
+    ap.add_argument("--grace", type=float, default=2.5,
+                    help="发完后继续监听多少秒等回包（默认 2.5）")
+    ap.add_argument("--server", help="信令服务器 ip:port（与 --room 配合，自动配对）")
+    ap.add_argument("--room", help="房间名；同一房间的两个客户端会被配对")
+    ap.add_argument("--wait", type=float, default=60.0,
+                    help="等对方加入房间的秒数（默认 60）")
+    ap.add_argument("--stun", action="store_true", help="只查询自己的公网映射后退出")
+    ap.add_argument("--stun-port", type=int, default=0,
+                    help="配合 --stun：用指定本地端口发 STUN（与打洞端口一致时才能对比映射）")
+    args = ap.parse_args()
+
+    # ---- 只查 STUN
+    if args.stun:
+        s = None
+        if args.stun_port:
+            s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+            s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            s.bind(("0.0.0.0", args.stun_port))
+            print("[STUN] 用本机端口 %d 查询（与打洞同端口）..." % args.stun_port)
+        else:
+            print("[STUN] 查询公网映射（临时端口）...")
+        r = stun_mapped(sock=s)
+        if s:
+            s.close()
+        if r:
+            print("  对 Google STUN 的映射 = %s:%d" % r)
+            if args.stun_port:
+                print("  本机端口              = %d" % args.stun_port)
+                print("  下一步：对比信令服务器日志里记录的源端口")
+                print("    两者相同 → 端点无关映射（锥形 NAT）→ 打洞大概率成功")
+                print("    两者不同 → 对称 NAT → 打洞困难，需要端口预测或中继")
+        else:
+            print("  查询失败（STUN 19302 可能被封；可稍后重试）")
+        return 0
+
+    # ---- 决定地址族与模式
+    peer = None
+    if args.peer:
+        host, pport, family = parse_addr(args.peer)
+        peer = (host, pport)
+        bind_host = "::" if family == socket.AF_INET6 else "0.0.0.0"
+        mode = "双向打洞（手工填地址）"
+    elif args.server and args.room:
+        _h, _p, family = parse_addr(args.server)
+        bind_host = "::" if family == socket.AF_INET6 else "0.0.0.0"
+        mode = "信令自动配对 + 打洞"
+    else:
+        family = socket.AF_INET
+        bind_host = "0.0.0.0"
+        mode = "被动监听"
+
+    probe = Probe(bind_host, args.port, family)
+    print("=" * 60)
+    print(" UDP 打洞探针  模式=%s" % mode)
+    print(" 本机监听      %s:%d" % (bind_host, probe.port))
+    if peer:
+        print(" 发往          %s  （%s）" % (fmt_addr(peer + (0, 0)),
+                                          "IPv6" if family == socket.AF_INET6 else "IPv4"))
+    print("=" * 60)
+
+    # ---- 信令配对：不用自己查公网 IP，服务器看到的就是你的公网映射
+    if args.server and args.room and peer is None:
+        srv = parse_addr(args.server)[:2]
+        print("\n向信令服务器 %s 注册 room=%s ..." % (fmt_addr(srv), args.room))
+        found = discover_peer(probe.sock, srv, args.room, timeout=args.wait)
+        if found is None:
+            print("  ❌ 超时：没等到对方加入同一个房间")
+            probe.sock.close()
+            return 1
+        peer = found
+        print("  ✅ 配对成功，对方公网地址 = %s" % fmt_addr(found))
+
+    # 信令服务器的回复（PEER/WAIT）绝不能算作打通，接收线程必须把它排除掉
+    ignore = set()
+    if args.server:
+        _sh, _sp, _sf = parse_addr(args.server)
+        ignore.add((_sh, _sp))
+
+    t = threading.Thread(target=probe.receiver, args=(ignore,), daemon=True)
+    t.start()
+
+    try:
+        if peer:
+            print("\n开始同时发包（若对方也在发包，第 1~3 轮通常就通）...")
+            probe.send_rounds(peer, args.rounds, args.interval)
+            # 对方可能比我晚启动：发完后继续监听，否则会把"晚到的成功"误判成失败
+            if probe.first_src is None:
+                print("\n发包结束，继续监听 %.1f 秒等对方回包 ..." % args.grace)
+                waited = 0.0
+                while waited < args.grace and probe.first_src is None:
+                    time.sleep(0.1)
+                    waited += 0.1
+        else:
+            print("\n被动监听中，Ctrl+C 退出 ...")
+            while not probe.stop.is_set():
+                time.sleep(0.3)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        probe.stop.set()
+        time.sleep(0.3)
+        probe.sock.close()
+
+    print("\n" + "-" * 60)
+    if probe.first_src is not None:
+        print("结论：✅ 打洞成功")
+        print("      对方实际源地址 = %s" % fmt_addr(probe.first_src))
+        print("      共收到 %d 个包" % probe.packets)
+    else:
+        print("结论：❌ 本轮没有收到对方的打洞包")
+        if probe.junk:
+            print("  （另外收到 %d 个非打洞包并已忽略：那是信令服务器的回复，不算打通）"
+                  % probe.junk)
+        print("  可能原因（按概率排序）：")
+        print("   1. 一端或两端是对称型 NAT / 运营商级 NAT(CGNAT) → 需要端口预测或中继")
+        print("   2. 一方根本没发包（对方没启动、或地址填错/端口填错）")
+        print("   3. UDP 被防火墙拦截（企业网络常见）")
+        print("   4. 双方没有真正同时发包（时间差超过 NAT 表项寿命）")
+        print("  下一步：两端各跑一次 --stun，看看是不是落在 100.64~100.127 网段（CGNAT）")
+    print("-" * 60)
+    return 0 if probe.first_src is not None else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tools/rendezvous.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""极简 rendezvous（信令）服务器 —— POC 用
+
+作用只有一个：**告诉双方「对方看到的你」是什么地址**。
+双方注册到同一个房间后，服务器把各自观察到的公网地址回推给对方，
+之后双方直接打洞，服务器不再参与（也不承载任何媒体流量）。
+
+用法（跑在有公网 IP 的机器上，比如 43.140.215.244）:
+    py rendezvous.py --port 47999
+
+客户端：
+    py punch_probe.py --server <服务器IP>:47999 --room test01 --port 47800
+"""
+
+import argparse
+import socket
+import sys
+import time
+
+# 房间成员多久没动静就清掉
+MEMBER_TTL = 30.0
+
+
+def fmt(sockaddr):
+    host, port = sockaddr[0], sockaddr[1]
+    return "[%s]:%d" % (host, port) if ":" in host else "%s:%d" % (host, port)
+
+
+def main():
+    ap = argparse.ArgumentParser(description="极简 rendezvous 服务器")
+    ap.add_argument("--bind", default="0.0.0.0")
+    ap.add_argument("--port", type=int, default=47999)
+    args = ap.parse_args()
+
+    # 重定向到文件时 stdout 会全缓冲，日志要等进程退出才出现；强制行缓冲
+    try:
+        sys.stdout.reconfigure(line_buffering=True)
+    except (AttributeError, OSError):
+        pass
+
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    sock.bind((args.bind, args.port))
+
+    print("[rendezvous] 监听 udp://%s:%d" % (args.bind, args.port))
+    print("[rendezvous] 房间成员 TTL = %.0fs，Ctrl+C 退出\n" % MEMBER_TTL)
+
+    rooms = {}  # room -> [(addr, last_seen)]
+
+    try:
+        while True:
+            data, src = sock.recvfrom(2048)
+            txt = data.decode("utf-8", "replace").strip()
+            now = time.time()
+
+            if not txt.startswith("REGISTER|"):
+                continue
+            room = txt.split("|", 1)[1].strip()
+            if not room:
+                continue
+
+            # 清掉过期成员 + 去掉本机的旧记录（支持重复注册）
+            members = [(a, t) for (a, t) in rooms.get(room, [])
+                       if now - t < MEMBER_TTL and a[1] != src[1]]
+            members.append((src, now))
+            rooms[room] = members
+
+            print("[rendezvous] %s 注册 room=%s  (现有 %d 人)  源地址=%s"
+                  % (fmt(src), room, len(members), fmt(src)))
+
+            if len(members) >= 2:
+                a1, _ = members[0]
+                a2, _ = members[1]
+                sock.sendto(b"PEER|" + fmt(a2).encode(), a1)
+                sock.sendto(b"PEER|" + fmt(a1).encode(), a2)
+                print("[rendezvous]   -> 配对成功：%s  <==>  %s"
+                      % (fmt(a1), fmt(a2)))
+            else:
+                sock.sendto(b"WAIT", src)
+                print("[rendezvous]   -> 等待第二个人加入 ...")
+    except KeyboardInterrupt:
+        print("\n[rendezvous] 退出")
+    finally:
+        sock.close()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

vendor/nvenc/.gitignore

@@ -0,0 +1,2 @@
+/target
+/.vscode

vendor/nvenc/Cargo.toml

@@ -0,0 +1,63 @@
+# THIS FILE IS AUTOMATICALLY GENERATED BY CARGO
+#
+# When uploading crates to the registry Cargo will automatically
+# "normalize" Cargo.toml files for maximal compatibility
+# with all versions of Cargo and also rewrite `path` dependencies
+# to registry (e.g., crates.io) dependencies.
+#
+# If you are reading this file be aware that the original Cargo.toml
+# will likely look very different (and much more reasonable).
+# See Cargo.toml.orig for the original contents.
+
+[package]
+edition = "2024"
+rust-version = "1.85.1"
+name = "nvenc"
+version = "0.1.0"
+authors = ["AlsoSylv"]
+build = false
+autolib = false
+autobins = false
+autoexamples = false
+autotests = false
+autobenches = false
+description = "Wrapper for the nvidia NVENC API"
+readme = "README.md"
+keywords = [
+    "nvidia",
+    "graphics",
+    "media",
+    "video",
+    "ffi",
+]
+categories = [
+    "multimedia",
+    "external-ffi-bindings",
+]
+license = "MIT"
+repository = "https://github.com/AlsoSylv/nvenc"
+
+[lib]
+name = "nvenc"
+path = "src/lib.rs"
+# 上游 README 的示例是已过时的 Linux GLX 用法（Session<NeedsConfig> 等类型已不存在），
+# 直接跑 doctest 会失败。本项目只做 vendor 补丁、不维护文档示例，故关闭。
+doctest = false
+
+[[example]]
+name = "simple_encode"
+path = "examples/simple_encode.rs"
+
+[dependencies.bitfields]
+version = "1.0.2"
+
+[dependencies.libloading]
+version = "0.8.9"
+
+[target."cfg(windows)".dependencies.windows]
+version = "0.62"
+features = [
+    "Win32_Graphics_Dxgi_Common",
+    "Win32_Graphics_Direct3D",
+    "Win32_Graphics_Direct3D11",
+]

vendor/nvenc/Cargo.toml.orig

@@ -0,0 +1,24 @@
+[package]
+name = "nvenc"
+version = "0.1.0"
+edition = "2024"
+authors = ["AlsoSylv"]
+description = "Wrapper for the nvidia NVENC API"
+rust-version = "1.85.1"
+readme = "README.md"
+repository = "https://github.com/AlsoSylv/nvenc"
+license = "MIT"
+keywords = ["nvidia", "graphics", "media", "video", "ffi"]
+categories = ["multimedia", "external-ffi-bindings"]
+
+[dependencies]
+libloading = "0.8.9"
+bitfields = "1.0.2"
+
+[target.'cfg(windows)'.dependencies.windows]
+version = "0.62"
+features = [
+    "Win32_Graphics_Dxgi_Common",
+    "Win32_Graphics_Direct3D",
+    "Win32_Graphics_Direct3D11",
+]

vendor/nvenc/LICENSE.txt

@@ -0,0 +1,27 @@
+Notice Regarding Standards. I do not provide a license or sublicense to
+any Intellectual Property Rights relating to any standards, including but not
+limited to any audio and/or video codec technologies such as MPEG-2, MPEG-4;
+AVC/H.264; HEVC/H.265; AAC decode/FFMPEG; AAC encode/FFMPEG; VC-1; and MP3
+(collectively, the "Media Technologies"). For clarity, you will pay any
+royalties due for such third party technologies, which may include the Media
+Technologies that are owed as a result of me providing the Software to you.
+
+Copyright 2025 AlsoSylv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

vendor/nvenc/README.md

@@ -0,0 +1,34 @@
+### If you like my work and want to support what I do, support me on Ko-Fi 💜!
+[![Ko-Fi](https://img.shields.io/badge/Ko--fi-F16061?style=for-the-badge&logo=ko-fi&logoColor=white)](https://ko-fi.com/cyberite)
+---
+
+![Crates.io MSRV](https://img.shields.io/crates/msrv/nvenc?style=for-the-badge) ![Crates.io License](https://img.shields.io/crates/l/nvenc?style=for-the-badge) ![GitHub Repo stars](https://img.shields.io/github/stars/AlsoSylv/nvenc?style=for-the-badge)
+
+The following example is for Linux GLX
+
+```rust
+use nvenc::{session::Session, encoder::Encoder};
+
+fn main() {
+    // Setup GLX context
+    let session: Session<NeedsConfig> = Session::open_gl();
+    let (session, config): (Session<NeedsInit>, NVencPresetConfig) 
+        = session.get_preset_config(
+            NV_ENC_CODEC_H264_GUID, 
+            NV_ENC_PRESET_P3_GUID, 
+            NVencTuningInfo::LowLatency
+        );
+    let init_params = nvenc::session::InitParams {
+        encode_guid: NV_ENC_H264_GUID,
+        preset_guid: NV_ENC_PRESET_P3_GUID,
+        resolution: [1920, 1080],
+        aspect_ratio: [16, 9],
+        frame_rate: [30, 1],
+        tuning_info: NVencTuningInfo::LowLatency,
+        buffer_format: NVencBufferFormat::ARGB,
+        encode_config: &mut config.preset_cfg,
+        enable_ptd: true,
+    };
+    let encoder: Encoder = session.init(init_params);
+}
+```

vendor/nvenc/examples/simple_encode.rs

@@ -0,0 +1,203 @@
+use std::fs::File;
+use std::io::Write;
+use std::time::Instant;
+
+use nvenc::bitstream::BitStream;
+use nvenc::session::InitParams;
+use nvenc::{
+    session::Session,
+    sys::guids::{NV_ENC_CODEC_H264_GUID, NV_ENC_PRESET_P3_GUID},
+};
+#[cfg(windows)]
+use windows::Win32::Graphics::Direct3D11::{ID3D11Device, ID3D11Texture2D};
+
+#[cfg(windows)]
+pub fn setup() -> ID3D11Device {
+    let dxgi_factory: windows::Win32::Graphics::Dxgi::IDXGIFactory =
+        unsafe { windows::Win32::Graphics::Dxgi::CreateDXGIFactory() }.unwrap();
+    let dxgi_adapter = unsafe { dxgi_factory.EnumAdapters(0) }.unwrap();
+
+    let desc = unsafe { dxgi_adapter.GetDesc() }.unwrap();
+    println!("{:?}", windows::core::HSTRING::from_wide(&desc.Description));
+
+    let mut device = None;
+    let mut device_context = None;
+    unsafe {
+        use windows::Win32::{
+            Foundation::HMODULE,
+            Graphics::{
+                Direct3D::{D3D_DRIVER_TYPE_UNKNOWN, D3D_FEATURE_LEVEL_11_0},
+                Direct3D11::{D3D11_CREATE_DEVICE_FLAG, D3D11_SDK_VERSION, D3D11CreateDevice},
+            },
+        };
+
+        D3D11CreateDevice(
+            &dxgi_adapter,
+            D3D_DRIVER_TYPE_UNKNOWN,
+            HMODULE(std::ptr::null_mut()),
+            D3D11_CREATE_DEVICE_FLAG(0),
+            Some(&[D3D_FEATURE_LEVEL_11_0]),
+            D3D11_SDK_VERSION,
+            Some(&raw mut device),
+            None,
+            Some(&raw mut device_context),
+        )
+    }
+    .unwrap();
+    let device = device.unwrap();
+    let _device_context = device_context.unwrap();
+
+    device
+}
+
+#[cfg(windows)]
+fn image(device: &ID3D11Device) -> ID3D11Texture2D {
+    let data: [u8; 1920 * 4] = std::array::from_fn(|idx| match idx % 4 {
+        0 => 255,
+        1 => 0,
+        2 => 0,
+        3 => 255,
+        _ => unreachable!(),
+    });
+
+    let mut texture = None;
+    let desc = windows::Win32::Graphics::Direct3D11::D3D11_TEXTURE2D_DESC {
+        Width: 1920,
+        Height: 1080,
+        MipLevels: 1,
+        ArraySize: 1,
+        Format: windows::Win32::Graphics::Dxgi::Common::DXGI_FORMAT_R8G8B8A8_UNORM_SRGB,
+        SampleDesc: windows::Win32::Graphics::Dxgi::Common::DXGI_SAMPLE_DESC {
+            Count: 1,
+            Quality: 0,
+        },
+        Usage: windows::Win32::Graphics::Direct3D11::D3D11_USAGE_DEFAULT,
+        BindFlags: windows::Win32::Graphics::Direct3D11::D3D11_BIND_SHADER_RESOURCE.0 as u32,
+        CPUAccessFlags: windows::Win32::Graphics::Dxgi::Common::DXGI_CPU_ACCESS_NONE,
+        MiscFlags: 0,
+    };
+    let data = windows::Win32::Graphics::Direct3D11::D3D11_SUBRESOURCE_DATA {
+        pSysMem: data.as_ptr() as _,
+        SysMemPitch: 1920 * 4,
+        SysMemSlicePitch: 0,
+    };
+    unsafe {
+        device.CreateTexture2D(
+            &raw const desc,
+            Some(&raw const data),
+            Some(&raw mut texture),
+        )
+    }
+    .unwrap();
+    texture.unwrap()
+}
+
+fn main() {
+    let device = setup();
+
+    #[cfg(target_os = "linux")]
+    compile_error!("Linux is currently unsupported in this example");
+    #[cfg(windows)]
+    let session: Session<nvenc::session::NeedsConfig> = Session::open_dx(&device).unwrap();
+    assert!(
+        session
+            .get_encode_codecs()
+            .unwrap()
+            .contains(&NV_ENC_CODEC_H264_GUID)
+    );
+    assert!(
+        session
+            .get_encode_presets(NV_ENC_CODEC_H264_GUID)
+            .unwrap()
+            .contains(&NV_ENC_PRESET_P3_GUID)
+    );
+    let (session, mut config) = session
+        .get_encode_preset_config_ex(
+            NV_ENC_CODEC_H264_GUID,
+            NV_ENC_PRESET_P3_GUID,
+            nvenc::sys::enums::NVencTuningInfo::LowLatency,
+        )
+        .unwrap();
+
+    let texture = image(&device);
+
+    config.preset_cfg.rc_params.rate_control_mode = nvenc::sys::enums::NVencParamsRcMode::VBR;
+    config.preset_cfg.rc_params.average_bit_rate = 10_000_000;
+    config.preset_cfg.gop_len = 0xffffffff;
+    config.preset_cfg.frame_interval_p = 1;
+    println!("P-Frames: {}", config.preset_cfg.frame_interval_p);
+    println!("Bitrate: {}", config.preset_cfg.rc_params.average_bit_rate);
+
+    let init_params = InitParams {
+        encode_guid: NV_ENC_CODEC_H264_GUID,
+        preset_guid: NV_ENC_PRESET_P3_GUID,
+        aspect_ratio: [16, 9],
+        encode_config: &mut config.preset_cfg,
+        tuning_info: nvenc::sys::enums::NVencTuningInfo::LowLatency,
+        buffer_format: nvenc::sys::enums::NVencBufferFormat::ARGB,
+        frame_rate: [30, 1],
+        resolution: [1920, 1080],
+        enable_ptd: true,
+        max_encoder_resolution: [0, 0],
+    };
+
+    println!("FPS: 30");
+    println!("Len: 600 frames");
+    println!("Expected time: {}", 600 / 30);
+    println!("Codec: H264");
+    println!("Tuning Info {:?}:", init_params.tuning_info);
+
+    let encoder = session.init_encoder(init_params).unwrap();
+    let registered = encoder
+        .register_resource_dx11(&texture, nvenc::sys::enums::NVencBufferFormat::ARGB, 0)
+        .unwrap();
+
+    let (processed, to_use) = std::sync::mpsc::sync_channel::<BitStream>(2);
+    let (re_use, to_process) = std::sync::mpsc::sync_channel::<BitStream>(2);
+    processed
+        .send(encoder.create_bitstream_buffer().unwrap())
+        .unwrap();
+    processed
+        .send(encoder.create_bitstream_buffer().unwrap())
+        .unwrap();
+
+    let handle = std::thread::spawn({
+        move || {
+            let mut out = File::create("output.h264").unwrap();
+
+            while let Ok(output) = to_process.recv() {
+                let lock = output.try_lock(true).unwrap();
+                out.write_all(lock.as_slice()).unwrap();
+                drop(lock);
+                if let Err(_) = processed.send(output) {
+                    break;
+                }
+            }
+        }
+    });
+
+    let instant = Instant::now();
+    let mut i = 0;
+    while i < 600 {
+        if let Ok(output) = to_use.recv() {
+            encoder
+                .encode_picture(
+                    &registered,
+                    &output,
+                    i,
+                    instant.duration_since(Instant::now()).as_millis() as u64,
+                    nvenc::sys::enums::NVencBufferFormat::ARGB,
+                    nvenc::sys::enums::NVencPicStruct::Frame,
+                    nvenc::sys::enums::NVencPicType::P,
+                    None,
+                )
+                .unwrap();
+            re_use.send(output).unwrap();
+            i += 1;
+        }
+    }
+
+    drop(to_use);
+    drop(re_use);
+    handle.join().unwrap();
+}

vendor/nvenc/src/lib.rs

@@ -0,0 +1,86 @@
+#![doc = include_str!("../README.md")]
+
+use std::{mem::MaybeUninit, sync::OnceLock};
+
+use libloading::Library;
+
+use crate::sys::{
+    function_table::NVencFunctionList,
+    result::{NVencError, NVencResult},
+    version::NVENC_API_LIST_VERSION,
+};
+
+mod safe;
+pub use safe::*;
+/// Contains the original C Types, functions, enums, and constants
+pub mod sys;
+
+#[cfg(all(target_arch = "x86_64", target_os = "windows"))]
+pub const NVENC_DLL: &str = "nvEncodeAPI64.dll";
+#[cfg(all(target_arch = "x86", target_os = "windows"))]
+pub const NVENC_DLL: &str = "nvEncodeAPI.dll";
+
+#[cfg(target_os = "linux")]
+/// Platform specific DLL name, `libnvidia-encode.so.1` on Linux, `nvEncodeAPI64.dll` on Windows
+pub const NVENC_DLL: &str = "libnvidia-encode.so.1";
+
+#[cfg(all(target_arch = "x86", windows))]
+#[macro_export]
+macro_rules! stdcall {
+        (fn $args:tt $(-> $ret:tt)?) => { unsafe extern "stdcall" fn $args $(-> $ret)? };
+}
+
+#[doc(hidden)]
+#[cfg(not(all(target_arch = "x86", windows)))]
+#[macro_export]
+macro_rules! stdcall {
+        (fn $args:tt $(-> $ret:ty)?) => { unsafe extern "C" fn $args $(-> $ret)? };
+}
+
+pub(crate) static LIBRARY: OnceLock<NVENCLibrary> = OnceLock::new();
+
+/// Struct containing the library handle, init and get_max_version number functions
+pub struct NVENCLibrary {
+    #[allow(unused)]
+    // Lib must stay alive for nvenc to be used
+    lib: Library,
+    init: stdcall!(fn(list: *mut MaybeUninit<NVencFunctionList>) -> NVencResult),
+    get_max_version: stdcall!(fn(version: *mut u32) -> NVencResult),
+}
+
+/// Attempt to init NVENC, returns an error if the library or loading functions cannot be found
+pub fn nvenc_init() -> Result<&'static NVENCLibrary, libloading::Error> {
+    if let Some(lib) = LIBRARY.get() {
+        Ok(lib)
+    } else {
+        let lib = unsafe { Library::new(NVENC_DLL) }?;
+        let init: stdcall!(fn(function_list: *mut MaybeUninit<NVencFunctionList>) -> NVencResult) =
+            *unsafe { lib.get(b"NvEncodeAPICreateInstance") }?;
+        let get_max_version: stdcall!(fn(version: *mut u32) -> NVencResult) =
+            *unsafe { lib.get(b"NvEncodeAPIGetMaxSupportedVersion") }?;
+
+        Ok(LIBRARY.get_or_init(|| NVENCLibrary {
+            lib,
+            init,
+            get_max_version,
+        }))
+    }
+}
+
+impl NVENCLibrary {
+    /// Create a new instance of the NVencFunctionList,
+    pub fn create_instance(&self) -> Result<NVencFunctionList, NVencError> {
+        let mut list = MaybeUninit::zeroed();
+        unsafe { *(list.as_mut_ptr() as *mut u32) = NVENC_API_LIST_VERSION };
+        unsafe { (self.init)(&raw mut list) }.into_error().unwrap();
+        Ok(unsafe { list.assume_init() })
+    }
+
+    pub fn get_max_version(&self) -> Result<u32, NVencError> {
+        let mut version = 0;
+        unsafe { (self.get_max_version)(&raw mut version) }.into_error()?;
+        let minor = version & 0x0F;
+        let version = (version >> 4) | minor << 28;
+        Ok(version)
+    }
+}

vendor/nvenc/src/safe/bitstream.rs

@@ -0,0 +1,53 @@
+use std::{ffi::c_void, sync::Arc};
+
+use crate::{safe::encoder::EncoderInternal, sys::result::NVencError};
+
+pub struct BitStream {
+    pub(crate) buffer: *mut c_void,
+    pub(crate) encoder: Arc<EncoderInternal>,
+}
+
+impl Drop for BitStream {
+    fn drop(&mut self) {
+        println!("Dropping bitstream buffer");
+        self.encoder.destroy_bitstream_buffer(self.buffer).unwrap();
+    }
+}
+
+unsafe impl Send for BitStream {}
+
+impl BitStream {
+    /// Attempts to lock the bit stream, if `wait` is true it will wait
+    /// otherwise a `LockBusy` Error may be returned, in which case the
+    /// client should retry in a few milliseconds
+    pub fn try_lock(&self, wait: bool) -> Result<BitStreamLockGuard<'_>, NVencError> {
+        let lock = self.encoder.lock_bit_stream_buffer(self.buffer, wait)?;
+        Ok(BitStreamLockGuard {
+            buffer: self,
+            data_ptr: lock.bitstream_buffer,
+            data_len: lock.bitstream_size_in_bytes,
+        })
+    }
+}
+
+/// Holds a reference to the `BitStream` and holds the data and associated fields
+pub struct BitStreamLockGuard<'a> {
+    buffer: &'a BitStream,
+    data_ptr: *mut c_void,
+    data_len: u32,
+}
+
+impl BitStreamLockGuard<'_> {
+    pub fn as_slice(&self) -> &[u8] {
+        unsafe { std::slice::from_raw_parts(self.data_ptr as _, self.data_len as _) }
+    }
+}
+
+impl<'a> Drop for BitStreamLockGuard<'a> {
+    fn drop(&mut self) {
+        self.buffer
+            .encoder
+            .unlock_bit_stream_buffer(self.buffer.buffer)
+            .unwrap();
+    }
+}

vendor/nvenc/src/safe/encoder.rs

@@ -0,0 +1,517 @@
+use std::ffi::{CStr, c_void};
+use std::marker::PhantomData;
+use std::mem::ManuallyDrop;
+use std::sync::Arc;
+use std::{mem::MaybeUninit, ptr::NonNull};
+
+#[cfg(windows)]
+use windows::Win32::Graphics::Direct3D11::ID3D11Texture2D;
+
+use crate::input_buffer::InputBuffer;
+use crate::safe::bitstream::BitStream;
+use crate::sys::enums::{
+    NVencBufferFormat, NVencBufferUsage, NVencInputResourceType, NVencMemoryHeap, NVencPicStruct,
+    NVencPicType,
+};
+use crate::sys::structs::{
+    Guid, NV_ENC_CREATE_INPUT_BUFFER_VER, NV_ENC_LOCK_INPUT_BUFFER_VER, NVencCodecPicParams,
+    NVencCreateInputBuffer, NVencLockInputBuffer, NVencPicParamsH264, NVencRegisterResource,
+};
+use crate::sys::{
+    enums::{NVencPicFlags, NVencTuningInfo},
+    function_table::NVencFunctionList,
+    result::NVencError,
+    structs::{
+        NV_ENC_CONFIG_VER, NV_ENC_CREATE_BITSTREAM_BUFFER_VER, NV_ENC_LOCK_BITSTREAM_VER,
+        NV_ENC_MAP_INPUT_RESOURCE_VER, NV_ENC_PIC_PARAMS_VER, NV_ENC_PRESET_CONFIG_VER,
+        NV_ENC_REGISTER_RESOURCE_VER, NVencCreateBitstreamBuffer, NVencInitializeParams,
+        NVencLockBitStream, NVencPicParams, NVencPresetConfig,
+    },
+};
+
+pub struct Encoder {
+    pub(crate) encoder: Arc<EncoderInternal>,
+    pub(crate) marker: PhantomData<*mut ()>,
+}
+
+pub trait EncoderInput {
+    #[doc(hidden)]
+    fn as_ptr(&self) -> *mut c_void;
+
+    fn pitch(&self) -> u32;
+    fn height(&self) -> u32;
+    fn width(&self) -> u32;
+}
+
+impl EncoderInput for RegisteredResource {
+    fn as_ptr(&self) -> *mut c_void {
+        self.mapped
+    }
+
+    fn pitch(&self) -> u32 {
+        self.pitch
+    }
+
+    fn height(&self) -> u32 {
+        self.height
+    }
+
+    fn width(&self) -> u32 {
+        self.width
+    }
+}
+
+impl EncoderInput for InputBuffer {
+    fn as_ptr(&self) -> *mut c_void {
+        self.buffer
+    }
+
+    fn pitch(&self) -> u32 {
+        self.width
+    }
+
+    fn height(&self) -> u32 {
+        self.height
+    }
+
+    fn width(&self) -> u32 {
+        self.width
+    }
+}
+
+impl Encoder {
+    #[cfg(windows)]
+    /// Registers a DX11 texture as an nvenc input resource
+    pub fn register_resource_dx11(
+        &self,
+        resource: &ID3D11Texture2D,
+        format: NVencBufferFormat,
+        pitch: u32,
+    ) -> Result<RegisteredResource, NVencError> {
+        self.encoder.register_resource_dx(resource, format, pitch)
+    }
+
+    /// # Safety
+    /// `resource` must not be null
+    /// `ty` and `format` should match the original buffer
+    pub unsafe fn register_resource_raw(
+        &self,
+        resource: *mut c_void,
+        format: NVencBufferFormat,
+        usage: NVencBufferUsage,
+        ty: NVencInputResourceType,
+        resolution: [u32; 2],
+        pitch: u32,
+    ) -> Result<*mut c_void, NVencError> {
+        unsafe {
+            self.encoder
+                .register_resource_raw(resource, format, usage, ty, resolution, pitch)
+        }
+    }
+
+    /// Takes an encoder inout, and outputs a bit stream that can be read back
+    pub fn encode_picture<I: EncoderInput>(
+        &self,
+        input: &I,
+        output: &BitStream,
+        frame_count: usize,
+        timestamp: u64,
+        format: NVencBufferFormat,
+        pic_struct: NVencPicStruct,
+        ty: NVencPicType,
+        codec_params: Option<CodecPicParams>,
+    ) -> Result<(), NVencError> {
+        self.encoder.encode_picture(
+            input,
+            output,
+            frame_count,
+            timestamp,
+            format,
+            pic_struct,
+            ty,
+            codec_params,
+        )
+    }
+
+    /// Ends the encoder session
+    pub fn end_encode(&self) -> Result<(), NVencError> {
+        self.encoder.end_encode()
+    }
+
+    /// Creates a bitstream bfufer that can be used for output storage
+    pub fn create_bitstream_buffer(&self) -> Result<BitStream, NVencError> {
+        self.encoder.create_bitstream_buffer()
+    }
+
+    pub fn create_input_buffer(
+        &self,
+        width: u32,
+        height: u32,
+        memory_heap: NVencMemoryHeap,
+        format: NVencBufferFormat,
+    ) -> Result<InputBuffer, NVencError> {
+        Ok(InputBuffer {
+            encoder: self.encoder.clone(),
+            buffer: self
+                .encoder
+                .create_input_buffer(width, height, memory_heap, format)?,
+            width,
+            height,
+        })
+    }
+}
+
+pub(crate) struct EncoderInternal {
+    pub(super) encoder: NonNull<c_void>,
+    pub(super) function_list: NVencFunctionList,
+}
+
+/// The Nvidia encoder is technically thread-safe
+unsafe impl Send for EncoderInternal {}
+
+/// The Nvidia encoder handles syncing via `lock_bit_stream` which is all that is allowed to be Send
+unsafe impl Sync for EncoderInternal {}
+
+impl Drop for EncoderInternal {
+    fn drop(&mut self) {
+        println!("Dropping encoder, this should happen last");
+        unsafe { (self.function_list.nvenc_destroy_encoder)(self.encoder.as_ptr()) };
+    }
+}
+
+impl EncoderInternal {
+    pub(crate) fn get_encode_preset_config_ex(
+        &self,
+        codec: Guid,
+        preset: Guid,
+        tuning_info: NVencTuningInfo,
+    ) -> Result<NVencPresetConfig, NVencError> {
+        let mut config: std::mem::MaybeUninit<NVencPresetConfig> = std::mem::MaybeUninit::zeroed();
+        unsafe { &mut *config.as_mut_ptr() }.version = NV_ENC_PRESET_CONFIG_VER;
+        unsafe { &mut *config.as_mut_ptr() }.preset_cfg.version = NV_ENC_CONFIG_VER;
+        unsafe {
+            (self.function_list.nvenc_get_encode_preset_config_ex)(
+                self.encoder.as_ptr(),
+                codec,
+                preset,
+                tuning_info,
+                &raw mut config,
+            )
+            .into_error()?
+        };
+
+        Ok(unsafe { config.assume_init() })
+    }
+
+    pub(crate) fn init_encoder(
+        &self,
+        mut init_params: NVencInitializeParams,
+    ) -> Result<(), NVencError> {
+        unsafe {
+            (self.function_list.nvenc_initialize_encoder)(
+                self.encoder.as_ptr(),
+                &raw mut init_params,
+            )
+        }
+        .into_error()?;
+        Ok(())
+    }
+
+    #[cfg(windows)]
+    pub fn register_resource_dx(
+        self: &Arc<EncoderInternal>,
+        resource: &ID3D11Texture2D,
+        format: NVencBufferFormat,
+        pitch: u32,
+    ) -> Result<RegisteredResource, NVencError> {
+        use windows::Win32::Graphics::Direct3D11::D3D11_TEXTURE2D_DESC;
+        use windows::core::Interface;
+
+        let mut desc = D3D11_TEXTURE2D_DESC::default();
+        unsafe { resource.GetDesc(&raw mut desc) };
+
+        let registered = unsafe {
+            self.register_resource_raw(
+                resource.as_raw(),
+                NVencBufferFormat::Undefined,
+                NVencBufferUsage::Image,
+                NVencInputResourceType::DirectX,
+                [desc.Width, desc.Height],
+                pitch,
+            )?
+        };
+
+        let mapped = unsafe { self.map_input_resource_raw(registered, format)? };
+
+        Ok(RegisteredResource {
+            encoder: self.clone(),
+            pitch,
+            width: desc.Width,
+            height: desc.Height,
+            registered,
+            mapped,
+        })
+    }
+
+    pub unsafe fn map_input_resource_raw(
+        &self,
+        resource: *mut c_void,
+        format: NVencBufferFormat,
+    ) -> Result<*mut c_void, NVencError> {
+        let mut map: crate::sys::structs::NVencMapInputResource = unsafe { std::mem::zeroed() };
+        map.version = NV_ENC_MAP_INPUT_RESOURCE_VER;
+        map.registered_resource = resource;
+        map.mapped_buffer_format = format;
+
+        unsafe {
+            (self.function_list.nvenc_map_input_resource)(self.encoder.as_ptr(), &raw mut map)
+        }
+        .into_error()?;
+
+        Ok(map.mapped_resource)
+    }
+
+    pub unsafe fn register_resource_raw(
+        &self,
+        resource: *mut c_void,
+        format: NVencBufferFormat,
+        usage: NVencBufferUsage,
+        ty: NVencInputResourceType,
+        resolution: [u32; 2],
+        pitch: u32,
+    ) -> Result<*mut c_void, NVencError> {
+        let mut register_resource: NVencRegisterResource = unsafe { std::mem::zeroed() };
+        register_resource.buffer_format = format;
+        register_resource.buffer_usage = usage;
+        register_resource.resource_type = ty;
+        register_resource.version = NV_ENC_REGISTER_RESOURCE_VER;
+        register_resource.width = resolution[0];
+        register_resource.height = resolution[1];
+        register_resource.pitch = pitch;
+        register_resource.sub_resource_index = 0;
+        register_resource.resource_to_register = resource;
+        unsafe {
+            (self.function_list.nvenc_register_resource)(
+                self.encoder.as_ptr(),
+                &raw mut register_resource,
+            )
+            .into_error()
+        }?;
+        Ok(register_resource.registered_resource)
+    }
+
+    pub unsafe fn unmap_input_resource(
+        &self,
+        mapped_resource: *mut c_void,
+    ) -> Result<(), NVencError> {
+        unsafe {
+            (self.function_list.nvenc_unmap_input_resource)(self.encoder.as_ptr(), mapped_resource)
+        }
+        .into_error()
+    }
+
+    pub unsafe fn unregister_resource(
+        &self,
+        registered_resource: *mut c_void,
+    ) -> Result<(), NVencError> {
+        unsafe {
+            (self.function_list.nvenc_unregister_resource)(
+                self.encoder.as_ptr(),
+                registered_resource,
+            )
+        }
+        .into_error()
+    }
+
+    pub fn create_input_buffer(
+        &self,
+        width: u32,
+        height: u32,
+        memory_heap: NVencMemoryHeap,
+        format: NVencBufferFormat,
+    ) -> Result<*mut c_void, NVencError> {
+        let mut input = NVencCreateInputBuffer {
+            version: NV_ENC_CREATE_INPUT_BUFFER_VER,
+            width: width,
+            height: height,
+            memory_heap,
+            buffer_fmt: format,
+            rsvd: 0,
+            input_buffer: std::ptr::null_mut(),
+            p_sys_mem_buffer: std::ptr::null_mut(),
+            rsvd1: unsafe { std::mem::zeroed() },
+            rsvd2: unsafe { std::mem::zeroed() },
+        };
+        unsafe {
+            (self.function_list.nvenc_create_input_buffer)(self.encoder.as_ptr(), &raw mut input)
+                .into_error()?
+        };
+
+        Ok(input.input_buffer)
+    }
+
+    pub fn destroy_input_buffer(&self, buffer: *mut c_void) -> Result<(), NVencError> {
+        unsafe { (self.function_list.nvenc_destroy_input_buffer)(self.encoder.as_ptr(), buffer) }
+            .into_error()
+    }
+
+    pub fn lock_input_buffer(&self, buffer: *mut c_void) -> Result<(*mut c_void, u32), NVencError> {
+        let mut lock = NVencLockInputBuffer {
+            version: NV_ENC_LOCK_INPUT_BUFFER_VER,
+            bitflags: 0,
+            input_buffer: buffer,
+            buffer_data_ptr: std::ptr::null_mut(),
+            pitch: 0,
+            rsvd1: unsafe { std::mem::zeroed() },
+            rsvd2: unsafe { std::mem::zeroed() },
+        };
+
+        unsafe {
+            (self.function_list.nvenc_lock_input_buffer)(self.encoder.as_ptr(), &raw mut lock)
+                .into_error()?;
+        }
+
+        Ok((lock.buffer_data_ptr, lock.pitch))
+    }
+
+    pub fn unlock_input_buffer(&self, locked_buffer: *mut c_void) -> Result<(), NVencError> {
+        unsafe {
+            (self.function_list.nvenc_unlock_input_buffer)(self.encoder.as_ptr(), locked_buffer)
+                .into_error()
+        }
+    }
+
+    pub fn encode_picture<I: EncoderInput>(
+        &self,
+        input: &I,
+        output: &BitStream,
+        frame_count: usize,
+        timestamp: u64,
+        format: NVencBufferFormat,
+        pic_struct: NVencPicStruct,
+        ty: NVencPicType,
+        codec_params: Option<CodecPicParams>,
+    ) -> Result<(), NVencError> {
+        let mut params: MaybeUninit<NVencPicParams> = MaybeUninit::zeroed();
+        let sys_codec = match codec_params {
+            None => NVencCodecPicParams { rsvd: [0; 256] },
+            Some(CodecPicParams::H264(codec)) => NVencCodecPicParams {
+                h264_pic_params: ManuallyDrop::new(codec),
+            },
+        };
+        unsafe { &mut *params.as_mut_ptr() }.version = NV_ENC_PIC_PARAMS_VER;
+        unsafe { &mut *params.as_mut_ptr() }.input_width = input.width();
+        unsafe { &mut *params.as_mut_ptr() }.input_height = input.height();
+        unsafe { &mut *params.as_mut_ptr() }.input_pitch = input.pitch();
+        unsafe { &mut *params.as_mut_ptr() }.output_bitstream = output.buffer;
+        unsafe { &mut *params.as_mut_ptr() }.input_buffer = input.as_ptr();
+        unsafe { &mut *params.as_mut_ptr() }.buffer_format = format;
+        unsafe { &mut *params.as_mut_ptr() }.picture_struct = pic_struct;
+        // [本项目补丁] 只设 picture_type=IDR 不足以让 NVENC 真正输出 IDR 切片，
+        // 必须同时置 encode_pic_flags |= NV_ENC_PIC_FLAG_FORCEIDR。
+        //
+        // 上游 0.1.0 未设置该标志，导致运行期请求关键帧时编码器静默忽略、
+        // 继续输出 P 帧（实测：picture_type=IDR 但输出 NAL type=1）。
+        // 首帧之所以"看起来正常"，是因为 frame_idx==0 本来就强制 IDR，与本字段无关。
+        //
+        // 语义区分：IntraRefresh 走 ForceIntra，其余 IDR 类走 ForceIDR。
+        // 必须在 `picture_type = ty` 之前计算，否则 ty 已被移动。
+        let pic_flags = match &ty {
+            NVencPicType::IDR => NVencPicFlags::ForceIDR as u32,
+            NVencPicType::IntraRefresh => NVencPicFlags::ForceIntra as u32,
+            _ => 0,
+        };
+        unsafe { &mut *params.as_mut_ptr() }.picture_type = ty;
+        unsafe { &mut *params.as_mut_ptr() }.encode_pic_flags = pic_flags;
+        unsafe { &mut *params.as_mut_ptr() }.frame_idx = frame_count as u32;
+        unsafe { &mut *params.as_mut_ptr() }.input_time_stamp = timestamp;
+        unsafe { &mut *params.as_mut_ptr() }.codec_pic_params = sys_codec;
+        match unsafe {
+            (self.function_list.nvenc_encode_picture)(self.encoder.as_ptr(), &raw mut params)
+                .into_error()
+        } {
+            Err(err) => {
+                let ptr =
+                    unsafe { (self.function_list.nvenc_get_last_error)(self.encoder.as_ptr()) };
+                println!("{:?}", unsafe { CStr::from_ptr(ptr) });
+                Err(err)
+            }
+            Ok(()) => Ok(()),
+        }
+    }
+
+    pub fn end_encode(&self) -> Result<(), NVencError> {
+        let mut params: MaybeUninit<NVencPicParams> = MaybeUninit::zeroed();
+        unsafe { &mut *params.as_mut_ptr() }.version = NV_ENC_PIC_PARAMS_VER;
+        unsafe { &mut *params.as_mut_ptr() }.encode_pic_flags = NVencPicFlags::Eos as u32;
+        unsafe {
+            (self.function_list.nvenc_encode_picture)(self.encoder.as_ptr(), &raw mut params)
+                .into_error()
+        }?;
+        Ok(())
+    }
+
+    pub(crate) fn lock_bit_stream_buffer(
+        &self,
+        buffer: *mut c_void,
+        wait: bool,
+    ) -> Result<NVencLockBitStream, NVencError> {
+        let mut lock: MaybeUninit<NVencLockBitStream> = MaybeUninit::zeroed();
+        unsafe { &mut *lock.as_mut_ptr() }.version = NV_ENC_LOCK_BITSTREAM_VER;
+        unsafe { &mut *lock.as_mut_ptr() }.output_bit_stream = buffer;
+        unsafe { &mut *lock.as_mut_ptr() }
+            .bit_fields
+            .set_do_not_wait(!wait);
+        unsafe { (self.function_list.nvenc_lock_bit_stream)(self.encoder.as_ptr(), &raw mut lock) }
+            .into_error()?;
+        Ok(unsafe { lock.assume_init() })
+    }
+
+    pub(crate) fn unlock_bit_stream_buffer(&self, buffer: *mut c_void) -> Result<(), NVencError> {
+        unsafe { (self.function_list.nvenc_unlock_bit_stream)(self.encoder.as_ptr(), buffer) }
+            .into_error()
+    }
+
+    pub fn create_bitstream_buffer(self: &Arc<Self>) -> Result<BitStream, NVencError> {
+        let mut params: NVencCreateBitstreamBuffer = unsafe { std::mem::zeroed() };
+        params.version = NV_ENC_CREATE_BITSTREAM_BUFFER_VER;
+        unsafe {
+            (self.function_list.nvenc_create_bit_stream_buffer)(
+                self.encoder.as_ptr(),
+                &raw mut params,
+            )
+        }
+        .into_error()?;
+        Ok(BitStream {
+            buffer: params.bitstream_buffer,
+            encoder: self.clone(),
+        })
+    }
+
+    pub(crate) fn destroy_bitstream_buffer(&self, buffer: *mut c_void) -> Result<(), NVencError> {
+        unsafe {
+            (self.function_list.nvenc_destory_bit_stream_buffer)(self.encoder.as_ptr(), buffer)
+        }
+        .into_error()
+    }
+}
+
+pub enum CodecPicParams {
+    H264(NVencPicParamsH264),
+}
+
+pub struct RegisteredResource {
+    registered: *mut c_void,
+    mapped: *mut c_void,
+    pitch: u32,
+    width: u32,
+    height: u32,
+    encoder: Arc<EncoderInternal>,
+}
+
+impl Drop for RegisteredResource {
+    fn drop(&mut self) {
+        unsafe { self.encoder.unmap_input_resource(self.mapped).unwrap() };
+        unsafe { self.encoder.unregister_resource(self.registered).unwrap() };
+    }
+}

vendor/nvenc/src/safe/input_buffer.rs

@@ -0,0 +1,60 @@
+use std::{ffi::c_void, sync::Arc};
+
+use crate::{encoder::EncoderInternal, sys::result::NVencError};
+
+pub struct InputBuffer {
+    pub(crate) encoder: Arc<EncoderInternal>,
+    pub(crate) buffer: *mut c_void,
+    pub(crate) width: u32,
+    pub(crate) height: u32,
+}
+
+impl InputBuffer {
+    pub fn lock(&self) -> Result<InputBufferLock<'_>, NVencError> {
+        let (lock_ptr, pitch) = self.encoder.lock_input_buffer(self.buffer)?;
+        Ok(InputBufferLock {
+            input_buffer: self,
+            lock_ptr,
+            pitch,
+        })
+    }
+}
+
+impl Drop for InputBuffer {
+    fn drop(&mut self) {
+        self.encoder.destroy_input_buffer(self.buffer).unwrap()
+    }
+}
+
+pub struct InputBufferLock<'a> {
+    input_buffer: &'a InputBuffer,
+    lock_ptr: *mut c_void,
+    pitch: u32,
+}
+
+impl InputBufferLock<'_> {
+    pub unsafe fn data_ptr(&self) -> *mut u8 {
+        self.lock_ptr as _
+    }
+
+    pub fn width(&self) -> u32 {
+        self.input_buffer.width
+    }
+
+    pub fn height(&self) -> u32 {
+        self.input_buffer.height
+    }
+
+    pub fn pitch(&self) -> u32 {
+        self.pitch
+    }
+}
+
+impl Drop for InputBufferLock<'_> {
+    fn drop(&mut self) {
+        self.input_buffer
+            .encoder
+            .unlock_input_buffer(self.lock_ptr)
+            .unwrap();
+    }
+}

vendor/nvenc/src/safe/mod.rs

@@ -0,0 +1,8 @@
+/// Contains the type for the safe BitStream buffer wrapper
+pub mod bitstream;
+/// Wrapper for the NVEncoder after creating an active session
+pub mod encoder;
+/// Wrapper around an NVenc input buffer
+pub mod input_buffer;
+/// Type-state wrapper around session initialization
+pub mod session;

vendor/nvenc/src/safe/session.rs

@@ -0,0 +1,198 @@
+use std::{marker::PhantomData, sync::Arc};
+
+use crate::{
+    encoder::{Encoder, EncoderInternal},
+    sys::{
+        enums::{NVencBufferFormat, NVencDeviceType, NVencTuningInfo},
+        result::NVencError,
+        structs::{
+            Guid, NV_ENC_INITIALIZE_PARAMS_VER, NV_ENC_OPEN_ENCODE_SESSION_EX_PARAMS_VER,
+            NVencConfig, NVencInitializeParams, NVencOpenEncodeSessionExParams, NVencPresetConfig,
+        },
+        version::NVENC_API_VERSION,
+    },
+};
+
+pub struct Session<T> {
+    encoder: Arc<EncoderInternal>,
+    p: PhantomData<T>,
+}
+
+pub struct NeedsConfig;
+
+pub struct NeedsInit;
+
+#[cfg(windows)]
+use windows::core::Interface;
+
+impl Session<NeedsConfig> {
+    #[cfg(windows)]
+    pub fn open_dx(device: &impl Interface) -> Result<Self, NVencError> {
+        let lib = crate::nvenc_init().unwrap();
+        let function_list = lib.create_instance()?;
+        let mut session_params: NVencOpenEncodeSessionExParams = unsafe { std::mem::zeroed() };
+        session_params.version = NV_ENC_OPEN_ENCODE_SESSION_EX_PARAMS_VER;
+        session_params.device_type = NVencDeviceType::DirectX;
+        session_params.api_version = NVENC_API_VERSION;
+        session_params.device = device.as_raw();
+        let mut encoder = std::ptr::null_mut();
+        unsafe {
+            (function_list.nvenc_open_encode_session_ex)(&raw mut session_params, &raw mut encoder)
+                .into_error()
+        }?;
+        assert!(!encoder.is_null());
+        let encoder = EncoderInternal {
+            encoder: unsafe { std::ptr::NonNull::new_unchecked(encoder) },
+            function_list,
+        };
+        Ok(Self {
+            encoder: Arc::new(encoder),
+            p: PhantomData,
+        })
+    }
+
+    pub fn open_gl() -> Result<Self, NVencError> {
+        let lib = crate::nvenc_init().unwrap();
+        let function_list = lib.create_instance()?;
+        let mut session_params: NVencOpenEncodeSessionExParams = unsafe { std::mem::zeroed() };
+        session_params.version = NV_ENC_OPEN_ENCODE_SESSION_EX_PARAMS_VER;
+        session_params.device_type = NVencDeviceType::OpenGL;
+        session_params.api_version = NVENC_API_VERSION;
+        session_params.device = std::ptr::null_mut();
+
+        let mut encoder = std::ptr::null_mut();
+        unsafe {
+            (function_list.nvenc_open_encode_session_ex)(&raw mut session_params, &raw mut encoder)
+                .into_error()
+        }?;
+        assert!(!encoder.is_null());
+        let encoder = EncoderInternal {
+            encoder: unsafe { std::ptr::NonNull::new_unchecked(encoder) },
+            function_list,
+        };
+        Ok(Self {
+            encoder: Arc::new(encoder),
+            p: PhantomData,
+        })
+    }
+
+    pub fn get_encode_codecs(&self) -> Result<Box<[Guid]>, NVencError> {
+        let mut count = 0;
+        unsafe {
+            (self.encoder.function_list.nvenc_get_encoder_guid_count)(
+                self.encoder.encoder.as_ptr(),
+                &raw mut count,
+            )
+            .into_error()
+        }?;
+        let mut array = vec![Guid::default(); count as usize];
+        unsafe {
+            (self.encoder.function_list.nvenc_get_encoder_guids)(
+                self.encoder.encoder.as_ptr(),
+                array.as_mut_ptr(),
+                count,
+                &raw mut count,
+            )
+        }
+        .into_error()?;
+        array.truncate(count as usize);
+        Ok(array.into())
+    }
+
+    pub fn get_encode_presets(&self, codec: Guid) -> Result<Box<[Guid]>, NVencError> {
+        let mut count = 0;
+        unsafe {
+            (self.encoder.function_list.nvenc_get_encode_preset_count)(
+                self.encoder.encoder.as_ptr(),
+                codec.clone(),
+                &raw mut count,
+            )
+            .into_error()
+        }?;
+        let mut array = vec![Guid::default(); count as usize];
+        unsafe {
+            (self.encoder.function_list.nvenc_get_encode_preset_guids)(
+                self.encoder.encoder.as_ptr(),
+                codec,
+                array.as_mut_ptr(),
+                count,
+                &raw mut count,
+            )
+        }
+        .into_error()?;
+        array.truncate(count as usize);
+        Ok(array.into())
+    }
+
+    pub fn get_encode_preset_config_ex(
+        self,
+        codec: Guid,
+        preset: Guid,
+        tuning_info: NVencTuningInfo,
+    ) -> Result<(Session<NeedsInit>, NVencPresetConfig), NVencError> {
+        self.encoder
+            .get_encode_preset_config_ex(codec, preset, tuning_info)
+            .map(|config| {
+                (
+                    Session {
+                        encoder: self.encoder,
+                        p: PhantomData,
+                    },
+                    config,
+                )
+            })
+    }
+}
+
+pub struct InitParams<'a> {
+    pub encode_guid: Guid,
+    pub preset_guid: Guid,
+    pub resolution: [u32; 2],
+    pub aspect_ratio: [u32; 2],
+    pub frame_rate: [u32; 2],
+    pub tuning_info: NVencTuningInfo,
+    pub buffer_format: NVencBufferFormat,
+    pub encode_config: &'a mut NVencConfig,
+    pub enable_ptd: bool,
+    pub max_encoder_resolution: [u32; 2],
+    // TODO: Support for async encoding and bit fields
+}
+
+impl Session<NeedsInit> {
+    pub fn init_encoder(self, init_params: InitParams) -> Result<Encoder, NVencError> {
+        // This sucks, lol
+        let raw_init_params = NVencInitializeParams {
+            encode_guid: init_params.encode_guid,
+            preset_guid: init_params.preset_guid,
+            encode_width: init_params.resolution[0],
+            encode_height: init_params.resolution[1],
+            dar_width: init_params.aspect_ratio[0],
+            dar_height: init_params.aspect_ratio[1],
+            frame_rate_num: init_params.frame_rate[0],
+            frame_rate_den: init_params.frame_rate[1],
+            tuning_info: init_params.tuning_info,
+            buffer_format: init_params.buffer_format,
+            encode_config: init_params.encode_config as _,
+            enable_ptd: init_params.enable_ptd as u32,
+            version: NV_ENC_INITIALIZE_PARAMS_VER,
+            enable_encode_async: 0,
+            bit_flags: crate::sys::structs::NVencInitializeParamsBitfields::new(),
+            priv_data_size: 0,
+            rsvd: 0,
+            priv_data: std::ptr::null_mut(),
+            max_encode_width: init_params.max_encoder_resolution[0],
+            max_encode_height: init_params.max_encoder_resolution[1],
+            max_me_hint_counts_per_block: [Default::default(), Default::default()],
+            num_state_buffers: 0,
+            output_stats_level: crate::sys::enums::NVencOutputStatsLevel::None,
+            rsvd1: unsafe { std::mem::zeroed() },
+            rsvd2: unsafe { std::mem::zeroed() },
+        };
+
+        self.encoder.init_encoder(raw_init_params)?;
+        Ok(Encoder {
+            encoder: self.encoder,
+            marker: PhantomData,
+        })
+    }
+}

vendor/nvenc/src/sys/enums.rs

@@ -0,0 +1,481 @@
+#[repr(C)]
+pub enum NVencParamsFrameFieldMode {
+    Frame = 0x01,
+    Field = 0x02,
+    MBAFF = 0x03,
+}
+
+#[repr(C)]
+pub enum NVencParamsRcMode {
+    ConstQP = 0x00,
+    VBR = 0x01,
+    CBR = 0x02,
+}
+
+#[repr(C)]
+pub enum NVencMultiPass {
+    Disabled = 0x00,
+    TwoPassQuarterResolution = 0x01,
+    TwoPassFullResolution = 0x02,
+}
+
+#[repr(C)]
+pub enum NVencStateRestoreType {
+    Full = 0x01,
+    RateControl = 0x02,
+    Encode = 0x03,
+}
+
+#[repr(C)]
+pub enum NVencOutputStatsLevel {
+    None = 0,
+    BlockLevel = 1,
+    RowLevel = 2,
+}
+
+#[repr(C)]
+pub enum NVencEmphasisMapLevel {
+    Level0 = 0x0,
+    Level1 = 0x1,
+    Level2 = 0x2,
+    Level3 = 0x3,
+    Level4 = 0x4,
+    Level5 = 0x5,
+}
+
+#[repr(C)]
+pub enum NVencQPMapMode {
+    Disabled = 0x0,
+    Emphasis = 0x1,
+    Delta = 0x2,
+    /// Currently unsupported as of NVENC 13.0
+    Map = 0x3,
+}
+
+#[repr(C)]
+pub enum NVencPicStruct {
+    Frame = 0x01,
+    FieldTopBottom = 0x02,
+    FieldBottomTop = 0x03,
+}
+
+#[repr(C)]
+pub enum NVencDisplayPicStruct {
+    Frame = 0x0,
+    FieldTopBottom = 0x1,
+    FieldBottomTop = 0x2,
+    Doubling = 0x3,
+    Tripling = 0x4,
+}
+
+#[repr(C)]
+pub enum NVencPicType {
+    P = 0x00,
+    B = 0x01,
+    IDR = 0x03,
+    BI = 0x04,
+    Skipped = 0x05,
+    IntraRefresh = 0x06,
+    NonRefP = 0x07,
+    Switch = 0x08,
+    UNKNOWN = 0xFF,
+}
+
+#[repr(C)]
+pub enum NVencMVPrecision {
+    Default = 0x00,
+    FullPel = 0x01,
+    HalfPel = 0x02,
+    QuarterPel = 0x03,
+}
+
+#[repr(C)]
+pub enum NVencBufferFormat {
+    Undefined = 0x00000000,
+    NV12 = 0x00000001,
+    YV12 = 0x00000010,
+    IYUV = 0x00000100,
+    YUV444 = 0x00001000,
+    YUV420_10Bit = 0x00010000,
+    YUV444_10Bit = 0x00100000,
+    ARGB = 0x01000000,
+    ARGB10 = 0x02000000,
+    AYUV = 0x04000000,
+    ABGR = 0x10000000,
+    ABGR10 = 0x20000000,
+    U8 = 0x40000000,
+    NV16 = 0x40000001,
+    P210 = 0x40000002,
+}
+
+#[repr(C)]
+pub enum NvencLevel {
+    AutoSelect = 0,
+}
+
+// TODO: Translate level macro
+#[repr(C)]
+pub enum H264Level {
+    H264_1 = 10,
+    H264_1b = 9,
+    H264_11 = 11,
+    H264_12 = 12,
+    H264_13 = 13,
+    H264_2 = 20,
+    H264_21 = 21,
+    H264_22 = 22,
+    H264_3 = 30,
+    H264_31 = 31,
+    H264_32 = 32,
+    H264_4 = 40,
+    H264_41 = 41,
+    H264_42 = 42,
+    H264_5 = 50,
+    H264_51 = 51,
+    H264_52 = 52,
+    H264_60 = 60,
+    H264_61 = 61,
+    H264_62 = 62,
+}
+
+#[repr(C)]
+pub enum HEVCLevel {
+    HEVC1 = 30,
+    HEVC2 = 60,
+    HEVC21 = 63,
+    HEVC3 = 90,
+    HEVC31 = 93,
+    HEVC4 = 120,
+    HEVC41 = 123,
+    HEVC5 = 150,
+    HEVC51 = 153,
+    HEVC52 = 156,
+    HEVC6 = 180,
+    HEVC61 = 183,
+    HEVC62 = 186,
+    HEVCMain = 0,
+    HEVCHigh = 1,
+}
+
+#[repr(C)]
+pub enum AV1Level {
+    // Also AV1_0
+    AV1_2 = 0,
+    // Also AV1_1
+    AV1_21 = 1,
+    AV1_22 = 2,
+    AV1_23 = 3,
+    AV1_3 = 4,
+    AV1_31 = 5,
+    AV1_32 = 6,
+    AV1_33 = 7,
+    AV1_4 = 8,
+    AV1_41 = 9,
+    AV1_42 = 10,
+    AV1_43 = 11,
+    AV1_5 = 12,
+    AV1_51 = 13,
+    AV1_52 = 14,
+    AV1_53 = 15,
+    AV1_6 = 16,
+    AV1_61 = 17,
+    AV1_62 = 18,
+    AV1_63 = 19,
+    AV1_7 = 20,
+    AV1_71 = 21,
+    AV1_72 = 22,
+    AV1_73 = 23,
+    AV1AutoSelect = 24,
+}
+
+#[repr(C)]
+pub enum NVencPicFlags {
+    ForceIntra = 0x1,
+    ForceIDR = 0x2,
+    OutputSpspps = 0x4,
+    Eos = 0x8,
+    DisableEncStateAdvance = 0x10,
+    OuputReconFrame = 0x20,
+}
+
+#[repr(C)]
+pub enum NVencMemoryHeap {
+    AutoSelect = 0,
+    VID = 1,
+    SystemCached = 2,
+    SystemUncached = 3,
+}
+
+#[repr(C)]
+pub enum NVencBFrameRefMode {
+    Disabled = 0x0,
+    Each = 0x1,
+    Middle = 0x2,
+}
+
+#[repr(C)]
+pub enum NVencH264EntropyCodingMode {
+    AutoSelect = 0x0,
+    Cabac = 0x1,
+    Cavlc = 0x2,
+}
+
+#[repr(C)]
+pub enum NVencH264BDirectMode {
+    Autoselect = 0x0,
+    Disable = 0x1,
+    Temporal = 0x2,
+    Spatial = 0x3,
+}
+
+#[repr(C)]
+pub enum NVencH264FMOMode {
+    AutoSelect = 0x0,
+    Enable = 0x1,
+    Disable = 0x2,
+}
+
+#[repr(C)]
+pub enum NVencH264AdaptiveTransformMode {
+    AutoSelect = 0x0,
+    Disable = 0x1,
+    Enable = 0x2,
+}
+
+#[repr(C)]
+pub enum NVencStereoPackingMode {
+    None = 0x0,
+    Checkerboard = 0x1,
+    ColInterleave = 0x2,
+    RowInterleave = 0x3,
+    SideBySide = 0x4,
+    TopBottm = 0x5,
+    FrameSeq = 0x6,
+}
+
+#[repr(C)]
+pub enum NVencInputResourceType {
+    DirectX = 0x0,
+    CudaDeivcePtr = 0x1,
+    CudaArray = 0x2,
+    OpenGLTex = 0x3,
+}
+
+#[repr(C)]
+pub enum NVencBufferUsage {
+    Image = 0x0,
+    MotionVector = 0x1,
+    BitStream = 0x2,
+    OutputRecon = 0x4,
+}
+
+#[repr(C)]
+#[derive(Clone)]
+pub enum NVencDeviceType {
+    DirectX = 0x0,
+    Cuda = 0x1,
+    OpenGL = 0x2,
+}
+
+#[repr(C)]
+pub enum NVencNumRefFrames {
+    AutoSelect = 0x0,
+    Frames1 = 0x1,
+    Frames2 = 0x2,
+    Frames3 = 0x3,
+    Frames4 = 0x4,
+    Frames5 = 0x5,
+    Frames6 = 0x6,
+    Frames7 = 0x7,
+}
+
+#[repr(C)]
+pub enum NVencTemporalFilterLevel {
+    Level0 = 0,
+    Level4 = 4,
+}
+
+#[repr(C)]
+pub enum NVencCaps {
+    NumMaxBFrames,
+    SupportedRateControlModes,
+    FieldEncoding,
+    MonoChrome,
+    FMO,
+    QPELMV,
+    BDirectMode,
+    CABAC,
+    AdaptiveTransform,
+    StereoMVC,
+    MaxTemporalLayers,
+    HierarchicalBFrames,
+    LevelMax,
+    LevelMin,
+    SeperateColorPlane,
+    WidthMax,
+    HeightMax,
+    TemporalSVC,
+    DynResChnage,
+    DynBitrateChange,
+    DynForceConstQP,
+    DynRcModeChange,
+    SubframeReadBack,
+    ConstrainedEncoding,
+    IntraRefresh,
+    CustomVBVBufSize,
+    DynamicSliceMode,
+    Invalidation,
+    PreProcSupport,
+    AsyncEncodeSupport,
+    MbNumMax,
+    MbPerSecMax,
+    YUV444Encode,
+    LoselessEncode,
+    SupportSao,
+    MeOnlyMode,
+    LookAhead,
+    TemporalAQ,
+    MaxLtrFrames,
+    SupportWeightedPrediction,
+    DynamicQueryEncoderCapacity,
+    BFrameRefMode,
+    EmphasisLevelMap,
+    WidthMin,
+    HeightMin,
+    MultipleRefFrames,
+    AlphaLayerEncoding,
+    NumEncoderEngines,
+    SingleSliceIntraRefresh,
+    DisableEncStateAdvance,
+    OutputReconSurface,
+    OutputBlockStats,
+    SupportTemporalFilter,
+    LookAheadLevel,
+    UndirectionalB,
+    MVHEVCEncode,
+    SupportYUV422Encode,
+    ExposedCount,
+}
+
+#[repr(C)]
+pub enum NVencHEVCCuSize {
+    AutoSelect = 0,
+    Size8x8 = 1,
+    Size16x16 = 2,
+    Size32x32 = 3,
+    Size64x64 = 4,
+}
+
+#[repr(C)]
+pub enum NVencAV1PartSize {
+    AutoSelect = 0,
+    Size4x4 = 1,
+    Size8x8 = 2,
+    Size16x16 = 3,
+    Size32x32 = 4,
+    Size64x64 = 5,
+}
+
+#[repr(C)]
+pub enum NVencVUIVideoFormat {
+    Component = 0,
+    Pal = 1,
+    NTSC = 2,
+    SeCam = 3,
+    Mac = 4,
+    Unspecified = 5,
+}
+
+#[repr(C)]
+pub enum NVencVUIColorPrimaries {
+    Undefined = 0,
+    BT709 = 1,
+    Unspecified = 2,
+    Reserved = 3,
+    BT470M = 4,
+    BT470BG = 5,
+    SMPTE170M = 6,
+    SMPTE240M = 7,
+    FIlm = 8,
+    BT2020 = 9,
+    SMPTE428 = 10,
+    SMPTE431 = 11,
+    SMPTE432 = 12,
+    JEDECP22 = 22,
+}
+
+#[repr(C)]
+pub enum NVencVUITransCharacteristics {
+    Undefined = 0,
+    BT709 = 1,
+    Unspecified = 2,
+    Reserved = 3,
+    BT470M = 4,
+    BT470BG = 5,
+    SMPTE170M = 6,
+    SMPTE240M = 7,
+    Linear = 8,
+    Log = 9,
+    LogSqrt = 10,
+    IEC61966_2_4 = 11,
+    SRGB = 13,
+    BT2020_10 = 14,
+    BT2020_12 = 15,
+    SMPTE2084 = 16,
+    SMPTE428 = 17,
+    AribStdB67 = 18,
+}
+
+#[repr(C)]
+pub enum NVencVUIMatrixCoeffs {
+    RGB = 0,
+    BT709 = 1,
+    Unspecified = 2,
+    Reserved = 3,
+    FCC = 4,
+    BT470BG = 5,
+    SMPTE170M,
+    SMPTE240M,
+    YCGCO = 8,
+    BT2020NCL = 9,
+    BT2020CL = 10,
+    SMPTE2085 = 11,
+}
+
+#[repr(C)]
+pub enum NVencLookAheadLevel {
+    Level0 = 0,
+    Level1 = 1,
+    Level2 = 2,
+    Level3 = 3,
+    AutoSelect = 15,
+}
+
+#[repr(C)]
+pub enum NVencBitDepth {
+    Invalid = 0,
+    Depth8 = 8,
+    Depth10 = 10,
+}
+
+#[derive(Debug)]
+#[repr(C)]
+pub enum NVencTuningInfo {
+    Undefined = 0,
+    HighQuality = 1,
+    LowLatency = 2,
+    UltraLowLatency = 3,
+    Lossless = 4,
+    UltraHighQuality = 5,
+    Count,
+}
+
+#[repr(C)]
+pub enum NVencSplitEncodeMode {
+    Audo = 0,
+    AutoForced = 1,
+    TwoForced = 2,
+    ThreeForced = 3,
+    FourForced = 4,
+    Disable = 15,
+}

vendor/nvenc/src/sys/function_table.rs

@@ -0,0 +1,214 @@
+use std::{ffi::c_char, mem::MaybeUninit, os::raw::c_void};
+
+use crate::{
+    stdcall,
+    sys::{
+        enums::{NVencBufferFormat, NVencTuningInfo},
+        result::NVencResult,
+        structs::{
+            Guid, NVencCapsParam, NVencCreateBitstreamBuffer, NVencCreateInputBuffer,
+            NVencInitializeParams, NVencLockBitStream, NVencLockInputBuffer, NVencMapInputResource,
+            NVencOpenEncodeSessionExParams, NVencPicParams, NVencPresetConfig,
+            NVencRegisterResource,
+        },
+    },
+};
+
+#[repr(C)]
+#[derive(Clone)]
+pub struct NVencFunctionList {
+    pub version: u32,
+    rsvd: u32,
+    #[deprecated]
+    nvenc_open_encode_session: NvencOpenEncodeSession,
+    pub nvenc_get_encoder_guid_count: NvencGetEncodeGuidCount,
+    nvenc_get_encoder_profile_guid_count: NvencGetEncodeProfileGuidCount,
+    nvenc_get_encoder_profile_guids: NvencGetEncodeProfileGuids,
+    pub nvenc_get_encoder_guids: NvencGetEncodeGuids,
+    nvenc_get_input_format_count: NvencGetInputFormatCount,
+    nvenc_get_input_formats: NvencGetInputFormats,
+    nvenc_get_encode_caps: NvencGetEncodeCaps,
+    pub nvenc_get_encode_preset_count: NvencGetEncodePresetCount,
+    pub nvenc_get_encode_preset_guids: NvencGetEncodePresetGuids,
+    nvenc_get_encode_preset_config: NvencGetEncodePresetConfig,
+    pub nvenc_initialize_encoder: NvencInitializeEncoder,
+    pub nvenc_create_input_buffer: NvencCreateInputBuffer,
+    pub nvenc_destroy_input_buffer: NvencDestroyInputBuffer,
+    pub nvenc_create_bit_stream_buffer: NvencCreateBitStreamBuffer,
+    pub nvenc_destory_bit_stream_buffer: NvencDestroyBitStreamBuffer,
+    pub nvenc_encode_picture: NvencEncodePicture,
+    pub nvenc_lock_bit_stream: NvencLockBitStream,
+    pub nvenc_unlock_bit_stream: NvencUnlockBitStream,
+    pub nvenc_lock_input_buffer: NvencLockInputBuffer,
+    pub nvenc_unlock_input_buffer: NvencUnlockInputBuffer,
+    nvenc_get_encode_stats: NvencGetEncodeStats,
+    nvenc_get_sequence_params: NvencGetSequenceParams,
+    nvenc_register_async_event: NvencRegisterAsyncEvent,
+    nvenc_unregister_async_event: NvencUnregisterAsyncEvent,
+    pub nvenc_map_input_resource: NvencMapInputResource,
+    pub nvenc_unmap_input_resource: NvencUnmapInputResource,
+    pub nvenc_destroy_encoder: NvencDestroyEncoder,
+    nvenc_invalidate_ref_frames: NvencInvalidateRefFrames,
+    pub nvenc_open_encode_session_ex: NvencOpenEncodeSessionEx,
+    pub nvenc_register_resource: NvencRegisterResource,
+    pub nvenc_unregister_resource: NvencUnRegisterResource,
+    nvenc_reconfigure_encoder: NvencReconfigureEncoder,
+    rsvd1: *mut c_void,
+    nvenc_create_mv_buffer: NvencCreateMVBuffer,
+    nvenc_destory_mv_buffer: NvencDestoryMVBuffer,
+    nvenc_run_motion_estimation_only: NvencRunMotionEstimationOnly,
+    pub nvenc_get_last_error: NvencGetLastError,
+    nvenc_set_io_cuda_streams: NvencSetIOCudaStreams,
+    pub nvenc_get_encode_preset_config_ex: NvencGetEncodePresetConfigEx,
+    nvenc_get_sequence_params_ex: NvencGetSequenceParamsEx,
+    nvenc_store_encoder_state: NvencStoreEncoderState,
+    nvenc_look_ahead_picture: NvencLookAheadPicture,
+    rsvd2: [*mut c_void; 275],
+}
+
+type NvencOpenEncodeSession =
+    stdcall!(fn(device: *mut c_void, device_type: i32, encoder: *mut *mut c_void) -> NVencResult);
+type NvencGetEncodeGuidCount =
+    stdcall!(fn(encoder: *mut c_void, encoder_guid_count: *mut u32) -> NVencResult);
+type NvencGetEncodeGuids = stdcall!(
+    fn(
+        encoder: *mut c_void,
+        guids: *mut Guid,
+        guid_array_size: u32,
+        guid_count: *mut u32,
+    ) -> NVencResult
+);
+type NvencGetEncodeProfileGuidCount = stdcall!(
+    fn(
+        encoder: *mut c_void,
+        encode_guid: Guid,
+        encoder_profile_guid_count: *mut u32,
+    ) -> NVencResult
+);
+type NvencGetEncodeProfileGuids = stdcall!(
+    fn(
+        encoder: *mut c_void,
+        profile_guids: *mut Guid,
+        guid_array_size: u32,
+        guid_count: *mut u32,
+    ) -> NVencResult
+);
+type NvencGetInputFormatCount = stdcall!(
+    fn(encoder: *mut c_void, encoder_guid: Guid, input_fmt_count: *mut u32) -> NVencResult
+);
+type NvencGetInputFormats = stdcall!(
+    fn(
+        encoder: *mut c_void,
+        input_formats: *mut NVencBufferFormat,
+        input_format_array_size: u32,
+        input_format_count: *mut u32,
+    ) -> NVencResult
+);
+type NvencGetEncodeCaps = stdcall!(
+    fn(
+        encoder: *mut c_void,
+        encoder_guid: Guid,
+        caps_param: *mut NVencCapsParam,
+        caps_val: *mut i32,
+    ) -> NVencResult
+);
+type NvencGetEncodePresetCount = stdcall!(
+    fn(
+        encoder: *mut c_void,
+        encoder_guid: Guid,
+        encoder_preset_guid_count: *mut u32,
+    ) -> NVencResult
+);
+type NvencGetEncodePresetGuids = stdcall!(
+    fn(
+        encoder: *mut c_void,
+        encode_guid: Guid,
+        preset_guids: *mut Guid,
+        guid_array_size: u32,
+        encoder_preset_guid_count: *mut u32,
+    ) -> NVencResult
+);
+type NvencGetEncodePresetConfig = stdcall!(
+    fn(
+        encoder: *mut c_void,
+        encode_guid: Guid,
+        preset_guid: Guid,
+        preset_config: *mut NVencPresetConfig,
+    ) -> NVencResult
+);
+type NvencGetEncodePresetConfigEx = stdcall!(
+    fn(
+        encoder: *mut c_void,
+        encode_guid: Guid,
+        preset_guid: Guid,
+        tuning_info: NVencTuningInfo,
+        preset_config: *mut MaybeUninit<NVencPresetConfig>,
+    ) -> NVencResult
+);
+type NvencInitializeEncoder = stdcall!(
+    fn(encoder: *mut c_void, create_encode_params: *mut NVencInitializeParams) -> NVencResult
+);
+type NvencCreateInputBuffer = stdcall!(
+    fn(
+        encoder: *mut c_void,
+        create_input_buffer_params: *mut NVencCreateInputBuffer,
+    ) -> NVencResult
+);
+type NvencDestroyInputBuffer =
+    stdcall!(fn(encoder: *mut c_void, input_buffer: *mut c_void) -> NVencResult);
+type NvencCreateBitStreamBuffer = stdcall!(
+    fn(
+        encoder: *mut c_void,
+        create_bit_stream_buffer_params: *mut NVencCreateBitstreamBuffer,
+    ) -> NVencResult
+);
+type NvencDestroyBitStreamBuffer =
+    stdcall!(fn(encoder: *mut c_void, bitstream_buffer: *mut c_void) -> NVencResult);
+type NvencEncodePicture = stdcall!(
+    fn(encoder: *mut c_void, encode_pic_params: *mut MaybeUninit<NVencPicParams>) -> NVencResult
+);
+type NvencLockBitStream = stdcall!(
+    fn(
+        encoder: *mut c_void,
+        lock_bitstream_buffer_params: *mut MaybeUninit<NVencLockBitStream>,
+    ) -> NVencResult
+);
+type NvencUnlockBitStream =
+    stdcall!(fn(encoder: *mut c_void, bitstream_buffer: *mut c_void) -> NVencResult);
+type NvencLockInputBuffer = stdcall!(
+    fn(encoder: *mut c_void, lock_input_buffer_params: *mut NVencLockInputBuffer) -> NVencResult
+);
+type NvencUnlockInputBuffer =
+    stdcall!(fn(encoder: *mut c_void, input_buffer: *mut c_void) -> NVencResult);
+type NvencGetEncodeStats = stdcall!(fn(encoder: *mut c_void) -> NVencResult);
+type NvencGetSequenceParams = stdcall!(fn(encoder: *mut c_void) -> NVencResult);
+type NvencRegisterAsyncEvent = stdcall!(fn(encoder: *mut c_void) -> NVencResult);
+type NvencUnregisterAsyncEvent = stdcall!(fn(encoder: *mut c_void) -> NVencResult);
+type NvencMapInputResource = stdcall!(
+    fn(encoder: *mut c_void, map_input_resource_params: *mut NVencMapInputResource) -> NVencResult
+);
+type NvencUnmapInputResource =
+    stdcall!(fn(encoder: *mut c_void, mapped_input_buffer: *mut c_void) -> NVencResult);
+type NvencDestroyEncoder = stdcall!(fn(encoder: *mut c_void) -> NVencResult);
+type NvencInvalidateRefFrames = stdcall!(fn(encoder: *mut c_void) -> NVencResult);
+type NvencOpenEncodeSessionEx = stdcall!(
+    fn(
+        open_session_ex_params: *mut NVencOpenEncodeSessionExParams,
+        encoder: *mut *mut c_void,
+    ) -> NVencResult
+);
+type NvencRegisterResource = stdcall!(
+    fn(encoder: *mut c_void, register_res_params: *mut NVencRegisterResource) -> NVencResult
+);
+type NvencUnRegisterResource =
+    stdcall!(fn(encoder: *mut c_void, registered_res: *mut c_void) -> NVencResult);
+type NvencReconfigureEncoder = stdcall!(fn(encoder: *mut c_void) -> NVencResult);
+
+type NvencCreateMVBuffer = stdcall!(fn(encoder: *mut c_void) -> NVencResult);
+type NvencDestoryMVBuffer = stdcall!(fn(encoder: *mut c_void) -> NVencResult);
+type NvencRunMotionEstimationOnly = stdcall!(fn(encoder: *mut c_void) -> NVencResult);
+type NvencGetLastError = stdcall!(fn(encoder: *mut c_void) -> *const c_char);
+type NvencSetIOCudaStreams = stdcall!(fn(encoder: *mut c_void) -> NVencResult);
+type NvencGetSequenceParamsEx = stdcall!(fn(encoder: *mut c_void) -> NVencResult);
+type NvencStoreEncoderState = stdcall!(fn(encoder: *mut c_void) -> NVencResult);
+type NvencLookAheadPicture = stdcall!(fn(encoder: *mut c_void) -> NVencResult);

vendor/nvenc/src/sys/guids.rs

@@ -0,0 +1,146 @@
+use crate::sys::structs::Guid;
+
+pub const NV_ENC_CODEC_H264_GUID: Guid = Guid::from_values(
+    0x6bc82762,
+    0x4e63,
+    0x4ca4,
+    [0xaa, 0x85, 0x1e, 0x50, 0xf3, 0x21, 0xf6, 0xbf],
+);
+pub const NV_ENC_CODEC_HEVC_GUID: Guid = Guid::from_values(
+    0x790cdc88,
+    0x4522,
+    0x4d7b,
+    [0x94, 0x25, 0xbd, 0xa9, 0x97, 0x5f, 0x76, 0x3],
+);
+pub const NV_ENC_CODEC_AV1_GUID: Guid = Guid::from_values(
+    0x0a352289,
+    0x0aa7,
+    0x4759,
+    [0x86, 0x2d, 0x5d, 0x15, 0xcd, 0x16, 0xd2, 0x54],
+);
+pub const NV_ENC_CODEC_PROFILE_AUTOSELECT_GUID: Guid = Guid::from_values(
+    0xbfd6f8e7,
+    0x233c,
+    0x4341,
+    [0x8b, 0x3e, 0x48, 0x18, 0x52, 0x38, 0x3, 0xf4],
+);
+pub const NV_ENC_H264_PROFILE_BASELINE_GUID: Guid = Guid::from_values(
+    0x727bcaa,
+    0x78c4,
+    0x4c83,
+    [0x8c, 0x2f, 0xef, 0x3d, 0xff, 0x26, 0x7c, 0x6a],
+);
+pub const NV_ENC_H264_PROFILE_MAIN_GUID: Guid = Guid::from_values(
+    0x60b5c1d4,
+    0x67fe,
+    0x4790,
+    [0x94, 0xd5, 0xc4, 0x72, 0x6d, 0x7b, 0x6e, 0x6d],
+);
+pub const NV_ENC_H264_PROFILE_HIGH_GUID: Guid = Guid::from_values(
+    0xe7cbc309,
+    0x4f7a,
+    0x4b89,
+    [0xaf, 0x2a, 0xd5, 0x37, 0xc9, 0x2b, 0xe3, 0x10],
+);
+pub const NV_ENC_H264_PROFILE_HIGH_10_GUID: Guid = Guid::from_values(
+    0x8f0c337e,
+    0x186c,
+    0x48e9,
+    [0xa6, 0x9d, 0x7a, 0x83, 0x34, 0x08, 0x97, 0x5],
+);
+pub const NV_ENC_H264_PROFILE_HIGH_422_GUID: Guid = Guid::from_values(
+    0xff3242e9,
+    0x613c,
+    0x4295,
+    [0xa1, 0xe8, 0x2a, 0x7f, 0xe9, 0x4d, 0x81, 0x33],
+);
+pub const NV_ENC_H264_PROFILE_HIGH_444_GUID: Guid = Guid::from_values(
+    0x7ac663cb,
+    0xa598,
+    0x4960,
+    [0xb8, 0x44, 0x33, 0x9b, 0x26, 0x1a, 0x7d, 0x52],
+);
+pub const NV_ENC_H264_PROFILE_STEREO_GUID: Guid = Guid::from_values(
+    0x40847bf5,
+    0x33f7,
+    0x4601,
+    [0x90, 0x84, 0xe8, 0xfe, 0x3c, 0x1d, 0xb8, 0xb7],
+);
+pub const NV_ENC_H264_PROFILE_PROGRESSIVE_HIGH_GUID: Guid = Guid::from_values(
+    0xb405afac,
+    0xf32b,
+    0x417b,
+    [0x89, 0xc4, 0x9a, 0xbe, 0xed, 0x3e, 0x59, 0x78],
+);
+pub const NV_ENC_H264_PROFILE_CONSTRAINED_HIGH_GUID: Guid = Guid::from_values(
+    0xaec1bd87,
+    0xe85b,
+    0x48f2,
+    [0x84, 0xc3, 0x98, 0xbc, 0xa6, 0x28, 0x50, 0x72],
+);
+pub const NV_ENC_HEVC_PROFILE_MAIN_GUID: Guid = Guid::from_values(
+    0xb514c39a,
+    0xb55b,
+    0x40fa,
+    [0x87, 0x8f, 0xf1, 0x25, 0x3b, 0x4d, 0xfd, 0xec],
+);
+pub const NV_ENC_HEVC_PROFILE_MAIN10_GUID: Guid = Guid::from_values(
+    0xfa4d2b6c,
+    0x3a5b,
+    0x411a,
+    [0x80, 0x18, 0x0a, 0x3f, 0x5e, 0x3c, 0x9b, 0xe5],
+);
+pub const NV_ENC_HEVC_PROFILE_FREXT_GUID: Guid = Guid::from_values(
+    0x51ec32b5,
+    0x1b4c,
+    0x453c,
+    [0x9c, 0xbd, 0xb6, 0x16, 0xbd, 0x62, 0x13, 0x41],
+);
+pub const NV_ENC_AV1_PROFILE_MAIN_GUID: Guid = Guid::from_values(
+    0x5f2a39f5,
+    0xf14e,
+    0x4f95,
+    [0x9a, 0x9e, 0xb7, 0x6d, 0x56, 0x8f, 0xcf, 0x97],
+);
+pub const NV_ENC_PRESET_P1_GUID: Guid = Guid::from_values(
+    0xfc0a8d3e,
+    0x45f8,
+    0x4cf8,
+    [0x80, 0xc7, 0x29, 0x88, 0x71, 0x59, 0xe, 0xbf],
+);
+pub const NV_ENC_PRESET_P2_GUID: Guid = Guid::from_values(
+    0xf581cfb8,
+    0x88d6,
+    0x4381,
+    [0x93, 0xf0, 0xdf, 0x13, 0xf9, 0xc2, 0x7d, 0xab],
+);
+pub const NV_ENC_PRESET_P3_GUID: Guid = Guid::from_values(
+    0x36850110,
+    0x3a07,
+    0x441f,
+    [0x94, 0xd5, 0x36, 0x70, 0x63, 0x1f, 0x91, 0xf6],
+);
+pub const NV_ENC_PRESET_P4_GUID: Guid = Guid::from_values(
+    0x90a7b826,
+    0xdf06,
+    0x4862,
+    [0xb9, 0xd2, 0xcd, 0x6d, 0x73, 0xa0, 0x86, 0x81],
+);
+pub const NV_ENC_PRESET_P5_GUID: Guid = Guid::from_values(
+    0x21c6e6b4,
+    0x297a,
+    0x4cba,
+    [0x99, 0x8f, 0xb6, 0xcb, 0xde, 0x72, 0xad, 0xe3],
+);
+pub const NV_ENC_PRESET_P6_GUID: Guid = Guid::from_values(
+    0x8e75c279,
+    0x6299,
+    0x4ab6,
+    [0x83, 0x2, 0xb, 0x21, 0x5a, 0x33, 0x5c, 0xf5],
+);
+pub const NV_ENC_PRESET_P7_GUID: Guid = Guid::from_values(
+    0x84848c12,
+    0x6f71,
+    0x4c13,
+    [0x93, 0x1b, 0x53, 0xe2, 0x83, 0xf5, 0x79, 0x74],
+);

vendor/nvenc/src/sys/mod.rs

@@ -0,0 +1,6 @@
+pub mod enums;
+pub mod function_table;
+pub mod guids;
+pub mod result;
+pub mod structs;
+pub mod version;

vendor/nvenc/src/sys/result.rs

@@ -0,0 +1,79 @@
+#[derive(Debug, PartialEq, Eq)]
+#[repr(C)]
+pub enum NVencResult {
+    Success,
+    NoDevice,
+    UnsupportedDevice,
+    InvalidEncoderDevice,
+    InvalidDevice,
+    DeviceNotExist,
+    InvalidPtr,
+    InvalidParam,
+    InvalidEvent,
+    InvalidCall,
+    OutOfMemory,
+    NotInitialized,
+    UnsupportedParam,
+    LockBusy,
+    NotEnoughBuffer,
+    InvalidVersion,
+    MapFailed,
+    NeedMoreInput,
+    EncoderBusy,
+    EventNotRegisterd,
+    Generic,
+    IncompatibleClientKey,
+    Unimplemented,
+    ResourceRegisterFailed,
+    ResourceNotRegistered,
+    ResourceNotMapped,
+    NeedMoreOutput,
+}
+
+impl NVencResult {
+    pub fn into_error(self) -> Result<(), NVencError> {
+        NVencError::from_result(self)
+    }
+}
+
+impl NVencError {
+    pub fn from_result(value: NVencResult) -> Result<(), Self> {
+        if value == NVencResult::Success {
+            Ok(())
+        } else {
+            // Safety: They are one case different, so they always align
+            unsafe { Err(std::mem::transmute::<NVencResult, NVencError>(value)) }
+        }
+    }
+}
+
+#[derive(Debug, PartialEq, Eq)]
+#[repr(C)]
+pub enum NVencError {
+    NoDevice = NVencResult::NoDevice as isize,
+    UnsupportedDevice,
+    InvalidEncoderDevice,
+    InvalidDevice,
+    DeviceNotExist,
+    InvalidPtr,
+    InvalidEvent,
+    InvalidParam,
+    InvalidCall,
+    OutOfMemory,
+    NotInitialized,
+    UnsupportedParam,
+    LockBusy,
+    NotEnoughBuffer,
+    InvalidVersion,
+    MapFailed,
+    NeedMoreInput,
+    EncoderBusy,
+    EventNotRegisterd,
+    Generic,
+    IncompatibleClientKey,
+    Unimplemented,
+    ResourceRegisterFailed,
+    ResourceNotRegistered,
+    ResourceNotMapped,
+    NeedMoreOutput,
+}

vendor/nvenc/src/sys/structs.rs

@@ -0,0 +1,944 @@
+use std::{ffi::c_void, mem::ManuallyDrop};
+
+use crate::sys::{
+    enums::{
+        NVencAV1PartSize, NVencBFrameRefMode, NVencBitDepth, NVencBufferFormat, NVencBufferUsage,
+        NVencCaps, NVencDeviceType, NVencDisplayPicStruct, NVencH264AdaptiveTransformMode,
+        NVencH264BDirectMode, NVencH264EntropyCodingMode, NVencH264FMOMode, NVencHEVCCuSize,
+        NVencInputResourceType, NVencLookAheadLevel, NVencMVPrecision, NVencMemoryHeap,
+        NVencMultiPass, NVencNumRefFrames, NVencOutputStatsLevel, NVencParamsFrameFieldMode,
+        NVencParamsRcMode, NVencPicStruct, NVencPicType, NVencQPMapMode, NVencStateRestoreType,
+        NVencStereoPackingMode, NVencTemporalFilterLevel, NVencTuningInfo, NVencVUIColorPrimaries,
+        NVencVUIMatrixCoeffs, NVencVUITransCharacteristics, NVencVUIVideoFormat,
+    },
+    version::struct_version,
+};
+
+#[derive(Default, Clone, PartialEq, Eq)]
+#[repr(C)]
+pub struct Guid {
+    pub data1: u32,
+    pub data2: u16,
+    pub data3: u16,
+    pub data4: [u8; 8],
+}
+
+impl Guid {
+    pub const fn from_values(data1: u32, data2: u16, data3: u16, data4: [u8; 8]) -> Self {
+        Self {
+            data1,
+            data2,
+            data3,
+            data4,
+        }
+    }
+
+    pub const fn from_u128(uuid: u128) -> Self {
+        Self {
+            data1: (uuid >> 96) as u32,
+            data2: ((uuid >> 80) & 0xffff) as u16,
+            data3: ((uuid >> 64) & 0xffff) as u16,
+            data4: (uuid as u64).to_be_bytes(),
+        }
+    }
+}
+
+#[repr(C)]
+pub struct NVencCapsParam {
+    version: u32,
+    caps_to_query: NVencCaps,
+    rsvd: [u32; 62],
+}
+
+pub const NV_ENC_CAPS_PARAM_VERSION: u32 = struct_version(1);
+
+#[repr(C)]
+pub struct NVencRestoreEncoderStateParams {
+    version: u32,
+    buffer: u32,
+    state: NVencStateRestoreType,
+    rsvd: u32,
+    output_bit_stream: *mut c_void,
+    completion_event: *mut c_void,
+    rsvd1: [u32; 64],
+    rsvd2: [*mut c_void; 64],
+}
+
+pub const NV_ENC_RESTORE_STATE_PARAMS_VER: u32 = struct_version(2);
+
+#[repr(C)]
+pub struct NVencOutputStatsBlock {
+    version: u32,
+    qp: u8,
+    rsvd: [u8; 3],
+    bit_count: u32,
+    satd_cost: u32,
+    rsvd1: [u32; 12],
+}
+
+pub const NV_ENC_OUTPUT_STATS_BLOCK_VER: u32 = struct_version(1);
+
+#[repr(C)]
+pub struct NVencOutputStatsRow {
+    version: u32,
+    qp: u8,
+    rsvd: [u8; 3],
+    bit_count: u32,
+    satd_cost: u32,
+    rsvd1: [u32; 12],
+}
+
+pub const NV_ENC_OUTPUT_STATS_ROW_VER: u32 = struct_version(1);
+
+#[repr(C)]
+pub struct NVencEncodeOutParams {
+    version: u32,
+    bitstream_size_in_bytes: u32,
+    rsvd: [u32; 62],
+}
+
+pub const NV_ENC_ENCODE_OUT_PARAMS_VER: u32 = struct_version(1);
+
+#[repr(C)]
+pub struct NVencLookAheadPicParams {
+    version: u32,
+    rsvd: u32,
+    input_buffer: *mut c_void,
+    picture_type: NVencPicType,
+    rsvd1: [u32; 63],
+    rsvd2: [*mut c_void; 64],
+}
+
+pub const NV_ENC_LOOKAHEAD_PIC_PARAMS_VER: u32 = struct_version(2);
+
+#[repr(C)]
+pub struct NVencCreateInputBuffer {
+    pub version: u32,
+    pub width: u32,
+    pub height: u32,
+    pub memory_heap: NVencMemoryHeap,
+    pub buffer_fmt: NVencBufferFormat,
+    pub rsvd: u32,
+    pub input_buffer: *mut c_void,
+    pub p_sys_mem_buffer: *mut c_void,
+    pub rsvd1: [u32; 58],
+    pub rsvd2: [*mut c_void; 63],
+}
+
+pub const NV_ENC_CREATE_INPUT_BUFFER_VER: u32 = struct_version(2);
+
+#[repr(C)]
+pub struct NVencCreateBitstreamBuffer {
+    pub version: u32,
+    #[deprecated]
+    size: u32,
+    #[deprecated]
+    memory_heap: NVencMemoryHeap,
+    rsvd: u32,
+    pub bitstream_buffer: *mut c_void,
+    bitstream_buffer_ptr: *mut c_void,
+    rsvd1: [u32; 58],
+    rsvd2: [*mut c_void; 64],
+}
+
+pub const NV_ENC_CREATE_BITSTREAM_BUFFER_VER: u32 = struct_version(1);
+
+#[repr(C)]
+pub struct NVencMVector {
+    mvx: i16,
+    mvy: i16,
+}
+
+#[repr(C)]
+pub struct NVencH264MVData {
+    mv: [NVencMVector; 4],
+    mb_type: u8,
+    partition_type: u8,
+    rsvd: u16,
+    mb_cost: u32,
+}
+
+#[repr(C)]
+pub struct NVencHEVCMVData {
+    mv: [NVencMVector; 4],
+    cu_type: u8,
+    cu_size: u8,
+    partition_mode: u8,
+    last_cu_int_ctb: u8,
+}
+
+#[repr(C)]
+pub struct NVencCreateMVBuffer {
+    version: u32,
+    rsvd: u32,
+    mv_buffer: *mut c_void,
+    rsvd1: [u32; 254],
+    rsvd2: [*mut c_void; 63],
+}
+
+pub const NV_ENC_CREATE_MV_BUFFER_VER: u32 = struct_version(2);
+
+#[repr(C)]
+pub struct NVencQP {
+    qp_inter_p: u32,
+    qp_inter_b: u32,
+    qp_intra: u32,
+}
+
+pub const MAX_NUM_VIEWS_MINUS_1: usize = 7;
+
+#[repr(C)]
+pub struct NVencRcParams {
+    version: u32,
+    pub rate_control_mode: NVencParamsRcMode,
+    const_qp: NVencQP,
+    pub average_bit_rate: u32,
+    max_bit_rate: u32,
+    vbv_buffer_size: u32,
+    vbv_initial_delay: u32,
+    // TODO: bit fields
+    bit_fields: NVencRcParamsBitFlags,
+    min_qp: NVencQP,
+    max_qp: NVencQP,
+    initial_rcqp: NVencQP,
+    temporal_layer_idx_mask: u32,
+    temporal_layer_qp: [u8; 8],
+    target_quality: u8,
+    target_quality_lsb: u8,
+    pub look_ahead_depth: u16,
+    low_delay_key_frame_scale: u8,
+    y_dc_qp_index_offset: i8,
+    u_dc_qp_index_offset: i8,
+    v_dc_qp_index_offset: i8,
+    qp_map_mode: NVencQPMapMode,
+    multi_pass: NVencMultiPass,
+    alpha_layer_bitrate_ratio: u32,
+    cb_qp_index_offset: i8,
+    cr_qp_index_offset: i8,
+    rsvd2: u16,
+    lookahead_level: NVencLookAheadLevel,
+    view_bitrate_ratios: [u8; MAX_NUM_VIEWS_MINUS_1],
+    rsvd3: u8,
+    rsvd1: u32,
+}
+
+#[repr(transparent)]
+pub struct NVencRcParamsBitFlags(u32);
+
+impl NVencRcParamsBitFlags {}
+
+pub const NV_ENC_RC_PARAMS_VER: u32 = struct_version(1);
+
+pub const MAX_NUM_CLOCK_TS: usize = 3;
+
+#[repr(C)]
+pub struct NVencClockTimeStampSet {
+    pub bitflags: u32,
+    pub time_offset: u32,
+}
+
+impl NVencClockTimeStampSet {}
+
+#[repr(C)]
+pub struct NVencTimeCode {
+    pub display_pic_struct: NVencDisplayPicStruct,
+    pub clock_timestamp: [NVencClockTimeStampSet; MAX_NUM_CLOCK_TS],
+    pub skip_clock_timestamp_insertion: u32,
+}
+
+pub const MULTIVIEW_MAX_NUM_REF_DISPLAY: usize = 32;
+
+#[repr(C)]
+pub struct HEVC3DReferenceDisplayInfo {
+    // TODO
+    pub bitflags: u32,
+    pub prec_ref_display_width: i32,
+    pub prec_ref_viewing_dist: i32,
+    pub num_ref_displays_minus1: i32,
+    pub left_view_id: [i32; MULTIVIEW_MAX_NUM_REF_DISPLAY],
+    pub right_view_id: [i32; MULTIVIEW_MAX_NUM_REF_DISPLAY],
+    pub exponent_ref_display_width: [i32; MULTIVIEW_MAX_NUM_REF_DISPLAY],
+    pub mantissa_ref_display_width: [i32; MULTIVIEW_MAX_NUM_REF_DISPLAY],
+    pub exponent_ref_viewing_distance: [i32; MULTIVIEW_MAX_NUM_REF_DISPLAY],
+    pub mantissa_ref_viewing_distance: [i32; MULTIVIEW_MAX_NUM_REF_DISPLAY],
+    pub num_sample_shift_plus512: [i32; MULTIVIEW_MAX_NUM_REF_DISPLAY],
+    pub additional_shift_present_flag: [u8; MULTIVIEW_MAX_NUM_REF_DISPLAY],
+    pub rsvd2: [u32; 4],
+}
+
+#[repr(C)]
+pub struct ChromaPoints {
+    x: u16,
+    y: u16,
+}
+
+#[repr(C)]
+pub struct MasteringDisplayInfo {
+    pub g: ChromaPoints,
+    pub b: ChromaPoints,
+    pub r: ChromaPoints,
+    pub white_point: ChromaPoints,
+    pub max_luma: u32,
+    pub min_luma: u32,
+}
+
+#[repr(C)]
+pub struct ContentLightLevel {
+    pub max_content_light_level: u16,
+    pub max_pic_average_light_level: u16,
+}
+
+#[repr(C)]
+pub struct NVencConfigH264VUIParameters {
+    overscan_info_present_flag: u32,
+    overscan_info: u32,
+    video_signal_type_present_flag: u32,
+    video_format: NVencVUIVideoFormat,
+    video_full_range_flag: u32,
+    color_description_present_flag: u32,
+    color_primaries: NVencVUIColorPrimaries,
+    transfer_characteristics: NVencVUITransCharacteristics,
+    color_matrix: NVencVUIMatrixCoeffs,
+    chroma_sample_location_flag: u32,
+    chroma_sample_location_top: u32,
+    chroma_sample_location_bot: u32,
+    bitstream_restriction_flag: u32,
+    timing_info_present_flag: u32,
+    num_unit_in_ticks: u32,
+    time_scale: u32,
+    rsvd: [u32; 12],
+}
+
+pub type NVencConfigHEVCVUIParamaters = NVencConfigH264VUIParameters;
+
+#[repr(C)]
+#[derive(Default)]
+pub struct NVencExternalMeHintCountsPerBlockType {
+    pub bitflags: u32,
+    pub rsvd1: [u32; 3],
+}
+
+#[repr(transparent)]
+pub struct NVencExternalMeHint(i32);
+
+#[repr(C)]
+pub struct NVencExternalMeSbHint {
+    flags1: i16,
+    flags2: i16,
+    flags3: i16,
+}
+
+#[repr(C)]
+pub struct NVencConfigH264 {
+    bitflags: u32,
+    level: u32,
+    idr_period: u32,
+    seperate_color_plane_flag: u32,
+    disable_deblocking_filter_idc: u32,
+    num_termpoal_layers: u32,
+    sps_id: u32,
+    pps_id: u32,
+    adaptive_transform_mode: NVencH264AdaptiveTransformMode,
+    fmo_mode: NVencH264FMOMode,
+    bdirect_mode: NVencH264BDirectMode,
+    entropy_coding_mode: NVencH264EntropyCodingMode,
+    stereo_mode: NVencStereoPackingMode,
+    intra_refresh_period: u32,
+    intra_refresh_count: u32,
+    max_num_ref_frames: u32,
+    slice_mode: u32,
+    slice_mode_data: u32,
+    h264_vui_parameters: NVencConfigH264VUIParameters,
+    ltr_num_frames: u32,
+    ltr_trust_mode: u32,
+    chroma_format_idc: u32,
+    max_termpoal_layers: u32,
+    use_b_frames_as_ref: NVencBFrameRefMode,
+    num_ref_l0: NVencNumRefFrames,
+    num_ref_l1: NVencNumRefFrames,
+    output_bit_depth: NVencBitDepth,
+    input_bit_depth: NVencBitDepth,
+    tf_level: NVencTemporalFilterLevel,
+    rsvd1: [u32; 264],
+    rsvd: [*mut c_void; 64],
+}
+
+#[repr(C)]
+pub struct NVencConfigHEVC {
+    level: u32,
+    tier: u32,
+    min_cu_size: NVencHEVCCuSize,
+    max_cu_size: NVencHEVCCuSize,
+    bitflags: u32,
+    idr_period: u32,
+    intra_refresh_cnt: u32,
+    max_num_ref_frames_in_dpb: u32,
+    ltr_num_frames: u32,
+    vps_id: u32,
+    sps_id: u32,
+    pps_id: u32,
+    slice_mode: u32,
+    slice_mode_data: u32,
+    max_temporal_layers_minus_1: u32,
+    hevc_vui_paramters: NVencConfigHEVCVUIParamaters,
+    ltr_trust_mode: u32,
+    use_b_frames_as_ref: NVencBFrameRefMode,
+    tf_level: NVencTemporalFilterLevel,
+    disable_deblocking_filter_idc: u32,
+    output_bit_depth: NVencBitDepth,
+    input_bit_depth: NVencBitDepth,
+    num_temporal_layers: u32,
+    num_views: u32,
+    rsvd1: [u32; 208],
+    rsvd2: [*mut c_void; 64],
+}
+
+pub const NV_MAX_TILE_COLS_AV1: usize = 64;
+pub const NV_MAX_TILE_ROWS_AV1: usize = 64;
+
+#[repr(C)]
+pub struct NVencFilmGrainParamsAV1 {
+    bitfields: u32,
+    point_y_value: [u8; 14],
+    point_y_scaling: [u8; 14],
+    point_cb_value: [u8; 10],
+    point_cb_scaling: [u8; 10],
+    point_cr_value: [u8; 10],
+    point_cr_scaling: [u8; 10],
+    ar_coeffs_y_plus128: [u8; 24],
+    ar_coeffs_cb_plus128: [u8; 25],
+    ar_coeffs_cr_plus128: [u8; 25],
+    rsvd2: [u8; 2],
+    cb_mult: u8,
+    cb_luma_mult: u8,
+    cb_offset: u16,
+    cr_mult: u8,
+    cr_luma_mult: u8,
+    cr_offset: u16,
+}
+
+#[repr(C)]
+pub struct NVencConfigAV1 {
+    level: u32,
+    tier: u32,
+    min_part_size: NVencAV1PartSize,
+    max_part_size: NVencAV1PartSize,
+    bitflags: u32,
+    idr_period: u32,
+    intra_refresh_period: u32,
+    intra_refresh_count: u32,
+    max_num_ref_frames_in_dpb: u32,
+    num_tiles_columns: u32,
+    num_tile_rows: u32,
+    rsvd2: u32,
+    tile_widths: *mut u32,
+    tile_heights: *mut u32,
+    max_temporal_layers_minus_1: u32,
+    color_primaries: NVencVUIColorPrimaries,
+    transfer_characteristics: NVencVUITransCharacteristics,
+    matrix_coefficients: NVencVUIMatrixCoeffs,
+    color_range: u32,
+    chroma_sample_position: u32,
+    use_b_frames_as_ref: NVencBFrameRefMode,
+    film_grain_params: NVencFilmGrainParamsAV1,
+    num_fwd_refs: NVencNumRefFrames,
+    num_bwd_refs: NVencNumRefFrames,
+    input_bit_depth: NVencBitDepth,
+    ltr_num_frames: u32,
+    num_temporal_layers: u32,
+    tf_level: NVencTemporalFilterLevel,
+    rsvd1: [u32; 230],
+    rsvd3: [*mut c_void; 62],
+}
+
+#[repr(C)]
+pub struct NVencConfigH264MeOnly {
+    bitflags: u32,
+    rsvd1: [u32; 255],
+    rsvd2: [*mut c_void; 64],
+}
+
+#[repr(C)]
+pub struct NVencConfigHEVCMeOnly {
+    rsvd: [u32; 256],
+    rsvd1: [*mut c_void; 64],
+}
+
+#[repr(C)]
+pub union NVencCodecConfig {
+    h264: ManuallyDrop<NVencConfigH264>,
+    hevc: ManuallyDrop<NVencConfigHEVC>,
+    av1: ManuallyDrop<NVencConfigAV1>,
+    h264_meonly: ManuallyDrop<NVencConfigH264MeOnly>,
+    hevc_meonly: ManuallyDrop<NVencConfigHEVCMeOnly>,
+    rsvd: [u32; 320],
+}
+
+#[repr(C)]
+pub struct NVencConfig {
+    pub version: u32,
+    pub profile_guid: Guid,
+    pub gop_len: u32,
+    pub frame_interval_p: i32,
+    mono_chrome_encoding: u32,
+    frame_field_mode: NVencParamsFrameFieldMode,
+    mv_precision: NVencMVPrecision,
+    pub rc_params: NVencRcParams,
+    encode_codec_config: NVencCodecConfig,
+    rsvd: [u32; 278],
+    rsvd2: [*mut c_void; 64],
+}
+
+pub const NV_ENC_CONFIG_VER: u32 = struct_version(9) | (1 << 31);
+
+#[bitfields::bitfield(u32)]
+pub struct NVencInitializeParamsBitfields {
+    #[bits(1)]
+    pub report_slice_offsets: bool,
+    #[bits(1)]
+    pub enable_sub_frame_write: bool,
+    #[bits(1)]
+    pub enable_external_me_hints: bool,
+    #[bits(1)]
+    pub enable_me_only_mode: bool,
+    #[bits(1)]
+    pub enable_weighted_prediction: bool,
+    #[bits(4)]
+    pub split_encode_mode: u8,
+    #[bits(1)]
+    pub enable_output_in_vid_mem: bool,
+    #[bits(1)]
+    pub enable_recon_frame_output: bool,
+    #[bits(1)]
+    pub enable_output_stats: bool,
+    #[bits(1)]
+    pub enable_uni_directional_b: bool,
+    #[bits(19)]
+    pub rsvd: u32,
+}
+
+#[repr(C)]
+pub struct NVencInitializeParams {
+    pub version: u32,
+    pub encode_guid: Guid,
+    pub preset_guid: Guid,
+    pub encode_width: u32,
+    pub encode_height: u32,
+    pub dar_width: u32,
+    pub dar_height: u32,
+    pub frame_rate_num: u32,
+    pub frame_rate_den: u32,
+    pub enable_encode_async: u32,
+    pub enable_ptd: u32,
+    pub bit_flags: NVencInitializeParamsBitfields,
+    pub(crate) priv_data_size: u32,
+    pub(crate) rsvd: u32,
+    pub(crate) priv_data: *mut c_void,
+    pub encode_config: *mut NVencConfig,
+    pub max_encode_width: u32,
+    pub max_encode_height: u32,
+    pub max_me_hint_counts_per_block: [NVencExternalMeHintCountsPerBlockType; 2],
+    pub tuning_info: NVencTuningInfo,
+    pub buffer_format: NVencBufferFormat,
+    pub num_state_buffers: u32,
+    pub output_stats_level: NVencOutputStatsLevel,
+    pub(crate) rsvd1: [u32; 284],
+    pub(crate) rsvd2: [*mut c_void; 64],
+}
+
+pub const NV_ENC_INITIALIZE_PARAMS_VER: u32 = struct_version(7) | (1 << 31);
+
+#[repr(C)]
+pub struct NVencReconfigureParams {
+    version: u32,
+    rsvd: u32,
+    re_init_encode_params: NVencInitializeParams,
+    bitflags: u32,
+    rsvd2: u32,
+}
+
+pub const NV_ENC_RECONFIGURE_PARAMS_VER: u32 = struct_version(2) | (1 << 31);
+
+#[repr(C)]
+pub struct NVencPresetConfig {
+    pub version: u32,
+    rsvd: u32,
+    pub preset_cfg: NVencConfig,
+    rsvd1: [u32; 256],
+    rsvd2: [*mut c_void; 64],
+}
+
+pub const NV_ENC_PRESET_CONFIG_VER: u32 = struct_version(5) | (1 << 31);
+
+#[repr(C)]
+pub struct NVencPicParamsMVC {
+    version: u32,
+    view_id: u32,
+    temporal_id: u32,
+    priority_id: u32,
+    rsvd1: [u32; 12],
+    rsvd2: [*mut c_void; 8],
+}
+
+pub const NV_ENC_PIC_PARAMS_MVC_VER: u32 = struct_version(1);
+
+#[repr(C)]
+pub union NVencPicParamsH264EXT {
+    pub mvc_pic_params: ManuallyDrop<NVencPicParamsMVC>,
+    pub rsvd1: [u32; 32],
+}
+
+#[repr(C)]
+pub struct NVencSeiPayload {
+    pub payload_size: u32,
+    pub payload_type: u32,
+    pub payload: *mut u8,
+}
+
+pub type NVencH264SeiPayload = NVencSeiPayload;
+
+#[repr(C)]
+pub struct NVencPicParamsH264 {
+    pub display_poc_syntax: u32,
+    pub rsvd3: u32,
+    pub ref_pic_flag: u32,
+    pub color_plane_id: u32,
+    pub force_intra_refresh_with_frame_count: u32,
+    pub bitflags: u32,
+    pub slice_type_data: *mut u8,
+    pub slice_type_array_count: u32,
+    pub sei_payload_array_count: u32,
+    pub sei_payload_array: *mut NVencSeiPayload,
+    pub slice_mode: u32,
+    pub slice_mode_data: u32,
+    pub ltr_mark_framce_idx: u32,
+    pub ltr_use_frame_bitmap: u32,
+    pub ltr_usage_mode: u32,
+    pub force_intra_slice_count: u32,
+    pub force_intra_slice_idx: *mut u32,
+    pub h264_ext_pic_params: NVencPicParamsH264EXT,
+    pub time_code: NVencTimeCode,
+    pub rsvd: [u32; 202],
+    pub rsvd2: [*mut c_void; 61],
+}
+
+#[repr(C)]
+pub struct NVencPicParamsHEVC {
+    pub display_poc_syntax: u32,
+    pub ref_pic_flag: u32,
+    pub temporal_id: u32,
+    pub force_intra_refresh_with_frame_count: u32,
+    pub bitflags: u32,
+    pub rsvd1: u32,
+    pub slice_type_data: *mut u8,
+    pub slice_type_array_count: u32,
+    pub slice_mode: u32,
+    pub slice_mode_data: u32,
+    pub ltr_mark_frame_idx: u32,
+    pub ltr_usage_frame_bitmap: u32,
+    pub ltr_usage_mode: u32,
+    pub sei_payload_array_count: u32,
+    pub rsvd: u32,
+    pub sei_payload_array: *mut NVencSeiPayload,
+    pub time_code: NVencTimeCode,
+    pub num_temporal_layers: u32,
+    pub view_id: u32,
+    pub _3d_reference_display_info: *mut HEVC3DReferenceDisplayInfo,
+    pub max_cll: *mut ContentLightLevel,
+    pub mastering_display: *mut MasteringDisplayInfo,
+    pub rsvd2: [u32; 234],
+    pub rsvd3: [*mut c_void; 58],
+}
+
+pub type NVencAV1OBUPayload = NVencSeiPayload;
+
+#[repr(C)]
+pub struct NVencPicParamsAV1 {
+    display_poc_syntax: u32,
+    ref_pic_flag: u32,
+    temporal_id: u32,
+    force_intra_refresh_with_frame_count: u32,
+    bitflags: u32,
+    num_tile_columns: u32,
+    num_tile_rows: u32,
+    rsvd: u32,
+    tile_widths: *mut u32,
+    tile_heights: *mut u32,
+    obu_payload_array_count: u32,
+    rsvd1: u32,
+    obu_payload_array: *mut NVencAV1OBUPayload,
+    file_grain_params: *mut NVencFilmGrainParamsAV1,
+    ltr_mark_frame_idx: u32,
+    ltr_use_frame_bitmap: u32,
+    num_temporal_layers: u32,
+    rsvd4: u32,
+    max_cll: *mut ContentLightLevel,
+    mastering_display: *mut MasteringDisplayInfo,
+    rsvd2: [u32; 242],
+    rsvd3: [*mut c_void; 59],
+}
+
+#[repr(C)]
+pub union NVencCodecPicParams {
+    pub h264_pic_params: ManuallyDrop<NVencPicParamsH264>,
+    pub hevc_pic_params: ManuallyDrop<NVencPicParamsHEVC>,
+    av1_pic_params: ManuallyDrop<NVencPicParamsAV1>,
+    pub rsvd: [u32; 256],
+}
+
+#[repr(C)]
+pub struct NVencPicParams {
+    pub version: u32,
+    pub input_width: u32,
+    pub input_height: u32,
+    pub input_pitch: u32,
+    pub encode_pic_flags: u32,
+    pub frame_idx: u32,
+    pub input_time_stamp: u64,
+    input_duration: u64,
+    pub input_buffer: *mut c_void,
+    pub output_bitstream: *mut c_void,
+    // TODO: Windows only, needed for async
+    completion_event: *mut c_void,
+    pub buffer_format: NVencBufferFormat,
+    pub picture_struct: NVencPicStruct,
+    pub picture_type: NVencPicType,
+    pub codec_pic_params: NVencCodecPicParams,
+    me_hint_counts_per_block: [NVencExternalMeHintCountsPerBlockType; 2],
+    me_external_hints: *mut NVencExternalMeHint,
+    rsvd2: [u32; 7],
+    rsvd5: [*mut c_void; 2],
+    qp_delta_map: *mut i8,
+    qp_deltra_map_size: u32,
+    rsvd_bit_fields: u32,
+    me_hint_ref_pic_dist: [u16; 2],
+    rsvd4: u32,
+    alpha_buffer: *mut c_void,
+    me_external_sb_hints: *mut NVencExternalMeSbHint,
+    me_sb_hints_count: u32,
+    state_buffer_idx: u32,
+    output_recon_buffer: *mut c_void,
+    rsvd3: [u32; 284],
+    rsvd6: [*mut c_void; 57],
+}
+
+pub const NV_ENC_PIC_PARAMS_VER: u32 = struct_version(7) | (1 << 31);
+
+#[repr(C)]
+pub struct NVencMeOnlyParams {
+    version: u32,
+    input_width: u32,
+    input_height: u32,
+    rsvd: u32,
+    input_buffer: *mut c_void,
+    reference_frame: *mut c_void,
+    mv_buffer: *mut c_void,
+    rsvd2: u32,
+    buffer_formtat: NVencBufferFormat,
+    view_id: u32,
+    me_hint_counts_per_block: [NVencExternalMeHintCountsPerBlockType; 2],
+    me_external_hints: NVencExternalMeHint,
+    rsvd1: [u32; 241],
+    rsvd3: [*mut c_void; 59],
+}
+
+pub const NV_ENC_MEONLY_PARAMS_VER: u32 = struct_version(4);
+
+#[bitfields::bitfield(u32)]
+pub struct NVencLockBitStreamBitFields {
+    #[bits(1)]
+    pub do_not_wait: bool,
+    #[bits(1)]
+    pub ltr_frame: bool,
+    #[bits(1)]
+    pub get_rc_stats: bool,
+    #[bits(29)]
+    rsvd: u32,
+}
+
+#[repr(C)]
+pub struct NVencLockBitStream {
+    pub version: u32,
+    pub bit_fields: NVencLockBitStreamBitFields,
+    pub output_bit_stream: *mut c_void,
+    slice_offsets: *mut u32,
+    frame_idx: u32,
+    hw_encode_status: u32,
+    num_slices: u32,
+    pub bitstream_size_in_bytes: u32,
+    output_time_stamp: u64,
+    pub output_duration: u64,
+    pub bitstream_buffer: *mut c_void,
+    picture_type: NVencPicType,
+    picture_struct: NVencPicStruct,
+    framge_avg_qp: u32,
+    frame_satd: u32,
+    ltr_frame_idx: u32,
+    ltr_frame_bitmap: u32,
+    temporal_id: u32,
+    inter_mb_count: u32,
+    average_mvx: i32,
+    average_mvy: i32,
+    alpha_layer_size_in_bytes: u32,
+    output_stats_ptr_size: u32,
+    rsvd: u32,
+    output_stats_ptr: *mut c_void,
+    frame_idx_display: u32,
+    rsvd1: [u32; 219],
+    rsvd2: [*mut c_void; 63],
+    rsvd_interanl: [u32; 8],
+}
+
+pub const NV_ENC_LOCK_BITSTREAM_VER: u32 = struct_version(2) | (1 << 31);
+
+#[repr(C)]
+pub struct NVencLockInputBuffer {
+    pub version: u32,
+    pub bitflags: u32,
+    pub input_buffer: *mut c_void,
+    pub buffer_data_ptr: *mut c_void,
+    pub pitch: u32,
+    pub rsvd1: [u32; 251],
+    pub rsvd2: [*mut c_void; 64],
+}
+
+pub const NV_ENC_LOCK_INPUT_BUFFER_VER: u32 = struct_version(1);
+
+#[repr(C)]
+pub struct NVencMapInputResource {
+    pub version: u32,
+    sub_resource_idx: u32,
+    input_resource: *mut c_void,
+    pub registered_resource: *mut c_void,
+    pub mapped_resource: *mut c_void,
+    pub mapped_buffer_format: NVencBufferFormat,
+    rsvd1: [u32; 251],
+    rsvd: [*mut c_void; 63],
+}
+
+pub const NV_ENC_MAP_INPUT_RESOURCE_VER: u32 = struct_version(4);
+
+#[repr(C)]
+pub struct NVencInputResourceOpenGLTex {
+    texture: u32,
+    target: u32,
+}
+
+#[repr(C)]
+pub struct NVencFencePointD3D12 {
+    version: u32,
+    rsvd: u32,
+    p_fence: *mut c_void,
+    wait_value: u64,
+    signal_value: u64,
+    bit_flags: u32,
+    rsvd1: [u32; 7],
+}
+
+pub const NV_ENC_FENCE_POINT_D3D12_VER: u32 = struct_version(1);
+
+#[repr(C)]
+pub struct NVencInputResourceD3D12 {
+    version: u32,
+    rsvd: u32,
+    input_buffer: *mut c_void,
+    input_fence_point: NVencFencePointD3D12,
+    rsvd1: [u32; 16],
+    rsvd2: [*mut c_void; 16],
+}
+
+pub const NV_ENC_INPUT_RESOURCE_D3D12_VER: u32 = struct_version(1);
+
+#[repr(C)]
+pub struct NVencOutputResourceD3D12 {
+    version: u32,
+    rsvd: u32,
+    output_buffer: *mut c_void,
+    output_fence_point: NVencFencePointD3D12,
+    rsvd1: [u32; 16],
+    rsvd2: [*mut c_void; 16],
+}
+
+pub const NV_ENC_OUTPUT_RESOURCE_D3D12_VER: u32 = struct_version(1);
+
+#[repr(C)]
+pub struct NVencRegisterResource {
+    pub version: u32,
+    pub resource_type: NVencInputResourceType,
+    pub width: u32,
+    pub height: u32,
+    pub pitch: u32,
+    pub sub_resource_index: u32,
+    pub resource_to_register: *mut c_void,
+    pub registered_resource: *mut c_void,
+    pub buffer_format: NVencBufferFormat,
+    pub buffer_usage: NVencBufferUsage,
+    pub input_fence_point: *mut NVencFencePointD3D12,
+    pub chroma_offset: [u32; 2],
+    pub chroma_offset_in: [u32; 2],
+    pub(crate) rsvd1: [u32; 244],
+    pub(crate) rsvd2: [*mut c_void; 61],
+}
+
+pub const NV_ENC_REGISTER_RESOURCE_VER: u32 = struct_version(5);
+
+#[repr(C)]
+pub struct NVencStat {
+    version: u32,
+    rsvd: u32,
+    output_bit_stream: *mut c_void,
+    bit_stream_size: u32,
+    pic_type: u32,
+    last_valid_byte_offset: u32,
+    slice_offsets: [u32; 16],
+    pic_idx: u32,
+    frame_avg_qp: u32,
+    bit_flags: u32,
+    ltr_frame_idx: u32,
+    intra_mb_count: u32,
+    inter_mb_count: u32,
+    average_mv_x: i32,
+    average_mv_y: i32,
+    rsvd1: [u32; 227],
+    rsvd2: [*mut c_void; 64],
+}
+
+pub const NV_ENC_STAT_VER: u32 = struct_version(2);
+
+#[repr(C)]
+pub struct NVencSequenceParamPayload {
+    version: u32,
+    in_buffer_size: u32,
+    sps_id: u32,
+    pps_id: u32,
+    spspps_buffer: *mut c_void,
+    output_spspps_payload_size: *mut u32,
+    rsvd: [u32; 250],
+    rsvd2: [*mut c_void; 64],
+}
+
+pub const NV_ENC_SEQUENCE_PARAM_PAYLOAD_VER: u32 = struct_version(1);
+
+#[repr(C)]
+pub struct NVencEventParams {
+    version: u32,
+    rsvd: u32,
+    completion_event: *mut c_void,
+    rsvd1: [u32; 254],
+    rsvd2: [*mut c_void; 64],
+}
+
+pub const NV_ENC_EVENT_PARAMS_VER: u32 = struct_version(2);
+
+#[repr(C)]
+pub struct NVencOpenEncodeSessionExParams {
+    pub version: u32,
+    pub device_type: NVencDeviceType,
+    pub device: *mut c_void,
+    rsvd: *mut c_void,
+    pub api_version: u32,
+    rsvd1: [u32; 253],
+    rsvd2: [*mut c_void; 64],
+}
+
+pub const NV_ENC_OPEN_ENCODE_SESSION_EX_PARAMS_VER: u32 = struct_version(1);

vendor/nvenc/src/sys/version.rs

@@ -0,0 +1,12 @@
+//! Contains the nvenc version numbers, encoded as they are in C, for the version this crate was built against
+
+pub const NVENC_MAJOR_VERSION: u16 = 13;
+pub const NVENC_MINOR_VERSION: u8 = 0;
+
+pub const NVENC_API_VERSION: u32 = NVENC_MAJOR_VERSION as u32 | (NVENC_MINOR_VERSION as u32) << 24;
+
+pub const NVENC_API_LIST_VERSION: u32 = struct_version(2);
+
+pub const fn struct_version(nvenc_api_version: u8) -> u32 {
+    NVENC_API_VERSION | (nvenc_api_version as u32) << 16 | 0x7 << 28
+}

viewer/src/main.rs

@@ -110,6 +110,8 @@ struct Stats {
     agent_sent: AtomicU64,
     /// H.264 解码失败计数（关键帧自愈验证指标）
     dec_fail: AtomicU64,
+    /// 当前是否处于「参考链断裂、等待 IDR」状态（HUD 显示 RECOVER）
+    awaiting_idr: AtomicBool,
     /// 帧到达间隔环形缓冲
     gaps: std::sync::Mutex<GapRing>,
 }
@@ -129,6 +131,7 @@ impl Default for Stats {
             agent_lost: AtomicU64::new(0),
             agent_sent: AtomicU64::new(0),
             dec_fail: AtomicU64::new(0),
+            awaiting_idr: AtomicBool::new(true),
             gaps: std::sync::Mutex::new(GapRing {
                 last: None,
                 ring: [0; 64],
@@ -218,9 +221,27 @@ async fn run(addr: String, port: u16, code: String) -> Result<()> {
 
     let (mut send, mut recv) = conn.open_bi().await?;
 
-    write_control(&mut send, &ControlMsg::Auth { code }).await?;
+    write_control(
+        &mut send,
+        &ControlMsg::Auth {
+            code,
+            proto_version: common::PROTO_VERSION,
+        },
+    )
+    .await?;
     match read_control(&mut recv).await? {
-        ControlMsg::AuthOk { width, height } => {
+        ControlMsg::AuthOk {
+            width,
+            height,
+            proto_version,
+        } => {
+            // 版本已在 Auth 里声明，这里再核对一次：防止被控端是旧版却"接受"了认证
+            if proto_version != common::PROTO_VERSION {
+                bail!(
+                    "protocol version mismatch: server={proto_version}, client={}",
+                    common::PROTO_VERSION
+                );
+            }
             println!("[viewer] auth ok, remote desktop {width}x{height}");
             // 流 2：键鼠输入 + Ping/Pong 独立通道，不与视频流竞争
             let (isend, irecv) = conn.open_bi().await?;
@@ -241,52 +262,134 @@ fn session(
     let (w, h) = (width as usize, height as usize);
     let stats = Arc::new(Stats::default());
 
-    // 读任务（流 1）：H.264 解码 → RGB → mpsc；同时统计端到端延迟与流量
-    let (frame_tx, frame_rx) = std::sync::mpsc::channel::<Vec<u8>>();
+    // 读任务（流 1）：H.264 解码 → RGB → 单槽 latest-wins；同时统计端到端延迟与流量
+    // 帧格式 (src_w, src_h, rgb)；(0,0,_) = 解码失败占位，触发 KeyFrameReq
+    // 单槽而非无界队列：渲染跟不上 60fps 到达率时旧帧直接被覆盖，绝不积压
+    //（无界 mpsc 在 NVENC 60fps 下会无限积压 → 延迟线性增长 + 渲染 drain 时
+    //  长时间阻塞窗口消息泵 → 窗口假死、HUD 停刷新）
+    let latest: Arc<std::sync::Mutex<Option<(u32, u32, Vec<u8>)>>> =
+        Arc::new(std::sync::Mutex::new(None));
     {
         let stats = stats.clone();
+        let latest = latest.clone();
         let mut decoder = openh264::decoder::Decoder::new()
             .map_err(|e| anyhow::anyhow!("decoder init failed: {e}"))?;
+        let mut rgb_buf: Vec<u8> = Vec::new();
+        let mut last_kfreq = Instant::now();
+        let mut skip_stale = 0u64;
+        let mut last_arr: Option<Instant> = None;
+        // 「等待 IDR」状态：参考链一旦断裂（跳帧或解码失败），后续 P 帧**必然**
+        // 解不出来。此时必须停止喂解码器，只等 IDR 重新同步。
+        //
+        // 之前没有这个状态，后果是：跳掉一帧后，每个 P 帧都被送进 decoder →
+        // 每个都失败 → 每个都打日志 → 每个都触发一次 KeyFrameReq。
+        // 表现为「decode failed」刷屏，且解码器反复在错误状态里挣扎。
+        //
+        // 放在 Stats 里（而非局部变量）以便 HUD 显示 RECOVER 状态。
+        // 初始 true：入会时已发 KeyFrameReq，拿到第一个 IDR 前不该硬解。
         tokio::spawn(async move {
+            let mut size_logged = false;
             loop {
                 match common::read_video_frame(&mut recv).await {
                     Ok((hdr, payload)) => {
                         stats.bytes.fetch_add(payload.len() as u64, Ordering::Relaxed);
                         stats.frames.fetch_add(1, Ordering::Relaxed);
+                        // 与上一帧的到达间隔：≤100ms 才算"突发到达"。
+                        // 桌面静止时 agent 以 2Hz 空闲重发，帧龄天然 ≥500ms，
+                        // 不能按陈旧帧丢弃——否则静止桌面所有帧被跳过 →
+                        // 永久黑屏 + KeyFrameReq/IDR 死循环（v0.8 实测教训）
+                        let burst = matches!(last_arr, Some(t) if t.elapsed() <= Duration::from_millis(100));
+                        last_arr = Some(Instant::now());
                         // 端到端延迟 = 接收时刻 - 时钟偏移 - 采集时刻（EMA 平滑）
                         let mut est = None;
+                        let mut stale = false;
                         if stats.offset_valid.load(Ordering::Relaxed) {
                             let e =
                                 now_ms() as i64 - stats.offset.load(Ordering::Relaxed)
                                     - hdr.ts_ms as i64;
                             if (0..5000).contains(&e) {
-                                let old = stats.e2e.load(Ordering::Relaxed) as i64;
-                                let sm = if stats.e2e_valid.load(Ordering::Relaxed) {
-                                    (old * 4 + e) / 5
-                                } else {
-                                    e
-                                };
-                                stats.e2e.store(sm as u64, Ordering::Relaxed);
-                                stats.e2e_valid.store(true, Ordering::Relaxed);
-                                est = Some(sm);
+                                // 积压判定必须同时满足：突发到达（背靠背）+ 帧龄>250ms。
+                                // QUIC 可靠有序，积压须逐帧读出但可不解码——跳过解码
+                                // 让队列以网络速度排空
+                                stale = burst && e > 250;
+                                // 空闲重发帧的帧龄不代表显示延迟，不计入 EMA
+                                if burst || e < 250 {
+                                    let old = stats.e2e.load(Ordering::Relaxed) as i64;
+                                    let sm = if stats.e2e_valid.load(Ordering::Relaxed) {
+                                        (old * 4 + e) / 5
+                                    } else {
+                                        e
+                                    };
+                                    stats.e2e.store(sm as u64, Ordering::Relaxed);
+                                    stats.e2e_valid.store(true, Ordering::Relaxed);
+                                    est = Some(sm);
+                                }
                             }
                         }
                         stats.on_frame_arrival(est);
+                        if stale {
+                            skip_stale += 1;
+                            if skip_stale % 60 == 1 {
+                                eprintln!(
+                                    "[viewer] backlog: stale burst frame skipped (total {skip_stale})"
+                                );
+                            }
+                            // 跳帧直接切断 H.264 参考链：之后所有 P 帧都解不出来。
+                            // 立刻转入「等待 IDR」并请求关键帧，绝不能让后续 P 帧
+                            // 继续喂给解码器（那是必然失败的徒劳尝试）。
+                            stats.awaiting_idr.store(true, Ordering::Relaxed);
+                            if last_kfreq.elapsed() >= Duration::from_millis(200) {
+                                last_kfreq = Instant::now();
+                                if let Ok(mut slot) = latest.lock() {
+                                    *slot = Some((0, 0, Vec::new()));
+                                }
+                            }
+                            continue;
+                        }
+                        // 参考链未恢复时，P 帧一律跳过——此为正确性要求，不是优化。
+                        if stats.awaiting_idr.load(Ordering::Relaxed) && !hdr.keyframe {
+                            skip_stale += 1;
+                            // 补发请求，防止首次 KeyFrameReq 丢失（时间闸限频）
+                            if last_kfreq.elapsed() >= Duration::from_millis(200) {
+                                last_kfreq = Instant::now();
+                                if let Ok(mut slot) = latest.lock() {
+                                    *slot = Some((0, 0, Vec::new()));
+                                }
+                            }
+                            continue;
+                        }
+                        // 拿到 IDR 才能重新开始解码
+                        if hdr.keyframe {
+                            stats.awaiting_idr.store(false, Ordering::Relaxed);
+                        }
                         match decoder.decode(&payload) {
                             Ok(Some(yuv)) => {
                                 let (dw, dh) = yuv.dimensions();
-                                let mut rgb = vec![0u8; dw * dh * 3];
-                                yuv.write_rgb8(&mut rgb);
-                                if frame_tx.send(rgb).is_err() {
-                                    break;
+                                let (dw, dh) = (dw as u32, dh as u32);
+                                if !size_logged {
+                                    size_logged = true;
+                                    eprintln!(
+                                        "[viewer] decoded frame {dw}x{dh} (window {}x{})",
+                                        hdr.width, hdr.height
+                                    );
+                                }
+                                rgb_buf.clear();
+                                rgb_buf.resize(dw as usize * dh as usize * 3, 0);
+                                yuv.write_rgb8(&mut rgb_buf);
+                                // latest-wins：直接覆盖旧帧，无积压
+                                if let Ok(mut slot) = latest.lock() {
+                                    *slot = Some((dw, dh, rgb_buf.clone()));
                                 }
                             }
                             Ok(None) => {}
                             Err(e) => {
-                                // 解码异常：请求被控端强制关键帧
+                                // 解码异常：参考链已不可信，转入等待 IDR
+                                stats.awaiting_idr.store(true, Ordering::Relaxed);
                                 stats.dec_fail.fetch_add(1, Ordering::Relaxed);
                                 eprintln!("[viewer] decode failed: {e}, request keyframe");
-                                let _ = frame_tx.send(Vec::new()); // 空帧占位唤醒渲染循环
+                                if let Ok(mut slot) = latest.lock() {
+                                    *slot = Some((0, 0, Vec::new()));
+                                }
                             }
                         }
                     }
@@ -322,7 +425,10 @@ fn session(
                         stats.offset_valid.store(true, Ordering::Relaxed);
                     }
                     Ok(_) => {}
-                    Err(_) => break,
+                    Err(e) => {
+                        eprintln!("[viewer] control stream closed: {e} (RTT/LOSS 将停止更新)");
+                        break;
+                    }
                 }
             }
         });
@@ -342,9 +448,11 @@ fn session(
     let push = |tx: &tokio::sync::mpsc::UnboundedSender<Vec<u8>>, m: ControlMsg| {
         let _ = tx.send(common::encode_control(&m));
     };
+    // 入会立即请求 IDR：避免从 GOP 中间接入收到裸 P 帧解码失败导致启动黑屏
+    push(&msg_tx, ControlMsg::KeyFrameReq);
 
     let mut window = Window::new(
-        "mvp-remote viewer (Esc 退出)",
+        "mvp-remote v0.8.1-CatchUp (Esc 退出)",
         w,
         h,
         WindowOptions {
@@ -379,18 +487,15 @@ fn session(
             push(&msg_tx, ControlMsg::Ping(now_ms()));
         }
 
-        // 1) 渲染最新帧（只保留最新，丢弃积压）；空帧=解码异常，请求关键帧
-        loop {
-            match frame_rx.try_recv() {
-                Ok(raw) => {
-                    if raw.is_empty() {
-                        push(&msg_tx, ControlMsg::KeyFrameReq);
-                    } else if raw.len() == w * h * 3 {
-                        blit(&mut buffer, &raw);
-                        dirty = true;
-                    }
+        // 1) 渲染最新帧（单槽 latest-wins：每迭代只取最新一帧，天然防积压）
+        if let Ok(mut slot) = latest.lock() {
+            if let Some((sw, sh, raw)) = slot.take() {
+                if raw.is_empty() {
+                    push(&msg_tx, ControlMsg::KeyFrameReq);
+                } else if sw > 0 && sh > 0 {
+                    blit(&mut buffer, w, h, &raw, sw as usize, sh as usize);
+                    dirty = true;
                 }
-                Err(_) => break,
             }
         }
 
@@ -456,7 +561,8 @@ fn session(
             }
         }
 
-        // 6) HUD：每秒刷新一次指标，画在右上角
+        // 6) HUD：指标每秒刷新一次；每秒至少强制呈现一次（视频冻结/黑屏时 HUD 依然可见）
+        let mut need_present = dirty;
         let (hud_loss, hud_jit, hud_p95, hud_dec);
         if hud_last.elapsed() >= Duration::from_secs(1) {
             let f = stats.frames.load(Ordering::Relaxed);
@@ -479,13 +585,14 @@ fn session(
             hud_p95 = stats.gap_p95();
             hud_dec = stats.dec_fail.load(Ordering::Relaxed);
             hud_last = Instant::now();
+            need_present = true; // HUD 面板每秒至少重绘一次
         } else {
             hud_loss = f64::NAN;
             hud_jit = 0;
             hud_p95 = None;
             hud_dec = 0;
         }
-        if dirty {
+        if need_present {
             let rtt = stats.rtt.load(Ordering::Relaxed);
             let e2e = stats.e2e.load(Ordering::Relaxed);
             let e2e_ok = stats.e2e_valid.load(Ordering::Relaxed);
@@ -520,6 +627,21 @@ fn session(
                     ("P95", &hud_p95.map(|p| format!("{p}ms")).unwrap_or("--".into()), p95_c),
                     ("LOSS", &loss_str, loss_c),
                     ("DECFAIL", &format!("{hud_dec}"), if hud_dec == 0 { C_GRAY } else { C_RED }),
+                    (
+                        // 参考链断裂、正在等 IDR 的显式指示：此时画面冻结是**预期行为**，
+                        // 不是故障。没有这个指示，用户会以为软件卡死。
+                        "STATE",
+                        &if stats.awaiting_idr.load(Ordering::Relaxed) {
+                            "RECOVER".to_string()
+                        } else {
+                            "OK".to_string()
+                        },
+                        if stats.awaiting_idr.load(Ordering::Relaxed) {
+                            C_AMBER
+                        } else {
+                            C_GREEN
+                        },
+                    ),
                     ("RATE", &format!("{:.0}MBP", hud_mbps), C_GRAY),
                     ("RES", &format!("{w}x{h}"), C_GRAY),
                 ],
@@ -675,9 +797,17 @@ fn draw_hud(buffer: &mut [u32], w: usize, lines: &[(&str, &str, u32)]) {
     }
 }
 
-/// RGB888 字节（openh264 解码输出）→ minifb 0RGB u32 缓冲
-fn blit(buffer: &mut [u32], raw: &[u8]) {
-    for (px, chunk) in buffer.iter_mut().zip(raw.chunks_exact(3)) {
-        *px = ((chunk[0] as u32) << 16) | ((chunk[1] as u32) << 8) | chunk[2] as u32;
+/// RGB888 字节（openh264 解码输出）→ minifb 0RGB u32 缓冲。
+/// 支持源尺寸与窗口不同（解码器可能对齐到 16 倍数，如 1080→1088）：
+/// 逐行拷贝重叠区域，源小于窗口时右侧/下方留黑。
+fn blit(buffer: &mut [u32], w: usize, h: usize, raw: &[u8], dw: usize, dh: usize) {
+    let cw = w.min(dw);
+    let ch = h.min(dh);
+    for row in 0..ch {
+        let src = &raw[row * dw * 3..row * dw * 3 + cw * 3];
+        let dst = &mut buffer[row * w..row * w + cw];
+        for (px, chunk) in dst.iter_mut().zip(src.chunks_exact(3)) {
+            *px = ((chunk[0] as u32) << 16) | ((chunk[1] as u32) << 8) | chunk[2] as u32;
+        }
     }
 }

借鉴映射与落地规范.md

@@ -0,0 +1,301 @@
+# 借鉴映射与落地规范
+
+> 配套《多平台架构设计.md》。本文回答三个问题：**每个模块怎么设计、看谁、抄什么、不抄什么。**
+> 状态：架构部分已定稿；第 2 章的「逆向需求清单」等同事的逆向资料回填。
+
+---
+
+## 0. 使用方式
+
+| 角色 | 看哪几章 |
+|---|---|
+| A（被控侧） | §3.5 platform、§3.6 agent-core、§4 表中 agent 相关行 |
+| B（主控+协议） | §3.1–3.4、§3.7 viewer-core、§5 许可 |
+| 移动端（待补人） | §3.4 media（解码后端）、§3.8 apps |
+| 全员 | §2 逆向红线（踩了会出大事） |
+
+---
+
+## 1. 两条铁律
+
+1. **架构由需求决定，不由参考项目决定。** 参考项目用来解决"这一块业界怎么做的"，不是用来决定"我们做成什么样"。
+2. **能抄的是算法和协议思路，抄不到的是平台集成和 UI。** 后者是体力活，任何参考项目都救不了（它们自己也是硬写的）。
+
+---
+
+## 2. 逆向资料的用法与红线
+
+### 2.1 红线（务必转告同事）
+
+| 可以做 | 不可以做 |
+|---|---|
+| 记录**功能清单、交互流程、界面布局** | 把反编译产物、反汇编清单提交进仓库 |
+| 记录**用户可见的错误提示、状态显示** | 逐字复制对方的 UI 文案、图标、素材 |
+| 推断**产品模型**（账号/设备/授权怎么设计） | 抄对方私有协议的具体编码（抄了也不能互通） |
+| 记录**网络行为的宏观特征**（是否中转、连接耗时） | 提取并移植对方的算法实现 |
+
+**仓库里只提交"行为结论"，不提交"逆向产物"。** 建议逆向资料单独放一个**不纳入 git** 的目录（或内部网盘），文档里只写结论。这条不是洁癖——商用产品里出现竞品反编译代码是实打实的法律风险。
+
+### 2.2 逆向需求清单（直接发给同事）
+
+**A. 产品功能面（最重要，优先做）**
+
+1. 主控端完整交互流程截图流：登录 → 设备列表 → 连接（输密码/免密）→ 会话中 → 断开
+2. 每个平台的功能矩阵：Win/Linux/Android/iOS 各有哪些功能、哪些缺失
+3. 会话中工具栏全清单：分辨率切换、多屏、文件传输、剪贴板、音频开关、画质/帧率档位、游戏模式
+4. 设置项全清单（分"被控设置"和"主控设置"两类）
+5. 错误提示文案全集 + 断线重连时的用户可见行为
+
+**B. 身份与授权模型**
+
+6. 设备 ID 的形式（长度/字符集）、在哪里查看、能否自定义
+7. 授权方式有几种：临时密码 / 固定密码 / 免密白名单 / 账号直接授权？默认是哪种
+8. 账号体系：是否必须登录、登录后设备列表怎么呈现、一台设备能否被多账号访问
+9. 被控端的"允许谁连"控制（黑名单/白名单/单次确认弹窗）
+
+**C. 被控端形态**
+
+10. 是不是系统服务？开机自启吗？锁屏/注销/UAC 提权界面能不能连？
+11. 安装包形态、是否需要管理员权限、卸载残留
+
+**D. 网络行为（只看宏观，不要深入协议）**
+
+12. 连接时用户是否能看到"直连 / 中转"标识
+13. 典型连接耗时、转中继时的画质变化
+14. 端口/协议宏观特征：UDP 还是 TCP 为主、监听端口是否固定
+
+**E. 商业化（可选但有用）**
+
+15. 免费额度/收费点/增值功能边界
+
+### 2.3 逆向资料回填位置
+
+| 资料 | 回填到 |
+|---|---|
+| A 组 | 本文 §6「产品范围基线」+ 里程碑取舍 |
+| B/C 组 | §3.3 session（身份模型影响状态机） |
+| D 组 | §3.2 conn（验证我们的打洞/中继策略） |
+| E 组 | 不在本文，属于商业决策 |
+
+---
+
+## 3. 模块级设计规范
+
+### 3.1 `proto` — 协议
+
+**职责**：信令消息、控制消息、媒体容器格式。三端（agent/viewer/信令服务）共享契约。
+
+**设计点**
+- **双协议分离**：信令协议（`signaling.rs`，文本友好、低频、可 JSON）与媒体控制协议（`lib.rs`，二进制、高频）**不要混**。前者要便于抓包排查，后者要极致紧凑。
+- **版本协商**：`SIGNALING_VERSION` 不一致直接拒绝，不做兼容。媒体协议用"能力协商"而非版本号（见 §3.3）。
+- **消息演进**：现用 bincode。二期若换 protobuf，**必须一次性切换**，不要两套并存。
+- **单帧长度上限**：现有 `ensure!(len < 1<<20)` 这类边界检查要保留，且信令侧对端候选列表必须经 `sanitize_candidates`。
+
+**看谁 / 抄什么**
+
+| 项目 | 抄什么 | 不抄 |
+|---|---|---|
+| RustDesk `libs/hbb_common` | 消息分类方式（信令/中继/控制分层） | 具体协议编码（AGPL + 抄了不互通） |
+| Moonlight `moonlight-common-c` | **控制消息与媒体分离**的成熟做法 | 它的私有控制协议 |
+
+**产出物**：`crates/proto/src/{lib.rs, signaling.rs}`
+
+---
+
+### 3.2 `conn` — 连接层（最值得借鉴的一块）
+
+**职责**：信令客户端、打洞编排、路径选择、QUIC 会话、保活。
+
+**设计点**
+- **`PathProvider` 抽象**（已在《打洞与信令设计.md》定义）：现在只实现 Direct，类型上预留 Relay。
+- **打洞编排**：候选收集（v6/Host/UPnP/Reflexive/Predicted）→ 排序 → 信令交换 → 同步打洞 → 落选清理。
+- **同一 socket 双角色**：打洞用的 UDP socket 必须与后续 QUIC 是同一个，否则洞不在同一映射上。
+- **保活**：按双方 `binding_timeout_s` 折半，5–60s。**这是"连一会儿就断"的根治点。**
+- **不用 QUIC 握手当探测**：先用轻量 UDP 探测包确认通路（秒级失败），再 `connect`。
+
+**看谁 / 抄什么**
+
+| 项目 | 抄什么 | 许可 |
+|---|---|---|
+| **iroh** | **整套**：打洞编排、中继回退、地址发现。技术栈与你们重合（Rust + quinn） | Apache-2.0 ✅ **可直接依赖** |
+| webrtc-rs / pion/ice | ICE 状态机、候选配对（candidate pairing）策略 | MIT/Apache ✅ |
+| Tailscale / headscale | DERP 中继的**回退判定条件**与降级策略 | BSD-3 ✅ |
+| RustDesk `rendezvous_mediator` 相关 | 信令 ↔ 打洞的**编排顺序**（读思路） | AGPL ⚠️ 只读 |
+| libjuice / libnice | ICE 精简实现（作为对照，不必依赖） | MPL / LGPL |
+
+> **建议**：`conn` 优先评估**直接依赖 iroh**。它解决的正是你们纠结的"打洞要不要中继"，而且给了"直连优先、失败回退"的完整实现。自研仅当 iroh 有硬伤（体积、可控性、特定 NAT 场景）时才考虑。
+
+**产出物**：`crates/conn/`
+
+---
+
+### 3.3 `session` — 会话编排（"一体程序"的核心）
+
+**职责**：会话状态机、角色仲裁、能力协商、生命周期管理、被控端准入控制。
+
+**设计点**
+- **状态机双线**：主控线 / 被控线各自独立，同一进程可并发（被控中也能主控别人）。
+- **角色仲裁**：打洞阶段双方对称，**谁先打通谁定角色**（被控方做 QUIC server），不预设。
+- **能力协商**：被控端上报硬件能力（可用编码器、最大分辨率、帧率上限、是否支持音频），主控端选择。**用能力协商代替版本号**——旧客户端缺字段就是"不支持"，天然向后兼容。
+- **准入控制**：单会话/多会话、白名单、单次确认弹窗。**这一条直接来自 §2 逆向需求 B 组第 7/9 项**，等资料回填后定稿。
+- **失败出口**：`PunchFailReason::user_hint()` 必须一路透传到 UI，不允许出现无解释的"连接中"。
+
+**看谁 / 抄什么**
+
+| 项目 | 抄什么 |
+|---|---|
+| RustDesk `src/server` / `src/client` | 会话生命周期与连接管理的分层方式（读思路） |
+| Sunshine + Moonlight | host/client 两侧的**能力协商**与配置下发流程 |
+| — | 状态机本身建议自己画，不要套用别人的（各家产品逻辑差异大） |
+
+**产出物**：`crates/session/`
+
+---
+
+### 3.4 `media` — 编解码抽象
+
+**职责**：编码/解码 trait、各平台后端、零拷贝通路、码率自适应闭环。
+
+**设计点**
+- **不对称策略**：**编码用 FFmpeg**（只在 Win/Linux，桌面端不心疼包体），**解码用平台原生**（四个主控平台都要，移动端必须硬解且要零拷贝）。
+- **trait 收口**（见《多平台架构设计.md》§4 决策 4），上层不允许出现平台判断。
+- **零拷贝**：解码器直接输出到渲染表面（D3D11 纹理 / `SurfaceView` / `CAMetalLayer`），中间不做 CPU 拷贝。
+- **软硬兜底**：硬编失败回落 openh264；硬解失败回落软解（桌面可，移动端应直接提示而非硬撑）。
+- **码率自适应闭环**：接收端统计（丢包/抖动/帧间隔 p95）→ 反馈编码端 → AIMD 调码率。协议已留 `RateReport`（见 B侧设计文档 B2）。
+
+**看谁 / 抄什么**
+
+| 项目 | 抄什么 | 许可 |
+|---|---|---|
+| **libwebrtc** `modules/congestion_controller/goog_cc` | **GCC 拥塞控制**的完整思路——这是码率自适应的教科书 | BSD-3 ✅ 可参考可移植 |
+| **libwebrtc** `modules/video_coding/jitter_buffer` | 抖动缓冲与丢包重排 | BSD-3 ✅ |
+| **Sunshine** `src/video` + `src/platform` | **抓屏→编码→打包**的完整管线组织，尤其是多编码器抽象与回落 | GPL-3.0 ⚠️ 只读 |
+| **Moonlight** `moonlight-common-c` | 接收端解码→渲染→HUD 的管线，以及**丢包恢复策略** | GPL-3.0 ⚠️ 只读 |
+| FFmpeg | NVENC/QSV/AMF/VAAPI 的调用姿势与参数 | LGPL/GPL ⚠️ 注意构建选项 |
+| openh264 | 软编兜底（已在用） | BSD ✅ |
+
+**产出物**：`crates/media/`
+
+---
+
+### 3.5 `platform` — L0 平台层（抄不到，只能自己写）
+
+**职责**：抓屏、注入、渲染表面、音频 IO、权限、常驻。
+
+**为什么抄不到**：这层是各平台 API 的体力活。参考项目能给的是"用哪个 API、踩过什么坑"，不是可复用代码。
+
+**设计点**
+
+| 平台 | 关键坑 |
+|---|---|
+| Win 抓屏 | DXGI DD 在**会话切换/RDP 断开**时失效，必须处理 `DXGI_ERROR_ACCESS_LOST` 并重建 |
+| Win 注入 | 服务进程注入到用户会话需要 `CreateProcessAsUser` + 会话隔离处理；UAC 提权界面默认收不到输入（需 `uiAccess` 签名） |
+| Win 常驻 | 服务 + 用户会话代理双进程，锁屏可连靠的是**服务侧保持会话** |
+| Linux 抓屏 | X11 用 XShm/XComposite；**Wayland 必须走 PipeWire + xdg-desktop-portal**（有授权弹窗，无法静默） |
+| Linux 注入 | X11 用 XTest；**Wayland 用 libei/uinput**（uinput 需 root 或 udev 规则） |
+| Linux 常驻 | systemd 服务 + 会话切换处理（Wayland 的 portal 授权是最大障碍） |
+| 渲染表面 | 四平台各一套；**必须支持"表面尺寸≠视频尺寸"的缩放与拉伸模式** |
+
+**看谁**
+
+| 项目 | 看什么 |
+|---|---|
+| Sunshine `src/platform/{windows,linux}` | 抓屏与注入的分平台组织方式、Wayland 处理 |
+| RustDesk `libs/scrap` | 同样的抓屏抽象（多平台统一 trait）——**这是它最有价值的部分** |
+| libei / xdg-desktop-portal 官方文档 | Wayland 的正规姿势（别用野路子） |
+
+**产出物**：`crates/platform/`
+
+---
+
+### 3.6 `agent-core` / `viewer-core` — 两条链路
+
+**职责**：把现有 `agent`/`viewer` 的 main 逻辑抽成库，供一体程序按角色调用。
+
+**设计点**
+- **`agent-core`**：capture → encode → 打包 → 发送；输入接收 → 注入。A 已在进行中（`agent-core/src/lib.rs` 398 行）。
+- **`viewer-core`**：接收 → 解码 → 渲染表面；输入采集 → 发送。
+- **生命周期**：两者都不允许自己决定退出，由 `session` 层驱动。
+- **单槽 latest-wins**：现有做法保留（网络慢时只发最新帧），这是正确设计。
+
+**看谁**：RustDesk（抽库方式）、Sunshine/Moonlight（管线组织）。
+
+**产出物**：`crates/agent-core/`、`crates/viewer-core/`
+
+---
+
+### 3.7 `apps/*` — UI 与常驻（第二个抄不到的地方）
+
+**职责**：UI 壳、常驻服务、安装包。
+
+**设计点**
+- **硬约束**：所有业务逻辑在 Rust，UI 只调一层稳定 API（决定了将来能否换 UI 框架）。
+- **视频走原生子表面**，绝不在 WebView 里逐帧渲染。
+- **一体 = 一个安装包 + 两个进程**：前台 UI + 后台被控服务，本地 IPC。
+- **移动端只有前台进程**（纯主控）。
+
+**看谁**
+
+| 项目 | 抄什么 |
+|---|---|
+| Tauri v2 官方 mobile 示例 | WKWebView/Android WebView 与原生 surface 的叠加方式 |
+| RustDesk `flutter/` | 同一套 UI 适配多端的组织方式（它用 Flutter，可对照取舍） |
+| Moonlight `moonlight-android` / `moonlight-ios` | **移动端主控的完整交互**：虚拟鼠标、手势映射、软键盘、性能档位 |
+
+**产出物**：`apps/desktop/`、`apps/android/`、`apps/ios/`、`apps/daemon-win/`、`apps/daemon-linux/`
+
+---
+
+## 4. 借鉴映射总表
+
+| 模块 | 主参考 | 许可 | 用法 |
+|---|---|---|---|
+| 打洞 / 中继 / 地址发现 | **iroh** | Apache-2.0 | **直接依赖** |
+| ICE / STUN / TURN | webrtc-rs、pion、coturn | MIT/BSD | 依赖或参考 |
+| 中继回退策略 | Tailscale / headscale | BSD-3 | 读思路 |
+| 拥塞控制 / 抖动缓冲 | **libwebrtc** | BSD-3 | 读思路，重写 |
+| 抓屏→编码管线 | **Sunshine** | GPL-3.0 | 只读 |
+| 接收端解码→渲染 | **Moonlight** | GPL-3.0 | 只读 |
+| 整机架构 / 抽库方式 | **RustDesk** | **AGPL-3.0** | **只读，绝不抄代码** |
+| 移动端主控交互 | Moonlight mobile | GPL-3.0 | 只读 |
+| Rust↔移动端绑定 | UniFFI | MPL-2.0 | 依赖 |
+
+---
+
+## 5. 许可结论与依赖策略
+
+| 许可 | 能否进产品 | 项目 |
+|---|---|---|
+| MIT / Apache-2.0 / BSD | ✅ 可依赖、可移植 | iroh、webrtc-rs、pion、coturn、libwebrtc、UniFFI(MPL 弱) |
+| LGPL | ⚠️ 可动态链接，改库要开源 | FFmpeg、GStreamer、libnice |
+| **GPL / AGPL** | ❌ **不可进代码** | **RustDesk(AGPL)、Sunshine/Moonlight(GPL)** |
+
+**AGPL 特别提示**：网络服务也算分发。引入 RustDesk 代码 = 你们整个产品连服务端都要开源。
+
+**依赖准入流程**（补充进《Git协作规范.md》的合并规则）：新增依赖必须在 PR 描述里写明**许可证 + 是否修改其源码**，由另一人确认。
+
+---
+
+## 6. 产品范围基线（待逆向资料回填）
+
+> 拿到 §2.2 的 A 组资料后填这里，用于定"做哪些功能、砍哪些平台"。
+
+| 功能 | UU 有 | 我们一期 | 备注 |
+|---|---|---|---|
+| 桌面画面 | | ✅ | 已有 |
+| 键鼠控制 | | ✅ | 已有 |
+| 音频 | | ? | |
+| 文件传输 | | ? | |
+| 剪贴板同步 | | ? | |
+| 多屏 | | ? | |
+| 移动端主控 | | ? | 人力问题见《多平台架构设计.md》§8 |
+| 无人值守 | | ? | 安全含义，需固定密码+白名单 |
+
+---
+
+## 7. 待拍板
+
+1. `conn` 是否**直接依赖 iroh**（而不是自研打洞）——建议先花 2 天做技术验证
+2. 逆向资料回来后，"产品范围基线"的取舍（尤其移动端）
+3. `media` 编码侧是否引入 FFmpeg（包体/构建成本 vs 省下的适配工作）
+4. 依赖准入流程是否写进《Git协作规范.md》

多平台架构设计.md

@@ -0,0 +1,315 @@
+# 多平台架构设计
+
+> 需求：**主控端** Windows / Linux / Android / iOS；**被控端** Windows / Linux。
+> 桌面端（Win/Linux）主控+被控合为一体；移动端仅主控。
+> 前置文档：《打洞与信令设计.md》《B侧设计文档.md》《构建运行手册.md》
+
+---
+
+## 0. 一句话架构
+
+**一个 Rust 核心 + 一层薄平台适配 + 可替换的 UI 壳。**
+业务逻辑（连接/打洞/会话/协议）100% 在 Rust 里跨平台共享；只有**抓屏、编解码、注入、渲染表面**四件事分平台写；UI 层只管"壳"，**永远不碰视频流**。
+
+---
+
+## 1. 纵向分层
+
+```
+┌──────────────────────────────────────────────────────────┐
+│ L4  UI 壳            Win/Linux/Android/iOS  各自实现       │
+│     设备列表 / 设置 / 连接管理 / 悬浮控件                   │
+│     ★ 绝不放视频渲染                                       │
+├──────────────────────────────────────────────────────────┤
+│ L3  会话层  session             纯 Rust，全平台共享        │
+│     会话状态机、角色仲裁、能力协商、keepalive 调度          │
+├──────────────────────────────────────────────────────────┤
+│ L2  连接层  conn                纯 Rust，全平台共享        │
+│     信令客户端、打洞编排、中继接口(预留)、QUIC(quinn)多流    │
+├──────────────────────────────────────────────────────────┤
+│ L1  媒体层  media               Rust + 平台后端            │
+│     编码/解码/色彩转换/缩放/音频(Opus)  trait 化            │
+├──────────────────────────────────────────────────────────┤
+│ L0  平台层  platform            唯一必须分平台的地方        │
+│     抓屏 / 注入 / 音频IO / 渲染表面 / 权限 / 常驻           │
+└──────────────────────────────────────────────────────────┘
+```
+
+**分界线原则**：L1 以上任何代码不允许出现 `#[cfg(windows)]`。平台差异只能通过 L0 的 trait 暴露。
+
+---
+
+## 2. 仓库结构
+
+```
+remote/
+├── crates/
+│   ├── proto/          # 协议：信令 + 控制 + 媒体容器（现 common/）
+│   ├── conn/           # 信令客户端 / 打洞编排 / QUIC 会话 / 中继接口
+│   ├── session/        # 会话状态机 + 角色仲裁（"一体"的核心）
+│   ├── agent-core/     # 被控链路：capture → encode → send      [A 已在做]
+│   ├── viewer-core/    # 主控链路：recv → decode → surface
+│   ├── media/          # 编解码 trait + 各平台后端 + openh264 软兜底
+│   └── platform/       # L0 实现，按 cfg 编译各平台
+├── apps/
+│   ├── desktop/        # Tauri v2 壳：Win/Linux 一体程序
+│   ├── android/        # 主控（Tauri mobile 或原生 Kotlin）
+│   ├── ios/            # 主控（Tauri mobile 或原生 Swift）
+│   ├── daemon-win/     # Windows 服务：被控常驻
+│   └── daemon-linux/   # systemd：被控常驻
+├── bindings/           # UniFFI 生成的 Kotlin/Swift 绑定
+└── tools/              # bench / 信令服务器
+```
+
+`agent-core` 与 `viewer-core` 的拆分是**一体化的前提**：现在的 `agent`/`viewer` 是两个 main，必须先变成库，才能被同一个进程按角色调用。A 正在做的 `agent-core` 抽取就是在铺这条路。
+
+---
+
+## 3. 平台能力矩阵
+
+| 能力 | Windows | Linux | Android | iOS |
+|---|---|---|---|---|
+| 抓屏 | DXGI Desktop Duplication | X11 (XShm) / Wayland (PipeWire portal) | — | — |
+| 硬编 | NVENC / QSV / AMF | VAAPI / NVENC | — | — |
+| 硬解 | D3D11VA / NVDEC | VAAPI | MediaCodec | VideoToolbox |
+| 渲染表面 | D3D11 子窗口 | X11/GL 子窗口 | SurfaceView | UIView + CAMetalLayer |
+| 键鼠注入 | SendInput | XTest / uinput / libei | — | — |
+| 键鼠采集 | Raw Input | evdev | 触摸→鼠标映射 | 触摸→鼠标映射 |
+| 音频出 | WASAPI loopback | PulseAudio monitor | — | — |
+| 音频入/放 | WASAPI | PulseAudio | AudioTrack | AVAudioEngine |
+| 常驻服务 | Windows Service | systemd | — | — |
+| **角色** | **主 + 被** | **主 + 被** | **仅主** | **仅主** |
+
+移动端没有"被控"，所以 Android/iOS **不需要**抓屏、编码、注入、服务化——少了一半工作量，这是需求里最省事的一条。
+
+---
+
+## 4. 六个关键决策
+
+### 决策 1：视频渲染绝不走 UI 框架
+
+从 WebView / Compose / Flutter 里逐帧渲染 60fps 视频必然掉帧、增延迟。
+**做法**：UI 框架只画"壳"，视频走**原生子表面**叠加在 UI 之上——
+Win: 子 HWND + D3D11；Linux: 子窗口 + GL；Android: `SurfaceView`；iOS: `UIView` + `CAMetalLayer`。
+MediaCodec / VideoToolbox 都能**直接解码到该 Surface，零拷贝**。这是 Parsec/ToDesk 这类产品的通行做法。
+
+### 决策 2：UI 框架 —— 推荐 Tauri v2，但必须可替换
+
+| 方案 | 覆盖 | 评价 |
+|---|---|---|
+| **Tauri v2** | Win/Linux/Android/iOS | ✅ 推荐：Rust 原生、一套 UI 四端、IPC 天然 |
+| Flutter | 四端 | UI 强，但 Rust 桥（flutter_rust_bridge）+ 平台视图叠加更绕 |
+| 各平台原生 ×4 | 四端 | 性能最好，**2-3 人团队不可能维护** |
+
+选 Tauri v2 的理由：你们本来就写 Rust，视频走原生表面后 WebView 只做表单和列表，性能足够。
+**代价**：Tauri 移动端还不够成熟（WKWebView 与原生 surface 叠加、生命周期）。所以——
+
+> **硬性约束：所有业务逻辑必须在 Rust 里，UI 只通过一层稳定 API 调用。**
+> 这样移动端若体验不达标，可以单点退化成原生 Kotlin/Swift + UniFFI，桌面仍用 Tauri，核心零改动。
+
+### 决策 3：Rust ↔ 移动端绑定用 UniFFI
+
+6 个平台角色组合下手写 JNI/FFI 会失控。UniFFI 从 Rust 生成 Kotlin/Swift 绑定，含 async、错误类型、对象生命周期，是当前标准解法。
+
+### 决策 4：编码用 FFmpeg，解码用平台原生
+
+不对称，但都有理由：
+
+- **编码（只在 Win/Linux 被控端）**：用 FFmpeg 统一接管 NVENC/QSV/AMF/VAAPI，openh264 软编兜底。桌面端不心疼包体，省下大量适配。
+- **解码（四个主控平台都要）**：直接用平台原生 API。
+  - 移动端**必须**硬解（软解烧电池、发热、跑不动 1080p60）
+  - 平台原生能零拷贝直出渲染表面，FFmpeg 反而多一次拷贝
+  - 绕开 FFmpeg 在 Android/iOS 上的交叉编译地狱和许可问题
+
+`media` crate 用 trait 收口：
+
+```rust
+pub trait VideoDecoder {
+    fn configure(&mut self, cfg: &VideoConfig, target: SurfaceHandle) -> Result<()>;
+    fn decode(&mut self, packet: &[u8]) -> Result<Option<FrameHandle>>;
+}
+
+pub trait VideoEncoder {
+    fn configure(&mut self, cfg: &EncodeConfig) -> Result<()>;
+    fn encode(&mut self, frame: &FrameHandle, out: &mut Vec<u8>) -> Result<()>;
+    fn request_keyframe(&mut self);
+}
+```
+
+### 决策 5："一体程序" = 一个安装包 + 两个进程
+
+用户视角是一个 app，实现上职责分离：
+
+```
+        ┌────────────────────────┐        ┌──────────────────────────┐
+        │   前台进程（UI）         │  IPC   │   后台常驻（被控服务）      │
+        │   主控画面 / 设备列表     │<──────>│   抓屏·编码·注入·保活      │
+        │   退出即结束             │ 本地管道│   开机自启 / 锁屏可连      │
+        └────────────────────────┘        └──────────────────────────┘
+                  ▲                                     ▲
+                  │ 移动端只有这一个                      │ 仅 Win/Linux
+```
+
+理由：**两种角色的生命周期天然冲突**——被控要"开机就在、没人操作也在"，主控要"跟窗口走、关了就走"。硬塞进一个进程会导致主控一退出就掉线。
+IPC 用命名管道（Win）/ Unix socket（Linux），或复用 QUIC 走本地回环。
+
+### 决策 6：中继接口必须预留 —— 哪怕现在不实现
+
+`conn` 层定义：
+
+```rust
+pub trait PathProvider {
+    /// 返回一条可用数据通道：直连优先，失败时可回退
+    async fn establish(&self, peer: &PeerInfo) -> Result<Path>;
+}
+
+pub enum Path { Direct { addr: SocketAddr }, Relay { endpoint: EndpointId } }
+```
+
+现在只实现 `Direct`。**但类型上留出 `Relay`**，将来补中继不必动会话层。
+
+> ⚠️ **这条与"不做中继"的决定直接相关，见 §6。**
+
+---
+
+## 5. 会话状态机（L3 核心）
+
+一体程序两条线：
+
+```
+主控线:  Idle → Signalling → Punching → Handshaking → Streaming → Closing
+被控线:  Idle → Registered → Incoming → Punching → Handshaking → Serving → Closing
+                                        ↑ 同一进程两线可并发（被控中也能主控别人）
+```
+
+要点：
+- 打洞阶段**双方对称**：谁都不预设客户端/服务端，各自向对端候选发包，谁先打通谁定角色（被控方做 QUIC server）
+- 会话能力协商：分辨率、编码器、码率上限、是否带音频——由**被控端**根据硬件能力给候选，主控端选
+- 单进程内用 tokio 一runtime 跑多会话；被控同时只服务一个主控（可配置）
+
+---
+
+## 6. ✅ 已裁决：不做中继（2026-10-28）
+
+> **裁决结论**：公司不提供中继服务器，中继不做。以下保留原始分析以免后人重蹈讨论。
+
+**手机在蜂窝网络下几乎 100% 处于运营商级 NAT（CGNAT），打洞打不通。**
+这不是实现问题，是网络事实——`100.64.0.0/10` 那段地址根本没给你可映射的公网端口。
+
+后果：**"主控端支持安卓/iOS" + "不做中继" = 手机只能在 WiFi 下用。**
+地铁上、外面、用流量，一律连不上。
+
+三条出路：
+
+| 方案 | 代价 | 说明 |
+|---|---|---|
+| **A. 只靠 IPv6** | 部分用户不可用 | 国内三大运营商 v6 覆盖率高，手机 v6 可用性远好于 v4 公网 |
+| B. 补一个只为移动端服务的中继 | 视频带宽成本 | **已排除：公司不提供额外服务器** |
+| C. 接受"手机只能 WiFi" | 产品力受限 | 零成本，但要写进产品说明 |
+
+### 6.1 裁决内容与边界（2026-10-28）
+
+| 项 | 裁决 |
+|---|---|
+| 中继 / TURN / relay 服务器 | **不做**。公司不提供额外服务器，且无预算计划 |
+| IPv6 | **一等公民**。候选地址排序 v6 优先，`signaling.rs` 已实现 |
+| 中继接口预留 | **不预留**。不写 `PathProvider` trait、不写 `Path::Relay` 变体 |
+| 连接层边界 | **仍要做**。理由见 §6.2，与中继无关 |
+
+**为什么不留中继接口**：留接口的收益是「将来补中继不用动会话层」，但既然中继已被排除，
+`Path::Relay` 这类变体永远不会被构造，只会产生 `dead_code` 警告，要么 `#[allow]` 要么日后删除。
+**零收益的预留就是纯负担。**
+
+### 6.2 连接层边界与中继接口是两件事
+
+这两件事常被混为一谈，必须分开：
+
+| | 内容 | 现在做不做 |
+|---|---|---|
+| **连接层边界** | 把"怎么连"（信令/打洞/直连）与"连上干什么"（收流/解码/渲染）分开 | ✅ **要做** |
+| **中继接口** | `enum Path { Direct, Relay }` 这类类型预留 | ❌ **不做** |
+
+连接层边界本身就有独立价值，与中继无关：
+
+1. **连接方式确定会变**：局域网 `IP:端口` → 将来设备码 + 打洞，这是已定的路线；
+2. **安卓主控要复用**：`viewer-core` 收流解码渲染不应知道对面是怎么连上的；
+3. **可测性**：解码逻辑能脱离真连接单独测试。
+
+做法是把它抽成一个函数边界（输入目标描述、返回 `quinn::Connection`），
+**不是**定义 trait 或枚举。
+
+### 6.3 对产品的影响（必须写进对外说明）
+
+| 网络环境 | 能否连接 |
+|---|---|
+| 双方任一侧无公网 IPv6，且处于 CGNAT 后 | ❌ **无法连接，无解** |
+| 双方都有公网 IPv6 | ✅ 可直连 |
+| 局域网 / 双方都有可打洞的公网 IPv4 | ✅ 可直连 |
+| 对称 NAT（双方） | ❌ 通常不通 |
+
+**这不是 bug，是已知边界。** 用户在外网连不上时，UI 必须给出可执行提示
+（`PunchFailReason::user_hint()` 已提供文案），不能停留在"连接中"。
+
+---
+
+## 7. 分期路线（不要一次做 6 个组合）
+
+| 里程碑 | 内容 | 预估 | 依赖 |
+|---|---|---|---|
+| **M1** | Win↔Win 打通：信令 + 打洞 + 证书钉扎 | 2-3 周 | 协议已就绪 |
+| **M2** | Win 一体化：agent-core 抽库、会话状态机、前台/后台双进程 | 2-3 周 | M1 |
+| **M3** | Win 被控服务化（开机即在线、锁屏可连、UAC 处理） | 2 周 | M2 |
+| **M4** | Linux 被控（X11 先行，Wayland/PipeWire 预留） | 2-3 周 | M2，A 在做 |
+| **M5** | 桌面 UI（Tauri v2 壳 + 原生视频表面） | 3 周 | M2 |
+| **M6** | **Android 主控**（MediaCodec + UniFFI + 触摸映射） | 3-4 周 | M5 |
+| **M7** | **iOS 主控**（VideoToolbox + SwiftUI/UniFFI） | 3-4 周 | M6 |
+| **M8** | Linux 主控（复用 M5 的桌面 UI） | 1 周 | M5 |
+| 穿插 | 音频(Opus) / 文件传输 / 多屏 | 各 1-2 周 | — |
+
+**先做 Android 再做 iOS**：不用苹果开发者账号、真机调试方便、热重载快、审核风险低。iOS 放最后。
+
+---
+
+## 8. ⚠️ 必须说清楚的人力问题
+
+现有团队 **2-3 人**，目前连"Win↔Win 打通"都还没做完。而这份需求是：
+
+- 2 个被控平台（抓屏 + 编码 + 注入 + 服务化）× 各自两套显示服务器（Linux X11/Wayland）
+- 4 个主控平台（解码 + 渲染 + 输入 + UI）× 各自一套原生集成
+- 外加信令、打洞、音频、文件、多屏、账号体系
+
+**这是 6-10 人年的工作量，2-3 人做不完。** 不是唱衰，是排期事实——Android + iOS 两个平台的 UI 和平台集成，单独拿出来就够一个人全职做半年。
+
+可行的收缩方式（选一个）：
+
+1. **砍掉 iOS**（苹果审核 + 真机调试 + 开发者账号成本最高，收益最小）
+2. **移动端只做 Android**，iOS 用 Web 端替代（但 Web 端无法硬解，体验差）
+3. **桌面优先，做深做透**，移动端放到"产品验证之后"，先招人
+4. 移动端主控**外包**，核心协议和桌面端自己掌握
+
+我的建议是 **3 或 1**：先把 Win/Linux 两端做成一款真的好用的产品（含打洞、服务化、音频、文件），移动端等有用户了再投入。现在同时铺 6 个平台，最大概率是每个都半成品。
+
+---
+
+## 9. 给 A / B 的分工调整建议
+
+| 人 | 主责 | 说明 |
+|---|---|---|
+| A | `platform/` 被控侧：Win 抓屏/编码/注入/服务化 + Linux 被控 | 与现状一致 |
+| B | `proto/` + `conn/` + `session/` + `viewer-core/` + 桌面 UI | 与现状一致 |
+| — | **移动端（Android/iOS）** | **无人** ← 这是缺口 |
+
+现有分工在"桌面 + 协议"上是自洽的，**移动端是纯增量，必须补人或砍需求**。
+
+---
+
+## 10. 开放问题（需要拍板）
+
+> §10 第 1 条已于 2026-10-28 裁决，见 §6。
+
+1. ~~中继：确认走 §6 的 A 方案（v6 优先、留接口不实现）？~~
+   **已裁决：不做中继、不留接口、v6 优先、但保留连接层边界。详见 §6.1 / §6.2。**
+2. 移动端：先 Android 还是直接砍 iOS？
+3. UI 框架：确认 Tauri v2，还是先原生桌面 + 后面再说移动？
+4. 账号体系：现在是"输验证码"，要支持设备列表就得有账号/设备 ID 体系——什么时候做？
+5. 被控服务化后，主控端要不要支持"无人值守开机连接"（有安全含义，需要固定密码 + 白名单）？

打洞与信令设计.md

@@ -0,0 +1,124 @@
+# 打洞与信令设计（无中继方案）
+
+> 状态：协议契约已落在 `common/src/signaling.rs`，已合入 main（`703eb64`）。
+> 决策：**不做中继（无 TURN / coturn）**，服务器只保留信令 + STUN 职能。
+> **裁决确认（2026-10-28）**：公司不提供中继服务器，本决策为最终结论，
+> 同时**不预留中继接口**（理由见《多平台架构设计.md》§6.1 / §6.2）。
+> 关联：`构建运行手册.md` §7 第 4 项、`Git协作规范.md` 二·B 第 ③ 项。
+
+## 1. 结论先行：信令不是中继
+
+| | 信令服务器 | 中继服务器（已砍掉） |
+|---|---|---|
+| 承载媒体流量 | ❌ 不承载 | ✅ 全部承载 |
+| 生命周期 | 只在建连那几秒 | 整个会话期间 |
+| 成本 | 一台最低配 VPS 足够 | 视频流带宽，主要成本项 |
+| 必要性 | **必须**（无它则无法交换地址） | 可选（可用率兜底） |
+
+砍掉中继 ≠ 不要服务器。信令必须保留，因为它解决的是死循环：双方都在 NAT 后，
+各自只知道自己内网地址，**"自己的公网映射"这个信息只有第三方发包过来时才能看见**。
+
+## 2. 无中继的代价：可用率，不是功能
+
+打洞成功率由 NAT 类型决定，与代码质量基本无关：
+
+| NAT 类型 | 典型场景 | 无中继 |
+|---|---|---|
+| Full cone / Restricted cone | 家用路由器默认 | ✅ 很高 |
+| Port-restricted cone | 家用宽带常见 | ✅ 需同时发包 |
+| Symmetric NAT | 部分企业网关 | ⚠️ 仅端口可预测时可行 |
+| CGNAT（`100.64.0.0/10`） | 移动/社区宽带 | ❌ 无解（IPv6 除外） |
+
+预期 P2P 成功率 **80–90%**，其余连不上。
+
+**产品边界（需写进对外说明）**：目标用户框定为「家用宽带 + IPv6 可用 + 可开 UPnP」；
+企业网络 / CGNAT 标注为不支持。这样剩余失败就不是 bug，是已知边界。
+
+## 3. 打洞流程（协议见 `common/src/signaling.rs`）
+
+```
+agent                      信令服务器                      viewer
+  |-- Register(info) ------->|<------- Register(info) -----|
+  |<-- Registered(observed) -|------ Registered(observed) ->|   observed = 公网映射（等价一次 STUN binding）
+  |<-- PeerReady(peer info) -|------ PeerReady(peer info) -->|   + 打洞前景 outlook
+  |<-- PunchPlan(start_in) --|------ PunchPlan(start_in) --->|   两侧 start_in 不同，绝对时刻对齐
+  |      （双方同时向对端候选列表发包，多轮）                 |
+  |<========= 打通：UDP 直连 → QUIC 握手 + 证书钉扎 =========>|
+  |--- PunchReport(Connected) ->|<---- PunchReport ----------|
+```
+
+### 3.1 候选地址与优先级
+
+`Candidate::score()`：IPv6（+100）> UPnP 显式映射(90) > 本机地址(80) > 公网反射(60) > 端口预测(40)。
+
+**IPv6 是无中继策略的最强后盾** —— 双方都有公网 v6 就是真直连，成功率≈100%，
+因此候选列表按 v6 → v4 排序，`EndpointInfo` 两类都带。
+
+### 3.2 同时发包的时间对齐（不需要时钟同步）
+
+两侧 RTT 不同，若下发同一个延迟，RTT 大的一方晚发包就打不上。服务器按
+`punch_start_delay_ms(own_rtt, max_rtt, margin)` 给两侧算不同的 `start_in_ms`：
+
+```
+start_in_ms = max_rtt_ms / 2 + margin_ms - own_rtt_ms / 2
+```
+
+`start_in_ms` 是**相对消息送达**的延迟，所以两端时钟不需要同步，误差≈单程抖动。
+
+### 3.3 保活
+
+NAT 的 UDP 映射默认 30s 左右超时，洞是出站包维持的，超时后静默关闭
+（表现为"连上了一会儿就断"）。`keepalive_secs()` 取双方 `binding_timeout_s`
+较小值折半，夹在 5–60s。
+
+## 4. 提高成功率的实现清单（按性价比）
+
+1. **IPv6 优先**：候选排序已实现；agent 侧需枚举全局 v6 地址填 `CandidateKind::Host`。
+2. **UPnP / NAT-PMP / PCP**：agent 启动时就尝试为 `PUNCH_UDP_PORT(47800)` 申请映射，
+   成功后以 `CandidateKind::Upnp` 补报（走 `ClientMsg::UpdateCandidates`）。
+   一次成功就把对称 NAT 变成可直连，收益最大。
+3. **双方同时发包**：见 §3.2，这是打洞能成的关键。
+4. **端口预测**：`PortAllocation::Sequential/Preserved` 时才值得做，`Predicted` 候选由
+   `sanitize_candidates` 统一清洗（去重、丢端口 0、上限 32 个）。
+5. **多轮重试**：`rounds=3 / 200ms`，一次不通不代表不通。
+
+**不要走 TCP 打洞**：QUIC 只跑 UDP，TCP simultaneous open 成功率低，性价比不值得。
+
+## 5. 实现约束（两端各自注意）
+
+- **别拿 QUIC 握手当探测**：`quinn::Endpoint::connect` 打不通会持续重试，失败判定被
+  idle timeout 拖很久。应先用同一 UDP socket 发轻量探测包确认通路（秒级），
+  确认后再 `connect`；端口扫描也放这一层，便宜且可并行。
+- **UDP socket 复用**：打洞用的 socket 要和后续 QUIC 用同一个，否则洞不在同一个映射上。
+  `quinn::Endpoint` 支持同时 `accept()` 与 `connect()`，可以在一个 Endpoint 上做完整流程。
+- **固定端口**：`47800` 对端口预测和用户手动端口转发都友好，不要随机端口。
+
+## 6. 安全（本次必须同步改，否则公网不可用）
+
+1. **证书钉扎**：`viewer/src/main.rs` 的 `SkipVerify` 必须替换为对
+   `EndpointInfo.cert_fingerprint` 的校验（`CertFingerprint` 已定义 hex 编解码）。
+2. **认证**：`ClientMsg::Register.auth` 必须是一次性验证码（替代固定 `123456`/`888888`），
+   带过期与失败限速，否则公网等于没有认证。
+3. **候选列表视为不可信输入**：一律经 `sanitize_candidates` 后再发包。
+
+## 7. 失败必须有明确出口（无中继的用户体验下限）
+
+没有中继兜底，就必须把"为什么连不上"讲清楚，不允许用户停在"连接中"。
+`PunchFailReason::user_hint()` 已给出每种原因对应的可执行建议，例如：
+
+- `Cgnat` → "当前处于运营商级 NAT（大内网），无法直连。请改用 IPv6 网络……"
+- `SymmetricNat` → "请在被控端路由器开启 UPnP 后重试。"
+- `UdpBlocked` → "当前网络的防火墙拦截了 UDP 出站，请切换手机热点后重试。"
+
+`punch_outlook()` 还能在**开打之前**就给出前景（`Likely/Possible/Unlikely/Hopeless`），
+`Hopeless`（CGNAT）时可直接跳过打洞轮次并立刻提示，不让用户白等。
+
+## 8. 后续动作
+
+| 顺序 | 事项 | 负责 |
+|---|---|---|
+| 1 | `common/src/signaling.rs` 过审合入 main | B 提 PR / A review |
+| 2 | 信令服务最小实现（WSS/443，配对 + 回推 observed + 下发 PunchPlan） | B |
+| 3 | agent：候选收集（v6/Host/UPnP/Reflexive）、同步打洞、保活 | A |
+| 4 | viewer：候选收集、同步打洞、改为证书钉扎 | B |
+| 5 | 双机联调：家庭宽带 / 手机热点 / CGNAT 三种网络各跑一轮 | A + B |

打洞验证记录.md

@@ -0,0 +1,135 @@
+# 打洞连通性验证记录
+
+> 目的：用最小成本确认「自研 P2P 打洞」在本项目目标网络下是否可行，再决定要不要投入实现。
+> 工具：`tools/punch_probe.py`（探针）、`tools/rendezvous.py`（极简信令服务器）
+> 结论：**本机线路为锥形 NAT + 端口保留，打洞可行性高。**
+
+---
+
+## 1. 测试环境
+
+| 角色 | 地址 | 说明 |
+|---|---|---|
+| 信令服务器 | `47.98.245.66:47999/udp` | 阿里云 ECS，Ubuntu 24.04.2，python 3.12.3 |
+| 客户端 | 出口 `116.3.201.115` | 联通线路，位于 NAT 之后 |
+| 工具 | `tools/rendezvous.py` + `tools/punch_probe.py` | 纯 Python 标准库 |
+
+部署位置：`/root/uu-punch-poc/`（与服务器上其他服务完全隔离）
+
+---
+
+## 2. 验证过程与结果
+
+| # | 验证项 | 结果 |
+|---|---|---|
+| 1 | 信令服务器回环注册 | ✅ 能注册、能记录 |
+| 2 | 服务器进程/监听 | ✅ `0.0.0.0:47999`，长期运行稳定 |
+| 3 | **跨公网注册** | ✅ 服务器日志出现 `116.3.201.115:47800` |
+| 4 | **双方配对与地址回推** | ✅ `配对成功：116.3.201.115:47800 <==> :47801` |
+| 5 | 同一 NAT 内两实例互打 | ❌ 失败（见 §4.1，属 hairpinning 限制） |
+| 6 | **NAT 映射行为判定** | ✅ **端点无关映射 + 端口保留**（见 §3） |
+
+---
+
+## 3. 关键结论：NAT 类型 = 锥形 + 端口保留
+
+用**同一个本地端口 47800** 分别打两个完全不同的目标，观察公网映射：
+
+| 目标 | 观察到的公网映射 |
+|---|---|
+| Google STUN（境外） | `116.3.201.115:47800` |
+| 自建信令服务器 `47.98.245.66:47999` | `116.3.201.115:47800` |
+
+**不同目标 → 同一个公网端口 → 端点无关映射（Endpoint-Independent Mapping，即锥形 NAT），且端口原样保留。**
+
+按打洞成功率排序：
+
+```
+锥形 + 端口保留   ← 本机（最优）
+锥形 + 端口改写     成功率高
+对称 NAT            困难，需端口预测
+CGNAT               基本无解
+```
+
+**推论**：信令服务器观察到的地址，对该客户端是**可复用的真实映射**，对端直接向它发包即可打洞，无需端口预测。这是最理想的情形。
+
+复现命令：
+
+```powershell
+# 一定要带 --stun-port，用与打洞相同的端口，否则映射不可比
+py tools\punch_probe.py --stun --stun-port 47800
+```
+
+---
+
+## 4. 踩到的坑（Rust 实现必须处理）
+
+### 4.1 hairpinning：同一公网 IP 下两实例互打会失败
+
+两个客户端都在 `116.3.201.115` 后面，互相打对方的公网地址，需要路由器支持 **NAT 环回（hairpinning）**。本线路不支持。
+
+**这不代表真实打洞会失败**——真实场景是两台机器位于**不同**公网 IP 之后。此测试只能验证"信令配对"链路，不能验证穿透能力。
+
+### 4.2 Windows：ICMP 端口不可达会打断接收循环
+
+对方尚未启动时发包 → 收到 ICMP port unreachable → 下一次 `recv` 抛 `WSAECONNRESET(10054)`。若把它当致命错误 `break`，接收循环就此死掉，之后对方真打进来也收不到。
+
+处理方式（两层）：
+
+```python
+sock.ioctl(socket.SIO_UDP_CONNRESET, False)   # 1) 关闭该行为
+# 2) 收到该错误时 continue，绝不能 break
+```
+
+**Rust 对应**：`tokio` 的 `recv_from` 会返回 `ConnectionReset`，同样不能 `?` 或 `break`。
+
+### 4.3 发完就退出会漏掉晚到的回包
+
+对方可能比自己晚启动。发完最后一包立即关闭 socket，会把"晚到的成功"误判为失败。
+→ 发完后保留 grace 期（默认 2.5s）继续监听。
+
+### 4.4 部署层的两道防火墙
+
+| 层 | 现象 | 处理 |
+|---|---|---|
+| 主机 ufw | `INPUT DROP`，无规则则静默丢弃 | `ufw allow 47999/udp` |
+| 云安全组 | 包到不了网卡（tcpdump 零捕获） | 控制台加 UDP 入方向规则 |
+
+**排查手法**：`tcpdump -n -i any udp port <port>` 零捕获 = 包在到达主机前就被丢，问题在云安全组而不在主机防火墙。
+
+> 注意：首次配置时误把安全组规则设成了 **TCP**，UDP 包仍被丢弃。协议类型必须选 UDP。
+
+### 4.5 假阳性：信令回复被误判为"打通"
+
+客户端在拿到对端地址前会反复注册，服务器的 `PEER` / `WAIT` 回复可能在 `discover_peer` 返回之后才到达。若接收线程不做区分，会把**服务器发来的回复**当成"对方打进来了"，输出假的"✅ 打洞成功"。
+
+实测踩到的形态：报告的"对方源地址"是**信令服务器的 IP:端口**（`47.98.245.66:47999`），包长 22 字节——而真正的打洞包固定是 **16 字节**（`PUNCHv1|` + 8 字节时间戳）。
+
+**判据（Rust 实现必须照做）**：
+
+1. 只认以协议魔数开头的包，长度必须是约定值
+2. 显式排除信令服务器的 `IP:端口`
+3. 结论里如果出现"非打洞包 N 个"，说明收到了信令回复，**不能**据此判定成功
+
+---
+
+## 5. 尚未验证
+
+| 项 | 为什么重要 | 怎么验 |
+|---|---|---|
+| **两台不同网络的机器互打** | 唯一能证明真实穿透能力的测试 | 一台机器 + 一台连手机热点的笔记本 |
+| 手机热点（CGNAT）场景 | 决定"无中继"方案对移动端是否成立 | 同上，热点那端即为 CGNAT |
+| IPv6 直连 | 若两端都有公网 v6，可绕开 NAT | `--peer [v6地址]:端口` |
+| 对端 NAT 是否同样友好 | 打洞需要两端配合 | 在对方网络重复 §3 的映射判定 |
+
+**下一步优先级：手机热点组合 > IPv6 > 其他。**
+
+---
+
+## 6. 对实现的影响
+
+1. **信令服务器的职责就此确认**：注册、配对、回推观察到的源地址。不承载媒体，建连后即退出。
+2. **信令与打洞必须复用同一个 socket**：服务器看到的映射端口，必须就是打洞时使用的端口，否则映射不可复用。
+   - Rust 实现中：该 socket 需继续交给 `quinn::Endpoint` 使用（一次绑定，三处复用：信令 / 打洞 / QUIC）。
+3. **失败判定要快**：先做 NAT 行为探测，若判定为对称 NAT 直接给出结论，不必耗完多轮。
+4. **保活**：NAT 表项会超时，建连后需按 `binding_timeout_s` 折半做 keepalive（协议中已定义 `keepalive_secs()`）。

构建运行手册.md

@@ -1,37 +1,53 @@
 # MVP 远程控制 Demo · 构建运行手册
 
-> 项目路径：`D:\wordkb\2026-10-22-15-52-47\mvp-remote\`
-> 形态：Rust workspace，三个 crate：`common`（协议）、`agent`（被控端）、`viewer`（主控端）
+> 项目路径：`D:\code\remote\`
+> 形态：Rust workspace：`common`（协议）、`agent-core`（平台无关会话层，当前供 linux-agent 使用）、`agent`（Windows 被控端）、`linux-agent`（Linux 被控端）、`viewer`（主控端）
 
 ## 1. 功能范围（量级一 Demo）
 
-- ✅ DXGI Desktop Duplication 全屏采集（GPU 拷贝，脏区/硬编码留待二期）
-- ✅ LZ4 压缩 + QUIC 加密传输（自签名证书，传输层已加密）
+- ✅ DXGI Desktop Duplication 全屏采集 + NVENC 硬编（无 N 卡时自动回落 openh264 软编）
+- ✅ QUIC 加密传输（自签名证书，传输层已加密）
 - ✅ 验证码认证（默认 123456）
 - ✅ 键鼠远程控制（SendInput 注入，虚拟桌面绝对坐标 + 扫描码）
 - ✅ 桌面静止时低频重发（保持画面新鲜）
-- ❌ 暂无：硬件编码、P2P 打洞/中继（当前仅局域网/可直连地址）、音频、文件传输、Linux 被控
+- ✅ Linux 被控端（X11 采集 + XTest 注入，见第 8 节）
+- ❌ 暂无：P2P 打洞/中继（当前仅局域网/可直连地址）、音频、文件传输
 
 ## 2. 环境要求
 
 - Windows 8+（被控端需要 DXGI Duplication；主控端 Win7 亦可）
-- 工具链已全部部署在 D 盘（无需再装）：
-  - Rust (GNU)：`uurev/tools/rust/cargo/bin`
-  - MinGW-w64 14.2：`uurev/tools/mingw64/bin`
+- Rust（GNU host：`x86_64-pc-windows-gnu`）+ MinGW-w64，已验证可用组合：
+  - `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 不读 Windows 系统代理**，必须显式告诉它。
+  已在本机 `%USERPROFILE%\.cargo\config.toml` 写入（Clash 之类混合端口，按实际改）：
+
+  ```toml
+  [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. 运行（两台机器，或同机双开验证）
 
@@ -67,6 +83,30 @@ viewer.exe --addr <被控端IP> --port 47800 --code 888888
 4. 高 DPI/多屏：当前只采集主输出（EnumOutputs(0)）。
 5. 主控端窗口固定为远端分辨率，颜色序 BGRA→0RGB 若异常可在 `blit()` 一键翻转。
 
+### 6.1 待修问题（已定位，尚未修，均在 Windows `agent/`）
+
+1. **错误验证码时 `AuthFail` 送不达**：`agent/src/main.rs` 写完 `AuthFail` 后立刻
+   `send.finish()` 并返回，进程退出会把 QUIC 缓冲区里尚未发出的数据一起带走，
+   客户端只会看到 `connection lost` 而不是 `AuthFail`。
+   修法：`finish()` 后等对端读到并挂断（`conn.closed()` + 超时）再退出。
+
+2. **软编路径下静止桌面仍不响应关键帧请求**（`04c02d9` 只修了 NVENC 那一半）：
+   `agent/src/capture.rs` 的 `Ok(false)`（画面未变）分支里，`force_key` 被
+   `keyreq.swap` 消费后，只有 `EncoderKind::Nvenc` 分支拿它去重编 IDR；
+   `EncoderKind::Soft` 分支仍然只是「重发最后一帧码流副本」，标志被直接丢弃。
+   后果：**无 N 卡 / 驱动异常（走软编兜底）的机器上，解码端一旦出错，静止画面下
+   永远拿不到 IDR，表现为黑屏。**
+   修法：软编路径同样保留最近一帧裸像素，`force_key` 时重编一个真关键帧。
+
+3. **单次 `KeyFrameReq` 可能被静默吞掉**：同一个 `keyreq.swap(false, …)` 写在了
+   `if last_sent.elapsed() > 500ms` 的**外面**，因此请求若落在距上次发送 500ms 之内，
+   标志已被消费但分支不进入，该次请求就丢了，必须等下一次请求才可能生效
+   （主控端目前周期性重发，故表现为延迟而非永久黑屏）。
+   修法：把 `swap` 移进时间闸内，或先在闸外预判、进闸后再消费。
+
+> 第 1、2 条在 `feature/agent-linux` 分支的 `agent-core` 里已经实现（**Linux 侧生效**），
+> 但按"不与他线争抢 `agent/`"的约定，**本期没有改动 Windows 代码**。
+
 ## 7. 下一阶段任务队列（Phase 1 剩余）
 
 1. H.264：接 openh264（软编兜底）→ NVENC/QSV（硬编优先）
@@ -74,3 +114,86 @@ viewer.exe --addr <被控端IP> --port 47800 --code 888888
 3. QUIC 多流：视频/控制/键鼠分离流（键鼠零阻塞）
 4. P2P 打洞 + coturn 中继（自建信令服务器）
 5. 被控端服务化（Windows Service + 会话切换处理）
+
+## 8. Linux 被控端（linux-agent）
+
+### 8.1 现状与边界（重要）
+
+本期**只在新增文件里做，未改动 Windows `agent/`**，原因见下：
+
+| crate / 文件 | 职责 | 当前使用者 |
+|---|---|---|
+| `agent-core/src/lib.rs` | QUIC/TLS 握手、传输调优、验证码认证、会话/select 循环、latest-wins 单槽、输入分发，以及软件编码视频管线（openh264） | **仅 linux-agent** |
+| `linux-agent/src/capture.rs` | X11 `GetImage` 采集 + 整帧变更检测 | Linux |
+| `linux-agent/src/input.rs` | XTest 注入 + 扫描码→X11 keycode 映射 | Linux |
+| `agent/`（Windows） | 保留原有自持会话循环 + NVENC/软编双路编码，**本期未动** | Windows |
+
+**为什么 Windows 端没有一并接过来**：`agent/` 的 NVENC 路径是「GPU 内 BGRA→H.264 零转换零拷贝」，
+编码器必须直接吃 DXGI 的 GPU 纹理；而 `agent-core` 目前的接缝是 `ScreenCapturer`（返回 CPU 上的
+BGRA 字节），硬接会把零拷贝优势废掉。正确的接缝应是「平台视频管线产出**已编码帧**」
+（`VideoSource` 语义），待 `agent/` 由 NVENC 那条线稳定后再重切，届时应把 `openh264` 从
+`agent-core` 移到各平台 crate。
+
+在此之前 Windows 与 Linux 各持一份会话循环，属于**有意的过渡态**：`common/` 协议改动需要两处同步
+（例如本期跟着补的 `Pong{lost,sent}`）。
+
+### 8.2 构建
+
+Windows 侧照旧（`default-members` 已排除 linux-agent，产物仍是 agent.exe / viewer.exe）：
+
+```bash
+export PATH="$USERPROFILE/.cargo/bin:/d/mingw64/bin:$PATH"   # Git Bash 写法
+cargo build --release
+```
+
+Linux 侧显式指定包（跨平台交叉编译不推荐，用容器最省事）：
+
+```bash
+cargo build --release -p linux-agent
+```
+
+### 8.3 运行
+
+```bash
+# 被控 Linux 机器（Xorg 或 XWayland 均可，依赖 DISPLAY 环境变量）
+./linux-agent --port 47800 --code 123456
+# 主控端（Windows）命令行不变
+viewer.exe --addr <被控机IP> --port 47800 --code 123456
+```
+
+### 8.4 冒烟测试（不需要图形桌面）
+
+```bash
+bash scripts/linux-smoke.sh
+```
+
+脚本自建 Xvfb 虚拟屏后跑**单测 + 端到端**两层：
+
+- 单测（不需要 X server）：键码映射、坐标换算等纯逻辑；
+- 端到端：X11 采集 → openh264 编码 → QUIC 下行解帧、验证码认证（含**错误验证码被拒**）、
+  Ping/Pong（含下行丢包统计字段）、静止桌面下的关键帧恢复，以及**输入注入实证**——
+  注入鼠标移动后，从另一条 X11 连接读回指针真实坐标。
+
+> 单测那层别省：坐标换算的取整边界就是靠它才发现的（集成测试有 ±2 像素容差，
+> 期望值写错也照样绿）。
+
+> 静止关键帧那条用例做过**变异测试**：把修复退回会失败、恢复后通过，确认断言不是摆设。
+> 注意扰动量必须小（画 64x64 小方块）——整屏刷白会触发编码器场景切换自动 IDR，
+> 于是"重发旧帧"和"真重编关键帧"拿到同样的字节，用例就失去区分度。
+
+### 8.5 键码映射（两端最关键的差异）
+
+协议里键盘沿用 Windows 口味的 PS/2 Set-1 扫描码，而 X11 要的是 keycode，两者**并非处处等价**：
+
+- 主键区：满足 `keycode = scancode + 8`；
+- **E0 扩展键编号体系完全不同**（`↑` 是 0x48，但 X11 keycode 是 111 而不是 0x50）——必须查表。
+
+映射表在 `linux-agent/src/input.rs::keycode_of`，带单元测试防回归。
+
+### 8.6 Linux 侧已知限制
+
+1. 仅支持 32bpp TrueColor 视觉（绝大多数桌面满足），其他格式启动即明确报错而非静默出错；
+2. 采集走核心协议 `GetImage`，每帧经 X socket 全量传输，静止桌面也会持续轮询抓帧；
+   **MIT-SHM 共享内存 + XDamage 脏区**是下一步优化（锚点已写在 `linux-agent/src/capture.rs` 顶部注释）；
+3. 仅覆盖 X11 / XWayland；纯 Wayland（无 XWayland）需另走 PipeWire 门户；
+4. 键位表按 Xorg evdev 标准 keycode 编写，自定义键盘布局可能需要调整。