前言¶
在 DeepSeek Harness 里接桌面能力，常见路径是截图后让模型猜坐标、一步一步点。每步都要回模型，链路长；点没点上往往只能再截一张图猜。若同一条流程要反复跑，成本更高，失败后的重试也缺少统一语义。
dsh-gui-control（维护者 seetown，npm 包名 dsh-gui-control，当前版本 0.1.3，MIT 许可证）面向 Windows：优先读无障碍树、按控件名操作，并支持声明式任务文件与投递判定。社区目录归类为工作流，见 SkillHub 目录页；源码与说明见 GitHub。DSH 生态是「一切皆插件」；社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。
这是什么¶
一句话：给 DeepSeek Harness 用的 Windows 桌面操控插件——不是单次「帮我点一下」，而是把一串动作写成任务文件，一次工具调用跑完，跑任务文件时模型可不参与循环。
平台与依赖（README 原文）：
- 仅 Windows（Win32 + UI Automation）
- Windows 10 1809+、PowerShell 5.1
- DeepSeek Harness 0.1.5-rc.2 ~ 0.2.x
- Node（package.json）：
^22.19.0 || >=24.0.0
和常见桌面 Agent 的差异¶
| 常见做法 | dsh-gui-control | |
|---|---|---|
| 感知 | 截图 → 模型猜坐标 | 无障碍树优先，按控件名定位；树不可用时才截图 |
| 一次任务的往返 | 每步一次模型调用 | 一次调用跑完整个任务文件 |
| 失败之后 | 不知道点没点上 | 投递判定：没发出去 / 可能发出去了 / 已验证 |
| 重复执行 | 每次重跑一遍 | 任务文件可复用，带条件等待与重试 |
README 中的演示方向包括：打开 B 站搜番并选集、通过 UI Automation Invoke 做「零像素位移」语义点击、在表格类场景用多步任务一次填完（文档示例为 17 步 / 0.9 秒 / 一次调用）。
核心功能：三个工具¶
插件向 Harness 暴露三个工具，分工如下。
| 工具 | 作用 |
|---|---|
gui_snapshot |
读窗口的无障碍树（文本），或带屏幕坐标刻度尺的截图 |
gui_act |
执行单个动作，带身份校验和投递判定 |
gui_task |
跑声明式任务文件：一次调用多步，带条件、重试、风险闸门 |
下面先读树，再按文本点控件，是 README 推荐的路径。
读记事本窗口的无障碍树：
gui_snapshot { window: "Notepad", mode: "tree" }
→ Butto 关闭标签页 / Docum 文本编辑器 / MenuI 文件 ...
按控件名点击（优先于坐标；可走 Invoke，鼠标可不动）：
gui_act { action: "click_text", window: "Notepad", text: "最大化" }
→ click ok via InvokePattern | verified: text appeared
投递语义¶
每个动作返回三选一，决定是否可安全重试：
| 判定 | 含义 | 能否重试 |
|---|---|---|
not_delivered |
什么都没发出去（派发前就被拒） | 安全可重试 |
delivered_unverified |
发出去了，效果未确认 | 不能盲目重放 |
delivered_verified |
发出去了，且后置条件验证通过 | 不宜盲目重放 |
文档指出，这一条直接影响「发消息 / 删文件 / 提交表单」等不可逆操作能否稳妥自动化；结果不明时绝不自动重试。
任务文件¶
任务用 JSON 描述步骤。示例（摘自 README）：
{
"name": "fill-sheet",
"steps": [
{ "do": "activate", "win": "工作簿1" },
{ "do": "type", "text": "项目" },
{ "do": "key", "key": "tab" },
{ "do": "type", "text": "金额" },
{ "do": "key", "key": "enter",
"until": { "op": "pathexists", "text": "C:\\out\\report.xlsx" }, "untilTimeout": 10 }
]
}
每步除 do 与动作参数外，还可带 until（轮询到条件成立才算过）、untilTimeout、retry、risk。
risk: "high"的步骤默认拒绝执行，须显式confirm: truedryRun: true只返回计划，不碰桌面
安装与启用¶
在已满足 Windows 与 Harness 版本的前提下，在 Harness 环境中执行官方安装命令：
dsh plugin add dsh-gui-control
也可按仓库路径安装（README 原文）：
dsh plugin add seetown/dsh-gui-control
装完不需要重启 Harness。首次调用会预热常驻进程（文档约 1 秒），之后动作为本机 loopback 往返；服务只监听 127.0.0.1:38471，不对外暴露。
性能与限制（README 实测与说明）¶
文档给出的部分耗时参考（环境以作者实测为准，非性能承诺）：
| 操作 | 耗时 |
|---|---|
| 单步动作（常驻进程） | 10.8 ms |
| 语义点击（UIA 树） | 26–34 ms |
| 紧凑树读取 | 86 ms，865 字符 |
| 7 步任务（含启动计算器） | 680 ms，一次调用 |
| WPS 填 2×3 表格 | 0.9 s，17 步 |
已知限制：
- 画布类应用（WPS 表格、游戏、自绘列表）常无完整无障碍树，只能截图 + OCR，准确率下降
- 网页任务目前基于截图；CDP 通道已实现但尚未接入工具
- Roadmap 含 Set-of-Marks 截图、CDP 网页选择器、任务库与意图路由、macOS / Linux 适配（均未在文中标明完成）
安全与适用注意¶
插件能操控本机真实鼠标键盘，以当前 DSH 进程权限运行。安装与启用前建议阅读 源码 与 MIT 许可证，仅在可信环境使用。
README 列出的安全措施包括：loopback 监听、密码字段输出 <redacted>、高风险步骤需显式确认、投递未验证时不自动重试。
适合：需要在 Windows 上把重复 GUI 流程交给 Harness、且希望少依赖坐标猜测与逐步模型调用的工作流场景。不适合：非 Windows、或强依赖无无障碍树画布且不能接受 OCR 降级的场景。
结尾¶
dsh-gui-control 把「看树 → 按名操作 → 判定是否投递成功 → 任务文件一次跑完」收成一套 DSH 工具面，定位是工作流型桌面控制而非单次救火。
- 目录页：https://www.skillhub.cn/plugins/seetown/dsh-gui-control
- GitHub：https://github.com/seetown/dsh-gui-control
