Gui Agent

---
name: gui-agent
description: 用 gui-agent-example 插件操作 Windows 桌面程序,纯视觉为主:list 挑窗→focus→截图看,看不清就 region 裁局部放大;UIA 快照是结构捷径。凡要"点某软件某按钮/往某窗口填字"的桌面任务,先读这份。
---

# GUI Agent 操作纪律(纯视觉)

桌面程序长什么样,截图说了算。**你主要靠眼睛**:截图看画面,看不清就
裁局部放大,定位到坐标才动手。UIA 快照(gui_snapshot)是抄近道的手艺,
放在最后学——先学看,再学抄近道。

纪律一条:**先看一眼,动一下,再看一眼**。盲点两下,是死罪。

## 开工三步

1. 先调 `gui_status`:确认平台是 win32、
   DPI 感知不是 unaware、dry-run 是开是关。dry-run 开着就明说:本次
   任务只校验不真点,请用户决定是否关掉再跑。
2. 再 `gui_list_windows`(可带 `title_filter`)找到目标窗口,记下
   `window_id` 与 `rect`。窗口 id 只在本次桌面现场有效,不写进长期
   记忆当永久凭据。**刚 run_command 起的程序,窗口可能要几秒才成**:
   首查扑空别下结论,隔两秒重查,最多五次。
3. `gui_focus_window` 聚焦,然后 `gui_screenshot` 截图看画面。协议 v2
   起图随结果回喂——**你已经看见图**,直接描述画面、据图决策。

定位到坐标后,`gui_click` / `gui_type_text` 照旧带 `expected_window_rect`
(observation 里的 `window_rect` 原样填)防窗口挪动,挪了工具会拒
(stale_observation),这是保护,不是故障。

## 看不清就放大:region 裁局部

- 全图是认布局用的:长边超 1568 自动降采样省 token,布局够看,
  **小字会糊**。图上像素不再 1:1 对应 virtual_screen——回执里有
  `image_pixel_scale`,要换算先乘它。
- 字太小、图标太密、看不清按钮文字?带 `region` 再截一张:
  `region=[x,y,w,h]`,virtual_screen 口径(与快照 rect、点击坐标同一
  世界;target=window 时原点是 observation 的 `client_origin`)。
- 裁切局部**不走 1568 帽**:原像素直出,不插值不缩放——裁切即无损
  放大。回执带区域在全图的位置(`region_in_image`)与换算式:
  图中像素 (px,py) = virtual_screen (region_x+px, region_y+py)。
  在局部图里看清了目标,照这个式子算出精确点击坐标。
- 越界(裁出窗外/屏外)与空区(零宽高)都会明拒,拒了就先整幅截图
  对着布局重算 region,别瞎试。

## 桌面常识

Windows 桌面有些东西**不动鼠标就不出现**。每条都是"先做动作,再截图
确认"的路数:

- **任务栏可能自动隐藏**:屏幕底部空空的不等于没有任务栏。先把鼠标
  移到底缘(`gui_move_mouse` 到 y=虚拟屏底-1,移过去停半秒就是
  hover,下一次截图前它自己会唤出),再截底缘一条
  (`target=screen` + `region` 裁底部横条,原像素看得清图标)。
- **系统托盘溢出藏在 ^ 箭头后**:任务栏右下角若见 ^,先点它展开
  隐藏图标,再截图确认全列。
- **开始菜单/搜索在左下**:要点它们,先点或按 Win 键唤出,再截图
  看菜单开了没、条目在哪。
- **切窗口用 Alt-Tab 或点任务栏**:目标窗口不在前台,别对着旧图硬
  点——先切过去,重新截图。
- **UAC 提权弹窗永远置顶挡视线**:屏幕忽然变暗、出现"是否允许此应用
  更改设备"就停下——那在 secure desktop 上,本插件拍不到也点不进,
  请用户自己按。
- **浏览器页签栏在窗口顶部**:页签多了会截断显示,截图里看不见的
  页签不是没开——点页签栏的 ‹ › 溢出箭头,再截一张数全。
- 下结论"界面上没有 X"之前,先问自己:它在不在被折叠的地方
  (下拉、溢出菜单、自动隐藏条、要滚动的列表)?

## 捷径:结构路(gui_snapshot,后学)

前两节是正路。这条是抄近道——**Native 控件密集、控件名字明确的场景**
(标准 Win32/WPF 窗体)才值得走:

- `gui_snapshot` 把 UIA 控件树文本化,每行 `ref | 类型 | Name | rect`。
  快照是文本,比截图省 token 一个量级,坐标直接给到手上;动作取 rect
  中心。树被截断就用更小的 `depth` 收窄重拍。
- ref 只在本份快照内有效(快照重拍即换号);跨调用引用 rect 时带
  `expected_window_rect` 防过期。
- **自绘/Web/游戏/Electron 部分界面,UIA 看不见**:快照收 0 项或找不到
  目标,别反复重拍——这是结构路的盲区,回视觉路(截图→看→点)。
  tkinter 类自绘程序也多半这样。
- 有名无名有讲究:交互控件(按钮/输入/勾选/下拉/页签/列表项/菜单项)
  无名也收;文本与容器要带 Name 才收。快照里没看见的控件,就是 UIA
  看不见,不是不存在。

### 结构路动作:先 set_value/invoke,坐标与 typing 降为后备

快照行尾的短标是可选路牌:**[value] 支持整替值,[invoke] 支持结构路
"点击",[expand] 支持开合**。与"先结构后视觉"同一条纪律——有标就走
结构路,别回头硬点坐标:

- **填表单/清空重填 → `gui_set_value`**(按 ref 整体替换值)。比
  `gui_type_text` 可靠:不经键盘、不抢焦点、不怕输入法截胡,控件在
  后台、被遮挡也照写。要先点进去再逐字敲的,那是没带 [value] 标的
  控件(自绘居多)——工具会明报并指路 typing,别硬试。
- **点按钮/链接/菜单项 → `gui_invoke`**(action=invoke)。等价于点击,
  但不挪鼠标:控件挪了位、被浮层盖住、窗口不在前台,都不碍事。
- **下拉/树形/菜单开合 → `gui_invoke`**(action=expand/collapse)。
  硬点坐标开下拉是下策——点偏一格就点到别处;expand 结构路开,
  开完重新快照拿新出现的列表项。
- depth 要与出 ref 那份快照一致(默认 8 同),不然序号数错位,可能
  指到别的控件——回执里回显控件名与类型,对不上就重拍快照再来。
- 结构路动作也只报事实("已替换/已触发"),界面真变了没有,下一步
  快照或截图说了算。同一动作失败两次就停手,别换着花样硬闯。

## 动作

- **一次只做一项动作**,做完立刻重新观察(截图)再决定下一步。
  不许连点五下不看一眼。
- 坐标以最近一次截图/快照与元数据为准,不凭上一轮记忆猜;降采样过
  的全图要乘 `image_pixel_scale`,局部图按 `region` 原点直加。
- `gui_click` 只报告"点击已发送",不代表按钮生效。生效与否,下一步
  截图说了算。
- `gui_type_text` 输中文没问题(Unicode 直注);但密码、验证码、OTP
  一律不得经工具输入——遇到密码框就停下,请用户自己填。
- `gui_key` 只用枚举键名。Win 组合与 Alt+F4 默认被拦,别绕。

## 停手与复验

- 见"提交/删除/付款/发送/上传"字样,先停下向用户确认,得到明确
  同意才点。
- 见 `stale_observation`、`window_not_found`、`focus_failed`:
  不是重试同一份旧参数,而是重新 `gui_list_windows` → 截图,从新现场
  重新走。
- 同一动作失败两次,停下来向用户报告现象,不要换着花样硬闯。

## 收工

向用户报清:每一步做了什么动作、哪几步经过截图复验、哪些结果
**没有**复验过。没复验的不说成功。