DeepSeek Harness 插件：dsh-vdesktop

前言¶

DeepSeek Harness（DSH）采用插件化架构，允许通过扩展组件增强核心功能。dsh-vdesktop 是其中一款用于解决 GUI 应用交互问题的插件。它利用 Windows 的 CreateDesktopW API 创建一个用户不可见的 Win32 虚拟桌面，将 GUI 应用运行在隔离环境中。DSH 通过内置的 HTTP 抓帧服务与 JSON-RPC 工具链，让 LLM Agent 能够操作这些应用，同时为用户提供了一个真实的 Web 面板进行监控与接管。

插件简介¶

该插件由开发者 jafewff 维护，采用 MIT 许可证。它是一个基于 cordis 机制的插件，核心价值在于提供了一套完整的虚拟桌面生命周期管理工具和可视化交互面板，弥合了纯命令行智能体与图形化界面应用之间的鸿沟。

核心功能¶

插件主要包含以下五个方面的能力：

虚拟桌面生命周期管理
支持创建、附着、列出、关闭虚拟桌面。插件会自动清理带有 dshv- 前缀的“孤儿”桌面，防止资源泄漏。
Agent 工具链
提供 12 个 vdesk_* 工具，覆盖桌面操作、整桌/区域截图、鼠标操作（点击/拖拽/滚动）、键盘输入（含中文与 emoji）、文本读写及文件存取。
帧数据服务
内置 frameServer（HTTP 服务）。端口从 8790 自动探测至 8799，用于 Web 面板低频轮询 PNG 帧数据。响应头包含光标坐标（X-Cursor-X/Y），由前端面板叠加绘制，不烧录进图片。
真实语义点击
面板与 Agent 共享同一执行层。对于标准窗口，通过 WM_NCHITTEST 判别标题栏按钮；对于自绘窗口，走 postmessage 消息。任务栏按钮点击等价于窗口激活或启动。
进程监督
Python Sidecar 以子进程托管，具备心跳监测、惰性重启以及空闲回收机制，确保服务稳定性。

安装与启用¶

安装过程需要手动构建或链接仓库，并配置 Sidecar 路径。

获取代码与构建
克隆仓库并执行构建命令。仓库自带 lib/ 构建产物，通常无需重新构建，除非修改了源码。

    git clone https://github.com/jafewff/dsh-vdesktop dsh-vdesktop
    cd dsh-vdesktop
    npm install
    npm run build

DSH Profile 安装
在 DSH 的 Web Profile 目录（例如 C:\Users\<你>\.dsh\profiles\web）的 package.json 中添加依赖。

    "dependencies": {
      "dsh-vdesktop": "link:<本仓库绝对路径>"
    }

在 profile 配置中将插件加入 `dsh.profile.bundles`，然后执行 `pnpm install` 并重启 DSH。

配置 Sidecar 路径
插件通过 python -m dshv --rpc stdio 启动 Sidecar。需修改 cordis.patch.yml 或配置文件中的 sidecarCwd，将其指向仓库内的 sidecar 目录（绝对路径）。
安装后自检
重启 DSH 后，通过 curl 验证服务是否就绪。

    # 验证桌面列表接口
    curl.exe -s http://127.0.0.1:8790/vdesk/desktops

    # 验证抓帧接口
    curl.exe -s -o NUL -w "%{http_code}" "http://127.0.0.1:8790/vdesk/frame?desktop=dshv-e2e"

打开 DSH Web GUI，确认 `VDesktopPanel` 出现且画面正常刷新。

使用说明¶

Web 面板操作¶

在 DSH Web GUI 中使用 VDesktopPanel。用户可以选择或创建虚拟桌面，画面以低频轮询方式刷新。点击画面上的标题栏（×/最小化/最大化）或任务栏按钮，操作会直接映射为真实的窗口管理消息。

Agent 工具调用¶

Agent 可通过工具调用与虚拟桌面交互。

创建桌面与启动应用：使用 vdesk_desktop_create。注意 launch 是异步的，立即返回 PID 但 windowReady 为 false，需按 PID 匹配顶层窗口。
输入操作：由于虚拟桌面非前台，SendInput 被拒绝，客户区点击实际走 postmessage。键盘工具支持中文和 emoji。
验证安装：可以使用 vdesk_desktop_list 查看桌面列表。

行为细节与注意事项¶

输入降级链：客户区点击走 postmessage，标准窗口标题栏走 WM_NCHITTEST。开始菜单为“最佳努力”实现，完整操作仍需真实输入通道。
异步 Launch：应用启动有延迟，Agent 脚本需等待窗口出现后再进行操作，避免因 PID 匹配失败导致点击无效。
光标管理：光标位置由 Sidecar 自维护，每帧点击后会同步。
端口与 CORS：FrameServer 端口冲突时自动递增，CORS 白名单默认为 http://127.0.0.1:3080。
DPI 缩放：插件在 100% 缩放的 Windows 10/11 上实测（源 1920x1080，帧 1280x720）。

总结¶

dsh-vdesktop 为 DSH 提供了在隔离虚拟桌面中运行 GUI 应用的能力。它通过 12 个工具让 Agent 能够读写文本、截图、控制鼠标键盘，同时通过 HTTP 服务和 Web 面板解决了可视化与人工接管的需求。安装时需注意 Sidecar 路径配置及异步启动的处理逻辑。