dsh-desktop-uia：基于 UI Automation 的 Windows 桌面控制插件

前言¶

DeepSeek Harness (DSH) 采用插件化架构，旨在通过配置文件管理工具生态。在开发需要控制桌面应用的智能体时，传统方案通常依赖截图识别或坐标猜测，这种方式不仅脆弱，且难以应对窗口布局变化。dsh-desktop-uia 插件通过 Windows UI Automation (UIA) 接口读取窗口的控制树，利用稳定的自动化 ID 驱动元素。它不依赖截图，所有写入操作需经批准，所有动作均可审计。

安装与启用¶

该插件通过 npm 发布，也可以直接下载编译好的包安装。安装前需确保环境满足要求。

安装命令¶

使用官方提供的安装命令添加插件：

dsh plugin --profile web add dsh-desktop-uia

环境要求¶

操作系统：仅支持 Windows 10 或 11 (x64)。
DSH 版本：需使用基于配置文件的安装方式，且已验证对 0.1.2‑rc.1 / 0.1.5‑rc.1 插件契约的兼容性。
依赖工具链：无需额外安装 .NET SDK、NuGet 或 MSVC。插件自带 Sidecar，安装脚本会使用系统自带的编译器进行构建。

手动安装（可选）¶

从 Releases 下载 zip 包，解压后双击 install.cmd 即可完成安装。安装脚本会将插件放入 DSH 配置文件的 node_modules 中。

核心功能¶

插件提供了一套 desktop_* 工具集，用于管理窗口、读取控制树、执行动作以及等待状态变化。根据功能性质，部分操作免费，部分操作需要批准。

窗口管理¶

desktop_windows：列出顶层窗口（包含句柄、PID、标题、状态等）并管理窗口。list 和 focus 操作免费，其他操作（最小化、最大化、移动、关闭等）需要批准。
desktop_launch：启动程序、文档或 URI（如 notepad 或 ms-settings:）。
desktop_wait：等待窗口出现、元素出现、值变化或元素消失，避免无效睡眠。

探索与检查¶

desktop_snapshot：读取窗口控制树。可通过 query 按名称、类型或自动化 ID 查找元素。默认为 auto 模式（有预算探测），也可选 all 或 none（最快）。
desktop_inspect：检查单个元素的详细信息，包括框架、类名、启用/聚焦状态、支持的模式（Patterns）以及当前值。

动作与输入¶

desktop_act：执行点击、右键、双击、悬停、聚焦、调用、设置值、选择、拖动等操作。所有此类操作需要批准。
desktop_input：输入 Unicode 文本（支持 CJK 字符）或发送键组合（如 ctrl+s）。
desktop_clipboard：读取或替换剪贴板文本。写入操作需要批准。

辅助能力¶

desktop_screenshot：捕获窗口或整个桌面为 PNG 图片。
desktop_clipboard：读取或替换剪贴板文本。

典型用法¶

以下命令展示了如何启动程序、查找元素并执行操作：

# 启动记事本
desktop_launch notepad

# 在当前窗口输入文本
desktop_input "Hello World"

# 查找名为 "Save" 的元素（快照）
desktop_snapshot query {name: "Save"}

# 点击 ID 为 el_12 的元素
desktop_act click el_12

# 等待名为 "Calculator" 的窗口出现
desktop_wait window "Calculator"

注意事项¶

权限与批准：由于插件以 DSH 进程权限运行，涉及修改 UI 的操作（如 desktop_act、desktop_input）和剪贴板写入均需批准。只有 desktop_windows 的 list 和 focus 是免费的。
性能限制：对于响应较慢的窗口（如 Chromium、Java 应用），插件会自动限制读取的节点数（maxNodes 300）和深度（maxDepth 5），以避免阻塞。
元素稳定性：元素 ID 基于 UIA 运行时 ID 生成。如果窗口重建，ID 会失效并报告 STALE_ELEMENT，需重新快照。
操作反馈：系统会检测并反馈“新窗口出现”、“慢提供者”以及“重复无操作点击”（连续两次相同操作后，第三次相同操作会被拒绝，提示检查元素状态）。

总结¶

dsh-desktop-uia 为 DSH 提供了基于 UIA 的稳定桌面控制能力，通过 ID 驱动替代了脆弱的坐标猜测，并配合批准机制保证了操作的安全性。它适合需要在 Windows 环境下构建自动化代理的场景。更多细节与源码可参考插件目录或GitHub 仓库。