前言¶

在 DSH（DeepSeek Harness）里让智能体操作 Windows 桌面，常见路径是：截图或 OCR 得到坐标，再调用点击、输入。日志里往往显示「已点击」，界面却毫无反应。问题未必出在模型或控件识别，而是窗口被最小化、不在前台、DPI 缩放导致物理像素与逻辑像素混用，以及「激活窗口」与「发送按键」挤在同一次调用里导致首字符被吞。这些与具体应用无关，是 Windows API 使用方式上的固有坑。

若每次都让 agent 或开发者自行处理还原、置前、坐标换算和分步输入，成本高且容易漏。dsh-gui-guard（仓库 7gzgn/dsh-gui-guard）把上述步骤收进一次原子调用，作为 DSH 用的 Windows 窗口操作可靠性层：零依赖、纯本地、不联网。下面介绍它做什么、怎么用，以及和同类能力如何配合。

这是什么¶

维护者 7gzgn，在 SkillHub 社区目录中归类为工作流插件。一句话定位：在按坐标点击、往窗口里打字之前，先确认窗口当前能否被可靠操作，并在点击与输入时处理好激活顺序与坐标空间。

插件底层依赖 user32.dll，仅支持 Windows；需要系统能 spawn powershell.exe（有 pwsh 时会优先使用）。Node 侧要求 >=18。许可证为 MIT；package 版本为 v0.1.1（与目录页一致）。

声明的 DSH 兼容范围为 >=0.2.0-rc.2 <0.3.0-0，覆盖整个 0.2 线。运行时若拿不到 @deepseek-ai/dsh-tools 的 defineTool 会退化；ctx.systemPrompt 不存在则跳过公告段，避免把整个宿主拖崩。

核心功能¶

README 将能力归纳为五类动作，通过统一工具 gui_guard 调用：

设计上的几个要点（均来自仓库说明）：

• 坐标口径必须显式：默认 space: "physical"（对齐截图/OCR）；若坐标来自 GetWindowRect，应传 space: "logical"。
• 响应会报「做了什么」：例如 click 会回显请求坐标、实际落点、光标是否匹配、点击前是否前台等，便于排查。
• 不提供 OCR 或元素定位；Flutter / Electron / Qt 等自绘界面若 UIA 抓不到控件，本插件只能保证点在给定坐标上，不能保证控件响应。
• 后端为纯 ASCII 的 PowerShell 脚本；Node 与 PowerShell 之间只走 base64 JSON，避免命令行 JSON 引号转义问题。
• 每次调用会起一个 PowerShell 进程，单次约几百毫秒，侧重「点得准」而非「点得快」。

与 dsh-computer-use-win 的关系：后者提供 UIA、截图、OCR、窗口管理、键鼠等原始能力；本插件负责可靠性。推荐流程是先用 dsh-computer-use-win 拿到坐标，再用 gui_guard 落点。

安装与启用¶

SkillHub 目录页（7gzgn/dsh-gui-guard）标注插件可安装、当前 v0.1.1。在 DSH 生态里插件通常从社区目录或仓库接入；本文所依据的 README 与 package.json 未给出固定的 dsh plugin add … 单行命令，安装前请在目录页或 GitHub README 查看与你当前 DSH 版本一致的说明。

启用后，智能体可通过 Cordis 注册的 gui_guard 工具调用上述动作。插件以当前 DSH 进程权限运行，安装前请自行审阅源码与 MIT 许可证，确认符合你的安全策略。

典型用法¶

先对目标窗口做体检，确认最小化、前台与 DPI 状态。窗口标题示例为「记事本」（按你本机实际标题替换）：

gui_guard({ action: "probe", window: "记事本" })

probe 返回 JSON 示例结构如下（字段含义见 README）：

{
  "ok": true,
  "minimized": false,
  "foreground": true,
  "rect": { "left": -7, "top": -7, "width": 1721, "height": 1033 },
  "dpi": { "window": 144, "scale": 1.5 },
  "screen": { "logicalWidth": 1707, "physicalWidth": 2560 },
  "notes": ["DPI scaling is active (150%): screenshot/OCR tools report PHYSICAL pixels …"]
}

在确认窗口可操作后，用物理像素坐标做安全点击（与截图/OCR 口径一致）：

gui_guard({ action: "click", window: "记事本", x: 1412, y: 1 })

注意响应里的 requested 与 applied：你提交的是物理像素，实际落点为逻辑像素；换算由工具完成，两套值都会返回。若窗口此前不在前台，第一次点击可能只用于激活；README 提示若控件无反应，可在相同坐标再点一次：

{
  "ok": true,
  "requested": { "x": 1412, "y": 1, "space": "physical" },
  "applied":   { "x": 941,  "y": 0, "space": "logical", "scale": 1.5 },
  "cursorMatches": true,
  "wasForeground": false,
  "note": "Window was not foreground: this click first activated it. If the target control did not react, click once more at the same coordinates."
}

需要列出带窗进程或预先 prepare 窗口时，将 action 设为 list、prepare 或 type，并传入 README 中对应的 window 及其它参数即可。

适用场景与注意¶

适合谁：在 Windows 上跑 DSH、已用或计划用 dsh-computer-use-win 等拿到坐标，但希望把最小化/前台/DPI/输入时序等共性坑交给一层工具处理的开发者或工作流作者。

不适合替代：跨平台桌面自动化、纯 UIA 控件树操作、或需要高频连点（每次数百毫秒进程开销）的场景。

权限与安全：工具可还原、激活窗口并发送点击与按键，行为与运行 DSH 的用户会话一致。社区目录 SkillHub 为独立站点，与 DeepSeek / 幻方无官方从属关系；插件来源以 GitHub 仓库 7gzgn/dsh-gui-guard 为准。

结尾¶

dsh-gui-guard 不解决「坐标从哪来」，而是解决「坐标有了之后怎么点准、怎么输得稳」。若你的工作流里 agent 反复出现「点了没反应」，可先 probe 再 click/type，并对照返回的物理/逻辑坐标与前台状态排查。

• 社区目录：https://www.skillhub.cn/plugins/7gzgn/dsh-gui-guard
• 源码与文档：https://github.com/7gzgn/dsh-gui-guard