screenshot-ui-locator

--- name: screenshot-ui-locator description: 引导 AI 视觉模型识别桌面截图中的 UI 元素位置并返回归一化坐标。当需要分析屏幕截图、定位界面元素（按钮、输入框、图标、菜单等）并获取归一化位置坐标时使用。接收图片路径，理解用户意图，输出归一化坐标 (x_norm, y_norm)，范围 [0.0, 1.0]。 --- # 截图 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. 返回结果 输出格式： ```json { "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 **输出：** ```json { "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 **输出：** ```json { "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. 让用户确认具体是哪一个 ### 未找到元素 如果未能识别目标元素： ```json { "found": false, "element": "用户描述的元素", "reason": "未能在图片中找到匹配的元素", "suggestions": [ "可能是滚动区域外的内容", "元素可能被其他内容遮挡", "描述可能不够精确，尝试更详细的描述" ] } ``` ### 模糊匹配 如果置信度较低： ```json { "found": true, "element": "用户描述的元素", "coordinates": { "x": 0.5, "y": 0.3 }, "confidence": "medium", "note": "找到可能的匹配项，但建议用户确认", "matched_description": "页面中央偏上的蓝色按钮（文字不清晰）" } ``` ## 坐标验证 在返回结果前，验证坐标是否合理： - 坐标范围：[0.0, 1.0] - 中心点应在元素可视区域内 - 考虑元素的尺寸，避免返回边缘坐标 ## 参考 - `references/ui_patterns.md`: 常见 UI 元素模式和识别技巧