Yu-tao-Li/dsh-computer-use-win

dsh-computer-use-win

让 DSH 看懂并操作你的 Windows 桌面。

您的 Star ⭐ ↗ 就是我更新的动力，球球了，这对我很重要！如有问题，欢迎去 提 Issue ↗，您来许愿，我来实现！

语言 / Language: 简体中文 · English

Releases · npm · Issues

简体中文

这个插件让 DeepSeek Harness（DSH）里的 agent 看到并操作你电脑上真实的 Windows 程序：找到按钮和输入框，读出屏幕上的文字，点击、打字，切换和管理窗口。

23 个桌面工具 + 1 个管理入口 · 操作时有明显提示 · 按 Esc 随时停止 · 中英文设置界面

目录：1 快速开始 · 2 界面预览 · 3 能做什么 · 4 工作原理 · 5 设置 · 6 使用示例 · 7 工具与进阶 · 8 常见问题 · 9 数据与隐私 · 10 文档与开发 · English

1. 快速开始

1.1 安装

你需要一台 Windows 电脑，并且已经装好 DSH Desktop。插件用的是 Windows 自带的 PowerShell 5.1，不用另外安装。

1. 右键点击任务栏托盘里的 DSH 图标，选“打开 DSH 终端”，然后运行：

dsh plugin --profile desktop add dsh-computer-use-win

1. 再右键托盘图标，选“退出”，然后重新打开 DSH Desktop。只关掉窗口不够：窗口关了，DSH 还在托盘里运行，不会加载新装的插件。
2. 打开 设置 → 电脑操控（鼠标图标）看看各项选项。不改也能直接用，默认加载全部工具。然后给 agent 布置一个桌面任务，比如第 6 节里的例子。

1.2 升级

运行同一条安装命令，然后像上面第 2 步那样完全退出、再重新打开 DSH Desktop。

命令里的 desktop 是 DSH Desktop 使用的配置（profile）。如果装到了别的 profile，正在用的 DSH 不会有任何变化。

1.3 其他安装方式

DSH Web、GitHub 源、单独的 MCP 客户端

DSH Web：

dsh plugin --profile web add dsh-computer-use-win

装好后重启 dsh web。用别的 profile 时，把 web 换成它的名字。也可以在插件市场搜索 dsh-computer-use-win，或者从 GitHub 安装：

dsh plugin --profile desktop add github:Yu-tao-Li/dsh-computer-use-win

不在 DSH 里，也可以让任何 MCP 客户端启动它：

{
  "mcpServers": {
    "wincu": {
      "command": "npx",
      "args": ["-y", "dsh-computer-use-win"]
    }
  }
}

DSH Web 和单独的 MCP 客户端会用你电脑上的 Node.js 运行插件，需要 22 或更高版本。DSH Desktop 自带运行环境，不用另装 Node.js。

单独运行时默认加载全部工具。设置环境变量 WCU_TOOL_MODE=lite 只加载常用工具，WCU_TOOL_MODE=lazy 开始时只加载管理入口。也可以在 WCU_ENABLED_TOOLS 里写一个 JSON 数组，指定允许哪些工具。设置页、对话里的操作记录和整轮提示只有在 DSH 里才有。详见工具加载说明。

2. 界面预览

下面是 DSH Desktop 2.0.18 和插件 0.5.1 的真实截图（中文界面）。演示任务是：新开一个浏览器窗口，搜索“晴天”，确认结果里有“周杰伦”。截图只保留了对话或设置面板，点击图片可以看原图。

2.1 对话里能看到每一步

每次桌面操作都是一行带鼠标图标的记录，比如“输入了文本”“发送了按键”“检查了操作结果”。点“查看步骤和截图”，可以看到每一步的详情和截图。

2.2 设置页

设置在左侧的“电脑操控”（鼠标图标）里。先选一种工具加载方案：精简、全部、懒启动或自定义，默认是“全部”（24 个工具）。顶部的 Star 和 Issue 说明可以点“折叠”收成一个链接，下图就是折叠后的样子，点“展开”就能恢复。

2.3 更多截图

任务总结、自定义工具、接管提示、停止设置

任务总结。 一轮操作结束后，agent 会说明自己做了什么、在结果页里确认了什么。图中的文字由这次任务用的模型生成。

自定义工具。 选“自定义”后会展开工具清单，可以一个个勾选，也可以整组勾选。图中是没有保存的演示，截完图就放弃了。

接管提示。 agent 操作桌面时，屏幕边缘会亮起蓝色光晕，顶部或底部出现“DSH 正在控制电脑”提示条，鼠标旁跟着一个 DSH 标签。这几样可以分别开关，设置页里有预览。

停止设置。 默认按 Esc 停止。你也可以再录一个自己的快捷键，比如 F8。

3. 能做什么

你想让 agent 做的事 · 插件怎么做到 找到窗口、按钮和输入框 · 列出打开的窗口，再通过 UI Automation（UIA，Windows 给程序读取界面控件的接口）找到控件和它们的名字 读出界面上的文字，包括图片和自绘界面里的字 · 截图，用 Windows 自带的文字识别（OCR）找出文字和位置。界面控件很少、又没找到目标时，查找会自动改用 OCR 点击、输入、填写表单 · 优先直接操作控件，比如“按下按钮”“填入内容”，不行时再模拟鼠标和键盘。粘贴文字时不会挪动你的鼠标 等页面变化，确认操作真的生效 · 等某个窗口、控件或文字出现，再读取或截图确认 让你看清 agent 在做什么 · 屏幕提示、鼠标旁的 DSH 标签、对话里的步骤记录和结束总结

在 DSH 对话里，每次桌面操作都写成一句好懂的话，比如“点击了目标位置”，后面标出状态：“已完成”“操作已发送，效果待确认”“未完成”或“已停止”。重新打开对话时，这些记录还在。

4. 工作原理

4.1 一次桌面任务怎么进行

agent 每一步都按“观察 → 定位 → 执行 → 确认”来做，开头那张图的下半部分画的就是这个循环：

1. 观察：列出打开的窗口，读取界面控件，或者截图并识别文字。
2. 定位：找到要操作的按钮、输入框或文字的位置。
3. 执行：能直接操作控件就直接操作，比如按下按钮、填入内容，不行再用鼠标和键盘。
4. 确认：等预期的变化出现，再读一次界面。没达到目标，就回到第 1 步。

插件会区分两种结果。输入类操作只返回“已发送”（verification: "sent"），因为程序收到了输入，不等于任务完成了。只有 wait_for 看到预期的窗口、控件或文字出现时，才返回“已确认”（verification: "observed"）。所以布置任务时，最好写明要确认什么。

4.2 整体架构

图里蓝色的部分是本插件的代码，灰色的部分由 DSH 或 Windows 提供。各部分的分工如下：

• 插件适配器（mcp/dsh-plugin.mjs）运行在 DSH 里。它把你的设置交给 MCP 服务，并跟踪对话的轮次，保证同一时间只有一段对话在操作桌面。
• 设置页与操作记录（mcp/client.js）就是“设置 → 电脑操控”这一页。它也负责把对话里的工具调用显示成好懂的步骤。
• MCP 服务（mcp/server.mjs）由 DSH 的官方 MCP 桥启动。它按你选的方案提供工具，检查参数后把请求交给后端。
• PowerShell 后端（scripts/windows-uia.ps1）负责读取界面、发送输入和截图。它一直运行，所以后续调用不用每次重新启动 PowerShell。请求排队，一次只执行一个，两个操作不会同时抢鼠标和键盘。
• 接管助手（scripts/windows-takeover.ps1）是单独的进程，负责屏幕提示，并直接监听 Esc。因为它不经过 DSH 和后端，后端正忙时也能收到 Esc：还没开始的操作会被取消，正在进行的输入会尽快停下。

更多细节见架构说明。

5. 按你的习惯设置

在 设置 → 电脑操控 里调整，点“保存更改”后生效。界面跟随 DSH 的明暗主题。如果读不到设置，页面会直接说明，而不是显示一份看起来正常的默认值。

5.1 设置项

设置 · 可以怎么选 工具加载 · 全部（24 个，默认）；精简（10 个常用工具）；懒启动（开始只加载 1 个管理工具，需要时再加载，全部工具都允许）；自定义（逐个或整组勾选） 屏幕提示 · 开关屏幕边缘光晕和提示条；可以改提示文字，放在顶部或底部，并设置结束后多久收起（0.2–3 秒） 鼠标提示 · 单独开关鼠标旁的光斑和 DSH 标签。不会改你的系统鼠标样式，调大了的指针也会自动避开 远程与录屏可见 · 默认打开，让 UU 远程、屏幕共享和录屏也能看到提示。换显示器、调整布局或缩放后会自动跟上 停止快捷键 · 点“录制快捷键”，按下想用的键（比如 F8 或 Ctrl + Alt + K），再保存。“恢复默认（Esc）”会清掉额外的快捷键 预览 · 保存后点“预览接管提示”，看看提示在你屏幕上的样子

5.2 随时按 Esc 停止

按下 Esc 或你设的快捷键，这一轮的桌面操作和排队中的操作会立即停止，这一轮也不会自动重试。想继续时，直接发新任务或说“继续”就行，不用去设置里恢复。普通的鼠标移动和其他按键不会触发停止。即使关掉了屏幕提示，Esc 照样有效。

5.3 提示什么时候出现、什么时候收起

第一次桌面操作开始时出现，之后截图、读取和短暂思考期间一直显示。这一轮结束、取消或出错后，按你设的时间收起。如果最后一次桌面操作后 30 秒都没有新操作，提示也会收起，下次操作时再出现。单独运行的 MCP 服务没有“轮”的概念，所以每次调用单独显示。

5.4 使用须知

• 能直接操作控件时，插件会优先这样做，因为这样不用移动鼠标。但按坐标点击和键盘输入还是会用到你的鼠标和键盘，所以 agent 操作时最好别同时动它们。
• 同一时间只有一段对话能操作桌面，其他对话会收到“忙碌”的结果。
• 已经发给程序的操作无法撤回。如果程序卡住了，要等它响应后才能停下来。
• 切换方案时，你的自定义清单会保留。保存的改动在当前这一步操作结束后生效，重启后也还在。agent 不能打开你关掉的工具。

完整说明见设置与停止。

6. 使用示例

6.1 可以这样布置任务

在记事本中输入“会议纪要”，再读取文本确认写入成功。

在已打开的计算器中计算 25 × 4，并读取结果。

打开浏览器，搜索“Windows UI Automation”，确认出现搜索结果，并总结你做了什么。

打开网易云音乐，搜索“晴天”，确认结果页出现“周杰伦”。如果无障碍树看不到搜索框，用 OCR 定位可见文字。

任务里写清楚要确认什么，agent 就会去检查结果，而不是把输入发出去就结束（见 4.1）。结果也取决于目标程序、所用的模型和当前页面。

7. 工具与进阶

7.1 工具清单

一共 23 个桌面工具和 1 个管理入口。下表用的是短名；完整名字是 windows_computer_use_，在 DSH 里通常还会加上 mcp__wincu__ 前缀。

用途 · 工具 检查连接、找窗口 · health · list_windows 读取界面控件（UIA） · snapshot · accessibility_tree · find · element_info 截图和文字识别 · screenshot · ocr 鼠标 · click · double_click · move · drag · scroll 输入文字、操作控件 · type_text · keypress · focus · invoke · set_value 管理窗口 · activate_window · move_window · close_window 等待和确认 · wait_for · wait 管理工具 · tools

7.2 精简方案与管理入口

精简方案包含 list_windows、find、click、scroll、type_text、keypress、ocr、screenshot、wait_for 和 tools。

有了管理入口 tools，agent 可以查看某个工具的说明，也可以临时卸载或重新加载你允许的工具；reset 会恢复你保存的启动方案。卸载工具不会删掉对话里已有的说明和结果。

7.3 使用建议

能用 UIA 找到控件时，用 invoke / set_value 直接操作。UIA 找不到，或者只找到很少的控件时，用 OCR 读屏幕上的文字；图标和布局交给能看图的模型读截图。OCR 只返回文字和屏幕坐标，不会编造控件 ID。窗口移动或控件变化后，要重新观察。

完整参数与返回值 · 按需加载与客户端兼容性 · 不同应用的技术差异