Windows 电脑操控 esch30636/dsh-computer-use

dsh-computer-use

给 DeepSeek Harness 用的 Codex 风格 Windows 电脑操控：按窗口定位的 UI Automation + 抗遮挡截图 + SendInput 鼠标键盘注入，对外暴露五个面向模型的工具，底层由一个随包附带、长期驻留的 PowerShell 辅助进程支撑。

电脑操控开启期间，屏幕上会画出一层可点击穿透的覆盖层，呈现鲜亮的「液态玻璃」质感：一圈蓝宝石色边缘暗角（中心完全透明，向屏幕四边渐变为缎面藏青），显示屏边框内侧贴一道细青色玻璃亮边；顶部居中还有一颗「灵动岛」状态胶囊——蓝宝石渐变、斜向高光、明亮描边、蓝色呼吸光晕，文字为 DeepSeek Harness 正在操控你的电脑 | 按 ESC 终止。按下 ESC 会立即停止电脑操控并关闭覆盖层；智能体会收到停止指令并回报结果。

参照 OpenAI Codex 的 Windows Computer Use 接口面设计（list_apps / get_window_state / click(element_index | x,y) / press_key / type_text / scroll / drag / set_value / activate_window，X11 keysym 风格的按键名，执行一个动作后重新观察），重写为纯 DSH 插件，不依赖任何第三方运行时。

你能得到什么

| 工具 | 用途 |
| computer_list_windows | 列出可操作的目标顶层窗口（window_id、进程身份、标题、矩形区域、是否前台/最小化、是否被策略拦截）。可选列出开始菜单里可启动的应用。 |
| computer_observe | 抓取单个窗口的状态：截图（默认）和/或带元素索引的 UI Automation 树、焦点元素、选中内容、文档文本。返回 state_id 和截图坐标映射。 |
| computer_action | 针对某个状态只执行一个动作：click / double_click / right_click / middle_click / mouse_move / type / key / scroll / drag / set_value / wait / activate_window。 |
| computer_launch_app | 按 exe 路径、exe 名称、开始菜单显示名、.lnk 或 shell:AppsFolder\<AUMID> 启动应用；回报它打开的窗口。 |
| computer_sequence | 在同一个窗口上按顺序执行最多 100 个输入步骤，中间不重新观察（使用绝对屏幕像素）——适合画图这类重复性 GUI 操作；可选返回一张验证截图。 |

此外还有带 ESC 急停开关（USER_ESCAPE）的可点击穿透状态覆盖层、一段系统提示词（工作流、硬性禁止项、确认策略），以及一个包含完整操作手册的 computer-use 技能。

环境要求

- Windows 10/11，交互式用户会话（不是服务会话），PowerShell 5.1（powershell.exe——不需要 pwsh 7）。
- DSH 0.2.x（web/desktop 配置档；任何挂载了 tools、systemPrompt 和 attachments 的组合都行——随附的基础配置档三个都挂载了）。
- 无原生模块，无 npm 依赖，无 MCP 服务器。

安装

方案 A —— DSH 命令行（dsh plugin add）

对于 dsh 命令行能管理的配置档（web、tui、headless 等），插件按常规 DSH bundle 安装：

straight from GitHub (pnpm fetches the repo tarball)
dsh plugin --profile web add github:esch30636/dsh-computer-use

or from the release tarball (no git fetch; works behind a GitHub proxy too)
dsh plugin --profile web add "https://github.com/esch30636/dsh-computer-use/releases/latest/download/dsh-computer-use.tgz"

dsh plugin 把包装进配置档，并启用它的 bundle。重启宿主（或等 HMR 重新组合），computer_ 工具就会出现在新会话里。

方案 B —— 桌面应用（desktop 配置档）

桌面应用独占保留的 desktop 配置档，所以 dsh plugin --profile desktop 在那里会故意拒绝执行。两条受支持的路径：

1. 插件市场 —— 等本插件在 awesome-dsh-plugin 上架后（提交受「仓库满一天」规则限制，尚在等待），打开 设置 → 插件市场，一键安装。
2. 发布安装器（立即可用，不需要 git/pnpm）：从 releases 下载并解压归档，然后在解压后的文件夹里运行：

downloads the latest release tarball and installs into the desktop profile
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install-release.ps1

用 -Version v1.1.0 固定版本；用 -Profile web 指定别的配置档；加 -Verify 可在安装后跑一次离线组合转储。

方案 C —— 手动 / 完全离线

下载发布归档（releases），解压，然后运行随附的安装器：

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install.ps1 -Profile desktop

安装器把包复制到 ~/.dsh/profiles/<profile>/node_modules/dsh-computer-use，把 dsh-computer-use 追加到 dsh.profile.bundles（先备份 package.json），再把技能安装到 %USERPROFILE%\.agents\skills\computer-use。任何配置档都能用，比如 -Profile cu-test；加 -Verify 可离线转储组合后的配置档。

卸载：

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install.ps1 -Profile desktop -Uninstall

关于包名的说明： 一个无关的 npm 包已经占用了 dsh-computer-use 这个名字，所以 dsh plugin add dsh-computer-use 装的是那一个。请通过上面给出的 GitHub spec 或发布 tarball URL 安装本插件。仅支持 Windows（os: win32）：辅助程序通过 UI Automation + SendInput 驱动真实的交互式桌面会话。

配置

选项写在配置档的 cordis.patch.yml 里（行 id 是 computer-use）：

- id: computer-use
config:
extra process names/paths to deny (built-in denies always stay unless an
allow- escape hatch is enabled)
blockedProcesses: [msedge.exe]
allowlist mode: only these processes may be automated
allowedProcesses: [notepad.exe, mspaint.exe]
screenshotMaxWidth: 1600
screenshotMaxHeight: 1200
maxElements: 600
maxTreeDepth: 12
idleTimeoutMs: 600000
startupTimeoutMs: 90000
requestTimeoutMs: 30000
confirmRiskyActions: true
warnWhenApprovalUnavailable: true
allowWindowsKey: false
allowTerminalAutomation: false
keepScreenshots: false
screen overlay + ESC kill switch
overlayEnabled: true
overlayMessage: "DeepSeek Harness 正在操控你的电脑　|　按 ESC 终止" overlayIdleTimeoutMs: 90000 overlayEdgeOpacity: 55

| 选项 | 默认值 | 含义 |
| helperPath | 内置 | 覆盖辅助脚本路径。 |
| powershellPath | powershell.exe | 用来承载辅助脚本的 PowerShell。 |
| idleTimeoutMs | 600000 | 空闲时结束辅助进程；下次调用会重新启动。 |
| startupTimeoutMs | 90000 | 首次调用的时间预算（启动 PowerShell + 编译 Add-Type）。 |
| requestTimeoutMs | 30000 | 预热后每次请求的时间预算（截图和 UIA 内部会用更长的预算）。 |
| screenshotMaxWidth / screenshotMaxHeight | 1600 / 1200 | 辅助进程侧在写入附件存储前的缩放上限。 |
| maxElements / maxTreeDepth / maxTextChars | 600 / 12 / 20000 | 无障碍树的边界。 |
| blockedProcesses / blockedWindowClasses | [] | 在内置列表之外追加的拒绝项。 |
| allowedProcesses | [] | 非空时进入允许列表模式（其余全部拒绝）。 |
| keepScreenshots | false | 把截取的 PNG 留在 %TEMP%\dsh-computer-use 里，便于调试。 |
| confirmRiskyActions | true | 执行破坏性动作或对外可见动作前，先经 ctx.approval 询问。 |
| warnWhenApprovalUnavailable | true | 审批策略为 never 或没有审批通道时：给出 WARNING 后继续，而不是直接失败。设为 false 则改为失败关闭。 |
| allowWindowsKey / allowTerminalAutomation | false | 为两条最危险的硬性拒绝项开的逃生舱（仍不推荐；辅助进程自己也会做检查）。 |
| overlayEnabled | true | 绘制可点击穿透的桌面浮层，并启用 ESC 终止开关。 |
| overlayMessage | DeepSeek Harness 正在操控你的电脑　|　按 ESC 终止 | 状态岛文字。 |
| overlayIdleTimeoutMs | 90000 | computer-use 无活动超过这么久就隐藏浮层（下次动作时重新出现）。 |
| overlayEdgeOpacity | 55 | 边缘暗角强度 0–100；屏幕中心始终保持清晰。 |

工作原理

DSH host process Windows user session
┌──────────────────────────┐ JSON lines ┌───────────────────────────────┐
│ dsh-computer-use 插件 │◄──────────────►│ ComputerUseAgent.ps1 │ │ computer_* 工具 │ stdin/stdout │ UI Automation 树 │ │ 状态注册表 │ │ PrintWindow 截图 │ │ 附件（PNG） │ │ SendInput 鼠标/键盘 │ │ 安全策略 │ │ 窗口枚举/激活 │ │ 覆盖层防护（ESC） │ ├───────────────────────────────┤ │ │ 状态文件 │ CuOverlay.ps1（WPF 子进程） │ │ │◄──────────────►│ 边缘暗角 + 状态胶囊 │ └──────────────────────────┘ 心跳/esc └───────────────────────────────┘

- 辅助进程延迟启动：首次调用 computer-use 时才拉起（powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File helper\ComputerUseAgent.ps1）。请求串行处理（输入注入不能交错），每个请求都有超时限制，崩溃后自动重启，插件销毁或空闲时结束进程。
- 覆盖层：首次收到桌面请求时，辅助进程会启动一个独立的 STA PowerShell/WPF 子进程（CuOverlay.ps1），在主显示器上绘制两个点击穿透、置顶、不参与截图的窗口——一个是径向的液态玻璃边缘暗角（中心透明 → 缎面藏青边缘），沿屏幕边框带一圈细青色玻璃描边；另一个是蓝宝石渐变的灵动岛胶囊，带斜向光泽、明亮玻璃描边和呼吸式蓝色辉光。材质只用逐像素 alpha 的 WPF 渐变实现（不调用 DWM 亚克力/模糊 API，不做全屏动画，不挂全局键盘钩子）——鲜艳感来自颜色和层次，不依赖脆弱的系统特效。插件在每次工具调用和当前轮次的每个会话事件中刷新心跳文件；辅助进程在 sequence/wait 运行期间持续刷新；心跳过期、轮次结束、辅助进程死亡或用户按下 ESC 时，覆盖层自动隐藏。
- ESC 急停：覆盖层轮询 GetAsyncKeyState(VK_ESCAPE)（约 80 ms）。按下 ESC 时写入 escape.json 并关闭；辅助进程随即中止进行中的 sequence/wait，后续任何请求都返回 USER_ESCAPE，插件在本轮剩余时间内拒绝所有 computer_* 工具。当会话日志在 ESC 时间戳之后出现新的 user/message（即用户再次发言）时，停止状态自动清除，下一个任务无需重启即可工作。
- 截图写入 %TEMP%\dsh-computer-use，作为持久 DSH 图像附件提交（ctx.attachments.saveImage），以图像内容块返回，除非设置 keepScreenshots，否则随后删除。
- 坐标以附件图像像素定义；观测结果报告 origin + coordinate_scale，插件在注入前换算回屏幕像素。模型无需区分逻辑像素与物理像素。
- 每个输入动作都会消耗观测状态，强制执行 Codex 的「观测 → 一个动作 → 重新观测」纪律。
- helper 自己执行硬性策略（BLOCKED_APP、FORBIDDEN_KEY、PASSWORD_FIELD、DESKTOP_LOCKED、SECURE_DESKTOP），插件再执行一层，并在风险点要求确认。
- 配置档格式错误时，插件在加载阶段就报错，并指出出错的键名，不会静默忽略某个选项。

安全模型

三层防护，与 Codex Windows 的做法一致，另加一个随时可用的手动停止：

0. 手动停止（ESC）：浮层可见时，按 ESC 立即停止输入注入（正在运行的序列在下一个步骤边界停下，正在运行的等待在约 150 ms 内停下），用 USER_ESCAPE 回应当前调用，并阻止后续 computer-use 工具，直到用户再次开口。helper 和插件都会执行这个停止，所以即使模型继续调用工具也拦得住。

1. 硬性拒绝——永远不允许，不可确认：终端/控制台、regedit/taskmgr/mmc/control、UAC/安全桌面/锁屏、安全与杀毒界面、密码管理器、密码字段、DSH 宿主本身、其他智能体、Windows/Meta 键族、安全注意序列。

2. 风险点确认：破坏性操作、外部副作用（发送/提交/发布/上传/分享）、支付、安装、账户/权限/安全变更、敏感数据录入。会话策略为 ask 时，走 DSH 的审批接缝；策略为 never 时，结果带明确的 WARNING，模型必须自己询问用户。

3. 警告：较低风险的启发式判断（焦点窗口无名称、窗口标题看起来像登录界面、Alt+F4、含义不明的拖拽）。

屏幕内容一律视为不可信数据。插件从不把 UI 文本当作授权。

故障排查

| 现象 | 原因 / 修复 |
| helper script not found | 重新运行安装程序；helper 路径是 lib/ 旁边的 helper/ComputerUseAgent.ps1。 |
| 首次调用慢（2–6 秒） | 正常：PowerShell 启动，Add-Type 编译 P/Invoke/UIA 类型。之后的调用很快。 |
| 首次调用报 HELPER_TIMEOUT | 调大 startupTimeoutMs；检查杀毒软件是否拦截 PowerShell 子进程。 |
| computer use failed [DESKTOP_LOCKED] / [SECURE_DESKTOP] | 会话已锁定，或 UAC 提示框正开着。解锁 / 关掉它；插件不会绕过。 |
| BLOCKED_APP | 目标进程在拒绝列表里（或不在 allowedProcesses 里）。用 computer_list_windows 查看 BLOCKED 标记；如果默认策略对你的场景太严，配置 blockedProcesses/allowedProcesses（终端和 harness 本身实际上故意不可配置）。 |
| 截图全黑 | 某些硬件加速的界面拒绝 PrintWindow。激活窗口后重试；或用 include_text: true 走无障碍接口驱动。 |
| 执行操作后 Visio/Office 窗口立刻消失 | v1.0.1 已修复：辅助进程过去会对已可见的窗口调用 ShowWindow(SW_SHOW)；这种情况下 Visio 2021 会清除 WS_VISIBLE。现在辅助进程只强制显示隐藏/最小化的窗口。如果旧辅助进程仍在运行，结束命令行包含 ComputerUseAgent.ps1 的 powershell.exe 进程；下一次操作会重新拉起修复后的辅助进程。 |
| 树为空 / 太弱 | UI Automation 支持较差的应用（自绘 UI、部分 Electron/Qt 应用）暴露的信息很少。改用截图 + 坐标，或键盘导航。 |
| 没有边缘暗角 / 状态岛出现 | 覆盖层需要交互式桌面和 Windows PowerShell 5.1 WPF。检查 DSH 的 stderr 中是否有 computer-use: screen overlay enabled，以及 overlay start failed / overlay script not found；确认 helper/CuOverlay.ps1 与 ComputerUseAgent.ps1 位于同一目录。覆盖层在空闲时（默认 90 秒）和一轮结束后也会主动隐藏。 |
| 覆盖层可见但 ESC 无效 | 在胶囊可见时按 ESC（它隐藏后就没有可停止的东西了）。如果 ESC 仍无法停止智能体，检查 %TEMP%\dsh-computer-use-overlay\<pid>\ 下是否有残留的 escape.json —— 插件会在用户下一条消息时清除它。 |
| 工具结果中出现 USER_ESCAPE | 用户用 ESC 停止了计算机使用。不要重试：报告你已停止，等待用户的下一条指令。 |
| 桌面感觉被「吞掉」/ 点击不生效 | CuOverlay.ps1 中有安全防护：如果无法验证点击穿透扩展样式，覆盖层会自行关闭而不是绘制。如果有 CuOverlay.ps1 PowerShell 进程卡住，结束它。 |
| ELEMENT_OFFSCREEN | 控件已滚出视野；滚动容器，重新观察，再重试。 |
| state_id ... consumed | 每次观察只允许一次输入操作。重新观察。 |
| 审批提示从不出现，但警告出现 | 会话审批策略为 never（例如 danger-full-access）。插件会发出警告；直接询问用户。 |
| 安装后工具不出现 | 宿主没有重新组合。重启 DSH，或检查加载器日志中的 bundle 解析错误。scripts\install.ps1 -Verify 可验证模块能否导入。 |

开发

- docs/helper-protocol.md —— 辅助进程的 JSON-RPC 契约（方法、schema、错误码）。
- helper/tests/run-tests.ps1 —— 辅助进程协议端到端测试（启动记事本、输入、截图、断言）。
- test/tool-smoke.mjs —— 工具层冒烟测试，使用模拟宿主（@deepseek-ai/dsh-tools shim）验证 observe/action 渲染和状态消费。
- scripts/setup-test-profile.ps1 —— 创建真实的 headless 配置档，并运行一次性智能体任务。

目录结构：

dsh-computer-use/
package.json # DSH plugin manifest (bundle patch)
cordis.patch.yml # inserts the computer-use row
lib/
index.js # plugin entry: config, prompt section, tool registration, helper lifecycle
config.js # 配置校验 + 默认拒绝列表 helper-client.js # 长驻辅助进程的 JSON-RPC 客户端 overlay.js # 覆盖层心跳 + ESC 急停守卫（插件侧） policy.js # 硬性拒绝、按键校验、确认启发式 tools.js # 面向模型的五个工具 + 状态注册表 helper/ ComputerUseAgent.ps1 # Windows 辅助进程（UIA + PrintWindow + SendInput） CuOverlay.ps1 # WPF 覆盖层子进程（暗角 + 状态岛 + ESC 监听） tests/run-tests.ps1 skills/computer-use/ # 模型技能（安装到 ~/.agents/skills） docs/helper-protocol.md scripts/install.ps1, setup-test-profile.ps1

限制（有意为之，v1）

- 只针对窗口：没有全桌面或多显示器全景（按窗口截图更安全也更简单，坐标不会歧义）。覆盖层同样只覆盖主显示器。
- 覆盖层只是装饰和急停开关，不是操作面板：它从不抢焦点、不接收点击，也不进入屏幕截图，还不能暂停或恢复智能体本身（ESC 永远表示「停止这次电脑操作」）。
- 不支持剪贴板读写，不自动填写文件对话框，不支持多点拖拽路径（只支持单段直线拖拽），没有 perform_secondary_action，不支持按住按键。
- 无障碍树尽力而为且有上限（默认 600 个元素 / 深度 12）—— 超大结构会被截断。
- 辅助进程用 PowerShell 实现，以便零二进制分发；首次调用要付编译开销。原生辅助进程会更快，但这是分发与安全之间的取舍。
- 辅助进程必须运行在用户的交互会话里：RDP 断开或锁屏的会话、安全桌面，一律按设计拒绝。
- 工具描述用英文，安全提示对中文友好；除审批接缝外，确认策略由模型执行。