虚拟桌面操控 jafewff/dsh-vdesktop

dsh-vdesktop

dsh-vdesktop 是 DSH（DeepSeek Harness） 的一个 cordis 插件：它在你本机上开一个用户看不见的 Win32 虚拟桌面（CreateDesktopW），把 GUI 应用跑进这个隔离桌面里，然后——

- 给模型：提供 12 个 vdesk_ 工具，让 Agent 对虚拟桌面上的应用截图、点击、打字、读文本、存文件；
- 给人：DSH 的 Web GUI 里提供一个 VDesktopPanel 面板，实时看到虚拟桌面的画面，并直接用鼠标点击操作（标准窗口的标题栏 ×/最小化/最大化、任务栏按钮都是真的）。

面板截图（本机 Windows 10 1809 LTSC 实测，均为 DSH Web GUI 中的 VDesktopPanel）：

| VDesktopPanel 面板 | |
| 面板总览：桌面切换、实时帧（1280×720）、底部「输入到虚拟桌面」直发通道 | 虚拟桌面里正在运行的浏览器（DeepSeek 官网），右上角橙色为叠加光标 |
| 画面细节可放大看清：桌面内浏览器的 DevTools 控制台 | 点任务栏打开的资源管理器窗口，光标叠加在客户区 |

特性

- 虚拟桌面生命周期：创建 / 附着 / 列表 / 关闭 / 孤儿清理（dshv- 前缀的桌面在 DSH 启动时自动 sweep）。
- Agent 工具面（12 个 vdesk_ 工具）：桌面生命周期、整桌截图、区域放大（1x–4x zoom）、鼠标（move/click/double/right/middle/drag/scroll）、键盘（type/press/hotkey，含中文与 emoji）、写文本、读文本、把窗口文本存成文件。
- 帧数据面：插件内置一个 frameServer（HTTP，127.0.0.1:8790 起自动探测到 8799），Web 面板通过它低频轮询 PNG 帧；光标位置经响应头（X-Cursor-X/Y）随帧下发，由面板叠加绘制。
- 真实窗口语义的点击（面板/Agent 共用同一执行面）：
- 标准 DWM 标题栏的 ×/最小化/最大化 → WM_NCHITTEST 判别后直接发 WM_CLOSE / SC_MINIMIZE / SC_MAXIMIZE|RESTORE（对记事本、资源管理器这类标准框直接生效）；
- 自绘标题栏的窗口（VSCode、WPS 等）→ postmessage 客户区消息，走应用自己的处理逻辑；
- 任务栏按钮点击 → 等价窗口管理动作（激活 / 启动该按钮对应的应用）。
- 进程监督：Python sidecar 以子进程方式由插件托管，心跳监测 + 惰性重启 + 空闲回收。

架构

┌─────────────────────────────── DSH (cordis) 应用进程 ───────────────────────────────┐ │ 插件 dsh-vdesktop (lib/index.js) │ │ ├─ SidecarSupervisor ──JSON-RPC over stdio──▶ python -m dshv (sidecar 子进程) │ │ ├─ FrameServer (127.0.0.1:8790+) ◀──HTTP 抓帧/输入── DSH Web GUI (VDesktopPanel) │ │ └─ 12 个 vdesk_* 工具 + computerUse 注入（供 Agent 使用） │ └──────────────────────────────────────────────────────────────────────────────────────┘ │
python dshv (纯 ctypes，无第三方依赖)
│ CreateDesktopW / BitBlt / PostMessage
┌───────────────────▼───────────────────┐
│ 虚拟桌面 dshv-（用户屏幕上看不到） │ │ notepad / explorer / 任意 GUI 应用 │ └───────────────────────────────────────┘

- sidecar（sidecar/dshv/）：纯 Python ctypes 实现，虚拟桌面生命周期、GDI 抓帧、缩放、编码，以及输入链路（SendInput → PostMessage → SendMessage 逐级降级 + 光标自维护）。
- frameServer（src/frameServer.ts）：轻量 HTTP 服务，/vdesk/frame、/vdesk/desktops、/vdesk/input、/vdesk/launch、/vdesk/processes、/vdesk/activate、/vdesk/close_window 等路由，转发给 sidecar。

环境要求

| 组件 | 要求 |
| 操作系统 | Windows 10 / 11（1809 LTSC 实测） |
| 运行时 | Node.js LTS（构建与插件宿主） |
| Python | 3.11+（sidecar 纯 ctypes，无需 pip 安装任何依赖） |
| 宿主 | DSH（含 cordis 插件机制） |

安装

1. 克隆本仓库并构建（仓库已附带 lib/ 构建产物，仅当源码有改动时才需要重新构建）：

git clone dsh-vdesktop
cd dsh-vdesktop
npm install
npm run build # esbuild → lib/（可选，lib/ 已入库）

2. 在 DSH 的 web profile 中安装插件（以 C:\Users\\.dsh\profiles\web 为例）：

- 在该 profile 的 package.json 的 dependencies 里加一行指向本仓库的 link: 依赖；
- 在 profile 配置中把 dsh-vdesktop 加入 dsh.profile.bundles；
- pnpm install（或 npm install）后重启 DSH。

链接安装的写法示例："dsh-vdesktop": "link:"。

3. 确认 sidecar 工作目录：插件以 python -m dshv --rpc stdio 拉起 sidecar，工作目录由 sidecarCwd 决定。仓库自带的 cordis.patch.yml 与 src/config.ts 中的默认值是作者的本地路径（D:\Project\dsh-virtaul-computer\sidecar），安装时请改成 \sidecar（绝对路径）。

4. 安装后自检（DSH 重启、插件加载后，任选其一）：

curl.exe -s http://127.0.0.1:8790/vdesk/desktops # 返回 {"desktops":[...]} 即数据面已就绪 curl.exe -s -o NUL -w "%{http_code}" "http://127.0.0.1:8790/vdesk/frame?desktop=dshv-e2e" # 200 即抓帧链路通

打开 DSH Web GUI，VDesktopPanel 面板出现桌面画面即全部就绪。

使用

面板（VDesktopPanel）

- 选择 / 创建虚拟桌面，画面以低频轮询方式实时刷新；
- 画面上的点击就是真实输入：点标题栏 ×/最小化/最大化直接生效（标准窗口走 WM_NCHITTEST 非客户区拦截，自绘窗口走 postmessage）；点任务栏按钮等价于激活 / 启动对应应用；
- 面板上的光标是叠加层（经 X-Cursor-X/Y 响应头跟随），不是烧进帧里的。

Agent 工具（vdesk_）

| 工具 | 用途 |
| vdesk_desktop_create | 创建虚拟桌面并启动一个 GUI 应用（返回桌面句柄 / PID / 顶层 HWND） |
| vdesk_desktop_close | 关闭虚拟桌面并终止其上的进程 |
| vdesk_desktop_list | 列出所有 dshv- 虚拟桌面 |
| vdesk_orphan_sweep | 清理孤儿虚拟桌面 |
| vdesk_screenshot | 整桌截图落盘（jpg/png，可选质量） |
| vdesk_zoom | 指定区域 1x–4x 放大截图 |
| vdesk_click | 单点（left/right，客户区坐标） |
| vdesk_mouse | move / click / double_click / right_click / middle_click / drag / scroll |
| vdesk_keyboard | type / press / hotkey（支持中文、emoji 与组合键） |
| vdesk_type | 向目标窗口写入整段文本 |
| vdesk_read_text | 读取目标窗口文本（优先 Edit 子窗） |
| vdesk_save_file | 把窗口文本保存到文件 |

行为细节与已知限制

- 输入降级链：sidecar 的 vdesk 工作线程里 SendInput 恒 ACCESS_DENIED（虚拟桌面非前台），因此客户区点击实际走 postmessage（客户区坐标）；标准框标题栏按钮由 WM_NCHITTEST 判别后直接发窗口管理消息，两条路径都已在验收矩阵覆盖。
- launch 是异步的：/vdesk/launch 立即返回 pid（windowReady 恒为 false），目标窗口稍后才出现，请按 pid 匹配顶层窗口。
- 开始菜单为最佳努力：任务栏"开始"按钮触发 taskbar/start 动作，完整开始菜单操作需要真实输入通道，暂未实现。
- 光标由 sidecar 自维护"最后已知位置"并在每帧点击后同步（任务栏 / 标题栏按钮 / 客户区三条路径都会跟随）。
- 端口：frameServer 从 8790 起探测，冲突时 +1 直到 8799 上限；CORS 精确白名单默认 http://127.0.0.1:3080（DSH Web GUI）。
- DPI：在 100% 缩放的 1920×1080 桌面实测（帧 1280×720 ← 源 1920×1080 线性映射）；其他缩放比未系统验证。

开发

npm run build # TS 侧 esbuild → lib/
cd sidecar
python -m py_compile dshv\rpc_stdio.py # sidecar 语法自检
python -m dshv --help # CLI：--create-desktop / --attach-desktop / --sweep / --rpc stdio

- 设计文档（gui-agent-plan 01–07b）、里程碑交接记录保留在作者本地工作区，未随仓库发布（仓库只含运行所需代码）；
- 一次性补丁/验收脚本（scripts/patch-.mjs、scripts/accept-.mjs 等）保留在作者本地工作区，未随仓库发布；
- 抓帧为纯 GDI（BitBlt + 缩放 + JPEG/PNG 编码），不依赖 GDI+ 或任何第三方 Python 包。

仓库结构

├── src/ # TS 插件主体（supervisor / frameServer / 工具 / Web 面板） │ ├── client/ # VDesktopPanel Web UI │ ├── tools/ # 12 个 vdesk_ 工具定义 │ └── transport/ # JSON-RPC over stdio ├── lib/ # esbuild 构建产物（link: 安装免构建即用） ├── sidecar/ │ ├── pyproject.toml # dshv 包定义（Python 3.11+，纯 ctypes） │ └── dshv/ # sidecar 产品包（win32 抓帧/输入/桌面生命周期） ├── scripts/build-ts.mjs # npm run build（tsc + esbuild → lib/） ├── screenshots/ # README 引用的面板截图 ├── cordis.patch.yml # cordis 服务声明（安装时按本机路径修改 sidecarCwd） ├── package.json # 插件包 dsh-vdesktop └── esbuild.config.mjs / tsconfig.json

License

MIT © dsh-vdesktop contributors

基于 DSH / cordis 插件机制构建。

English Overview

dsh-vdesktop is a plugin for DSH (DeepSeek Harness / cordis) that runs GUI applications on an isolated, invisible Win32 virtual desktop (CreateDesktopW). An LLM agent drives those apps through 12 vdesk_* tools (screenshots, zoom, mouse, keyboard, text I/O, desktop lifecycle), while the DSH web GUI ships a VDesktopPanel so a human can watch the virtual desktop live and operate it with real mouse clicks — title-bar buttons, taskbar buttons and window management all behave like a normal desktop.

Stack: TypeScript plugin (src/, built to lib/) + a dependency-free pure-ctypes Python sidecar (sidecar/dshv/, JSON-RPC over stdio) + a built-in frame server (127.0.0.1:8790+). Windows 10/11, Node LTS, Python 3.11+. See the Chinese section above for installation and usage details.