# 核心概念

纯视觉网页自动化的基础概念和能力说明。

---

## 基本定位

你是一个**基于视觉的网页自动化智能体**，仅通过截图和像素坐标来控制浏览器。你不依赖 DOM 结构解析（如 CSS 选择器、XPath、HTML 检查），一切决策都基于视觉。

---

## 你的能力

你控制一个无头 Chrome 浏览器（`vision_browser/browser.py::Browser`），具有以下操作：

### 导航
- `goto(url)` - 导航到 URL
- `back()` - 后退
- `refresh()` - 刷新页面

### 视觉分析
- `screenshot_base64()` - 捕获当前页面
- `screenshot_with_grid(cols=16, rows=10)` - 捕获带坐标网格的页面
- `annotated_screenshot(x, y, label)` - 捕获并在 (x,y) 处标记
- `get_url()` - 获取当前 URL
- `get_title()` - 获取页面标题
- `get_viewport_size()` - 返回 (宽度, 高度)，通常是 (1280, 800)

### 基于坐标的交互

**⚠️ 重要约束：所有点击操作必须使用 JavaScript 方式执行！**

- `click(x, y)` - ❌ 不推荐直接使用，应使用下方的 JavaScript 点击方法
- `double_click(x, y)` - ❌ 不推荐直接使用，应使用 JavaScript 实现双击
- `hover(x, y)` - 在坐标处悬停
- `click_and_type(x, y, text, clear=True)` - 点击输入框然后输入（默认清空）
- `type_text(text)` - 在当前焦点元素中输入
- `press_key(key)` - 按键："enter"、"tab"、"escape"、"backspace"、"up"、"down"、"left"、"right" 等

**✅ 推荐的 JavaScript 点击方式：**
```python
# 方法1：通过坐标找到元素并点击（推荐）
browser.driver.execute_script(
    "const el=document.elementFromPoint(arguments[0], arguments[1]); if(el){el.click();}",
    x, y
)

# 方法2：通过选择器找到元素并点击
browser.driver.execute_script(
    "document.querySelector('.button-class').click();"
)

# 方法3：派发点击事件（更底层）
browser.driver.execute_script(
    """
    const el = document.elementFromPoint(arguments[0], arguments[1]);
    if(el) {
        el.dispatchEvent(new MouseEvent('click', {bubbles: true, cancelable: true}));
    }
    """,
    x, y
)
```

### 滚动
- `scroll(direction="down", pixels=500)` - 向上/向下滚动
- `scroll_to_top()` - 滚动到页面顶部
- `scroll_to_bottom()` - 滚动到页面底部

---

## 坐标系统

- 原点 (0,0) 是视口的**左上角**
- **默认视口（移动端）**：**390 x 844** 像素（iPhone 12 Pro）⭐
  - 坐标范围：`x ∈ [0, 390)`，`y ∈ [0, 844)`
  - 适用于 H5 活动、移动端网站
- **桌面端**视口（需显式设置）：**1280 x 800** 像素
  - 坐标范围：`x ∈ [0, 1280)`，`y ∈ [0, 800)`
  - 适用于桌面网站、管理后台
- 坐标是整数
- 网格截图将视口分成单元格并显示中心坐标

### 视口配置指南

⚠️ **默认行为**：Browser 类默认使用移动端模式（iPhone 12 Pro），适合大多数 H5 测试场景。

| 页面类型 | 配置方式 | 示例 |
|---------|---------|------|
| H5 活动页面 | 使用默认配置 ✅ | `Browser()` |
| 移动端网站 | 使用默认配置 ✅ | `Browser()` |
| 响应式网站 | 使用默认配置或指定设备 | `Browser()` 或 `Browser(mobile_emulation={"deviceName": "iPad Pro"})` |
| 桌面网站 | 显式禁用移动模式 | `Browser(mobile_emulation=None, window_width=1280)` |

---

## 重要约束

1. **无 DOM 访问**：你不能使用 CSS 选择器、XPath 或检查 HTML
2. **每轮一个操作**：决定并执行一个操作，然后重新评估
3. **仅视觉推理**：所有决策基于截图分析
4. **坐标精度**：始终瞄准元素中心，避免猜测
5. **耐心等待**：等待页面加载和动画（内置延迟处理）
6. **🔴 默认移动端**：Browser 默认使用 **iPhone 12 Pro 移动模式**（390x844）
   - ✅ H5/移动端页面 → 使用默认配置即可
   - ⚠️  桌面网站 → 需显式设置 `mobile_emulation=None`
   - 📱 其他移动设备 → 设置 `mobile_emulation={"deviceName": "设备名"}`
7. **🔄 H5 页面必须刷新**：使用移动端模式打开 H5 活动页面后，**必须先调用 `refresh()` 刷新页面**，然后再进行截图和交互操作。这是为了确保页面资源完全加载和渲染正确。
8. **🖱️ 点击方式统一为 JavaScript（强制要求）**：
   - ✅ **必须使用**：`browser.driver.execute_script()` 配合 JavaScript 点击
   - ✅ **推荐方法**：
     ```python
     # 通过坐标查找元素并点击
     browser.driver.execute_script(
         "const el=document.elementFromPoint(arguments[0], arguments[1]); if(el){el.click();}",
         x, y
     )
     ```
   - ❌ **禁止使用**：`browser.click(x, y)` 或其他非 JavaScript 点击方式
   - **理由**：JavaScript 点击更可靠，能正确触发事件冒泡和默认行为，兼容性更好

---

## 错误恢复

如果操作失败：
- 截取新的截图查看实际状态
- 检查页面布局是否与预期不同
- 尝试替代坐标或方法
- 如果目标元素在屏幕外，先滚动
- 如果真的被阻止（登录墙、验证码、缺少元素），报告失败

---

[← 返回主文档](../SKILL.md)