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

> **[English](./README.md) | 中文**

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

- 工具 exe 独立仓库：**[uia-agent](https://github.com/cnyc6n/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 页面](https://github.com/cnyc6n/dsh-uia-agent/releases)** 有**两个自包含脚本**，下载**任一个**即可（互不依赖）：

- **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 安装

```powershell
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 校验）

## 手动安装

```powershell
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 构建）

## 开发/自测

```powershell
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）。