dsh-uia-agent — DeepSeek Harness 的 Windows UI 自动化插件

English | 中文

dsh 插件：注册一个 uia 工具，让模型能枚举窗口、快照 UI 树、查找控件、点击、输入文本、滚动/拖动/滑动、截图、控制窗口状态（置顶/最小化/最大化/恢复/关闭）。

• 工具 exe 独立仓库：uia-agent（C++17/MSVC 单 exe，release 含 uia_agent.exe）
• 本插件自带 exe 的 base64 内嵌资产（assets/uia_agent.exe.b64），启动时自动释放到固定位置 %DSH_HOME%\bin\uia_agent.exe；释放失败会 console.error 并在工具调用时提示补上。

一键安装（新手）

仓库根目录或 v1.0 release 页面 有两个自包含脚本，下载任一个即可（互不依赖）：

• install.cmd — Windows 上双击运行
• install.ps1 — powershell -ExecutionPolicy Bypass -File install.ps1

脚本会自动：检测 dsh → dsh plugin --profile web add github:cnyc6n/dsh-uia-agent → 提示重启。 无需编译、无需下载 exe：插件包内嵌 base64，首次启动自动释放并校验哈希。

npm 安装

npm i -g dsh-uia-agent
# 然后让 dsh 的 profile 指向它（或按下文一键安装用 github: 源）

已发布版本：1.1.0（latest）、1.0.0（legacy 标签）。

更新日志

1.2.1

• desktop 增加 --limit（返回图标上限；0=全部）和 --name（子串过滤）——不再截断，能看到每个图标

1.2.0

• 新增 desktop 命令：自动定位桌面图标宿主（Progman + WorkerW 双布局）并列出全部图标（含屏幕坐标）
• 新增全局 timeout 参数：所有命令都可传 timeout（毫秒），转发给 exe
• 修复：FindDesktopIconHost 只查 WorkerW（漏掉 Progman 布局）

1.1.0（最新）

• 新增 geometry / props 命令（窗口几何读写；控件属性）
• drag 支持 steps / hold_ms 精细控制
• 新增 send_keys / clipboard / wait_for / foreach 命令
• snapshot 把控件树内联进模型文本
• screenshot 返回保存的文件路径（模型自行决定如何查看）
• 权限模型：命令档位 ≤ 当前会话权限时直接执行
• 修复：raw 输出恒为对象、get_text 缺字段容错

1.0.0

• 首个独立发布：list / snapshot / snapshot_all / find / click / set_text / get_text / scroll / drag / swipe / screenshot / 窗口状态（置顶/最大化/最小化/恢复/关闭）
• 权限分档 + 审批提权、内嵌 exe 自释放（sha256 校验）

手动安装

dsh plugin --profile web add github:cnyc6n/dsh-uia-agent

安装后重启 dsh，uia 工具即进入模型工具集。exe 由插件启动时自释放（无需手动构建）。

权限分档与提权

与 dsh sandbox 档位对齐（参考 pwsh 工具的 sandbox_permissions + justification + ctx.approval 机制）：

| 档位 | sandbox_permissions | 命令 | | --- | --- | --- | | read-only | 无（直接执行） | list / snapshot / snapshot_all / find / get_text / screenshot | | workspace-write | workspace-write | minimize / maximize / restore / topmost / close | | danger-full-access | danger-full-access | click / set_text / scroll / drag / swipe / send_keys / foreach |

高档位命令执行前必须先带 sandbox_permissions + justification，经用户审批（approveEscalation）通过后才真正执行；未带或档位不匹配会直接报错，引导模型携带正确权限重试。

工具 uia 参数

command（枚举 20 个动作）、hwnd、depth、query（find 条件 JSON）、text、keys、set、timeout_ms、interval_ms、cmd、args、mode、x/y/x1/y1/x2/y2、duration、amount、direction、distance、out、base64、off，以及提权参数 sandbox_permissions / justification。

模型调用后收到一行摘要文本；结构化原始结果经 presentationMeta 持久化。

测试环境

• @deepseek-ai/dsh-tools 0.1.5-rc.3（宿主依赖经 $DSH_HOME/profiles/node_modules fallback 解析）
• Node.js 24（dsh 要求 22+）
• Windows 10 x64 + MSVC 2022（exe 构建）

开发/自测

node smoke.mjs                     # 无 LLM 冒烟（模块加载 + 工具定义 + apply 注册）
powershell -ExecutionPolicy Bypass -File scripts/install.ps1   # 手动释放 exe

已知限制

• 自绘 UI / 游戏 / DirectX / 默认 Qt 拍不到 UIA 树（snapshot 返回 unsupported；可用 screenshot + 图像识别兜底）。
• 管理员窗口需 exe 以管理员运行，否则 UIPI 拦截。
• Chromium/Electron 默认关闭 accessibility，首次访问可能为空。
• UIA 调用可能挂起：exe 内置 5s 超时，工具 spawn 超时 15s。
• PrintWindow 对个别 DRM/自绘窗口可能黑屏（capture_failed）。