前言¶
DeepSeek Harness (DSH) 的 agent 在处理桌面应用任务时，需要具备“看”和“做”的能力。现有的 DSH profile 可能缺乏针对 Windows 桌面的具体交互手段。sage-guikit 是一个专为 DSH 设计的 GUI 工具包，它将 Windows 桌面控制能力打包成 profile bundle，为 agent 提供屏幕布局监控、截图、鼠标/键盘操作、窗口管理以及基于 UI Automation 的结构化查询与验证功能。
核心功能¶
该插件提供 13 个模型工具，核心能力包括：
- 屏幕与截图：获取显示器布局契约，支持全屏及单窗口截图，并附带坐标标注功能。
- 交互操作：支持点击、拖拽、打字、按键及滚动。
- 窗口管理：列出窗口、获取/激活/移动窗口。
- 定位与验证：通过元素名或 UIA 树定位控件，支持轮询验证和语义验证。
安装与启用¶
安装该插件需要手动操作，将其作为 DSH profile bundle 引入。
- 进入 DSH profile 目录（例如
~/.dsh/profiles/web）。 - 执行安装命令：
pnpm add dsh-guikit
- 编辑该目录下的
package.json，在dsh.profile.bundles数组中添加"dsh-guikit"。 - 重启 DSH Web 服务。
本地开发时也可使用 link: 方式，但需注意裸导入可能无法解析到 profile 的 node_modules，此时需在插件目录自行安装 peer 依赖（@deepseek-ai/cordis、@deepseek-ai/dsh-tools）。
工具概览¶
插件注册了以下模型工具：
屏幕与截图¶
gui_screen: 获取显示器布局、虚拟桌面原点、DPI 缩放等信息。任何坐标操作前应先调用此工具。gui_screenshot: 截取全屏或指定区域，返回图片路径。开启annotate后会绘制标尺、网格坐标标签和左下角水印。gui_window_shot: 单窗口截图（PrintWindow），不激活窗口，不遮挡。返回window-local空间坐标。
交互操作¶
gui_click: 在指定坐标点击。支持window参数和space参数（window-local）。可选verify参数进行点击后验证。gui_drag: 模拟按住鼠标拖动，用于选文字、拖动滑块等。gui_type: 向焦点控件打字，支持unicode（绕过 IME）和clipboard模式。gui_key: 发送系统按键或组合键（如ctrl+s）。gui_scroll: 在指定位置滚动滚轮。
定位与管理¶
gui_locate: 通过元素名或窗口标题定位。不猜测坐标，仅在status="found"时返回可点击坐标。支持timeoutMs轮询。gui_uia: 使用 Windows UI Automation 结构化查询，支持tree、find、invoke、value等操作。gui_window: 窗口管理，支持list、rect、activate、move操作。
验证¶
gui_wait: 轮询验证，支持像素变化对比或窗口出现等待。gui_verify: 语义验证，断言元素是否存在或属性是否满足条件。返回三态结果（satisfied/unsatisfied/unknown）。
坐标系统与契约¶
插件定义了三套空间，工具之间不互相猜测，必须严格遵循返回的契约进行换算：
| 空间名称 | 用途 | 原点 |
|---|---|---|
| virtual-desktop-physical | gui_click / gui_drag 入参；gui_screen / gui_locate 返回值 |
虚拟桌面左上 |
| image-pixels (截图) | read_image 读取的图像像素 |
截取区域左上 |
| window-local | gui_window_shot 返回值；gui_click 的 space="window-local" 入参 |
窗口左上 |
换算逻辑：
* 图内像素 → 桌面坐标：绝对 = origin + 图内像素 × scale
* 桌面坐标 → 图内像素：图内 = (绝对 − origin) ÷ scale
注意事项：read_image 返回的图像通常经过了降采样（如 ×1.50），图素间距不可信。请务必使用 annotate=true 生成的图片中的标签文本读取坐标，而非手动计算。
注意事项¶
- 平台限制：仅支持 Windows 10/11。
- 依赖环境：依赖 PowerShell 7 和 .NET 的
System.Drawing/UIAutomationClient。 - 权限与安全：工具在当前 DSH 进程权限下运行，调用前应检查源码与许可证。
- 验证结果：
gui_verify返回unknown并不表示成功，表示“判不出来”，绝不可作为成功读数。
结语¶
sage-guikit 通过提供结构化的 UI Automation 查询和明确的坐标契约，解决了 DSH agent 在 Windows 桌面自动化中定位不准、验证困难的问题。安装后，agent 即可获得完整的“眼手”能力。更多细节可参考其 GitHub 仓库：gezi-wen/sage-guikit。
