截图 UI 元素定位器

概述

此技能用于引导 AI 视觉模型分析桌面截图，识别用户描述的 UI 元素，并返回归一化坐标位置。

工作流程

1. 读取图片

使用 read 工具读取用户提供的图片文件，将图片内容传递给 AI 视觉模型。

操作步骤：

1. 接收用户提供的图片文件路径（如：/path/to/screenshot.png）
2. 使用 read 工具读取该图片文件
3. 工具会自动将图片转换为 base64 格式并展示给视觉模型
4. AI 视觉模型即可"看到"图片内容并进行分析

示例：

用户：帮我找到这张截图中的登录按钮位置
图片路径：/Users/wuwenze/Desktop/screenshot.png

操作：
read(filePath="/Users/wuwenze/Desktop/screenshot.png")

支持格式：

• PNG (.png)
• JPEG/JPG (.jpg, .jpeg)
• 其他常见图片格式

注意事项：

• 确保图片路径是绝对路径
• 确保文件存在且可读
• 读取后视觉模型会自动解析图片内容

2. 理解用户意图

解析用户想要定位的 UI 元素：

• 按钮（如：登录按钮、提交按钮、取消按钮）
• 输入框（如：搜索框、用户名输入框、密码框）
• 图标（如：设置图标、菜单图标、关闭按钮）
• 文本元素（如：标题、链接、标签）
• 其他界面组件

3. 视觉分析

使用 AI 视觉能力分析图片：

分析步骤：

1. 整体观察图片布局结构
2. 识别各个 UI 组件
3. 根据用户描述匹配目标元素
4. 精确定位元素在图片中的像素位置
5. 计算归一化坐标

定位技巧：

• 注意元素的边界框（bounding box）
• 返回元素中心点的坐标
• 考虑元素的视觉特征（颜色、形状、文字、图标）
• 结合上下文理解（如："右上角的设置按钮"）

4. 计算归一化坐标

公式：

x_norm = x_pixel / image_width
y_norm = y_pixel / image_height

范围： [0.0, 1.0]

坐标系：

• 左上角为原点 (0.0, 0.0)
• 右下角为 (1.0, 1.0)

5. 返回结果

输出格式：

{
  "found": true,
  "element": "用户描述的元素",
  "coordinates": {
    "x": 0.523,
    "y": 0.234
  },
  "confidence": "high",
  "description": "位于页面中央的蓝色登录按钮"
}

coordinates 说明：

• 包含归一化坐标 (x, y)，范围 [0.0, 1.0]
• 计算公式：x = pixel_x / image_width, y = pixel_y / image_height
• 坐标系：左上角为原点 (0.0, 0.0)，右下角为 (1.0, 1.0)

示例分析

示例 1：定位登录按钮

用户输入：

• 图片：桌面截图
• 意图："找到登录按钮"

分析过程：

1. 读取图片，尺寸为 1920x1080
2. 在图片中央偏上位置看到一个蓝色按钮，上面有"登录"文字
3. 按钮中心像素坐标约为 (960, 450)
4. 计算归一化坐标：
   • x_norm = 960 / 1920 = 0.5
   • y_norm = 450 / 1080 = 0.417

输出：

{
  "found": true,
  "element": "登录按钮",
  "coordinates": {
    "x": 0.5,
    "y": 0.417
  },
  "confidence": "high",
  "description": "位于页面中央偏上的蓝色按钮，显示'登录'文字"
}

示例 2：定位右上角菜单

用户输入：

• 图片：应用界面截图
• 意图："右上角的三条横线菜单图标"

分析过程：

1. 读取图片，尺寸为 1440x900
2. 在右上角看到一个汉堡菜单图标（三条横线）
3. 图标中心像素坐标约为 (1350, 60)
4. 计算归一化坐标：
   • x_norm = 1350 / 1440 = 0.9375
   • y_norm = 60 / 900 = 0.067

输出：

{
  "found": true,
  "element": "菜单图标",
  "coordinates": {
    "x": 0.938,
    "y": 0.067
  },
  "confidence": "high",
  "description": "位于右上角的汉堡菜单图标（三条横线）"
}

常见 UI 元素识别指南

按钮 (Button)

• 特征：矩形或圆角矩形，可能有边框或背景色
• 通常包含文字或图标
• 可能有悬停/点击状态提示

输入框 (Input Field)

• 特征：矩形框，可能有占位符文字
• 常见类型：文本框、密码框、搜索框
• 通常有边框或下划线

图标 (Icon)

• 特征：小型图形元素
• 常见类型：设置齿轮、菜单汉堡线、搜索放大镜、关闭 X
• 通常位于工具栏或标题栏

文本元素 (Text Elements)

• 标题（大字号、加粗）
• 正文（常规字号）
• 链接（带下划线或特殊颜色）
• 标签（用于表单字段）

导航元素

• 标签页（Tab）
• 面包屑导航
• 分页控件
• 侧边栏菜单项

精确定位技巧

1. 使用相对位置描述

   • "左上角的..."
   • "页面中央的..."
   • "右上角的..."
   • "底部的..."

2. 结合颜色和样式

   • "蓝色的提交按钮"
   • "红色的警告图标"
   • "灰色背景的输入框"

3. 结合文字内容

   • "显示'确认'的按钮"
   • "标有'搜索'的输入框"

4. 考虑层级关系

   • "弹窗中的关闭按钮"
   • "侧边栏里的设置选项"

处理边界情况

多个匹配项

如果找到多个可能的匹配项：

1. 选择最符合用户描述的
2. 或返回所有匹配项并说明差异
3. 让用户确认具体是哪一个

未找到元素

如果未能识别目标元素：

{
  "found": false,
  "element": "用户描述的元素",
  "reason": "未能在图片中找到匹配的元素",
  "suggestions": [
    "可能是滚动区域外的内容",
    "元素可能被其他内容遮挡",
    "描述可能不够精确，尝试更详细的描述"
  ]
}

模糊匹配

如果置信度较低：

{
  "found": true,
  "element": "用户描述的元素",
  "coordinates": {
    "x": 0.5,
    "y": 0.3
  },
  "confidence": "medium",
  "note": "找到可能的匹配项，但建议用户确认",
  "matched_description": "页面中央偏上的蓝色按钮（文字不清晰）"
}

坐标验证

在返回结果前，验证坐标是否合理：

• 坐标范围：[0.0, 1.0]
• 中心点应在元素可视区域内
• 考虑元素的尺寸，避免返回边缘坐标

参考

• references/ui_patterns.md: 常见 UI 元素模式和识别技巧