nefarius/vd_agent

源代码：https://github.com/nefarius/vd_agent

适用于 Windows 的 Spice VD Agent

面向 SPICE（https://www.spice-space.org/）的社区维护型 Windows 客户机代理。本仓库是已弃用的 freedesktop.org spice/win32/vd_agent（https://gitlab.freedesktop.org/spice/win32/vd_agent）项目的公共镜像。
正式发布版本可在 GitHub Releases（https://github.com/nefarius/vd_agent/releases）下载。

该代理提供以下功能：

• 无需捕获指针即可启用客户端鼠标模式
• 客户端分辨率与桌面分辨率自动匹配
• 剪贴板共享（文本和图像）
• 向客户机传输文件
• Windows 服务（spice-agent）在每个会话中启动 vdagent.exe

项目状态

Red Hat 已不再维护上游 SPICE。本分支使 Windows 代理能够持续构建和发布，尤其适用于当前客户机系统，特别是 Linux 上的 Windows 11 虚拟机。代码库已包含来自 d7405ee（https://gitlab.freedesktop.org/spice/win32/vd_agent/-/commit/d7405ee）的多 GPU 鼠标修复（vdagent/desktop_layout.cpp）：当真实 GPU 与 SPICE 显示设备同时直通时，代理不再丢失鼠标移动事件。

许可证与来源

代理采用 GPL-2.0 或更高版本 许可证。详见 COPYING 文件及各源文件头版权声明。原始版权归属于 Red Hat, Inc. 及其他上游作者。本分支不主张 Red Hat 或 SPICE 商标。

固定构建时子模块（请勿随意升级）：

子模块 URL 使用 HTTPS。MSI 升级保留了历史 WiX UpgradeCode（7eb9b146-db04-42d7-a8ba-71fc8ced7eed）。相关产品会在 InstallValidate 之后、安装事务开始之前被移除，因此共享组件会被重新复制而非被旧包卸载程序删除。

由于 wixl 不读取 PE 版本资源，需在 File 表中显式设置 RC_FILEVERSION，并保持与 VS_VERSION_INFO 中的四个字段完全一致。

x64 安装程序仅将 vdagent.exe 和 vdservice.exe 安装到 C:\Program Files\SPICE agent\bin。

克隆仓库

git clone --recursive https://github.com/nefarius/vd_agent.git
cd vd_agent

若已克隆但未包含子模块：

git submodule update --init --recursive

freedesktop GitLab 远程地址在镜像创建后已保留为 upstream。获取方式：

git fetch upstream

本地构建（MSYS2 UCRT64）

使用 Autotools + MinGW-w64 UCRT64 路径是生成安装程序的官方支持方式。CMake + MSVC 仍可用于本地开发，但不会构建 MSI。

前提条件

• MSYS2（https://www.msys2.org/）
• UCRT64 环境（C:\msys64\ucrt64.exe 或设置 MSYSTEM=UCRT64）

在 UCRT64 终端中，于仓库根目录执行：

bash msys2/install.sh
autoreconf -i
bash msys2/build.sh builducrt64
bash msys2/package.sh builducrt64

install.sh 会拉取 autotools、autoconf-archive、UCRT64 工具链、msitools（wixl）及 ImageMagick（用于测试）。PNG 剪贴板转换使用 Windows Vista 及更高版本内置的 Windows Imaging Component。

build.sh 负责配置、编译 vdagent.exe / vdservice.exe，并运行 test-png、test-log 和 test-shell 测试。package.sh 随后调用 make msi 生成：

builducrt64/spice-vdagent-x64-<版本号>.msi

版本字符串通过 build-aux/git-version-gen 从 git describe 获取。发布标签格式应为 v0.11.0（次要版本号递增），以便程序与功能列表中正确显示版本标签。未打标签的构建会添加自上一个标签以来的提交计数（例如 v0.11.0 加上 83 次提交将显示为 0.11.0.83-）。

若该计数加上 --with-buildid 达到 256，配置将失败（因会与下一个微版本号冲突）。

若要对本地构建进行签名，请在 package.sh 执行前签名两个可执行文件，然后对 MSI 进行签名。

可选 MSVC 构建

git submodule update --init --recursive
cmake -S . -B build64 -A x64
cmake --build build64 --config Release
cmake --build build64 --config Release --target check

CI 与发布

GitHub Actions（.github/workflows/build.yml）在 windows-2022 上构建 x64 UCRT64 MSI。

签名通过 SignRelay（https://github.com/nefarius/SignRelay）完成，确保证书不会出现在运行器上。流程与 DsHidMini（https://github.com/nefarius/DsHidMini）一致：

1. 构建并测试未签名二进制文件
2. 在 v* 标签处，就地签名 vdagent.exe 和 vdservice.exe
3. 使用这些二进制文件打包 MSI
4. 对 MSI 进行签名
5. 验证 Authenticode（Get-AuthenticodeSignature 状态 = Valid）
6. 生成 .sha256 校验文件
7. 上传 vdagent-win-x64，并在标签事件时通知 AppVeyorArtifactsReceiver（https://github.com/nefarius/AppVeyorArtifactsReceiver）
8. 将 MSI 和校验文件附加到 GitHub Release

SignRelay 组合操作固定于提交 39ccbe0cef16a383237130380a5aef8db040d5d0。CLI 需要运行器上的 .NET 10（通过 actions/setup-dotnet 设置 10.0.x）。

仓库设置

在 nefarius/vd_agent 中创建以下 Secrets 和 Variables（Settings → Secrets and variables）：

SIGN_RELAY_CI_TOKEN 和 WEBHOOK_URL 可从已正常工作的仓库（如 DsHidMini）复制。SIGN_RELAY_SERVER 已设置为仓库变量。

请勿提交密钥值。 代码签名证书由 Windows SignRelay 代理持有，相关主体/指纹和时间戳配置应在代理端完成，而非本仓库内。

发布流程

1. 更新 CHANGELOG.md
2. 创建带注释的发布标签并推送：

git tag -a v0.11.0 -m "vdagent-win 0.11.0"
git push origin v0.11.0

3. 确认 Build 工作流：
   • 未使用未签名路径
   • 两个可执行文件和 MSI 均验证为 Valid
   • 产物接收器已接受 Webhook
   • GitHub Release 包含 MSI 和 .sha256
4. 在 Windows 11 SPICE 客户机中安装 MSI 并执行以下检查表

若签名开始后标签构建失败，请修复代码树并将标签前移（或使用新的次版本号）。切勿用不同内容复用已发布的 MSI 文件名。

恢复失败发布的方法：删除 GitHub Release 草稿（如有），推送新标签。若用户可能已下载旧版本，请保持已发布标签不变。

appveyor.yml 仅保留以与上游最后 UCRT64 MSI 布局保持历史兼容。GitHub Actions 是权威 CI，待签名 Actions MSI 完成冒烟测试后，应移除 AppVeyor。

Windows 11 虚拟机验证

使用 Linux 上的 Windows 11 客户机（QEMU/KVM + SPICE），显示设备为 QXL 或 qxl-wddm-dod。

1. 全新安装 — 以管理员身份运行 spice-vdagent-x64-*.msi
2. 服务 — spice-agent 状态为“正在运行”/启动类型为“自动”；vdagent.exe 存在于用户会话
3. SPICE 连接 — 重连 virt-viewer/spicy；代理通道已激活
4. 剪贴板 — 双向传输文本和图像
5. 文件传输 — 从客户端拖放文件至客户机桌面
6. 动态分辨率 — 调整客户端窗口大小，使用 WDDM QXL 驱动时客户机桌面随之变化
7. 多 GPU / 直通鼠标 — 添加真实 GPU 进行直通，保留 SPICE 显示设备，确认指针持续移动（d7405ee 修复）
8. 升级 — 覆盖安装旧版 Spice agent MSI；服务恢复正常
9. 卸载 — 移除产品；spice-agent 服务消失

可选 CMake / Fedora 说明

• Fedora 交叉构建仍可通过 .gitlab-ci.yml 和 mingw-spice-vdagent.spec.in 进行，但不用于 GitHub Releases。
• 维护流水线不再生成 x86 MSI 构建。