dsh-guikit

dsh plugin --profile web add dsh-guikit

dsh-guikit · DSH GUI Toolkit

Windows 桌面控制工具集，给 DeepSeek Harness（DSH）的 agent 装上眼睛和手：看屏幕、单窗口截图、点鼠标、拖动、打字、按快捷键、滚动、等生效、验证生效、管窗口，并能对标准控件做 Windows UI Automation 结构化定位，以及按元素名直接定位到可点击坐标（gui_locate）。

Windows desktop-control toolset for DeepSeek Harness (DSH): monitor layout, whole-screen and single-window capture, click / drag / type / key / scroll, pixel / window / semantic verification, window management, UI Automation structured queries, and element-name lookup. Thirteen model tools, zero external dependencies — no resident service, no Python, no API key.

• 平台：Windows 10/11（不跨平台）
• 依赖：PowerShell 7（pwsh）+ .NET 的 System.Drawing / UIAutomationClient，都是系统自带
• 形态：DSH profile bundle（host 侧注册 13 个模型工具）

安装

# 1. 进 DSH profile 目录（例如 ~/.dsh/profiles/web）
cd <DSH profile 目录>
pnpm add dsh-guikit

# 2. 在该目录的 package.json 里把 bundle 挂上
#    "dsh": { "profile": { "bundles": [ ..., "dsh-guikit" ] } }

# 3. 重启 dsh web

本地开发用 link: 也行：

"dependencies": { "dsh-guikit": "link:<你 clone 下来的目录>" }

⚠️ link 方式下裸导入从源位置向上解析，够不到 profile 的 node_modules——需要在插件目录自己跑一次 pnpm install 装 peer 依赖（@deepseek-ai/cordis、@deepseek-ai/dsh-tools）。从 npm 安装没有这个问题。

工具（13）

工具 · 参数 · 用途

gui_screen · — · 显示器布局 + 坐标契约：每块屏的 physical_rect{x,y,w,h} / logical_rect / dpi_scale / is_primary / display_id，顶层 virtual_desktop_origin{x,y} 与 space:"virtual-desktop-physical"。dpi_scale 按屏取（MonitorFromPoint + GetDpiForMonitor），取不到时是 null——不假装 1.0（logical_rect 同时为 null）。旧的 x/y/w/h/primary/device 与 virtual/cursor 全部保留。任何坐标操作之前先调它

gui_screenshot · screen / x,y,w,h / annotate / step · 截屏存 PNG 并返回路径（用 read_image 看）。回执带 space:"virtual-desktop-physical" / origin{x,y} / image_px{w,h} / scale / note。annotate=true 画顶部+左侧标尺、对齐网格交点的坐标标签和左下角水印（水印内容即 origin/space/scale/region/step）——别按图上像素距离量坐标，读标签文本

gui_window_shot · window / handle / annotate / step · 单窗口截图：PrintWindow 抓窗口自己的内容，被别的窗口盖住也照样抓，不激活、不移动。回执带 space:"window-local" / origin{x,y}（= 旧的 x/y，两个名字都在）/ scale / image_px；annotate 同样画标尺与左下角水印，标尺标签用绝对屏幕坐标。比整屏省一个数量级（实测 DSH 窗口 298 KB vs 整屏 8.8 MB）

gui_locate · name(必填) / window（title 是等价别名） / elType / index / depth / max / timeoutMs · 元素名 → 可点击坐标。在目标窗口（window 标题子串或 handle，不给就用前台窗口兜底）按 name（可选 elType / index）用 UIA 定位，返回可直接喂 gui_click 的虚拟桌面物理像素 point{x,y}（元素矩形中心）+ rect + type + enabled + offscreen + uiaPath（祖先链数组，最多 6 层）+ total/matched/depth_reached + space/origin/scale。七个状态里只有 status="found" 会给顶层 point（绝不返回猜测坐标）：ambiguous 回 candidates[] 前 5 个候选（各带 rect/point/offscreen；离屏候选的 point 为 null），offscreen / not-found / not-exposed / inconclusive / truncated 一律不给 point。timeoutMs 给了就反复重走直到元素出现（250 ms 间隔；默认 0 = 单次）；index 越界 → 明确 error 并附 validIndex（不静默回落 0）。见「UIA 五态」一节

gui_click · x y (必填) / button / clicks / window / space / verify · 真实光标移到物理像素并点击。1/2/3 = 单/双/三击。window 是 per-call 目标（标题子串或 handle，不再只认当前前台）；space="window-local" 时（必须给 window）入参按 gui_window_shot 的图内像素解释，换算在 pwsh 里做。回执新增 space / origin / scale / requested / absolute / insideWindow / target（旧 x/y/result/fgTitle/fgHandle 保留）。verify 可选：点完在同一进程内立刻跑一次 gui_verify 等价断言，结果并进 verify:{verdict,detail,observed,tries,streak}，默认关；delivery.verified 只在 verdict=satisfied 时为 true

gui_drag · fromX fromY toX toY (必填) / button / steps / stepDelayMs / window / space · 按住拖动：选文字、拖标题栏、拉滑块/滚动条、拖放。移动是插值的（只 SetCursorPos 不产生拖拽事件）。steps 调大更稳更慢。无论成败都保证松开按键。window/space 语义与 gui_click 一致（四个坐标一起换算），回执同样回带 space/origin/scale/insideWindow，requested/absolute 是 {from,to} 两点，insideWindow 要求起点与终点都在窗口内

gui_type · text (必填) / mode / x y · 向当前焦点控件打字。unicode（默认）逐字符 SendInput，绕过 IME，中文无损；clipboard 走剪贴板 Ctrl+V（会覆盖用户剪贴板）。可选先点击 (x,y) 定位焦点

gui_key · keys (必填) · 真实键盘按键或组合键：enter、ctrl+s、alt+f4、ctrl+shift+tab、win、printscreen。修饰键 ctrl/alt/shift/win，f1–f24，a–z，0–9，方向键等

gui_scroll · x y (必填) / direction / notches · 在 (x,y) 处滚轮。up/down 纵滚，left/right 横滚，默认 3 格

gui_window · action (必填)：list/rect/activate/move · 窗口管理：列出可见窗口（标题/句柄/pid/进程/矩形/z 序）、取单个窗口 bounds、激活到前台、移动改尺寸

gui_wait · mode (必填)：pixel/window · 轮询验证。pixel 盯某个像素：compare=change 与调用时基线比变化，eq/neq 比指定 RGB；window 等某个标题的顶层窗口出现。点完先等生效再截图

gui_verify · mode (必填)：element/window + title/handle/name/elType/enabled/valueEquals/boundsX..H/tolerancePx/timeoutMs/stableSamples · 语义验证：断言一个 UIA 元素存在（可选再要求可用 / 值相等），或断言某窗口存在（可选再比对 bounds）。连续 stableSamples 次都成立才算数，否则轮询到超时。返回三态 satisfied / unsatisfied / unknown——unknown 是「判不出来」，绝不可当成功读。缺席不可证明，所以 exists:false 会被拒。0.6.0 起与 gui_uia 遍历器同源（RawView + depth 40），Chromium a11y 也够得到——同一断言前后对照：unknown(5201 ms/tries=6) → satisfied(140 ms/tries=1)。输入类工具之后跟一次它，才算拿到结论

gui_uia · action (必填)：tree/find/invoke/value + handle/title/name/elType / depth (默认 40，硬顶 40) / max (默认 2000，硬顶 8000；遍历预算) / maxRows (默认 120，硬顶 2000；返回预算) · Windows UI Automation 结构化查询，一次限定一个窗口。0.6.0 改走 RawViewWalker 并把 depth 提到 40（两个机制叠加，见「UIA 五态」一节）。回带 total/matched/truncated/rows_truncated/depth_reached/walker。返回五态 status（见「UIA 五态」一节；只有 empty-but-accessible 能读成「确实没有」）。invoke 经 InvokePattern（回退 TogglePattern）直按按钮，不用坐标；value 经 ValuePattern 直读控件文本。返回的 type 是短名（Button，不再是 ControlType.Button）；矩形是物理像素，可直接喂 gui_click

坐标系契约

三套空间同时存在，工具之间不互相猜：每一步都把空间名与换算所需的数回带出来。

                 虚拟桌面（本机 5360×1750，origin (0,-278)）
   ┌─────────────────────────────────────────────────────────────┐ y=-278
   │  副屏 DISPLAY1 2800×1750 @200%        ┌───────

…(truncated)