# 全 Rust 架构迁移计划 本文是 [ADR 0001](adr/0001-all-rust-runtime.md) 的实施计划。它描述目标和验收门槛， 不代表对应能力已经实现。实际完成度以 [实现状态](implementation-status.md) 为准。 ## 迁移原则 - Agent 是服务端，Client 是原生客户端，发布运行时全部使用 Rust。 - 实时会话使用 str0m WebRTC；不自研替代 WebRTC 的媒体传输协议。 - 原始视频帧不得经过 JavaScript、WebView、Tauri IPC 或跨进程 CPU bitmap。 - 每一阶段先建立可重复测试和性能基线，再删除被替代实现。 - 迁移期间旧代码不得继续进入正式安装包或默认 CI 发布产物。 ## 阶段 1：删除 Go/Hysteria2 构建链 状态：未开始。 工作： - 从 Windows、Linux 和聚合打包脚本中删除 Hysteria2 构建步骤。 - 从 CI、发布清单、安装器、systemd 和环境模板中删除 Go/Hysteria2。 - 删除 transport/hysteria2-agent、go.mod、go.sum 及生成物引用。 - 移除 Go 工具链、缓存和供应链审计要求。 验收：Cargo workspace、CI 和所有安装包不调用 Go；仓库不存在被引用的 Hysteria2 二进制、服务或配置；Rust Agent 与 Client 的现有非 Hysteria2 构建仍通过。 ## 阶段 2：新增共享 WebRTC Rust crate 状态：未开始。 工作： - 新增共享 webrtc crate 并锁定 str0m 版本。 - 封装 ICE、SDP、DTLS、SRTP、RTP/RTCP 和 DataChannel 事件状态机。 - 定义 socket 驱动、时钟、超时、证书指纹和会话身份接口。 - 对所有消息、候选地址、SDP 和队列设置上限。 验收：crate 在 Windows、Linux 和 macOS 目标上编译；状态机具备确定性单元测试、 畸形输入测试和超时测试；上层代码不直接依赖 str0m 内部类型。 ## 阶段 3：Agent/Client Loopback 状态：未开始。 工作： - 在同机建立 Rust Agent 与 Rust Client 的 SDP offer/answer 交换。 - 支持 trickle ICE、候选结束、DTLS 指纹校验和 ICE restart。 - 建立可靠有序 control DataChannel。 - 建立不可靠无序 pointer DataChannel。 - 定义协议版本、消息大小、速率和权限边界。 验收：自动化测试完成 SDP、ICE、DTLS 和 DataChannel ping/pong；断开、重连、超时、 伪造指纹、乱序和超限消息均按预期失败；输入通道不被媒体测试流阻塞。 ## 阶段 4：接入 H.264 RTP 状态：未开始。 工作： - 固定 H.264 SDP profile、packetization-mode 和时钟频率。 - 实现 RFC 6184 单 NAL、STAP-A 和 FU-A 打包与重组。 - 接入 RTP 序列号、时间戳、帧边界、NACK、PLI、RTX 和关键帧恢复。 - 使用一到两帧有界队列并丢弃过期帧。 验收：录制码流可在 Agent 与 Client 间连续传输；随机和突发丢包测试可恢复； 缺片帧不呈现；关键帧丢失会请求新 IDR；媒体队列不会无界增长。 ## 阶段 5：平台硬件编码与解码 状态：未开始。 工作： - Windows 接入 Windows Graphics Capture 或 DXGI、Media Foundation 和 D3D11/D3D12。 - Linux 接入 PipeWire、DMA-BUF 和 VA-API。 - macOS 接入 ScreenCaptureKit、VideoToolbox 和 Metal。 - 将编码器、解码器和 GPU surface 约束到可验证的 Adapter/device。 - 不提供软件编码、软件解码或 CPU bitmap 兼容回退。 验收：每个平台至少一个硬件路径完成端到端测试；运行时可证明实际硬件后端、 surface 类型和 Adapter；硬件能力不足时明确拒绝会话，不静默降级。 ## 阶段 6：接入 wgpu 呈现 状态：未开始。 工作： - 使用 winit 管理窗口、显示器、DPI、全屏和输入生命周期。 - 使用 wgpu 创建高性能 Adapter、surface 和呈现管线。 - 为平台解码 surface 建立零拷贝或有证据约束的 GPU interop。 - egui 仅负责控制界面，不读取视频像素。 验收：Windows、Linux 和 macOS 均可呈现测试视频；resize、DPI、全屏、设备丢失和 显示器切换可恢复；不存在通过 JavaScript、WebView 或 CPU bitmap 的帧路径。 ## 阶段 7：接入 Opus 状态：未开始。 工作： - Agent 采集系统输出并编码 48 kHz Opus。 - 通过独立 RTP 音频 Track 发送并维护统一单调时钟。 - Client 使用有界 jitter buffer 解码和播放。 - 音频错误与视频、输入生命周期隔离。 验收：音频连续播放且无无界积压；丢包时使用 Opus PLC；音视频漂移受控； 音频设备切换或失败不会阻塞视频和输入。 ## 阶段 8：接入 STUN/TURN 状态：未开始。 工作： - 支持 host、server-reflexive 和 relay candidates。 - 接入 STUN、TURN/UDP、TURN/TCP 和 TURN/TLS 443。 - 使用短期、会话绑定的 TURN 凭据。 - 支持 ICE restart、网络切换、候选优先级和路径诊断。 验收：局域网直连、不同 NAT、公网 TURN/UDP 和受限网络 TURN/TLS 均完成测试； 客户端显示实际路径、RTT 和 relay；凭据过期、重放和跨会话使用均失败。 ## 阶段 9：更新安装包和 CI 状态：未开始。 工作： - Windows、Linux 和 macOS 只打包 Rust Agent、Rust Client 和必要资源。 - CI 覆盖格式化、Clippy、测试、跨平台编译、SBOM、签名和安装验证。 - 增加 WebRTC loopback、RTP 丢包、DataChannel 和包内容测试。 - 删除 npm、Tauri、WebView2 和 Go 的发布依赖。 验收：三平台产物可安装、升级和卸载；包内容白名单通过；CI 不下载或执行 Go、 Node、Tauri CLI 或 WebView 构建工具；发布产物具备签名、校验和和 SBOM。 ## 阶段 10：删除旧 Tauri/WebView 与兼容路径 状态：未开始。 工作： - 删除 client/web、Tauri app shell、React、Vite、npm lockfile 和 WebView 配置。 - 删除软件视频回退、zlib framebuffer、MSTSC fallback 和 Compatibility 策略。 - 删除旧 helper、旧协议字段、旧测试、旧打包入口和失效文档。 - 更新安全模型、用户指南、实现状态和架构图。 验收：仓库搜索不再出现生产 Tauri/WebView/Hysteria2/Go/Compatibility 入口； 所有正式功能通过 Rust 原生 Client 和 Rust Agent 完成；完整 workspace、安装包和 端到端测试通过。 ## 完成定义 只有十个阶段全部达到验收条件，并且旧构建链不再产生发布产物，才能将全 Rust 迁移标记为完成。存在源码骨架、未运行的平台代码或仅通过 cargo check 均不算完成。