前言¶
在 DeepSeek Harness（DSH）里做自动化，常见做法是写脚本或调 API；一旦任务落在本机 GUI——对话框、资源管理器、没有稳定接口的桌面软件——模型往往只能「猜界面」，你还得自己点鼠标。社区插件 dsh-gui-control（维护者 Macocin，GitHub：Macocin/dsh-gui-control）把截图、读屏和鼠标键盘控制收成一组 desktop_* 工具，让模型按「看 → 点 → 打字 → 再看」闭环操作 Windows 桌面。下面介绍它是什么、能做什么、怎么装，以及使用前必须知道的边界与安全点。
这是什么¶
dsh-gui-control 是 DSH 的客户端类插件：类似人类操作的桌面控制——查看截图、控制鼠标键盘，并附带低成本读屏（无障碍树、OCR、找色/网格、截图分级）。当前资料版本为 0.1.0，仅支持 Windows，要求 Node ≥ 18，零 npm 依赖（Node 内置模块 + 系统自带 PowerShell 5.1），许可证 MIT。
插件同时注册 gui-control skill，把坐标换算、省 token 的读屏策略和常见坑写进模型上下文。社区目录页：https://www.skillhub.cn/plugins/Macocin/dsh-gui-control ；源码与说明：https://github.com/Macocin/dsh-gui-control 。目录站点与 DeepSeek / 幻方无官方从属关系，属于 DSH「一切皆插件」生态里的第三方条目。
核心功能¶
读屏：L0 → L4，先便宜后贵¶
同一画面，读屏手段不同，token 代价可差约 5～20 倍。README 要求永远从 L0 往 L4 试，第一级成功就停，并在本会话内记住该应用适合哪一级。
| 层级 | 工具 | 作用概要 |
|---|---|---|
| L0 | desktop_a11y |
Windows UI Automation 控件树（名称 + 坐标） |
| L1 | desktop_ocr |
屏幕文字 JSON（文本 + 坐标，无图） |
| L2 | desktop_find |
找色 / 网格 / 校验某点颜色 |
| L3 / L4 | desktop_screenshot |
截图回传图像（可限窗口、区域、灰度、变更检测等） |
辅助工具 desktop_info 返回显示器、DPI、光标、前台窗口、窗口列表等纯文本，不消耗图像 token。
操作：类人轨迹与一步多动¶
desktop_mouse：move/click/right/double/drag/scroll；默认鼠标走三次贝塞尔曲线 + 缓动 + 抖动，而非瞬移。desktop_keyboard：type（逐字符 Unicode）、paste（剪贴板）、press/hold。desktop_act：一串步骤 + 末尾截图，一次调用完成多步；含waitChange等。desktop_click_text：按文字找坐标并点击，支持dryRun。
坐标默认绑定最近一张截图的像素：
screenX = region.left + imageX / scale.x。需要物理屏幕坐标时传 space: "screen"。
紧急停止（使用前必读）¶
| 热键 | 效果 |
|---|---|
| Ctrl+Shift+C | 所有桌面控制立刻失效 |
| Ctrl+Shift+C+V | 急停 + 要求 AI 结束对话 |
| Ctrl+Shift+X | 解除（仅用户按键，无工具可代解） |
急停后工具返回 HALTED，状态写入 %TEMP%\dsh-gui-control\halt-<pid>.json，Node 每次调用前读取。README 强调：务必阅读急停章节；不要给 DeepSeek 改这个插件，以免急停逻辑被改坏；代码经 AI 核查，可能存在未发现问题。敏感界面上不要让插件看屏——截图、OCR、无障碍树会把屏幕内容（含可见信息）送入模型上下文；paste 会临时读写剪贴板。
急停生效后，desktop_guard 仍可查看状态，是被拦截时唯一还能调通的工具。
实现要点（便于评估信任边界）¶
- 持久 helper 进程：
helper/win-helper.ps1，JSON 行协议，约 50–90ms/次调用。 - 截图走 GDI，输入走
SendInput；不执行 shell（无Invoke-Expression/cmd.exe等拼用户输入进脚本的路径）。 - 区域在 Node 侧
clampRegion()与 C# 侧均有像素上限，避免巨图拖垮 GDI。
安装与启用¶
在 DSH 内通过 plugin_manager 安装本地 bundle（路径换成你本机目录；资料未给出 dsh plugin add github:... 一类命令，勿自行拼接）：
plugin_manager install_bundle target=file:<你的路径>/dsh-gui-control
示例：
plugin_manager install_bundle target=file:D:/code/dsh-gui-control
装好后重启 DSH，会出现十个 desktop_* 工具与 gui-control skill。改代码后需重新 install_bundle 或覆盖 profile 下 node_modules/dsh-gui-control/（非软链）；仅改 helper/win-helper.ps1 时可杀掉 helper 进程，下次调用自动拉起新脚本。
配置项（package 默认）¶
| 项 | 默认 | 说明 |
|---|---|---|
helperPath |
包内 helper/win-helper.ps1 |
helper 脚本 |
powershell |
C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe |
PowerShell 可执行文件 |
timeoutMs |
60000 | 单条 helper 命令超时 |
环境变量 DSH_GUI_CONTROL_KEEP_DIR：设置后每张截图另存一份（调试用）。
典型用法与本地测试¶
脱离 DSH 时，可在插件目录用 Node 跑冒烟脚本（README 所列）：
node test/smoke.mjs # 工具注册 + info/截图/移动/批量
node test/input.mjs # 打开记事本, 聚焦, 打字(中文), 截图, 关闭
node test/click.mjs # 按截图坐标点击 + 长文本粘贴
node test/framing.mjs # act 步骤坐标跟随本次取景目标
node test/halt.mjs # 真按急停热键，断言拦截与恢复
node test/halt-midflight.mjs # 打字中途急停，断言约 1.5s 内中断
在 DSH 会话里，模型应优先 desktop_a11y / desktop_ocr / desktop_find，再必要时 desktop_screenshot；Electron/Chromium 类应用控件树常只有少量节点，资料建议直接走 L1。游戏或自绘界面可优先 L2 找色。
适用场景与注意¶
适合：需要在 Windows 上让 DSH 模型操作本机 GUI、又不想单独维护 RPA 框架的开发者；强调 token 成本的读屏分级与类人输入的场景。
不适合或需人工介入：UAC / 安全桌面（截图黑、输入无效）、最小化窗口（需先还原）、锁屏、被其他窗口遮挡的「窗口区域截图」、目标窗口以管理员权限运行而当前用户权限不足时 SendInput 被拒绝。
插件以当前 DSH 进程用户权限运行，不会自行提权。安装前应阅读源码与 MIT 许可证，并理解 README「安全模型」：超时后 Node 放弃等待但 helper 内命令可能仍在跑；屏幕与 OCR 结果会进入模型服务商上下文。
结尾¶
dsh-gui-control 把 Windows 桌面的看与控封装成 DSH 工具，并用 L0–L4 读屏策略和全局急停控制自动化风险。若要进一步了解参数与边界，以仓库 README 为准。
- 社区目录：https://www.skillhub.cn/plugins/Macocin/dsh-gui-control
- GitHub：https://github.com/Macocin/dsh-gui-control
