225 lines
42 KiB
Markdown
225 lines
42 KiB
Markdown
# RemoteDesk 实现状态
|
||
|
||
本文记录仓库代码实际可运行的能力。设计文档描述目标架构，不代表对应功能已经完成。
|
||
|
||
状态定义：
|
||
|
||
- **可用**：存在运行时实现，并有自动化测试或可重复的构建验证。
|
||
- **部分**：只有策略模型、界面或实验入口，尚不能完成端到端会话。
|
||
- **未实现**：目前只有设计或路线规划。
|
||
|
||
## 全 Rust 迁移快照
|
||
|
||
| 阶段 | 状态 | 已验证边界 |
|
||
|---|---|---|
|
||
| 删除 Go/Hysteria2 | 完成 | 源码、CI、Windows/Linux 安装入口均已删除 |
|
||
| 共享 `str0m` crate | 部分 | `str0m 0.23` 已锁定；共享边界测试和 Agent 复用校验通过 |
|
||
| SDP/ICE/DataChannel | 部分 | host ICE loopback 覆盖 DTLS/SCTP、control 与 pointer 通道 |
|
||
| H.264 RTP | 部分 | loopback 媒体事件及 RFC 6184 重组/丢包测试通过 |
|
||
| 硬件编解码 | 部分 | Windows/Linux 源码与编译路径存在，尚无三平台实机证明 |
|
||
| `wgpu` 呈现 | 部分 | 原生窗口和 surface 编译通过，解码 surface interop 尚未完成 |
|
||
| Opus | 部分 | loopback、Linux 编码和 Windows 播放源码存在，尚无设备端到端 |
|
||
| STUN/TURN | 部分 | 有界配置、外部 srflx/relay 注入和 Edge 凭据已接入，尚无 NAT 矩阵 |
|
||
| 打包/CI | 部分 | Drone 已覆盖 Windows 便携 ZIP、Linux DEB/RPM、Android APK 和 macOS 原生 GUI tar.gz；macOS 签名、notarization 及真实媒体链路仍待验收 |
|
||
| 删除 Tauri/WebView | 部分 | 源码和正式构建入口已删除；历史设计文档保留作迁移依据 |
|
||
|
||
以下长表保留了迁移前各子系统的实现边界，其中出现的 Tauri、WebView、Hysteria2、
|
||
软件回退或 `webrtc-rs` 只描述历史实现，不再是正式构建入口。当前状态以上述迁移快照
|
||
和 [全 Rust 迁移计划](all-rust-migration.md) 为准。
|
||
|
||
## 迁移前能力明细（历史基线）
|
||
|
||
| 能力 | 状态 | 当前边界 |
|
||
|---|---|---|
|
||
| Windows 控制端主机配置 | 可用 | 非敏感字段保存在应用 WebView 的 `localStorage`，账户字段不持久化 |
|
||
| Windows Tauri 桌面壳 | 部分 | 新增 Tauri 2 原生入口源码；优先使用固定 loopback 端口 `127.0.0.1:4173`，使 WebView `localStorage` origin 在重启和 MSI 升级后保持不变（端口被占用时才回退临时端口），并生成 256 位一次性启动令牌，以 stdin 生命周期绑定方式启动控制服务；HTTP ready 请求不发送令牌，控制服务返回令牌 SHA-256 proof，壳本地精确验证后才创建 WebView，从而拒绝端口释放/bind 间隙内的错误本机进程；WebView 只允许导航到本次 `127.0.0.1:<port>` origin，控制服务异常退出会关闭应用，窗口退出会先请求控制服务退出并在 2 秒后强制回收；MSI 快捷方式、payload 清单和升级后重启目标均已改为 `bin/remotedesk.exe`，不再由正式 MSI 打开系统浏览器；运行时能力通过 `application.desktop_shell/shell_kind` 区分 Tauri 与独立控制服务；本轮按要求尚未解析新 Tauri 依赖、编译或运行窗口，因此不标记为可用 |
|
||
| Windows 被控端便携入口 | 可用 | 组合包内双击 `host/RemoteDesk-Host.exe`，原生确认后提权配置；首次变更前备份 RDP/NLA/TermService/防火墙状态；不创建账户、不保存密码 |
|
||
| RDP 地址解析和 TCP 探测 | 可用 | 验证目标端口可达，不验证账号 |
|
||
| IronRDP 协议与证书探测 | 可用 | 独立 helper 解析 X.224/RDP Negotiation Confirm，确认 HYBRID/HYBRID_EX 后完成无凭据 TLS 握手并返回服务器证书 SHA-256；不进入 CredSSP/NLA 或账号验证 |
|
||
| Windows `mstsc` 启动 | 可用 | 生成不含密码的临时 `.rdp` 文件并启动系统客户端 |
|
||
| RDP 检测旁路 | 可用 | TCP/协议检测仅用于诊断；待检测、检测中或检测失败均不阻止直接启动客户端 |
|
||
| 控制端时钟与质量面板 | 部分 | 顶栏显示每秒更新的本地时间；Windows 启动前网络延迟使用 TCP/RDP 探针实测值，原生会话接入 vendored IronRDP 已解析的 `NetworkCharacteristicsResult`，服务器提供时回传会话平均 RTT、基础 RTT 和估算带宽；Linux X11 源码通过当前直连 WSS 或 Edge relay 内的 Ping/Pong 测量会话 RTT；IronRDP 原生会话另回传状态、累计帧数、最近一秒实际帧率、尺寸、本地解码处理耗时和本地呈现耗时。解码计时从网络 PDU 进入 `active_stage.process` 开始，覆盖图形处理与 framebuffer 像素转换，本地输入或 resize 产生的更新不计入；Linux X11 桌面源码另回传真实采集、zlib 编码、解码/完整性校验、呈现耗时和帧率，并显示当前 zlib level 1..6 与压缩后/未压缩字节比例。RDP 服务端编码耗时仍无数据；Agent runtime 新增有界 `QualityController`，将 RTT、丢包、抖动、编码队列 EWMA 映射到 Good/Fair/Poor/Critical，并按 2160p60 到 720p15 阶梯快速降档、迟滞升档，单元测试覆盖用户上限和恢复行为；尚未接入完整 UI/实机指标采集 |
|
||
| 客户端内 RDP | 部分 | 独立 IronRDP 原生窗口可发起单屏会话、跟随窗口动态调整远程桌面、启动/切换全屏和主动退出；原生多屏源码通过 Win32 枚举 2..16 个真实本地显示器，规范化主屏相对坐标，在服务端 RDPEDISP capabilities 到达后发送多 monitor layout PDU，并以无边框组合窗口覆盖本地虚拟桌面；退出组合全屏后可缩放查看，重连复用同一布局，单屏 resize 不会覆盖多屏配置，诊断回传实际 monitor count；TLS 探针返回证书 SHA-256，用户确认后原生启动强制携带指纹，实际 TLS 握手固定完整证书 DER 并验证握手签名；窗口聚焦时转发物理键盘扫描码、五键鼠标、缩放后的绝对坐标及水平/垂直滚轮，失焦或退出时释放远端输入状态；`Ctrl+Alt+Home` 发送远端 `Ctrl+Alt+End` 安全界面序列；viewer 通过 opaque 引用直接读取 Windows Credential Manager 凭据；控制服务源码已改用当前用户 SID ACL、拒绝远程客户端且单实例的 Windows Named Pipe，按 OS 返回的 pipe 客户端 PID、进程创建时间、镜像路径与 SHA-256 build hash 校验 helper，并通过一次性 32 字节密钥和 HMAC-SHA256 challenge 后才交付严格有界的连接配置，命令行只保留随机 pipe name；viewer 严格校验 schema 和全部配置字段后返回绑定载荷 SHA-256 与 challenge 的 HMAC ACK，服务端只有验证 ACK 版本、摘要和 MAC 后才确认配置已接受；连接、认证、配置与 ACK 共用 10 秒绝对 deadline，双端非阻塞有界读取避免已连接 helper 永久停滞握手线程；每个 viewer 启动后立即加入带 `KILL_ON_JOB_CLOSE` 的独立 Job Object，控制服务退出时由内核回收 helper，握手失败则终止整个 Job 并向现有诊断 API 写入 `secure_pipe_failed`；当前构建显式启用 Windows CLIPRDR 双向剪贴板并默认启用 RDPSND 本地音频；异常断线后释放输入并按 1/2/4 秒执行三次有界重连；Windows 优先创建硬件 D3D11 device、持久 CPU framebuffer、完整 GPU frame texture 与 DXGI swap chain；vendored IronRDP 只转换裁剪后的 `GraphicsUpdate` region 紧凑像素块，viewer 严格验证并合并到持久 framebuffer，再合并 redraw 前的多个待呈现区域，只对变化像素执行 CPU texture upload；discard swap chain 下每帧仍执行完整 GPU resource copy，失败时回退 software framebuffer；诊断回传本帧转换像素数、`full_frame`、`dirty_rect` 或 `cached_frame` 及实际 CPU 上传像素数；新增多屏/Named Pipe/Job/配置 ACK/全握手超时/dirty-region 转换与上传链路按要求尚未编译/实机验收，且尚非硬件解码或零拷贝，剪贴板和音频仍待真实远端专项验收 |
|
||
| 分辨率和全部显示器 | 可用 | UI 提供常用档位及 200..8192 自定义宽高；`mstsc` 支持动态/固定分辨率和 `use multimon`；IronRDP 单屏窗口发送带 generation 的动态 resize、以实际远端图像确认，并在不支持/超时时经用户确认重连；原生“全部本地显示器”源码发送真实 RDPEDISP 多屏布局；自定义本地显示器子集尚未开放 |
|
||
| Windows 凭据适配器 | 可用 | 每个主机保存 `RemoteDesk/RDP/<profile-id>` opaque 引用；独立本地遮罩窗口写入/覆盖 Windows Credential Manager，UI 可查询状态和删除；密码不进入 React、HTTP、控制服务、argv、日志或主机配置；已在 Windows 实测缺失条目查询，真实远端 NLA 登录仍待环境验收 |
|
||
| Windows 组合便携包 | 可用 | 单一版本化 ZIP，以根目录 `RemoteDesk.exe` 作为 Client GUI，`host/RemoteDesk-Host.exe` 作为 Host 配置入口；不包含安装器或自动升级 helper |
|
||
| Windows MSI 安装包 | 已删除 | WiX、NuGet、.NET、MSI 和 Authenticode 安装器入口不再属于 Windows 打包链 |
|
||
| Windows 控制端自动升级 | 未提供 | 便携版通过新目录解压和 SHA-256 验证手工升级；运行时自动安装能力关闭 |
|
||
| 协议与策略核心 | 部分 | 会话状态、显示布局、required features、零拷贝报告和 GPU 规划已有纯 Rust 模型及测试 |
|
||
| Native Video Helper | 部分 | 保留严格/兼容 GPU 管线规划和 Windows 硬件 D3D11 device/immediate-context 创建探针；H.264/DXVA allocation probe 源码会枚举适配器真实 H.264 VLD profiles、验证 NV12、选择未加密 raw-bitstream config，并实际创建 decoder、NV12 texture array 和 output view；`--probe-h264-file` 使用绑定同一 device manager 的 Media Foundation Source Reader，在最多 512 次读取内严格验证真实 H.264 文件的 NV12 `IMFDXGIBuffer`、完整 subresource layout 和所属 device。`--play-h264-file` 本地窗口链路有界枚举并选中 H.264 原生类型、跟踪动态 NV12 媒体类型和可见帧尺寸、拒绝 CPU buffer/跨 device texture，以媒体时间戳调度帧；同一 device 的 `ID3D11VideoProcessor` 将 NV12 texture subresource 转换和等比缩放到 BGRA swap chain。Windows Linux 桌面 helper 进一步接入 RFC 6184 单 NAL/STAP-A/FU-A 重组、16 MiB AU 上限、跨帧 RTP 序号检测、PLI/关键帧恢复和一槽有界邮箱；Annex-B 输入送入 D3D11-aware Media Foundation H.264 MFT，只接受同 device NV12 `IMFDXGIBuffer`，再由 VideoProcessor 呈现到现有桌面窗口。协议 minor 9 在第一张原生帧呈现后执行帧边界模式确认，确认后停止完整 zlib 编码/传输，以 sequence 绑定的 H.264 呈现 ACK 驱动下一次捕获；解码、积压、轨道、sender/encoder 或 ACK 超时均显式恢复 zlib。H.264 采集、编码、解码和呈现耗时分别进入质量诊断。该链路按要求尚未编译/实机执行，且 DXGI surface/VideoProcessor 呈现不能替代 ETW/GPUView 的硬解和隐藏复制证明，所以继续报告 `hardware_decode_verified=false`、`zero_copy_verified=false` 和 `linux.native_video=false`；IronRDP viewer 继续使用独立 D3D11 CPU framebuffer 路径 |
|
||
| Linux Agent 基础 | 部分 | 四个可运行进程已实现设备身份、限时一次性配对码、配对/重连 Ed25519 挑战签名、证书指纹固定、TLS WebSocket、`SO_PEERCRED` Unix IPC、systemd 服务和健康 CLI；控制 helper 源码新增无需用户认证的固定证书 TLS/WSS `Hello` 探测，控制 API 与 UI 可显示实际握手耗时、协议版本、终端/桌面/文件能力和 Edge 在线状态，不读取 Client 私钥或配对码；可选 Edge 客户端首次启动自动生成并保护设备身份，使用独立作用域令牌及设备签名主动注册 60 秒短 TTL 路由、每 30 秒续期并在优雅退出时 connection-bound 签名注销，在心跳间隔内用设备私钥和一次性 nonce 主动 poll/ack 签名 Session Intent，用户无需提供密钥文件，只有 Client Ed25519 签名、本地配对公钥、permission 与 allowed user 全部通过才接受；在线/信令计数进入 CLI 和 WSS Hello/Status；已生成静态 x64 便携包与 DEB，RPM/原生 DEB 由 Ubuntu CI 构建；相关 Agent runtime 自动化测试已通过，整体仍未在 Linux 主机运行验证 |
|
||
| Linux 终端会话 | 部分 | Agent 端具备权限绑定、普通用户限制、`runuser --login` PAM 会话、PTY 字节流/resize/interrupt 和生命周期回收；Windows 控制端 helper 使用固定 TLS 证书 WSS、Credential Manager 中的 Ed25519 身份、一次性本地遮罩配对、challenge 签名认证、原始按键/ANSI 输出和 resize，并可由 UI 启动独立终端窗口；配置 Edge 并录入 Agent 设备公钥后，首次配对和后续会话均无需 Client 直达 Agent，分别提交签名 `pairing`/`terminal` Intent，并在角色绑定 opaque relay 内完成证书固定 TLS/WSS、Agent 公钥核对、Client challenge 和一次性码认证；公钥随后按证书指纹保存，UI 与控制 API 可查询或显式删除，Windows 自动化测试覆盖真实 Credential Manager 往返；联合测试连续覆盖远程首次配对、已知设备重连、双向字节和票据重放，尚缺真实 Linux/PAM 端到端验收 |
|
||
| Linux 文件传输 | 可用 | 与终端共用证书固定、Ed25519 配对身份、Edge opaque relay 和独立 `files` 权限；上传/下载限制为授权普通用户主目录内相对路径和 2 GiB，使用 45 KiB 分块、声明大小及 SHA-256 端到端校验；协议 minor 4 支持双向断点续传：上传 transfer ID 绑定 user/remote path/size/hash，降权 helper 从同 ID 的普通文件实测 offset、保留未完成 partial 并在整文件校验后原子替换；下载由本地隐藏 partial 长度请求 offset，Agent 按远端真实大小校验，只发送剩余字节，Client 重新哈希已有前缀和新增数据后才改名，最终哈希不符会删除 partial；Ubuntu CI 脚本实际中断 4/10 字节后续传并验证上传/下载剩余段；UI 可启动独立传输窗口，仍待真实 Linux 主机专项验收 |
|
||
| Linux X11 桌面 | 部分 | 协议 minor 10 源码包含 `desktop` 权限、严格 zlib BGRA 分块/哈希/呈现 ACK、RTT、X11 `GetImage`/XTEST、绝对及有界相对鼠标、五键/滚轮/键盘、失焦释放、全屏/退出、跟随窗口 resize、三次有界重连和完整质量诊断；Windows helper 可通过 Raw Input 合并相对位移并显式抓取/释放光标。用户会话使用真实呈现 ACK 的 1..30 FPS 有界自适应 pacer，并依据真实编码预算与 ACK 在 zlib level 1..6 内调整压缩策略。Edge 桌面会话复用同一次 BGRA 捕获，以 GStreamer 按 VA/VAAPI/NVENC/QSV/OpenH264/x264 顺序建立 H.264 Annex-B AU 编码器；16 MiB AU 上限、45 KiB 分块、严格顺序、canonical base64、精确长度和 SHA-256 经 root/user IPC 验证后交给 WebRTC sender。Windows helper 已接入远端 H.264 RTP 到 Media Foundation/D3D11 原生窗口；第一帧呈现后双方在完整帧边界切换至 H.264-only，以呈现 ACK 驱动 pacer，不再并行传输完整 zlib 帧。RTP 序号中断立即触发回退；积压、重连、解码失败、媒体终止或三秒 H.264 ACK 超时也会恢复 zlib。协议 minor 14 源码增加默认关闭的 `opus_audio` 协商：只有同版本 Client 明确请求且已绑定 WebRTC sender 时，用户会话才从 Linux 输出 monitor 捕获 48 kHz 双声道 Opus，经 4 KiB 有界 IPC/SRTP 发送并由 Windows WASAPI 播放；音频与视频失败相互独立，旧客户端不接收音频事件。协议 minor 15 源码增加独立 `clipboard_read`/`clipboard_write` 权限、X11 selection 与 Windows `CF_UNICODETEXT` 双向纯文本剪贴板、Offer/Request/Data 按需传输、32 KiB/UTF-8/NUL/canonical Base64/SHA-256 校验和摘要防回环；root agentd 只授权和转发结构化消息。WSS/Edge 异常断开时立即释放输入并保留 15 秒 X11 租约、帧序列、pacer 和压缩控制器；32 字节随机恢复令牌绑定 agentd 注入的已认证 Client 指纹与 Linux 用户。新增输入/媒体/音频/剪贴板链路尚未解析依赖、编译或在真实 Windows/Xorg 主机验收，因此仍不标记为原生视频可用；Wayland 及 Wayland 剪贴板仍关闭。 |
|
||
| CDN Edge 独立服务 | 部分 | 独立 Rust 进程已实现管理员与 Agent Presence 独立作用域的 Bearer 认证 API、短 TTL Presence、Direct/Single/Dual 路径评分、coturn REST 凭据和一次性 HMAC relay 票据；签名 Session Intent 队列最多全局 1024、每设备 32、每设备/Client 8 个，最长 120 秒，request ID 幂等、15 秒投递租约、Agent proof nonce 防重放并绑定当前 Presence connection；普通请求验证本地已配对 Client/permission/user，首次 `pairing` 请求只在 Agent 本机配对窗口有效且允许目标用户/terminal 时接受；Edge 分别交付 Client/Agent 角色票据，并在双方各自的签名授权响应中下发绑定相同 session/expiry 的 coturn REST 短期凭据；已接受桌面会话的 Agent/Client 使用 `webrtc-rs` 0.20.1 创建真实 PeerConnection，注册 H.264/RTX/Opus、NACK/PLI/transport-cc、控制 DataChannel，并经有界签名 mailbox 交换 SDP/ICE。Agent 侧媒体 sender 以 session、过期时间、目标用户和 Client 指纹注册，单次消费且在 PeerConnection 关闭时撤销；Linux 捕获帧已接入 H.264 track，Windows 接收端也已接入有界 RTP 重组和原生解码/呈现源码。真实 coturn POP、UDP/TLS、双 POP、跨网络媒体和 RDP Edge 尚未验收，因此不开放通用 CDN 策略；新增接线按要求尚未解析依赖、编译或运行。 |
|
||
|
||
IronRDP 单屏 resize 源码现已补齐单调 generation、调整后尺寸回传、匹配远端图像确认、5 秒确认超时、不支持/超时诊断和用户确认重连。vendored client 不再因缺少 Display Control 静默重连；取消确认会保持当前会话，确认后的尺寸也会保留给后续有界故障重连。该新增链路仍按要求等待编译和 Windows 真实服务端验收。
|
||
|
||
Linux 用户会话现已将 X11 与 Wayland 生命周期收敛到统一 Agent 后端。Wayland 默认编译 `wayland-eis`，通过用户 D-Bus 实际查询 RemoteDesktop/ScreenCast Portal，按 `CreateSession -> SelectDevices -> SelectSources -> Start` 顺序授权，持有 PipeWire remote 与 EIS fd，并以 DMABUF 严格硬件 H.264 管线发送；Portal/EIS/VA 能力不足时返回明确错误，不伪装成 X11 或 CPU 回退。控制服务的 `linux.wayland_desktop` 现在表示 Linux Agent helper 已包含该能力，具体桌面是否可用仍由 Agent status 的 Portal probe 和会话启动结果决定。
|
||
|
||
Windows Headless 方案只接受可验证的硬件路径：IDD/IddCx SDR 8-bit 虚拟显示器、GPU surface、硬件编码器和 `str0m` SRTP。软件编码、CPU bitmap、跨 Adapter 和 opaque 路径不再作为运行时回退；硬件能力或证明不足时明确拒绝会话。IDD 不提供 HDR10/10-bit 能力，本方案不承诺 HDR10。
|
||
|
||
## 尚未实现
|
||
|
||
| 路线 | 未实现的主要能力 |
|
||
|---|---|
|
||
| M0 技术验证 | Tauri 壳、RDP viewer 安全握手/Job Object/D3D11 dirty-rect CPU 上传、native-video 本地文件播放，以及 Linux 远程 H.264 RTP -> Media Foundation NV12 DXGI surface -> D3D11 VideoProcessor -> swap-chain 窗口链路已完成源码接线并通过工作区编译/单元测试；Windows/Linux 实机验收仍未完成。Wayland Portal/PipeWire/EIS 严格媒体路径和认证 WSS 直连 WebRTC 信令已有源码，仍缺 ETW/GPUView 硬件解码和隐藏复制证明、Xorg DRI3，以及 Linux PTY 和图形桌面真实主机端到端实测 |
|
||
| M1 Windows RDP MVP | 原生客户端全部本地显示器布局、自定义显示器子集、D3D11 呈现路径已编译并通过自动化测试；仍缺真实主机验收、硬件解码/零拷贝、断线恢复实机验收、Credential Manager 远端 NLA 验收和正式签名安装包 |
|
||
| M2-M4 Linux Agent | X11 `GetImage`/XTEST、Windows 软件桌面窗口、权限路由、有界帧协议、三次有界桌面重连、用户会话进程内 15 秒绑定令牌续接、GStreamer H.264 AU 编码/WebRTC sender、Linux 输出 monitor Opus 编码/有界 IPC、Windows 远端 H.264 RTP 消费/原生呈现、Opus 解码/WASAPI 播放、认证 WSS 直连 WebRTC 信令、X11/Windows 双向 UTF-8 文本剪贴板，以及 Windows Credential Manager 支持的 helper 崩溃后短时续接已完成源码接线并通过相关 Rust 测试；真实 Linux/Windows 主机验收仍未完成。Wayland Portal 已完成能力探测、认证后授权、PipeWire/EIS fd 所有权、严格 DMABUF-to-VA-H.264 会话循环、呈现 ACK、resize 重建、`reis` EIS 输入和绑定 Portal/EIS 的 15 秒会话恢复源码；仍缺 GNOME/KDE/Xorg/纯终端端到端验证和 Wayland 文本剪贴板实现 |
|
||
| M5 体验和性能 | Linux X11 兼容帧链路已完成采集/编码/解码/呈现耗时源码遥测，并已接入基于呈现 ACK 的有界帧率和 zlib level 1..6 压缩策略自适应；IronRDP 已完成网络图形 PDU 本地处理与像素转换耗时源码遥测；相关 Rust/Web 自动化已通过。正式更新源发布自动化和 Authenticode 签名/验签已完成源码接线但尚未执行生产发布；仍缺 RDP 服务端编码遥测、H.264/Opus 码率与编解码策略自适应、HEVC/AV1、通用会话崩溃恢复，以及真实证书/时间戳/下载/原位升级验收；文件上传/下载断点续传已实现 |
|
||
| Windows Headless Native | 部分 | IDD/IddCx 虚拟显示器、IDD GPU frame、DDA 到 GPU 编码器 zero-copy、NVENC/AMF/VCE/VCN/Quick Sync、HEVC/AV1 和认证 session lifecycle 仍未完成；独立 Opus/WASAPI 源码链已接入 compatibility runtime，但统一 QPC 精确同步和实机验收未完成；SDR 8-bit H.264 compatibility 已接通到 RDV1 GUI；HDR10 明确不在目标范围内 |
|
||
| Windows Headless compatibility | 部分 | DDA staging/readback、CPU BGRA->NV12、Media Foundation H.264、Annex-B、encoded mmap ring、Go RDV1/RDA1/Hysteria2、Rust RDV1 重组、IDR 恢复、GUI MFT/D3D11 呈现，以及独立 WASAPI loopback/Opus/audio ring/jitter/PLC/FEC/WASAPI playback 源码已接入；无 GPU、4K/120、多路压力、统一 QPC 精确音画同步和真实 Windows 端到端验收仍未完成 |
|
||
| Android 控制 Windows | 部分 | 独立 Flutter Android 客户端已接入强制 TOTP、TCP SDP/ICE 信令、WebRTC H.264/RTCP/DTLS-SRTP、可靠控制与低延迟指针 DataChannel、原生 WebRTC Texture 呈现，以及 WebRTC 不可用时的 TCP BGRA+zlib 回退；Rust 与 Dart 自动化已通过。Windows 捕获仍经 DDA CPU readback 与 BGRA-to-NV12，TURN 凭据尚未接入这条 Windows 会话，且需真实 Android/Windows 网络端到端验收，因此不标记为端到端零拷贝。 |
|
||
| M6 CDN 边缘中继 | 已有单节点短 TTL Presence、Linux Agent 心跳、Windows Client 签名 Session Intent、Agent 本地授权、角色票据、远程首次配对、已知设备 outbound-only rendezvous、Linux 终端/文件 TLS-over-relay transport、设备签名的有界双向 SDP/ICE mailbox、授权响应内的 session-bound TURN 短期凭据、Agent/Client 共用的真实 PeerConnection/H.264/RTX/Opus/DataChannel 传输内核、Linux X11 捕获/GStreamer H.264 与 Opus track 发送，以及 Windows H.264 RTP 解码/呈现和 Opus/WASAPI 播放源码；Edge、Agent runtime、Linux terminal 和 native video 的自动化测试已通过。仍缺实际 coturn POP 部署与 UDP/TLS 验收、真实双 POP 骨干指标/亲和/故障切换、RDP TCP/UDP L4 Edge Connector、静态发布 CDN 与跨网络端到端验证 |
|
||
|
||
## 运行时能力接口
|
||
|
||
控制服务提供 `GET /api/v1/capabilities`。界面以该响应为准启用功能，而不是根据设计文档或静态页面推断能力。当前响应示例：
|
||
|
||
```json
|
||
{
|
||
"version": "0.2.10",
|
||
"platform": "windows",
|
||
"application": {
|
||
"desktop_shell": true,
|
||
"shell_kind": "tauri-2"
|
||
},
|
||
"rdp": {
|
||
"probe": true,
|
||
"protocol_probe": true,
|
||
"external_launch": true,
|
||
"native_launch": true,
|
||
"native_diagnostics": true,
|
||
"native_multimon": true,
|
||
"session_network_metrics": true,
|
||
"session_decode_metrics": true,
|
||
"region_pixel_conversion": true,
|
||
"secure_named_pipe": true,
|
||
"secure_pipe_config_ack": true,
|
||
"secure_pipe_handshake_timeout": true,
|
||
"job_object_lifecycle": true,
|
||
"certificate_pinning": false,
|
||
"automatic_reconnect": true,
|
||
"resize_confirmation": true,
|
||
"clipboard": true,
|
||
"audio_playback": true,
|
||
"native_renderer": "d3d11_cpu_upload",
|
||
"d3d11_device_available": true,
|
||
"d3d11_dirty_rect_upload": true,
|
||
"credential_manager": true,
|
||
"credential_store": true
|
||
},
|
||
"linux": {
|
||
"agent_session": true,
|
||
"agent_probe": true,
|
||
"terminal_session": true,
|
||
"desktop_session": true,
|
||
"x11_desktop": true,
|
||
"relative_pointer": true,
|
||
"adaptive_frame_pacing": true,
|
||
"adaptive_compression": true,
|
||
"desktop_session_resume": true,
|
||
"desktop_session_crash_resume": true,
|
||
"direct_webrtc_signaling": true,
|
||
"opus_audio": true,
|
||
"clipboard_read": true,
|
||
"clipboard_write": true,
|
||
"wayland_desktop": true,
|
||
"native_video": false,
|
||
"native_video_decoder_probe": true,
|
||
"native_video_surface_presenter": true,
|
||
"file_transfer": true,
|
||
"agent_identity_store": true
|
||
},
|
||
"edge": {
|
||
"relay": false,
|
||
"signed_intent": true,
|
||
"linux_session_relay": true,
|
||
"linux_known_device_rendezvous": true,
|
||
"remote_pairing": true
|
||
},
|
||
"update": {
|
||
"configured": false,
|
||
"check": false,
|
||
"install": false
|
||
}
|
||
}
|
||
```
|
||
|
||
`application.desktop_shell` 只在 Tauri 壳实际启动本次控制服务时为 `true`，此时 `shell_kind` 为 `tauri-2`；直接运行控制服务时分别为 `false` 和 `standalone`。`native_launch`、`rdp.session_network_metrics`、`rdp.secure_named_pipe`、`rdp.secure_pipe_config_ack`、`rdp.secure_pipe_handshake_timeout`、`rdp.job_object_lifecycle` 和 `protocol_probe` 只有在对应 helper 与控制服务位于同一目录时才为 `true`；`session_network_metrics` 表示 viewer 能把服务器提供的 RDP Network Characteristics 平均 RTT、基础 RTT 和带宽写入会话诊断，不表示每台服务器必然发送该结果；`secure_named_pipe` 表示控制服务启动 viewer 的真实运行时路径会执行受限 ACL、OS 进程身份和 challenge MAC 校验，`secure_pipe_config_ack` 表示 viewer 只有在严格 schema 和全部字段校验后才发送载荷摘要认证 ACK，服务端会验证 ACK 版本、摘要和 MAC，`secure_pipe_handshake_timeout` 表示连接、认证、配置与 ACK 受同一绝对 deadline 约束，`job_object_lifecycle` 表示同一路径会把 viewer 绑定到随控制服务关闭的 Job Object。`update.configured` 和 `update.check` 只有在更新清单 URL 与 Ed25519 公钥成对配置后才为 `true`；`update.install` 还要求 Windows 安装包中存在升级 helper。当前能力 JSON 不包含虚拟机电源集成。非 Windows 构建会将 Windows 启动、凭据和 MSI 安装能力报告为 `false`。Linux Agent 是独立被控端发布物；`linux.agent_session`、`agent_probe` 和 `terminal_session` 表示本控制端是否包含对应会话 helper，并不表示已经完成真实 Linux 主机验收。`linux.agent_probe` 只验证直连地址的固定证书 TLS/WSS 和公开 `Hello`，不认证用户或证明桌面会话可成功打开。`linux.agent_identity_store` 表示控制端可在 Windows Credential Manager 查询和删除证书绑定的 Agent 公钥映射。`linux.relative_pointer` 表示 Windows helper 和协议支持抓取光标、合并 Raw Input 位移并通过 XTEST 相对移动；它不代表 Wayland/libei。`linux.adaptive_frame_pacing` 与 `linux.adaptive_compression` 分别表示真实呈现 ACK 驱动的帧率和 zlib 压缩等级控制。`linux.desktop_session_resume` 表示 helper 进程内的短时传输续接；`linux.desktop_session_crash_resume` 仅在 Windows 控制端报告，表示恢复令牌可由 Credential Manager 跨 helper 进程保留。`edge.signed_intent` 表示签名准入，`edge.linux_session_relay` 表示终端/文件 opaque relay，`edge.linux_known_device_rendezvous` 表示已记录身份的设备无需 Client-Agent 直连，`edge.remote_pairing` 表示持有 Agent 本地输出公钥和证书指纹的 Client 可在有效配对窗口内经 Edge 首次配对；通用 `edge.relay` 仍为 `false`，因为媒体、RDP 和真实 POP 选择尚未接入。
|
||
|
||
`rdp.session_decode_metrics` 只有在原生 viewer helper 与控制服务位于同一目录时才为 `true`。它表示 viewer 能报告网络图形 PDU 的本地 IronRDP 处理及 dirty region 像素转换耗时，不表示 RDP 服务端编码耗时、GPU 视频解码或端到端延迟。`rdp.region_pixel_conversion` 表示图像事件只携带经过边界验证的变化区域像素块，viewer 会将其合并到持久 framebuffer；诊断中的 `frame_conversion_pixels` 是最近一次实际转换数量。
|
||
|
||
`linux.direct_webrtc_signaling` 仅表示同版本 helper 含协议 minor 13 的直连 SDP/ICE 和显式失败回退状态机，不表示 PeerConnection、H.264 或 Wayland 已通过实机验收。
|
||
|
||
`linux.opus_audio` 只在 Windows 控制端能找到同版本 Linux 桌面 helper 时报告。协议 minor 14 用默认关闭字段显式协商音频，并把选择绑定到直连授权或 Edge 桌面请求；它表示源码包含 Linux 输出 monitor 捕获、Opus 有界传输和 Windows WASAPI 播放，不表示音频设备、GStreamer 插件或跨网络播放已经实机验收。
|
||
|
||
`linux.clipboard_read` 和 `linux.clipboard_write` 只在 Windows 控制端能找到同版本 Linux 桌面 helper 时报告，并分别表示协议和本地 helper 可读取被控端 X11 文本剪贴板、可把 Windows 文本剪贴板写入被控端。Xorg 主机设置提供两个独立开关，控制服务只向 helper 传递启用的方向，helper 再与协议 minor 15 和配对记录中的同名授权取交集；CLI 未显式传入对应开关时默认关闭。Linux 桌面会话诊断另回传最终交集的 `clipboard_read`/`clipboard_write`，界面只在会话连接后按该结果显示实际方向，连接和重连期间显示等待协商，不再把本地主机开关当作 Agent 已授权。这两个能力字段不表示 Wayland 剪贴板可用，也不代替 Windows/Xorg 实机验收。
|
||
|
||
`rdp.resize_confirmation` 只有在原生 viewer helper 可用时为 `true`。它表示 resize 请求带 generation，只有匹配目标尺寸的远端图像才确认成功；不支持或超时后的重连由原生窗口明确询问用户，不表示所有 RDP 服务端都支持在线 Display Control。
|
||
|
||
`rdp.native_multimon` 表示控制服务和 viewer 支持严格传递“全部本地显示器”请求、枚举真实 Win32 monitor geometry，并在 RDP Display Control capabilities 到达后发送多 monitor layout。它不表示自定义显示器子集，也不替代真实 Windows RDP 服务端兼容性验收。
|
||
|
||
`rdp.d3d11_dirty_rect_upload` 只有在 Windows D3D11 device 可创建且原生 viewer helper 可用时才为 `true`。它表示 viewer 保留 IronRDP 图形更新区域、合并 redraw 前的待呈现矩形，并局部更新持久 GPU texture；它不表示持久 CPU framebuffer、GPU texture 到 discard swap-chain back buffer 的复制、硬件视频解码或端到端零拷贝已经消失。
|
||
|
||
`linux.native_video_decoder_probe` 只有在 Windows 控制端能够运行 native-video helper，且 helper 成功创建 H.264 decoder、NV12 texture array 和 decoder output view 时才为 `true`。探针输出同时固定声明 `sample_decoded=false` 和 `zero_copy_verified=false`，控制服务会验证这些边界标记；该字段不能用于开放 Linux 图形会话，只有完整媒体管线完成后 `linux.native_video` 才能变为 `true`。
|
||
|
||
`linux.native_video_surface_presenter` 只有在同版本 helper 的严格 `--capabilities` JSON 声明 H.264 file player、D3D11 VideoProcessor 和禁用 CPU frame mapping 时才为 `true`。它表示本地文件 DXGI surface 到原生窗口的呈现入口已包含在当前 helper，不表示远程 WebRTC 已接入、硬件 decode engine 已验证或端到端零拷贝成立。
|
||
|
||
## 更新规则
|
||
|
||
实现功能时应同时更新本页、相关使用指南和能力接口。纯数据模型、dry-run、静态界面或模拟数据不能标记为“可用”，硬件和跨网络能力必须保留对应平台的验证记录。
|
||
|
||
## 2026-08-11 构建与自动化验证记录
|
||
|
||
### 2026-08-11 继续发布构建
|
||
|
||
- 为保留重装前连接配置，Tauri 壳优先绑定固定 `127.0.0.1:4173`，避免 WebView origin 改变导致 `localStorage` 丢失；若该端口已被占用则回退临时端口，需先关闭占用进程后再启动以继续使用原连接数据。
|
||
- 当前 0.2.10 Windows 客户端 MSI：`artifacts/RemoteDesk-M0-0.2.10-windows-x64.msi`，SHA-256 `58be77dbb975c392910ef372d29b0db19e590cf555802fa98f9941ef5321cf26`。
|
||
- 当前 0.2.10 Windows 被控端 MSI：`artifacts/RemoteDesk-Host-0.2.10-windows-x64.msi`，SHA-256 `35830c543a86a08c39644af2346b6ac50802a1084bd156e12a97301de820335e`。
|
||
- 两个 MSI 均为未签名开发包。
|
||
|
||
- `cargo check --locked --workspace -j 1` 已通过（全工作区）。
|
||
- Windows 客户端发布 MSI 已重新生成：`artifacts/RemoteDesk-M0-0.2.9-windows-x64.msi`，SHA-256 `757dcc2470393c60aa98939a74283d9ef2805e27bdaa3265cf309753894dbb06`。
|
||
- Windows 被控端发布 MSI 已重新生成：`artifacts/RemoteDesk-Host-0.2.9-windows-x64.msi`，SHA-256 `eae9afbe226225697c2b22a208a084e13ed52609ff2215e467cbe2267e3c9620`。
|
||
- 两个 MSI 均为未签名开发包；Windows Named Pipe 真实握手的 4 个测试仍失败（`ERROR_NO_DATA`/`UnexpectedEof`），因此该安全握手不能视为实机验收完成。
|
||
- 修复 `remotedesk-linux-terminal` 调用 Edge presence 时遗漏 `DesktopMediaEvent` 通道参数；`remotedesk-edge-service`、`remotedesk-linux-terminal`、`remotedesk-native-video` 测试现已全部通过（22、1、26、15 项）。
|
||
- 追加串行回归：`remotedesk-control-service` 31 项测试和 `remotedesk-credential-store` 8 项测试全部通过；完整 `cargo test --workspace` 仍在工作区级别超时，尚未将其计为通过。
|
||
- 追加协议/RDP 回归：`remotedesk-protocol` 45 项、`remotedesk-rdp-session` 8 项、`remotedesk-rdp-viewer` 34 项全部通过；Tauri app 目标也可完成 0 测试编译运行。
|
||
- `cargo test --locked --workspace --exclude remotedesk-client-core -j 1` 已完整通过；工作区其余包（Agent core/runtime、app、control-service、credential-store、edge、Linux terminal、native video、protocol、RDP session/viewer）均无失败。完整工作区的未完成项已明确收敛为 client-core 的 4 个 Windows Named Pipe 实测用例。
|
||
- 最新源码已重新生成 Windows MSI：客户端 `RemoteDesk-M0-0.2.9-windows-x64.msi` SHA-256 `9b94158e001dc94816d62ce92bdc33fe6d5040795810e330b76d7e7a023df6ae`；Host `RemoteDesk-Host-0.2.9-windows-x64.msi` SHA-256 `b4241792fba8900112472ad0c1b23316801f878c8eb0a93e3269ea3ba0b710cb`。两者均为未签名开发包。
|
||
- Rust 在线升级清单生成器 `remotedesk-update-manifest` 的契约测试通过，覆盖签名字段、目标平台、MSI 类型、防覆盖和篡改拒绝；生产更新源、真实签名证书/时间戳和原位升级仍未验收。
|
||
- `remotedesk-client-core` 排除 4 个 Windows Named Pipe 实测用例后，其余 40 项测试全部通过；协议、显示布局、GPU 策略、凭据、会话和帧编解码均已自动化验证。
|
||
|
||
- Windows MSVC 工作区核心包已通过 `cargo check --locked -j 1`，覆盖协议、客户端核心、RDP viewer、控制服务、Linux Agent runtime 和 Edge service；Linux Agent runtime 的 43 个单元/协议/本地 Edge HTTP 集成测试全部通过。Edge 测试使用进程内真实 HTTP 服务，测试环境设置 `NO_PROXY=localhost,127.0.0.1`，不会把本地连接误送代理。
|
||
- Tauri `remotedesk-app`、Linux terminal helper、native-video helper 和 RDP session helper 也已通过 `cargo check --locked -j 1`；Linux terminal helper 的未使用导入和可变绑定 warning 已清理。
|
||
- Rust 原生控制端与 `remotedesk-update-manifest` 已纳入 workspace check/test；JavaScript、C#、Node.js 和 `csc.exe` 构建入口已删除。
|
||
- Linux x86_64 musl 被控端便携包和 DEB 已实际生成并写入 SHA-256 清单。静态兼容包使用 `--no-default-features`，关闭依赖系统 `libxkbcommon` 的 Wayland EIS 输入；该包仍包含 X11/终端/文件会话，Wayland EIS 运行时返回明确的不可用错误。
|
||
- 当前重建产物哈希：Windows 控制端 MSI `cd9a993edbd3eeac48626127880bb8089455c9c64cf86500f0a153c8a22c6e76`；Windows Host MSI `f70bb19c9f1997eee98fe02b20267c6807f3171c5c0232a9ac3ecae497`；Linux tar.gz `6a17413eb74f47879002eef93aa8122e22e0d1347bbb499489b1dfe31f52e28d`；Linux DEB `410dd67c5a18ac7634afa192a527bbce3e958f01413ded14e97a330691e92215`。
|
||
- Windows 原生 RDP 自定义显示器子集现已完成 secure-pipe JSON、控制端请求、Web UI 选择、viewer 参数和 Win32 monitor layout 筛选：索引必须唯一、范围有效且包含主显示器，筛选后重新计算组合窗口边界；viewer 单元测试和 Web build 已通过。仍需真实多显示器 Windows RDP 服务端验收。
|
||
- 自定义显示器子集接入后的控制端 MSI 已重新生成，最新 SHA-256 为 `66b34ea4a0292e6a4ddb5b8feab56ead19d6660135785f1893405e63cec4c7f0`（未签名开发包）。
|
||
- 上述结果证明可编译和自动化测试覆盖，不等同于 Windows RDP 服务端、GNOME/KDE/Xorg、PipeWire/VA 驱动、coturn 跨网络或硬件解码的实机端到端验收；这些项目仍保持原有“部分”状态。
|
||
|
||
## Windows Headless 媒体实现状态
|
||
|
||
本轮已完成以下可运行基础：
|
||
|
||
- protocol/src/windows_media.rs 提供 SDR 8-bit/NV12、H.264/HEVC/AV1、Opus、硬件优先和 compatibility 降级的校验模型。
|
||
- transport/hysteria2-agent 已接入 RDV1 视频分片大小校验和 Hysteria2 UDP datagram 转发；视频重组超时丢弃，不重传过期视频。Go client 还提供可选的 encoded-ring consumer，将 Rust 的 H.264 Annex-B access unit 复制、分片并发送到同一认证 Hysteria2 UDP session。
|
||
- agent/windows-agent/src/media_ring.rs 提供跨进程 memory-mapped SPSC ring 和 session-bound encoded-only descriptor，承载已编码码流，不承载原始 BGRA/NV12。满队列时非阻塞返回，调用方可丢弃视频包；Windows H.264 compatibility worker 已写入该 ring，Go Hysteria2 client 可通过 `--encoded-ring` 打开消费者并转成 RDV1 datagram。Windows 创建 ring 时使用受保护 DACL，只授权当前用户 SID，并允许同一会话消费者映射及关闭清理。
|
||
- remotedesk-windows-agent pipe 已使用当前用户 SID ACL、拒绝远程 Pipe 客户端和首实例保护；默认要求 `REMOTEDESK_AGENT_PIPE_TOKEN` 提供随机 32 字节 base64url bootstrap，每个连接以随机 nonce 执行 HMAC-SHA256 challenge，认证总时限 10 秒，认证后才把 `authenticated: true` hello 和 ring descriptor 交给 Go bridge。`--allow-unauthenticated` 与 loopback TCP 自动编排只保留本地开发兼容。
|
||
- Windows agent 的桌面请求支持 capture_mode: strict_hardware|compatibility 和 video_codec: h264|hevc|av1。Windows 兼容捕获已实现 Desktop Duplication 的 D3D11 staging/readback 路径，并在 DDA 不可用时回退 GDI；响应会报告实际后端、cpu_readback、cpu_map_count 和 degraded。H.264 compatibility worker 已完成 DDA BGRA -> CPU NV12 -> Media Foundation MFT -> Annex-B AU -> encoded ring 的短样本运行链；`hardware_encoder_verified` 只表示 MFT 短样本成功，`hardware_pipeline_verified` 仍为 false，因此 strict 请求仍返回结构化不可用错误。
|
||
- protocol 的 RDV1 decoder/reassembler 严格校验 58 字节 header、未知 flags、分片位置、元数据一致性、重复分片和 16 MiB 上限；首帧、序号中断、分片过期或 discontinuity 后丢弃 P-frame，直到收到 IDR。viewer 以一槽待处理门控接收 loopback RDV1，积压时丢视频而不阻塞输入；H.264 Annex-B 进入 D3D11-aware Media Foundation decoder，只接受同 device NV12 DXGI surface，再由 D3D11 VideoProcessor 呈现。
|
||
- protocol 与 Go transport 的 RDA1 decoder 严格校验 40 字节 header、version、reserved byte、已知 flags、stream/generation/sequence、10/20/40/60 ms duration 和 4 KiB Opus payload 上限；音频 datagram 不与视频帧重组，也不等待视频。Windows Agent 使用独立线程执行 WASAPI loopback、48 kHz 双声道归一化、20 ms Opus 编码并写入独立 audio mmap ring；Go bridge 独立轮询并发送 RDA1。audio ring 或 callback 积压时显式标记 discontinuity，不阻塞视频或输入。
|
||
- windows-agent-viewer 在 --media-udp 模式严格区分 RDV1/RDA1，使用容量 64 的非阻塞接收队列、三包启动缓冲、最多 64 包的有界 jitter map、Opus in-band FEC/PLC、按实际输出设备采样率重采样和 CPAL/WASAPI playback。音频设备或解码失败只关闭音频；音频播放时钟建立后，viewer 丢弃明显落后的旧视频帧，不等待未来视频帧。播放端现在以连续按序音频 PTS 估计源时钟偏差，并结合 60 ms 目标 PCM 占用以原子 ppm（±0.5%）调节重采样步长；stream/generation/discontinuity 重置时清空旧 PCM、清零校正并重新预缓冲。
|
||
- viewer 最多每 250 ms 合并一次 `request_keyframe`，经独立可靠输入连接按 session ID 路由到 Agent 的一槽请求队列；编码 worker 使用 `ICodecAPI/CODECAPI_AVEncVideoForceKeyFrame` 请求 IDR。Go Hysteria2 client 可通过 `--windows-agent-pipe` 完成 challenge 后自动打开编码会话并严格校验 ring descriptor，也保留手工 `--encoded-ring` 与开发用 loopback `--windows-agent-control` 模式。
|
||
|
||
以下仍未完成，不能作为已支持能力发布：
|
||
|
||
- IDD/IddCx 虚拟显示器驱动、Desktop Duplication 到 GPU 编码器的 zero-copy capture、BGRA 到 NV12 的 D3D11 GPU conversion。
|
||
- NVENC、AMF/VCE/VCN、Quick Sync 真实编码器探测与编码 worker，以及 x264/x265/SVT-AV1 真实 fallback。
|
||
- 音视频生产端统一 session-start QPC/PTS 映射已接入 Windows Agent compatibility 链；viewer 接收端已完成连续音频 PTS 漂移估计、60 ms PCM 占用反馈和 ±0.5% 有界动态重采样。仍需 Windows 实机长时间稳定性、默认设备切换/拔出和跨设备音画端到端验收，不能据此宣称已完成生产级硬件媒体链。
|
||
- WASAPI 默认设备切换/拔出、无输出设备、callback error、长时间稳定性、纯 Rust `mousiki` Opus 后端的产物体积/许可证和真实 Windows 音画端到端验收。
|
||
- 认证 Named Pipe 和 ring 当前按 Windows 当前用户 SID 隔离；生产安装器/控制服务仍需负责生成每次 Agent 生命周期唯一的 bootstrap、仅注入目标 Agent 与 Go bridge、启动后清除父进程环境，并把两进程纳入统一 Job/service 生命周期。viewer 的输入事件使用独立持久连接和有界优先队列，Win32 全局键盘 hook 复用该队列。
|
||
- Windows 实机下的多路 4K/120 性能、实际丢包/IDR 恢复和 NVENC/AMF/QSV 多路 session 压力测试。
|