basic-control · observe（带截图）

感知目标窗口的控件树，并可同时返回窗口截图。

能做什么

• 遍历指定窗口的 UIA 控件树，为每个控件分配临时引用 e1 / e2 / ...，供 click / type 直接使用
• 支持 from_ref 从已有引用的子树往下深挖，避免每次全窗口遍历
• 支持 screenshot 对目标窗口截图，即使窗口被遮挡、不在前台也能截，返回 PNG Data URL

典型场景

关键参数

截图能力说明

• 基于 PrintWindow，直接从窗口 DC 渲染，不依赖前台、不怕遮挡
• 窗口最小化时无法截取，会返回错误
• GPU 直绘的窗口（SolidWorks 3D 视口、游戏、部分硬件加速应用）可能返回黑屏，此时只能改用其它方式

返回示例（控件树）

{
  "ok": true,
  "action": "observe",
  "windowTitle": "工作簿1 - Excel",
  "rootHandle": 69352,
  "elementCount": 29,
  "tree": { "ref": "e1", "name": "工作簿1 - Excel", "type": "Window", "children": [ ... ] }
}

返回示例（截图）

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA...

可直接放进 <img src="...">、Markdown 或前端渲染。

配合使用

list_windows  →  找到目标窗口句柄
observe       →  感知控件树 / 深挖子树 / 截图
find          →  按名称或类型精确找到控件
click / type  →  用 ref 操作

定位：basic-control 是通用兜底层，对所有暴露 UIA 的 Windows 桌面软件都适用，不依赖特定软件的专用接口。遇到重度自绘界面（MFC、游戏引擎）读不到细粒度控件时，可回退到快捷键 / 命令搜索 / 坐标点击。