Windows 桌面操控 dao-awa/dsh-computer-use-native

dsh-computer-use-native

面向 DeepSeek Harness 的 Windows 桌面控制，专为视觉模型打造。

智能体截取屏幕截图，从像素中读取界面，并点击它所看到的内容。输入工具接受在该截图上测量的坐标，并自行将其转换为屏幕坐标，因此模型永远不需要进行那些会让视觉驱动点击变得不可靠的缩放运算。

为什么需要它

无障碍树自动化在现代 Windows 应用程序上会失败。Chromium、WebView2 和 Electron 窗口几乎不暴露任何可访问控件——在新版 Outlook 或 Vivaldi 窗口上运行 UI Automation 树只会返回少量节点，没有任何内容。基于该树构建的工具会报告窗口为空，智能体完全无法读取界面。

屏幕截图没有这个问题。无论是什么绘制了像素，像素就在那里。能看见它们的模型就能操作应用程序。

因此，这个提供程序与基于树的工具相反：它使用 PrintWindow 和 PW_RENDERFULLCONTENT 捕获真实渲染表面，这是唯一能为 DirectComposition 表面返回实际像素的途径；当这产生空白帧时，回退到屏幕区域捕获，并将图像连同坐标映射一起交给模型。

它还瞄准某个窗口，而不接管整个桌面。一个必须将它接触的每个窗口都置顶的智能体会让坐在机器前的人无法使用这台机器，因此输入默认向目标自身的消息队列投递消息：不会置顶任何窗口，真实光标不会移动，键盘前的人可以继续工作。有关实测行为及其带来的两个限制，请参见输入路由。

要求

- Windows 10 或更高版本，x64。
- Node.js 22 或更高版本。
- 接受图像输入的模型路由。
- 带有 computerUse、tools、systemPrompt 和 attachments 服务的 DSH。

安装

dsh plugin add dsh-computer-use-native

或者直接从仓库安装，并固定到某个提交，这样后续推送就不会改变你正在运行的内容：

dsh plugin --profile web add github:dao-awa/dsh-computer-use-native#1354d1d1481619c2cc0a5ecccfa8180f1a34452a

该 bundle 的补丁层挂载两行：@deepseek-ai/dsh-computer-use，它负责提供程序注册，且不属于基础 bundle；以及本提供程序。重启 DSH 并开始新会话；bundle 会在创建或恢复会话之前挂载。

与 MCP 桌面服务器共存

computer-use-win 及类似包是通过 @deepseek-ai/dsh-mcp-client 桥接的 MCP 服务器。它们不是 computer-use 提供程序，因此在注册时不会与本提供程序冲突。它们确实会向模型提供第二套重叠的桌面工具，这在实践中会造成混淆。请只挂载其中之一。

工具

| 工具 | 用途 |
| computer_screenshot | 捕获桌面或某个窗口；返回图像和一个视口 id。 |
| computer_window | 列出窗口、读取某个窗口的几何信息，或提升某个窗口。 |
| computer_click | 在最后一张截图的某个点上单击、双击或右键单击。 |
| computer_move | 移动指针而不点击，用于悬停菜单和工具提示。 |
| computer_type | 输入 Unicode 文本——任意字符，无论键盘布局如何。 |
| computer_key | 发送按键或组合键，例如 enter、f5、ctrl+shift+t。 |
| computer_scroll | 在最后一张截图的某个点上滚动滚轮。 |
| computer_drag | 在两个点之间拖动，用于滑块、选择和拖放。 |

这五个输入工具都接受相同的 dispatch 参数，详见输入路由。

坐标如何工作

这是决定智能体能否命中目标的关键部分。

截图在到达模型之前会被缩小，因此图像比它来自的屏幕区域更小。在 150% 缩放的 2560×1600 显示器上，捕获一个 2582×1550 的窗口并缩小到适合 1568 像素，缩放系数约为 1.65。如果模型假设图像像素就是屏幕像素，就会偏离目标，偏差为距原点距离的 65%——在宽窗口上就是数百像素。

因此，该插件会吸收这种转换：

1. computer_screenshot 会记录一个视口：图像尺寸、它来自的屏幕矩形、缩放系数，以及它所属的窗口。
2. 模型从图像上读取目标的位置，并将这些数字传给输入工具。
3. 该工具通过该视口将图像像素精确且可逆地转换为屏幕坐标，并报告操作实际落在何处。

有两道防护让这一点不仅方便，而且安全：

- 过期。 视口会记录源窗口框架的指纹。如果窗口在捕获之后移动或调整了大小，输入会被拒绝，而不是落在模型从未看过的地方。
- 边界。 图像之外的点会被拒绝，而不是被钳制。钳制会作用于桌面上不相关的部分。

查看成本很低，所以要经常查看

截图的成本主要在于其编码。在 2560x1600 桌面上测得：GDI 捕获约为 43 毫秒，转换为 PNG 并编码为 122–208 毫秒，而比较像素只需不到一毫秒。对未移动的屏幕重新编码，就是第二次查看的全部成本，而查看两次正是智能体所做的大部分事情。

因此，每次查看都会与对同一目标的最后一次查看进行比较；当视图没有移动时，工具会说明这一点，不发送图像，并指回已经描述它的那个视口。通过已发布工具进行端到端测量：首次查看 238 毫秒，重复查看 41 毫秒——仅为 17% 的成本，且不写入附件，请求中也没有图像。

这种比较刻意不是字节级完全相同。对活动桌面相隔五分之一秒采集的五个样本会产生五个不同的帧，因为一个光标闪烁、旋转、时钟滴答。看着那块屏幕的人看到的却是一成不变的画面。每一帧都被缩减为一个 32x20 的平均亮度网格，当移动的格子少于 2% 时，一次查看就算作未变化——这个阈值高于旋转指示器，低于窗口打开。在真实桌面上，运行中的代理循环里的动画指示器只会移动网格的 0.0–0.2%。

重复查看读取的是缩减后的捕获，而不是模型会看到的帧。两者获取成本相同——GDI 的屏幕回读占主导，且不会随目标尺寸缩小，所以 160x100 的探测和完整捕获一样要花 43 毫秒——但探测只有 63 KiB，而不是 15.6 MiB，因此反复查看不会搅动堆，而且它的分辨率损失恰好把那些并非变化的闪烁平均掉了。

waitForChangeMs 使用同样的比较来让动作的结果可观察。该工具不是捕获半绘制的帧或休眠一个猜测的延迟，而是观察屏幕，并报告它是否移动了以及过了多久。

下限是屏幕回读，而不是编码。要低于它就需要 Desktop Duplication API，它只读取合成器报告为脏的矩形；GDI 的 BitBlt 没有这种选项，总是复制整个表面。

输入路径：后台与前台

每个输入工具都接受一个 dispatch 参数，而这两条路径的代价正好相反。

background 是默认值。它把窗口消息——WM_LBUTTONDOWN、WM_CHAR、WM_MOUSEWHEEL——直接投递到截图来源的那个窗口。那个窗口永远不会被提升，真实光标永远不会移动，正在使用这台机器的人也能保住自己的焦点和输入。鼠标消息携带的是客户区坐标，所以工具在投递前会把截图坐标通过 ScreenToClient 转换回去；WM_MOUSEWHEEL 是唯一的例外，它的 lParam 保存的是屏幕坐标。

投递出去的消息会到达拥有该点的控件，而不是截图显示的那个框架。Windows 会把真实的鼠标输入发送到指针下方最深的窗口，而大多数经典 Win32 软件——对话框、属性表、任何由控件窗口构建的东西——都把编辑框和按钮放在子窗口中。一个收到本应发给其某个控件的消息的框架会静默地丢弃它，而 PostMessage 仍然报告成功。所以该模块用 WindowFromPoint 对点进行命中测试，确认命中项是目标窗口的后代，然后改为投递到那里。字符和按键会到达拥有焦点的控件，而只有在 AttachThreadInput 把目标的输入队列与我们的共享之后才能到达，因为线程的键盘焦点是该线程私有的。

一个拥有自己整个表面的窗口——浏览器，或没有子窗口的 XAML 应用程序——就是它自己的命中测试结果，所以对它来说没有任何变化。

foreground 会提升目标并通过 SendInput 移动真实光标。每个窗口都会收到它，代价是接管整个桌面。
默认是后台，因为模型能看见并重试的静默无操作，比夺取机器控制权是更小的失败。路由是按调用选择的，所以模型发现某一步什么都没做时，会用 dispatch="foreground" 重试那一步，并让运行的其余部分保持静默。

实测行为——Windows 11，150% DPI，每个目标都置于真实应用程序之后作为后台，并通过随附工具驱动：

| 用例 | 结果 |
| 点击一个后台的 Chromium 页面 | 已送达；该页面自己的点击计数器增加了。 |
| 向一个后台的 Chromium 页面的焦点字段输入 | 已送达；全部 15 个字符都到达了。 |
| 在点击正文文本后进行前台操作 | 无变化。 |
| 在点击文本字段后进行前台操作 | Chromium 会激活自己的窗口，因为该字段需要键盘焦点。结果说明会报告这一点。 |
| 通过 WinForms 文本框所在框架的坐标，点击并向该文本框输入 | 已送达子控件；全部 19 个字符都到达了，且前台保持在原处。 |
| 点击并向 Windows 11 记事本输入 | 什么都没到达。记事本是 XAML 应用，没有子窗口，也不读取投递的消息。dispatch="foreground" 是适用于它的路由。 |

由此产生三个后果。投递的字符会到达目标窗口内部当前已持有焦点的任何位置，因此必须先点击某个字段，文本才会落入其中。需要键盘焦点的控件——文本字段，而非正文文本——会使其自己的窗口激活，工具会报告这一点，而不是隐藏它。而一个读取硬件输入而非其消息队列的应用程序，包括 XAML 和 WinUI 软件，会完全忽略投递路由；结果会说明这一点，重试方式是 dispatch="foreground"。

如果窗口在前台路由下无法来到前面，前台锁通常是原因。该工具通过 AttachThreadInput 提升，以共享目标的输入队列，这是绕过该问题的文档化方法。当连这也失败时，它会报告拒绝，而不是把输入发送到错误的位置。

捕获路由

captureWindowAuto 先尝试带 PW_RENDERFULLCONTENT 的 PrintWindow，统计结果中的不同颜色，并在帧接近单色时回退到屏幕区域捕获。没有单一路由能覆盖所有窗口类：IME 宿主窗口通过 PrintWindow 返回一种颜色，而 Chromium 窗口通过朴素的 BitBlt 返回空白帧。如果一次捕获在所有路由下都保持空白，会作为不可靠结果报告给模型，而不是作为有效图像呈现。

配置

在 cordis.yml 中插件的 config 下设置这些项：

| 字段 | 默认值 | 含义 |
| maxEdge | 1568 | 返回截图的最长边，单位为像素。较低值每次捕获消耗更少 token；较高值使小号 UI 文本更易辨认。 |
| compressionLevel | 6 | PNG 压缩力度，0–9。实测 6 与 9 之间的差异约为文件大小的 1%，因此提高它很少划算。 |
| typeDelayMs | 0 | 键入字符之间的暂停。对于会丢弃快速输入的应用程序，请调高该值。 |
| providerName | native-win32 | 记录在 computer-use 注册中的名称。 |

在 2582×1550 浏览器窗口上测量，按 maxEdge 统计 PNG 字节数：

| maxEdge | 图像 | 字节数 |
| 1024 | 1024×615 | 533 KB |
| 1280 | 1280×768 | 762 KB |
| 1568 | 1568×941 | 1.08 MB |
| 1920 | 1920×1153 | 1.49 MB |

为其自身 token 预算而对图像进行归一化的路由，可能会在图像到达模型之前缩小它们。

它是如何构建的

通过 koffi FFI 直接调用 Win32 —— 没有原生插件，没有 C++ 工具链，也没有需要匹配 Node ABI 的编译产物。发布的包是 JavaScript 加上预构建的 FFI 绑定。

src/
index.ts plugin entry: calibration, registration, prompt
guidance.ts the model-facing system-prompt section
viewport.ts image screen coordinate mapping and staleness
encode.ts BGRA -> RGBA, downscale, PNG
tools/ the eight tools
win32/
structs.ts koffi structure layouts
dll.ts user32/gdi32/kernel32/shcore bindings and constants
native.ts layout assertions and UTF-16 decoding
window.ts DPI awareness, enumeration, geometry, foreground
capture.ts PrintWindow/BitBlt with fallback, colour sampling
input.ts SendInput: pointer, wheel, keys, Unicode text
post.ts posted messages: the background input route

有五个细节至关重要，如果出错就会导致静默失败：

- DPI 感知要在其他一切之前设置。 使用 PER_MONITOR_AWARE_V2 调用 SetProcessDpiAwarenessContext 必须在第一次捕获或坐标查询之前运行。否则，GetSystemMetrics 报告的是缩放后的逻辑像素，而捕获返回的是物理像素，因此每次点击都会偏离缩放系数。
- INPUT 结构被断言为 40 字节。 步长错误会让 SendInput 投递损坏的事件，而且不会报错。该插件会拒绝启动，而不是发送这些事件。
- 文本使用 KEYEVENTF_UNICODE。 字符的投递独立于当前键盘布局，因此中文、带重音符号的字符和 emoji 输入无需切换布局即可工作。代理对保持相邻。
- 投递的鼠标消息携带的是客户区坐标，而不是屏幕坐标，并且客户区原点不是框架原点 —— 浏览器会在客户区内绘制自己的工具栏。投递屏幕坐标会因该工具栏的高度而误点。WM_MOUSEWHEEL 是例外，它确实采用屏幕坐标。
- 投递的消息属于该点下方的控件，而不是框架。 向框架投递消息会被接受，然后被任何控件是独立子窗口的窗口丢弃，而大多数经典 Win32 软件都是如此。该点会用 WindowFromPoint 进行命中测试，消息会发送到目标窗口最深的子代。

限制
- 仅限 Windows。 该提供程序在其他平台上拒绝加载。
- 无会话隔离。 输入会发送到交互式桌面。已锁定或已断开连接的会话没有任何可捕获的内容。
- 受保护的窗口。 带有 DRM 或提升完整性保护的窗口可能拒绝捕获或拒绝合成输入。失败会被报告，而不是被隐藏。
- 投递的输入可能被忽略。 后台路由是默认方式，因为它安静，而不是因为它通用。一个读取硬件输入队列而不是其消息队列的窗口什么也看不到——例如 XAML 或 WinUI 应用程序如 Windows 11 记事本就是实测案例——而该工具会报告这一拒绝，以便模型可以用 dispatch="foreground" 重试。
- 无辅助功能数据。 该提供程序有意不读取 UI Automation 树。在看不到控件的情况下读取其值是一种不同的能力；如果你需要，可以同时使用 MCP UI Automation 服务器。

开发

npm install
npm run typecheck # 根据 harness 声明进行编译
npm run build
npm run pipeline # 捕获 -> 编码 -> 视口 -> 坐标
npm run pipeline:click # 同上，并发送一次真实点击
npm run compose # 在真实的 Cordis 上下文中挂载插件
npm run compose:real # 针对真实的 harness 服务挂载它
npm run bg-tools # 通过工具驱动一个后台 Chromium 页面
npm run child-routing # 投递到一个 WinForms 控件窗口
npm run unchanged-look # 对真实桌面看两次
npm run latency # 一次截图的时间花在哪里
npm run bench # 按 maxEdge 和 PNG effort 统计图像大小

存在三个 tsconfig，因为它们有不同的职责。tsconfig.json 根据 harness 声明文件进行类型检查，因此当宿主 API 发生变化时构建会失败。tsconfig.test.json 清除该映射，以便 spike 脚本在运行时从 node_modules 解析真实包；否则加载器会跟随该映射到一个 .d.ts 文件。tsconfig.harness.json 则相反，将说明符映射到 harness 源代码上，这是测试能够挂载真实 harness 服务而不是替代品的唯一方式。spike 脚本必须使用匹配的那个来启动。

compose:real 才是真正重要的组合检查。它针对真实的 @deepseek-ai/dsh-computer-use、@deepseek-ai/dsh-system-prompt 和 @deepseek-ai/dsh-tools 挂载插件，而不是替代品，并且这三者各自都有一个桩会掩盖的 API：

- 提供程序注册表通过一次在
register() 内部进行的 ctx.effect 调用来预留其槽位。Cordis 将服务的 this.ctx 解析为其调用者，因此
该 effect 绑定到本插件的 fiber，释放时会释放该槽位——一个关于框架行为的声明，以及一个失败后会在卸载后仍占用槽位的声明。
- 提示词服务拥有此插件所请求的章节顺序，而组装结果正是模型实际接收到的内容，因此该检查断言引导文本出现在组装结果中，并在处置时再次移除。
- 工具注册表会验证每个定义，并将其 schema 投影为无损 JSON。读回目录正是证明这八个工具可注册的依据；一个接受任何内容的桩 register() 做不到这一点。

配置文件这一侧无需启动应用即可验证：

dsh --profile web --dump-config # composes the tree, patches applied
dsh --profile web --dump-config-schema # imports every entry to read its Config

schema 转储是两者中更强的，因为打印某个条目的配置 schema 需要导入其模块。此插件的 maxEdge、compressionLevel 和 typeDelayMs 连同其默认值出现在那里，正是补丁行可解析且构建后的模块可加载的证明。

工具遵循的 harness schema 规则

这些规则很容易弄错，而且错误信息不会解释规则：

- 工具的 parameters 和工具的 output.schema 是不同的 DSL。parameters 通过在字段上设置 required: true 来标记必填字段。output.schema 也是如此——但仅限字段。输出 schema 的根级 required 键会被拒绝，无论它是 true 还是名称数组，因此那里的必填性是在每个属性上表达的。
- 任一 DSL 中的每个嵌套对象都必须显式声明 additionalProperties 为 true 或 false。省略它会导致错误。
- 函数插件导出 name、inject、Config 和 apply，并且必须没有默认导出；默认导出会使加载器丢弃该命名空间。
- 每次注册都必须在 ctx.effect() 内 yield，包括 systemPrompt.section()。在 effect 之外进行的注册会在处置后继续存在。
- spike/schema-probe.ts 和 spike/schema-probe2.ts 记录了已安装的 harness 接受哪些形式。在 harness 升级后重新运行它们。

spike/win32-smoke.ts 在没有插件层的情况下演练枚举、捕获和前台工作区。

许可证

MIT