# Cursor AI 自动视觉识别完整流程

## 🎯 完整流程

```
1. 测试脚本运行
   ↓
2. 定位失败（所有方法都失败）
   ↓
3. 自动截图（智能区域选择）
   ↓
4. 创建请求文件 (/tmp/mobile_screenshots/requests/request_xxx.json)
   ↓
5. 等待Cursor AI分析（轮询结果文件，最多30秒）
   ↓
6. Cursor AI自动分析（通过MCP工具）
   ↓
7. 写入结果文件 (/tmp/mobile_screenshots/results/result_xxx.json)
   ↓
8. 获取坐标并执行点击
   ↓
9. 断言验证
   ↓
10. 更新测试脚本（添加坐标注释）
```

## 📋 详细步骤

### 步骤1-4：自动截图和创建请求

测试脚本定位失败时，会自动：
- 📸 截图（根据元素描述智能选择区域）
- 📝 创建请求文件，包含：
  ```json
  {
    "request_id": "20241124_113000_12345",
    "screenshot_path": "/tmp/mobile_screenshots/screenshot_设置_xxx.png",
    "element_desc": "设置",
    "region": {"x": 0, "y": 0, "width": 1080, "height": 480},
    "script_path": "/path/to/test_设置切换语言.py",
    "timestamp": "20241124_113000_123456",
    "status": "pending"
  }
  ```

### 步骤5：等待Cursor AI分析

测试脚本会轮询结果文件（每秒检查一次，最多30秒）：
- ✅ 如果30秒内返回结果 → 继续执行
- ⏱️ 如果超时 → 提示手动调用

### 步骤6-7：Cursor AI自动分析

**方式1：自动模式（推荐）**

当你在Cursor中调用MCP工具时：
```
@mobile_analyze_screenshot request_id="20241124_113000_12345"
```

Cursor AI会：
1. 读取请求文件
2. 读取截图文件
3. 使用多模态能力分析截图
4. 找到元素并返回坐标
5. **自动写入结果文件**

**方式2：手动模式**

```
@mobile_analyze_screenshot screenshot_path="/tmp/mobile_screenshots/screenshot_设置_xxx.png" element_desc="设置"
```

### 步骤8：执行点击

测试脚本获取坐标后，自动执行点击：
```python
coord = result['coordinate']
await client.click("设置", ref=f"vision_coord_{coord['x']}_{coord['y']}")
```

### 步骤9：断言验证

```python
snapshot = await client.snapshot()
assert "设置" in snapshot or "Settings" in snapshot
```

### 步骤10：更新脚本

自动在测试脚本中添加坐标注释：
```python
("点击", "设置"),  # Cursor AI坐标: [976,159] (置信度:95%)
```

## 🔧 关键功能

### 1. 智能区域截图

根据元素描述自动选择截图区域：
- **底部元素** → 只截底部20%
- **顶部元素** → 只截顶部20%
- **中间元素** → 只截中间40%
- **其他** → 全屏截图

### 2. 自动分析机制

使用文件系统实现异步通信：
- 请求文件：测试脚本创建
- 结果文件：Cursor AI写入
- 轮询机制：测试脚本检查

### 3. 脚本自动更新

分析完成后，自动更新测试脚本：
- 添加坐标注释
- 不破坏原有逻辑
- 方便后续维护

## 📝 使用示例

### 测试脚本

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

### Cursor AI分析

当测试脚本定位失败时：
1. 自动截图并创建请求文件
2. 打印提示信息
3. 你可以在Cursor中调用：
   ```
   @mobile_analyze_screenshot request_id="xxx"
   ```
4. Cursor AI分析并写入结果文件
5. 测试脚本继续执行

## 🎯 优势

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

## 🔄 未来改进

- [ ] 支持批量分析（一次分析多个元素）
- [ ] 支持截图缓存（相同页面不重复截图）
- [ ] 支持坐标缓存（相同元素不重复分析）
- [ ] 后台监控服务（自动检测请求文件）

