Initial commit

docs/development.md

@@ -0,0 +1,180 @@
+# RemoteDesk 开发指南
+
+## 1. 环境
+
+- Rust stable，包含 rustfmt 和 Clippy。
+- Node.js 22 与 npm 10。
+- Windows RDP viewer 的安全 Named Pipe 和 Tauri 2 桌面壳已完成源码接线；Linux 远程 H.264 的 RFC 6184 接收、Media Foundation NV12 解码和 D3D11 VideoProcessor 窗口呈现也已接线，但尚未编译、实机验证或通过 ETW/GPUView 证明硬件解码与隐藏复制边界。Tauri 和媒体新依赖按本轮要求尚未解析或编译。
+- Linux PipeWire、Portal、DRI3 与硬件编码器必须在对应 Linux 测试机执行 M0 Spike。
+
+## 2. Rust workspace
+
+```powershell
+cargo fmt --all -- --check
+cargo clippy --workspace --all-targets -- -D warnings
+cargo test --workspace
+```
+
+当前 crate：
+
+- `remotedesk-protocol`：required features、显示拓扑/选择、协商摘要、双端内存路径报告和严格聚合。
+- `remotedesk-agent-core`：Linux 单/多屏捕获能力、逐屏 GPU import probe、编码器选择和分辨率/布局重验证。
+- `remotedesk-agent-runtime`：Linux `agentd`、用户会话 IPC、设备配对/WSS 认证、PAM/PTY 终端 helper，以及 Edge Presence、设备签名 poll/ack 和本地 Session Intent 授权。
+- `remotedesk-client-core`：会话状态、helper 身份验证、RDP 凭据引用、多屏布局、GPU 计划和本地呈现报告。
+- `remotedesk-control-service`：仅监听回环地址，提供静态界面、RDP 探测和三种 RDP 启动方式编排。
+- `remotedesk-rdp-session`：独立的无凭据 IronRDP 协议与 TLS 证书探针，只从 stdin 接受目标和超时。
+- `remotedesk-rdp-viewer`：独立 IronRDP 原生窗口；Windows 优先使用 D3D11 swap chain CPU 上传呈现，失败时回退 software framebuffer，不经过 React IPC。
+- `remotedesk-native-video`：输出 D3D11 管线计划，并可在 Windows 真实创建硬件 device/immediate context。
+- `remotedesk-edge-service`：独立 Edge Presence、有界签名 Session Intent 队列、Allocator/coturn credential 服务和限额透明 TCP byte relay；不随控制端或 Agent 进程启动。
+
+运行 native-video 规划：
+
+```powershell
+cargo run -p remotedesk-native-video -- --dry-run --window-adapter gpu-0
+```
+
+`--dry-run` 输出中的 `d3d11_created=false` 仅表示该规划命令不创建设备。真实设备探针使用：
+
+```powershell
+cargo run -p remotedesk-native-video -- --probe-d3d11
+```
+
+创建真实 H.264/DXVA decoder 对象、NV12 texture array 和 output view（仍不提交样本，也不证明零拷贝）：
+
+```powershell
+cargo run -p remotedesk-native-video -- --probe-h264-decoder
+```
+
+使用本地 H.264 MP4/M4V/MOV 文件验证首个解码样本必须以同一 device 上的 NV12 DXGI texture 返回：
+
+```powershell
+cargo run -p remotedesk-native-video -- --probe-h264-file C:\samples\baseline.mp4
+```
+
+在原生窗口按媒体时间戳播放同一受限 H.264 文件，并通过同 device D3D11 VideoProcessor 呈现 NV12 surface：
+
+```powershell
+cargo run -p remotedesk-native-video -- --play-h264-file C:\samples\baseline.mp4
+```
+
+窗口按启动配置进入全屏；按 `Ctrl+Alt+F` 在全屏与窗口模式之间切换，其余键盘输入直接转发到远端。该入口不映射 CPU frame，但在 ETW/GPUView 验证前仍不声明硬解或零拷贝。
+
+输入必须是本地常规文件且不超过 512 MiB；UNC、空文件、非 H.264 video stream、CPU media buffer、错误 subresource 或不同 D3D11 device 均失败。成功只证明样本进入 DXGI surface，正式 `hardware_decode`/`zero_copy` 仍要求 ETW/GPUView 和完整呈现链验证。
+
+成功时必须输出 `d3d11_created=true`、hardware driver type 和实际 feature level；这仍不代表解码器或端到端零拷贝已经接入。IronRDP viewer 的 swap chain 是独立 CPU 上传呈现路径。
+
+控制服务还提供 `GET /api/v1/capabilities`。Web UI 必须以该接口启用运行时功能；设计稿中存在但未接入的功能保持 `false`。新增实际能力时，应同时更新 [实现状态](implementation-status.md) 和接口测试。
+
+## 3. Web 管理界面
+
+```powershell
+cd client/web
+npm ci
+npm run lint
+npm run build
+npm run control
+npm run dev
+```
+
+控制服务监听 `http://127.0.0.1:4174`，Vite 开发服务器监听 `http://127.0.0.1:4173` 并转发 `/api`。默认主机列表为空，配置保存在浏览器本地存储；使用 `?demo=1` 才加载示例主机。
+
+受限环境可用 `npm run build:check` 完成不写入 `dist` 的完整 Vite 构建检查。
+
+## 4. M0 Windows 预览包
+
+```powershell
+.\packaging\windows\package-preview.ps1
+```
+
+输出位于 `artifacts/RemoteDesk-Portable-M0-<version>-windows-<arch>.zip`，并生成外部 `SHA256SUMS.txt`。解压后运行 `bin/remotedesk.exe`；Tauri 壳会选择随机 loopback 端口、验证控制服务的一次性启动 proof，并且只在 RemoteDesk WebView 中加载管理界面，不打开系统浏览器。
+
+该压缩包不是 MSI，也不包含 Linux Agent。Windows 同时提供 Tauri 壳、`mstsc`、独立 IronRDP viewer 和 Windows Credential Manager 凭据适配器；viewer 支持固定/自定义初始尺寸、窗口动态分辨率、全屏和主动退出，协议探针会确认服务端 RDP 协商与 TLS 证书，但不会尝试账号登录。
+
+生成按当前用户安装的 MSI：
+
+```powershell
+.\packaging\windows\package-installer.ps1
+```
+
+输出位于 `artifacts/RemoteDesk-M0-<version>-<culture>-windows-<arch>.msi`，其中 `culture` 支持 `zh-cn` 和 `en-us`，默认是 `zh-cn`；校验文件为 `artifacts/INSTALLER-SHA256SUMS.txt`。安装目录是 `%LOCALAPPDATA%\Programs\RemoteDesk`，安装器创建开始菜单快捷方式并注册 Windows 卸载入口，不要求管理员权限。
+
+使用统一脚本选择安装器语言：
+
+```powershell
+.\packaging\build-all.ps1 -Culture zh-cn
+.\packaging\build-all.ps1 -Culture en-us
+
+# 只构建 Hysteria2 UDP/QUIC 传输包
+.\packaging\build-all.ps1 -SkipClient -SkipHost
+
+# 重新生成全部产物前清空 artifacts
+.\packaging\build-all.ps1 -CleanArtifacts -Culture zh-cn
+```
+
+脚本下载固定版本和 SHA256 的 WiX 4.0.6 到忽略提交的 `target/tools`，WiX 不进入 MSI。当前没有切换到附带额外维护条款的 WiX 6 预编译发行包。无签名参数时脚本生成明确标记的开发包；正式环境先把具有私钥和 Code Signing EKU 的证书导入 `Cert:\CurrentUser\My`，再运行：
+
+```powershell
+./packaging/windows/package-installer.ps1 `
+  -SigningCertificateThumbprint <40位SHA1指纹> `
+  -TimestampUrl https://timestamp.digicert.com `
+  -ReleaseChannel stable
+```
+
+该路径在 payload 哈希之前签署并验证内部 EXE 和 PowerShell，在最终 MSI 哈希之前签署并验证 MSI。生产自动化及密钥要求见 [在线升级](online-updates.md)。
+
+## 5. 被控端安装包
+
+Windows 被控端 MSI：
+
+```powershell
+.\packaging\windows-host\package-host.ps1
+```
+
+输出 `artifacts/RemoteDesk-Host-<version>-<culture>-windows-x64.msi`。这是 per-machine 包，但安装过程不自动修改 RDP；用户从开始菜单显式配置时才提权、备份并启用。脚本支持 `-Culture zh-cn|en-us`，并接受与控制端相同的 `-SigningCertificateThumbprint` 和 `-TimestampUrl`，正式发布时先签署 PowerShell payload，再签署最终 MSI。当前脚本继续使用固定哈希的 WiX 4.0.6，不引入 WiX 6 预编译包的额外维护协议。
+
+Ubuntu/Fedora 构建机生成 Linux DEB/RPM：
+
+```sh
+sh ./packaging/linux/package-deb.sh
+sh ./packaging/linux/package-rpm.sh
+```
+
+Windows 开发机如已安装 Rust musl target、Android NDK LLVM 和 Git for Windows，可生成静态 x64 便携包与 musl DEB：
+
+```powershell
+.\packaging\linux\package-musl.ps1
+```
+
+Linux 包的 `/etc/remotedesk/agent.env` 包含默认监听地址和可选 Edge Presence 注释模板。Presence 配置必须四项同时存在；测试只能使用专用的非生产令牌，公网 URL 必须为 HTTPS。`remotedesk-agentd status --json` 可检查持久化的非敏感健康状态，SIGINT/SIGTERM 会触发限时 connection-bound 注销。
+
+Ubuntu 22.04 CI 会对 Linux 目标执行测试和 Clippy，再构建原生 DEB/RPM。Windows 上的 musl 交叉构建只验证静态 ELF 和包结构，不能替代 systemd、PAM、PTY 和发行版安装测试。
+
+独立 Edge 服务在 Ubuntu 构建原生 DEB：
+
+```sh
+sh ./packaging/edge/package-deb.sh
+```
+
+Windows 开发机生成静态 Edge TAR 和 musl DEB：
+
+```powershell
+.\packaging\edge\package-musl.ps1
+```
+
+输出为 `artifacts/RemoteDesk-Edge-<version>-linux-x64.tar.gz` 和 `artifacts/remotedesk-edge_<version>_amd64-musl.deb`。配置与部署边界见 `packaging/edge/README.md`：HTTP API 只能监听 loopback 并经 HTTPS reverse proxy 发布，TCP relay 应经 TLS/L4 入口发布，安装包不生成密钥且不会自动启动服务。CI 对 Edge crate 单独执行测试、Clippy 和 DEB 构建。
+
+本地联合验证可让 Agent 使用 Presence 专用令牌注册，再在 Windows 控制端“全局设置 > Edge 会话授权”填写 HTTPS Origin。Client 的 Session Intent 提交和状态查询由 Client Ed25519 key 认证，不要把 `REMOTEDESK_EDGE_API_TOKEN` 写入 Windows 设置。首次配对时录入 Agent 本地 `pairing-code` 命令输出的设备公钥和证书指纹；只要 Agent 已在线且本机配对窗口仍有效，未配对 Client 即可提交独立 `pairing` Intent，经角色票据和 opaque relay 完成证书固定 TLS/WSS、Agent 公钥核对、Client challenge 签名及一次性码验证，无需连接 Agent listener。成功后 Agent 公钥按证书指纹保存在 `RemoteDesk/Linux/agent/<certificate-sha256>` Windows Credential Manager 条目；缺少 Edge 或设备公钥时保留直连配对回退。后续已知设备同样直接向 Edge 建立，控制端可检查或显式删除身份映射。自动化联合测试连续覆盖远程首次配对、已知设备重连、双向 TLS/WebSocket 字节和两类票据重放；另一组联合 API 测试覆盖接受会话内签名 SDP/ICE mailbox 的双向 offer/answer、伪造、重放和顺序/代际冲突。这些测试仍不能替代端点 WebRTC、真实 TURN POP 或跨网络媒体验证。
+
+## 6. 实现边界
+
+首轮代码只实现可测试的策略和状态模型。以下能力仍必须由 M0 实验验证：
+
+- PipeWire DMA-BUF 到硬件编码器无 CPU 回读。
+- Xorg 捕获后端；Portal/PipeWire 优先，DRI3 只能按环境验证。
+- GStreamer D3D11 decoder、allocator、sink 和 Adapter LUID 一致。
+- IronRDP NLA、动态分辨率服务端兼容性、UDP multitransport 和图形 surface 的真实 Windows 主机验证。
+- TWCC/GCC、RTX/FEC 与硬件编码器码率动态更新。
+- RDP viewer Named Pipe/Job Object 尚需 Windows 实机完成 ACL、PID/创建时间、镜像 hash、challenge MAC、控制服务崩溃回收和 helper 失败诊断验收；Tauri 壳需完成依赖解析、Windows 编译、随机端口导航限制、控制服务异常退出和升级重启验收，native-video 管道仍未接入。
+- Windows Credential Manager 与 RDP NLA 凭据交付的真实远端登录验收。
+- RDP Display Control 与 Linux Portal/XRandR 多显示器平台适配、热插拔和混合 DPI 实测。
+- Linux WSS 配对、`SO_PEERCRED` IPC、PAM/PTY 和 systemd 在真实发行版的端到端实测。