Desktop App Automation

---
name: "desktop-app-automation"
description: "Use when assessing agent control of desktop apps."
priority: 0.5
imported-from: "hermes"
source-path: "hermes/skills/software-development/desktop-app-automation/SKILL.md"
---
# 让 agent 操作桌面软件：能力分层与选型

触发场景：用户问“agent 能不能连本机所有软件并控制它”“能不能帮我操作微信/浏览器/某 IDE”“能不能给产品加自动操作外部软件的能力”。
答案永远不是“能/不能”，而是**分层** —— 先分层，再选实现。

| 层 | 机制 | 覆盖 | 稳定性 |
|---|---|---|---|
| ① 官方 API / CLI | 软件自己的接口 | 有接口的 | ★★★★★ 可重复、可测、可审计 |
| ② 数据层 | 直读改它的配置/数据库 | 大多数桌面软件 | ★★★★ 有效，但绕过它的校验逻辑 |
| ③ 进程/系统层 | 启动/结束进程、窗口句柄、剪贴板、注册表、键鼠注入 | 几乎全部 | ★★★ 能做，但脆 |
| ④ 无障碍层（Windows UIAutomation / macOS AXAPI / Linux AT-SPI） | 按**控件**定位（“那个按钮”而非“那个坐标”） | Win32 / WPF / Qt / Electron / 浏览器 | ★★★★ 比坐标稳一个数量级 |
| ⑤ 纯视觉 + 坐标 | 截图 → 识图 → 点 (x,y) | 理论任何画面 | ★★ 最通用也最脆 |

## Procedure

1. **先查 harness 原生能力**：若已有桌面驱动类工具（cua 风格：`list_apps` / `list_windows` / `screenshot` / `click` / `type` / `key` / `set_value`，常带后台投递 + 逐动作审批），先 `tool_describe` 看清 schema 再断言能做/不能做 —— 不要凭印象说“不行”。
2. **跑只读探测**：`powershell -NoProfile -File scripts/uia_probe.ps1 [窗口名/类名关键字]`。判据：目标窗口列出来了且 `controls>0` → ④ 层可用；列不出或控件数 0 → 该软件退回 ① 或 ⑤。
3. **选实现**：① > ② > ④ > ③ > ⑤。**能 CLI 就别点界面。**
4. **设计授权**：软件白名单 + 动作分级 + 危险动作人工确认 + 全程日志（可回放）。
5. **验证**：每步留「意图 → 动作 → 结果截图」；不可逆动作前先确认当前状态。

## 铁律

- **a11y 优先于坐标**：坐标随分辨率/主题/语言/DPI 缩放而失效，控件定位不会。
- **一软件一接口**（一个 MCP server 或一个 skill），不要“万能 agent” —— 权限可单点审计、坏一个不塌全局。
- **危险动作**（支付/删除/发送/发布/覆盖）**必须人工确认**，不因“这个软件已授权”而豁免。
- **提示注入会升级为真实动作** —— 这是按**动作**分级授权（而非按软件）的最强理由。
- **默认后台投递**（不抢用户焦点、不移动用户光标），前台仅在必要时。
- 只读枚举不算“操作”；一旦触发 Invoke/输入，就进入审批语义。

## 硬边界（决定“能不能”，不是调优问题）

- **Windows UIPI**：普通完整性级别进程不能给更高完整性级别的窗口发输入 → UAC 提权后的软件点不动。**安全桌面**（UAC 弹窗、登录界面、Ctrl+Alt+Del）对普通进程不可注入（设计如此）。
- **反注入/反作弊软件**（游戏、银行客户端、部分安全软件）会拒绝或被检测。
- **跨会话不可达**：别的用户、RDP 会话、WSL、VM 内的窗口不在当前桌面会话里，需要各自通道。
- **macOS**：需“辅助功能”+“屏幕录制”授权；未授权时 API 静默失败/返回空。
- **Linux**：X11 一般可用；Wayland 下多数注入被 compositor 拒绝。

## Pitfalls

- 把“能枚举”当“能操作”：先确认的是可枚举性，动作是下一步。
- 用坐标点击做**验证**：验证应当走 DOM / CLI / 结构化输出，坐标只留给没有其它通道的软件。
- 没跑探测就说“agent 不能控制 X” —— 这是未证实的负面断言。
- git-bash 里中文窗口名可能显示为乱码（终端解码问题，不是探测失败）：用 ClassName / pid 判断，或让 PowerShell 写 UTF-8 文件再读。
- 把“全开”当目标：真正的交付形态是**按软件逐个接 + 按动作分级授权**。

## 支持文件

- `scripts/uia_probe.ps1` —— 只读探测：枚举顶层窗口与其控件数（不调用任何 Invoke 模式）。