datuloar/dsh-computer-use-win

dsh-computer-use

CI
license
platform

面向代理的 Windows 计算机使用：以文本形式读取屏幕，按名称点击控件，
截图、输入、滚动、拖拽——外加一个屏幕上可见的指示器，人类可以查看并用
ESC 停止。

代理操控机器时人类看到的指示器

纯文本模型也能借此操控图形界面：dsh-cu tree 和 dsh-cu read 将窗口转换为
几百个 token 的角色、名称和可点击点，而 dsh-cu tap "Save" 会点击匹配的那个
控件。当像素才是答案时，截图就在那里，而不是唯一的入口。

为 DeepSeek Harness 构建；CLI 可与
任何代理或脚本配合使用。CLI 是 dsh-cu，它注册的技能是 dsh-computer-use，
仓库是 dsh-computer-use-win——三个名称，同一件事。

无需安装任何东西。 没有包、没有驱动、没有 SDK：后端使用 Windows 自带的
.NET Framework 自行编译其 C# 代码。

需要 Node.js 18+ 以及 Windows 桌面上的 Windows PowerShell 5.1。C# 编译器由
内置的 .NET Framework 提供；用户无需 Visual Studio 或 .NET SDK。
PowerShell 7（pwsh）不是此 Framework/WinRT 后端的受支持替代品。

为什么选这个

- 对纯文本模型来说足够便宜。 tree 通过 UI Automation 读取控件树
（原生应用，以及浏览器辅助功能被唤醒后的网页），read 运行 Windows 自带的
OCR，两者都会为每一行打印一个可点击点。一个窗口只需几百个
token，而不是一整张截图。OCR 和 UI Automation 在本地运行；MCP screenshot
将图像数据返回给连接的客户端/模型。
- 人类可以看到它并终止它。 一个圆角状态面板会显示正在运行的命令
（"click 640,380"），屏幕边缘有一圈光晕，还有一个跟随真实指针的圆环；ESC
会停止一切。注入的 ESC 会被忽略，因此代理无法关闭自己的指示器。
- 始终只有一个指针。 圆环绘制在你自己的光标周围，因此永远不会出现第二个
箭头追逐第一个箭头。--hide-cursor 是另一种模式的选项：绘制的标记
成为屏幕上唯一的指针。
- 指示器关闭时输入会被拒绝。 在 dsh-cu overlay 将框架显示到屏幕上之前，
move、click、drag、wheel、type、
key、keys、clipboard 和 run 都会以拒绝作为回应。这道关卡存在于
工具中，而不是提示词中。
- 它可以在原装 Windows 机器上运行。 其他计算机使用插件会驱动一个必须先安装的
外部原生驱动（cua-driver 之类）；而这个只需要 PowerShell 和
.NET，Windows 已经自带。
- 它针对真实机器进行了验证。 dsh-cu self-test 通过 MCP 驱动一个隔离的测试窗口，
并检查倒计时门控、文本、点击、截图和光标恢复。
- 可在 Harness 沙箱内部工作。 Harness 文件沙箱会阻止嵌套进程的管道 stdio；
该 CLI 回退到文件描述符捕获，因此 dsh-cu 在朴素的 spawn(..., {stdio: 'pipe'}) 会得到 EPERM 的地方仍然可用。

它不是什么：它没有浏览器 DOM（UI Automation 看到的是应用暴露的内容，比 DOM 少，比像素多），
不支持多显示器，也没有按应用的白名单。

安装

| 方式 | 命令 | 你会得到什么 |
|---|---|---|
| 技能 + CLI + PATH | powershell -ExecutionPolicy Bypass -File install.ps1 | $DSH_HOME\skills\dsh-computer-use\ 中的 SKILL.md，以及用户 PATH 上的 dsh-cu shim |
| DSH 配置文件插件 | dsh plugin --profile web add github:datuloar/dsh-computer-use-win | 该 bundle 挂载插件，插件从仓库注册该技能 |
| 什么都不装 | 在克隆目录中运行 bin\dsh-cu.cmd  或 node src\cli.js  | 同一个 CLI，无需更改 PATH |

使用一种技能交付路径：复制到 $DSH_HOME\skills\dsh-computer-use\SKILL.md 的文件和
插件注册携带相同的技能名称。

如果都不使用：node src\cli.js  或 bin\dsh-cu.cmd 。

文件系统技能根目录会被实时扫描，因此复制后无需重启；配置文件
插件需要重启一次 dsh web。

循环

dsh-cu overlay                       # 向人类发出 8 秒警告，ESC 可取消
dsh-cu shot                          # 捕获屏幕，打印路径
dsh-cu click 640 380                 # 点击那里
dsh-cu type "hello"                  # 输入到聚焦的窗口
dsh-cu keys ctrl+l                   # 按键组合
dsh-cu drag 420 300 980 300          # 按下、滑动、释放
dsh-cu shot --region 1200 600 420 240   # 只读取一个细节，而不是整个屏幕
dsh-cu overlay --stop                # 停止并清理

1. 在第一次输入前执行 dsh-cu overlay。
2. 对目标窗口执行 dsh-cu focus （或 --title ）。
3. 执行 dsh-cu shot 并查看图像。
4. 根据该截图中的坐标进行操作；用 dsh-cu pos 确认 move。
5. 再次执行 dsh-cu shot——只有当第二张截图确认时，一步才算完成。
6. 在每次 GUI 交互后、进行 shell 工作或回复之前，执行 dsh-cu overlay --stop（MCP：带 action: "stop" 的 indicator），
包括失败时。不要等到整个项目完成。

命令

dsh-cu see  [--region    ]   向本地视觉询问屏幕内容，返回文本

dsh-cu shot [file.png] [--region    ]   捕获屏幕，或屏幕的裁剪区域
dsh-cu read [--region    ] [--lang ] [--json]   以文本形式读取屏幕，每行一个点
dsh-cu tree [--pid N | --title ] [--depth N] [--all] [--json]   窗口的控件树
dsh-cu find  [--pid N | --title ] [--json]   名称包含该文本的控件
dsh-cu tap  [--pid N | --title ]   点击名称与之匹配的那个控件
dsh-cu move                         移动指针
dsh-cu click   [left|right|middle|double|triple]   点击
dsh-cu drag             按下、滑到第二个点、松开
dsh-cu wheel  [ ] [--horizontal]   滚动，120 = 一格，给出 x y 时在该点滚动
dsh-cu type                         向聚焦窗口输入文本
dsh-cu key  [down|up]               Enter、Esc、Tab、Space、Ctrl、Alt、F1..F12、方向键
dsh-cu keys                        ctrl+l、ctrl+shift+t、……
dsh-cu clipboard [get|set |clear]   读取或写入剪贴板
dsh-cu pos                                指针位置和前台窗口
dsh-cu windows [--json]                   可见窗口及其 pid、标题和矩形
dsh-cu focus  | --title        将窗口置于前台，并已验证
dsh-cu wait-window  [seconds]       等待窗口出现，然后聚焦它
dsh-cu run                  运行命令行——参见安全规则
dsh-cu broker [start|stop|status]         提权输入代理，会请求 UAC
dsh-cu overlay [--announce N] [--quiet] [--hide-cursor]   屏幕指示器，按 ESC 停止
dsh-cu overlay-state                      指示器是否正在运行
dsh-cu display                            主屏幕尺寸和 DPI
dsh-cu mcp                                通过 MCP（stdio）提供相同的工具
dsh-cu doctor                             这台机器能做什么
dsh-cu self-test                          演练每一条命令
dsh-cu overlay --stop                     停止指示器，恢复光标
dsh-cu overlay --restore-cursor           紧急光标救援

read、tree、find 和 tap 是低成本路径；shot 写入 %TEMP%\dsh-computer-use\
并打印 SAVED  ；--region x y w h
将其裁剪到屏幕坐标中的该矩形。--quiet 只绘制指针标记，用于
像素级精确读取。参数以 JSON 数组形式交给后端，因此输入的文本和窗口
标题会保留其空格、引号和开头的短横线。

drag 在第一个点按下，以缓动步进滑到第二个点并松开，这正是
滑块、选择和拖放目标所期望的；click 也接受 middle 和
triple。

作为 MCP 工具（DeepSeek Harness、Claude Code、opencode、Cursor）

dsh-cu mcp 通过 MCP stdio 将每条命令作为原生工具提供：ui_tree、find、tap、
read_text、screenshot（返回图像）、click、move、drag、scroll、type、press、
windows、focus、wait 和 indicator。它会保持一个后端进程处于热状态，因此一次调用无需为每次调用重新编译 C#；耗时取决于应用程序的 UI Automation 提供程序。输入工具（包括 focus）会在第一次使用时自行启动屏幕上的指示器。

DeepSeek Harness — 在你的 profile 补丁（\profiles\web\cordis.patch.yml）中添加一行；这些工具随后会以 mcp__pc__click、mcp__pc__ui_tree……的形式出现：

- id: mcp-pc
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: pc
transport: stdio
command: node
args: ['C:\\path\\to\\dsh-computer-use\\src\\mcp.js']
toolCallTimeoutMs: 120000

Claude Code：claude mcp add pc -- node C:\path\to\dsh-computer-use\src\mcp.js。opencode 和 Cursor 在其 MCP 设置中采用相同的命令。

如果人类按下 ESC，指示器会记录该操作，并且每个输入工具在接下来的十分钟内都会拒绝执行，并给出提示信息让 agent 停止并询问——agent 无法悄悄重启刚刚被用来阻止它的指示器。

在没有视觉的情况下驱动 GUI

可选的本地视觉：运行一次 powershell -ExecutionPolicy Bypass -File install-vision.ps1。它会从官方仓库下载约 3.4 GB 的固定版本、经过 SHA256 校验的 Qwen3-VL 4B 权重以及一个 Vulkan llama.cpp 运行时。无需 Python、SDK 或 API 密钥。本地服务器按需在 127.0.0.1:19471 启动。在没有任务五分钟后，llama.cpp 会从内存中卸载模型及其缓存。轻量级服务器会保持运行，并在下一次请求时自动重新加载模型。活动任务会阻止空闲休眠。重启一次现有的 MCP 连接以发现新的 see 工具。

用具体问题和相关窗口的裁剪区域调用 see。它返回文本而不是图像块，因此仅支持文本的 DeepSeek 也能使用它。图像只会发送到本地服务器；生成的文本会发送到主模型。坐标是估算值；该工具会将归一化的模型框转换为屏幕像素中的 screen_box 和 screen_point。对于精确控件，优先使用 UIA，并在移动或滚动后重新观察。该工具仅进行观察，绝不会自行点击。

dsh-cu overlay                       # 人类会收到警告，ESC 可取消
dsh-cu focus --title "Settings"      # 选择窗口
dsh-cu tree                          # 角色、名称以及每个控件的一个可点击点
dsh-cu tap "Bluetooth"               # 点击具有该名称的单个控件
dsh-cu tree                          # 验证：树就是新状态

tree 使用 UI Automation 遍历窗口，并为每个控件打印一行：

TREE Invoice draft (6 elements, depth 6)
Text "Invoice draft" @1066,643
Edit "Customer name" @1250,754
Button "Save" @1075,1013
Button "Cancel" @1245,1013

find "save" 会筛选该列表，而 tap "Save" 会点击唯一的匹配项——或者在名称有歧义时拒绝并打印候选项，因此错误的点击绝不会悄无声息。在点击之前，tap
检查该点确实属于目标窗口，并在有东西遮挡它时拒绝。

Chrome、Edge 和其他 Chromium 浏览器会一直关闭其无障碍树，直到有客户端请求它；第一次 tree 或 find 会唤醒渲染器并等待页面，之后的调用则是即时的。浏览器窗口随后会以相同方式列出其链接、按钮和字段，这足以在没有 DOM 的情况下驱动大多数 Web UI。Firefox 和 Electron 应用暴露它们所暴露的内容——在规划运行之前先用 tree 检查。

当窗口不显示树时（canvas 应用、游戏、远程桌面、PDF 查看器），read 会回退到 Windows 自带的 OCR：

dsh-cu read --region 1200 600 420 240 --lang en-US
READ 3 lines (en-US, 420x240 at 1200,600)
[1310,648] Customer name
[1288,712] Design system audit
[1276,764] Save

每一行都带有要点击的点，小区域在识别前会被放大，--lang 会选择已安装的语言包（dsh-cu read --lang ru）。doctor 会列出已安装的内容。

当问题涉及像素——颜色、布局、图像、图表——时，截图仍然是正确的工具。此时 shot --region 可以让它保持较小，而具备视觉能力的路线（对于 DeepSeek Harness：Vision Toolkit 插件）可以回答关于它的问题。

滚动跟随指针，因此把它传给页面：dsh-cu wheel -600 1280 700 是在该点向下滚动五个刻度，--horizontal 会横向滚动，而 key PageDown / keys ctrl+End 会滚动获得焦点的页面。每次滚动都会移动你测量得到的坐标——在点击前重新截一张图。

人类看到的内容

代理工作时的整个屏幕：状态面板、边缘光晕和指针环

| 首次输入前的倒计时 | 一次点击，显示其落点 |
|---|---|
| 琥珀色面板正在倒计时，ESC 可取消 | 代理点击的按钮上出现涟漪环 |

- 面板会标明正在运行的命令；输入的文本仅以字符数显示。
- 当代理处于控制状态时，边缘光晕会呼吸；在倒计时期间则保持常亮。
- 该环会跟随你自己的指针，并在每次点击时脉动。截图从不包含系统光标，这就是为什么上面的图像中只显示该环。

本页所有图像都是在普通演示窗口上截取的，而不是真实桌面。

安全模型

- 当指示器关闭时，输入会被拒绝——并且在指示器进程死亡的那一刻再次拒绝，因此被杀死的指示器无法在心跳仍保持新鲜的数秒内让人类处于失明状态。仅在有意为之的情况下覆盖：DSH_CU_ALLOW_NO_INDICATOR=1。
- 指示器会在允许输入之前启动，并且在帧在屏幕上确认后，CLI 会等待完整的公告时间（默认 8 秒）。指示器仅在该倒计时之后发布就绪状态。CLI、MCP 和直接后端输入都会检查它，包括并发
调用。focus 和 wait-window 也受门控。--quiet 仅在倒计时结束后隐藏界面装饰。
- ESC 可停止它——仅限物理按键；注入的 ESC 会被忽略。
文本输入和拖拽在执行期间会检查门控；按键释放仍会在清理期间运行。
已启动的 run 进程不会被 ESC 取消。
- 面板会说明正在发生什么。 每个命令都会写入一行标签，指示器会将其显示在状态文本旁边，
以便人类可以跟进；type 报告为字符数而非文本内容，因此输入的密码绝不会出现在屏幕上。
- overlay --stop 通过 pid 文件终止指示器，重新加载系统光标并删除其状态文件。
指示器在没有桌面命令 60 秒后也会自行停止。
- 一个指针，绝无两个。 默认情况下，不会有任何东西替换你的光标：指示器会在光标周围绘制一个圆环，
因此你看到的指针就是真实的指针，圆环只是表示“代理在这里”。
dsh-cu overlay --hide-cursor 是用于屏幕共享和录制的可选功能：它会隐藏系统光标并绘制标记箭头，
因此仍然只有一个指针。该工具会记录它隐藏了光标，overlay --stop 会将其恢复，如果指示器被终止，
下一条 dsh-cu 命令会恢复它并说明情况。dsh-cu doctor 会报告 cursor: visible /
replaced by the marker / hidden, but not by this tool。
- run 和 broker start 是逃生通道。 broker start 会弹出 UAC 提示，并让
run 以提升权限执行命令行，用于此进程无法触及的窗口（UIPI）。两者都受指示器门控，
并且仅用于明确的人类请求——Harness 已经有一个 shell，因此它们唯一增加的就是提升权限。
- clipboard get 也受门控：它可能暴露人类最后复制的内容。
- 该技能指示代理在没有明确请求的情况下绝不按下任何破坏性内容。

环境变量

| 变量 | 作用 |
|---|---|
| DSH_CU_ALLOW_NO_INDICATOR=1 | 在指示器关闭时放行输入——这是有意覆盖，除此之外没有任何东西能绕过门控 |
| DSH_CU_UI_SCALE=1.5 | 在显示器 DPI 之上缩放指示器，适用于 4K 面板或视力较弱者（0.75–4） |
| DSH_CU_POWERSHELL=powershell | 默认值；仅当你的 PowerShell 位于其他位置时才将其设为另一个 PowerShell |

在沙盒化的代理会话中运行

Harness 文件沙盒会拒绝嵌套进程使用管道，因此 node 启动 powershell 并使用
stdio: 'pipe' 时，会在 PowerShell 甚至还未启动之前就以 EPERM 失败。CLI 会检测到这一确切的
失败，并使用两个文件描述符而非管道重新运行后端，因此每个命令都能继续工作。如果你宁愿完全跳过 Node，
可以直接调用后端——它接受相同的命令：

powershell -NoProfile -ExecutionPolicy Bypass -File backends\windows.ps1 shot C:\temp\shot.png

明确说明的限制
- 仅限 Windows 桌面。 doctor 可以报告不受支持的主机；交互式自检
也需要 Windows。
- 提权窗口无法从非提权进程驱动（UIPI）——请使用 broker start。
- UAC 同意对话框和锁屏无法触及：它们运行在安全桌面上，
没有签名的 UIAccess 二进制文件既无法捕获也无法点击。
- 验证码：这里没有求解器——没有 OCR、没有模型调用、没有绕过。复选框或
图块与其他任何目标一样，都是点击，由查看截图的人选择；是否允许
点击它，是你和网站之间的事。
- 仅主显示器，以物理像素为单位。该进程声明了每显示器 DPI 感知，因此
截图是原生分辨率，其坐标就是 click 所期望的坐标。
- 控件树是 UI Automation，不是 DOM。 它看到的是应用程序暴露的内容：大多数
原生 Windows 应用和 Chromium 浏览器表现良好，一些自绘 UI（游戏、画布、
模拟器）则完全不暴露任何内容。read（OCR）和 shot 可以覆盖这些情况。
- 唤醒浏览器的无障碍树会消耗浏览器一些内存和 CPU，只要它保持
开启，这就是在没有扩展的情况下读取页面的代价。
- OCR 的好坏取决于已安装的语言包，不会更好：它会误读小字号、低对比度
或装饰性文本。它返回的坐标是文本行自身的边界框，因此点击会落在文本上，
而不一定是其背后的控件上——在存在控件树的地方，优先使用 tree/tap。
- 打字以每字符 12 毫秒的速度运行，这是现代文本控件能够可靠接受的速率；换行
以 Enter 发送，制表符以 Tab 发送。超出 ±32767 的坐标会被拒绝，而不是被截断。
- 指示器绘制在物理屏幕上。该面板也会出现在远程桌面
流中；分层框架则不会。

故障排除

| 症状 | 原因 | 修复 |
|---|---|---|
| spawnSync powershell EPERM | 旧版本没有文件描述符回退机制，或不同的沙箱规则 | 更新；使用上面的直接后端调用 |
| the on-screen indicator is not running | 还没有 dsh-cu overlay，或者它被停止/按 ESC 退出了 | 运行 dsh-cu overlay，或有意设置 DSH_CU_ALLOW_NO_INDICATOR=1 |
| 光标不可见（仅当你从 1.1.0 升级时才可能出现，该版本将其清空） | 该版本替换了系统光标，而被杀死的指示器可能使它们保持空白 | dsh-cu overlay --restore-cursor；如果这没有帮助，请在设置 → 鼠标 → 其他鼠标选项 → 指针中重新应用一个指针方案，或注销后重新登录 |
| the elevated broker took the command but did not answer | 它仍在运行该命令 | 等待，然后根据需要重试；如果它卡住了，使用 dsh-cu broker stop |
| the backend was stopped after 60s | 模态对话框或繁忙的机器阻塞了调用 | 查看屏幕，关闭对话框，重试 |
| capture returned an empty image | 会话已锁定或显示器处于睡眠状态 | 解锁并重试 |
| SendInput delivered 0 of 1 events | 焦点窗口已提升权限 | 先运行 dsh-cu broker start，然后重试 |
| 代理始终看不到该技能 | $DSH_HOME 未设置，或技能 frontmatter 是无效的 YAML | dsh-cu doctor 会报告技能路径；node src\verify.js 会校验 frontmatter |

开发

node src\verify.js           # 静态检查：技能 frontmatter、文档化命令、插件清单
node test\run.mjs            # node:test 套件，测试纯逻辑部分（frontmatter、命令表、契约）
node src\cli.js self-test    # 真实机器：隔离的测试窗口，会接管鼠标和键盘
node src\cli.js doctor

verify 和测试套件不会触碰任何东西，因此运行器可以执行它们（参见
.github/workflows/ci.yml，它调用的正是这两个）。self-test 是侵入性的那个——请在你愿意
交出的已解锁桌面上运行它。它会创建自己的 Windows Forms 窗口，不碰现有的编辑器和剪贴板，
并且只关闭那个测试窗口。如果桌面无法接受输入，测试就会失败。它会拒绝替换活动会话，或在
最近有人按下 ESC 后重启。截图和文本证据会保留在报告中的临时文件夹里。
物理 ESC 和实际模型完成任务的能力仍然是各自独立的交互式检查。

src/cli.js              入口点：argv -> 一次命令调用，一条错误路径
src/commands.js         命令表：名称、参数、摘要、门控和处理程序
src/backend.js          唯一会生成进程或读取临时路径的文件
src/contract.js         静态契约检查（frontmatter、文档、插件清单）
src/selftest.js         针对真实机器的检查
src/tool-error.js       错误类型，其消息面向操作员
backends/windows.ps1    PowerShell 宿主：argv、分发、指示器生命周期、broker
backends/csharp/        它编译的 C#，每个文件一个类型
lib/index.js            DSH 插件入口：注册该技能
lib/skill.js            技能注册对象，从 SKILL.md 读取
lib/frontmatter.js      插件所需的两个 frontmatter 字段
cordis.patch.yml        挂载该插件的 bundle 补丁
test/                   node:test 套件（test/run.mjs 在单个进程中运行它）
SKILL.md                面向代理的技能：何时使用它、循环、安全规则
AGENTS.md               面向编码代理的索引：布局、入口点、容易被破坏的规则
install.ps1             一条命令安装

将其放入插件市场

市场就是 dshmarket 插件（设置 → Plugin Market）；其目录来自
精选 PR，目录安装插件时
可以从包注册表安装，也可以直接从其 GitHub 仓库安装——这个插件使用的是仓库方式，
所以无需先发布任何东西。

| 步骤 | 状态 |
|---|---|
| GitHub 仓库 | datuloar/dsh-computer-use-win — 公开，分支 main |
| dsh.bundle.patch + 插件入口 | 在仓库中，因此 bundle 会挂载并注册该技能 |
| 安装路径 | dsh plugin --profile web add github:datuloar/dsh-computer-use-win |
| 仓库元数据 | 在 GitHub 上添加 dsh-plugin 主题和一行描述 |
| 目录 PR | 一个文件 data/plugins/datuloar__dsh-computer-use-win.yml，包含 url、name、category: tools 和双语 description |

目录条目本身，可直接粘贴到该 PR 中：

url: https://github.com/datuloar/dsh-computer-use-win
name: datuloar/dsh-computer-use-win
category: tools
description:
en: Windows computer use for DeepSeek Harness agents — screenshot, click, type, scroll and focus windows, with an on-screen indicator the human can see and stop with ESC. No dependencies and no driver to install.

目录中的 CI 要求有 dsh.bundle、真实可运行的代码、至少创建一天的仓库，以及与代码匹配的描述。可选但推荐：在 package.json 旁边放置 screenshots.json（1–8 张 GitHub 托管的图片），这样卡片会显示精选截图，而不是抓取此 README —— docs/indicator.png 是本仓库附带的唯一截图。

如果 CLI 被重命名，有三个地方需要同步修改：package.json 中的 bin、lib/index.js 中导出的 name，以及 cordis.patch.yml 中的 id/name；该技能保留自己的名称 dsh-computer-use，这正是 $DSH_HOME\skills\ 和目录所显示的内容。如果它们不一致，node src\verify.js 会失败。

请注意，os: ["win32"] 会使包管理器在 macOS 和 Linux 上拒绝安装，而目录没有仅限 Windows 的标志 —— 市场仍会向所有人显示该卡片。

许可证

MIT