# Cursor AI 自动视觉识别完整指南

## 🎯 功能概述

完整的自动化流程，当定位失败时：
1. ✅ **自动截图**（智能区域选择）
2. ✅ **创建分析请求**
3. ✅ **Cursor AI自动分析**（通过MCP工具）
4. ✅ **自动获取坐标并点击**
5. ✅ **断言验证**
6. ✅ **自动更新脚本**（添加坐标注释）

## 📋 完整流程

```
测试脚本运行
  ↓
定位失败（所有方法都失败）
  ↓
自动截图（根据元素描述智能选择区域）
  ├─ 底部元素 → 只截底部20%
  ├─ 顶部元素 → 只截顶部20%
  └─ 中间元素 → 只截中间40%
  ↓
创建请求文件 (/tmp/mobile_screenshots/requests/request_xxx.json)
  ↓
等待Cursor AI分析（轮询结果文件，最多30秒）
  ↓
【Cursor AI介入】
  ↓
在Cursor中调用: @mobile_analyze_screenshot request_id="xxx"
  ↓
Cursor AI读取截图并分析
  ↓
Cursor AI写入结果文件 (/tmp/mobile_screenshots/results/result_xxx.json)
  ↓
测试脚本获取坐标
  ↓
执行点击
  ↓
断言验证
  ↓
更新测试脚本（添加坐标注释）
```

## 🔧 关键组件

### 1. 截图工具 (`cursor_vision_helper.py`)

**功能**：
- ✅ 支持全屏截图
- ✅ 支持区域截图（智能选择）
- ✅ 自动创建请求文件
- ✅ 轮询结果文件
- ✅ 自动更新测试脚本

**智能区域选择**：
```python
# 根据元素描述自动选择区域
- "底部导航栏" → 只截底部20%
- "设置图标" → 只截顶部20%
- "登录按钮" → 只截中间40%
```

### 2. MCP工具 (`mobile_analyze_screenshot`)

**功能**：
- ✅ 读取请求文件（自动模式）
- ✅ 读取截图文件
- ✅ 返回分析指令给Cursor AI
- ✅ 提示Cursor AI写入结果文件

**使用方式**：
```
# 自动模式（推荐）
@mobile_analyze_screenshot request_id="20241124_113000_12345"

# 手动模式
@mobile_analyze_screenshot screenshot_path="/tmp/xxx.png" element_desc="设置"
```

### 3. 脚本更新工具 (`script_updater.py`)

**功能**：
- ✅ 解析测试脚本
- ✅ 找到对应步骤
- ✅ 添加坐标注释
- ✅ 保存文件

**更新格式**：
```python
# 更新前
("点击", "设置"),

# 更新后
("点击", "设置"),  # Cursor AI坐标: [976,159] (置信度:95%)
```

## 📝 使用示例

### 测试脚本

```python
# test_设置切换语言.py
STEPS = [
    ("点击", "底部导航栏第4个图标"),
    ("等待", 1),
    ("点击", "设置"),  # 如果定位失败，会自动截图并请求Cursor AI分析
    ("等待", 1),
    ("点击", "语言"),
    # ...
]
```

### 运行测试

```bash
cd backend/mobile_mcp
source venv/bin/activate
python examples/test_设置切换语言_完整版.py
```

### Cursor AI分析

当测试脚本定位失败时：
1. 自动截图并创建请求文件
2. 打印提示信息：
   ```
   📸 已截图: /tmp/mobile_screenshots/screenshot_设置_xxx.png
   📝 已创建分析请求: /tmp/mobile_screenshots/requests/request_xxx.json
   💡 请在Cursor中使用以下命令分析截图：
      @mobile_analyze_screenshot request_id="xxx"
   ```
3. 在Cursor中调用MCP工具
4. Cursor AI分析并写入结果文件
5. 测试脚本继续执行

## 🎯 Cursor AI分析过程

当你在Cursor中调用 `@mobile_analyze_screenshot request_id="xxx"` 时：

1. **MCP工具读取请求文件**
   - 获取截图路径
   - 获取元素描述
   - 获取结果文件路径

2. **Cursor AI读取截图**
   - 使用 `read_file` 工具读取截图文件
   - 或者查看截图路径

3. **Cursor AI分析截图**
   - 使用多模态能力分析
   - 找到指定元素
   - 确定元素中心点坐标

4. **Cursor AI写入结果文件**
   ```json
   {
     "request_id": "xxx",
     "status": "completed",
     "coordinate": {
       "x": 976,
       "y": 159,
       "confidence": 95
     }
   }
   ```

5. **测试脚本获取坐标**
   - 轮询结果文件
   - 获取坐标
   - 执行点击

## ✅ 优势

1. **完全自动化**：定位失败时自动使用视觉识别
2. **智能区域截图**：提高准确率，减少干扰
3. **使用Cursor AI**：免费，无需API费用
4. **自动更新脚本**：保存坐标，方便维护
5. **高准确率**：视觉识别比XML分析更准确

## 🔄 工作流程示例

### 场景：定位"设置"按钮失败

1. **测试脚本**：
   ```
   步骤 4: 点击 设置
   🔍 MobileSmartLocator 定位: 设置
   ... 所有定位方法都失败 ...
   ⚠️  所有定位方法都失败，自动使用Cursor AI视觉识别（截图分析）...
   📸 已截图: /tmp/mobile_screenshots/screenshot_设置_20241124_113000.png
   📝 已创建分析请求: /tmp/mobile_screenshots/requests/request_xxx.json
   🎯 等待Cursor AI分析...
   ```

2. **你在Cursor中**：
   ```
   @mobile_analyze_screenshot request_id="20241124_113000_12345"
   ```

3. **Cursor AI**：
   - 读取请求文件
   - 读取截图文件
   - 分析截图，找到"设置"按钮
   - 返回坐标：{"x": 976, "y": 159, "confidence": 95}
   - 写入结果文件

4. **测试脚本继续**：
   ```
   ✅ Cursor AI分析完成，坐标: (976, 159)
   ✅ 点击成功
   📝 已更新测试脚本: test_设置切换语言.py
   ```

## 📊 文件结构

```
/tmp/mobile_screenshots/
├── screenshot_设置_20241124_113000.png  # 截图文件
├── requests/
│   └── request_20241124_113000_12345.json  # 请求文件
└── results/
    └── result_20241124_113000_12345.json   # 结果文件（Cursor AI写入）
```

## 🎯 关键点

1. **使用Cursor AI**：不是项目中的通义千问，而是Cursor的AI（我）
2. **自动模式**：通过请求文件和结果文件实现异步通信
3. **智能区域截图**：根据元素描述自动选择区域
4. **自动更新脚本**：分析完成后自动添加坐标注释

## 🚀 快速开始

1. 运行测试脚本
2. 如果定位失败，会自动截图并创建请求文件
3. 在Cursor中调用MCP工具分析
4. Cursor AI分析并写入结果文件
5. 测试脚本继续执行

就是这么简单！✨

