auto-browser

SKILL.md

---
name: auto-browser
description: 通过 Chrome Debug 模式（CDP）自动化操作真实浏览器——导航、点击、填表、提取数据、截图、执行多步流程。当用户说"帮我在网页上操作"、"打开浏览器"、"帮我点"、"帮我填"、"帮我抓取"、"帮我截图"、"auto-browser"时使用。
---

# auto-browser

你的浏览器遥控器。导航、点击、填表、抓数据、截图——说一句话就行。

## 使用方式

```
/auto-browser 打开 GitHub 看看我的 notifications
/auto-browser 去 Amazon 搜索 mechanical keyboard 截图前三个结果
/auto-browser 登录后台，把订单列表导出来
/auto-browser 帮我在这个页面点「下一步」然后填写地址表单
```

自然语言描述意图即可，不需要写代码。

## 必须使用 playwright-cdp 工具集

所有浏览器操作使用 **`user-playwright-cdp`** 的工具（连接真实 Chrome，保留登录态）。

- ✅ 用：`user-playwright-cdp` 的 `browser_navigate`、`browser_snapshot`、`browser_click` 等
- ❌ 禁止：`cursor-ide-browser` 的同名工具（沙盒浏览器，无登录态）

---

## 核心工作流

### 0. 确保 Chrome Debug 在线

```bash
curl -s http://127.0.0.1:9222/json/version
```

- ✅ 有响应 → 继续
- ❌ 无响应 → 直接启动，不问用户：

```bash
nohup /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="/tmp/chrome_debug_profile" \
  > /tmp/chrome_debug.log 2>&1 &
```

等 2 秒后重新 curl 确认。

### 1. 感知：snapshot 先行

**每次操作前**都先 `browser_snapshot`，获取页面无障碍树。这是你的「眼睛」。

- 用 snapshot 中的 `ref` 来定位元素
- 不确定页面状态时，先 snapshot 再决定下一步

### 2. 行动：选择合适的操作

根据用户意图选择操作，可自由组合：

| 意图 | 工具 | 说明 |
|------|------|------|
| 打开网页 | `browser_navigate` | 推断 URL，直接导航 |
| 后退 | `browser_navigate_back` | |
| 点击按钮/链接 | `browser_click` | 用 snapshot 的 ref |
| 填写输入框 | `browser_type`（追加）/ `browser_fill_form`（清空后填） | |
| 选择下拉框 | `browser_select_option` | |
| 上传文件 | `browser_file_upload` | 需绝对路径 |
| 按键 | `browser_press_key` | Enter、Escape、Tab 等 |
| 悬停 | `browser_hover` | 展开菜单、tooltip |
| 拖拽 | `browser_drag` | startRef → endRef |
| 处理弹窗 | `browser_handle_dialog` | alert/confirm/prompt |
| 等待加载 | `browser_wait_for` | 等时间或等文本出现/消失 |
| 执行 JS | `browser_evaluate` | 页面没有暴露 UI 时的后备手段 |
| 管理标签页 | `browser_tabs` | list/new/close/select |
| 调整窗口 | `browser_resize` | 测试响应式布局 |

### 3. 确认：截图反馈

操作完成后 `browser_take_screenshot` 截图给用户确认结果。

---

## 操作原则

### URL 推断

根据用户描述直接推断 URL 并导航，不要反问：

- 「打开 Google」→ `https://www.google.com`
- 「去 GitHub」→ `https://github.com`
- 「看看 V2EX」→ `https://www.v2ex.com`
- 模糊描述 → 用常识判断，导航后截图确认

只有完全无法推断时才问。

### 多步操作

复杂任务拆成步骤，每步遵循：**snapshot → 操作 → 等待 → snapshot 确认**。

```
示例：「登录后台导出订单」
1. navigate 到登录页 → snapshot
2. 如果已登录跳过，否则填写账号密码 → click 登录
3. wait_for 页面加载 → snapshot
4. click 导航到订单页 → snapshot
5. click 导出按钮 → 截图确认
```

### 等待策略

页面变化后（导航、点击、提交），用短间隔等待 + snapshot 确认：

```
browser_wait_for time=2 → snapshot → 检查是否就绪
→ 没好？再 wait_for time=2 → snapshot
```

不要一次等太久。2-3 秒一轮，最多重试 3 次。

### 数据提取

需要从页面抓取数据时：

1. `browser_snapshot` 获取页面结构
2. 从无障碍树中提取所需信息
3. 信息不够时用 `browser_evaluate` 执行 JS 提取
4. 结果太长写入文件，回复给摘要 + 路径

### 表单填写

填表场景遵循 auto-fill 的规则：

- 语义匹配字段，不要求精确
- 不确定的字段列出来问用户
- 密码类字段填前确认
- 多字段优先用 `browser_fill_form` 批量填写
- 填完截图确认

---

## 安全边界

| 操作 | Agent 直接做 | 需用户确认 |
|------|-------------|-----------|
| 导航、浏览、截图 | ✅ | |
| 点击普通按钮/链接 | ✅ | |
| 填写非敏感字段 | ✅ | |
| 读取/提取页面数据 | ✅ | |
| 填写密码 | | ✅ |
| 点击「提交」「付款」「删除」 | | ✅（除非用户明确说"帮我提交"） |
| 发送消息/邮件 | | ✅ |
| 关闭标签页 | | ✅（除非用户要求） |

**原则：只读操作自由做，写入/不可逆操作先确认。**

---

## 错误处理

| 问题 | 处理 |
|------|------|
| 元素找不到 | 重新 snapshot，ref 可能变了 |
| 页面加载慢 | `browser_wait_for` 等待，不要盲目重试 |
| 弹窗阻断 | `browser_handle_dialog` 处理 |
| 需要登录 | 告诉用户，等用户手动登录后继续 |
| 验证码/人机验证 | 截图告知用户，等用户处理 |
| JS 报错 | `browser_console_messages` 查看错误日志 |

---

## 环境配置（首次）

如果 `~/.cursor/mcp.json` 里没有 `playwright-cdp` 配置，添加：

```json
"playwright-cdp": {
  "command": "npx",
  "args": ["-y", "@playwright/mcp@latest", "--cdp-endpoint", "http://127.0.0.1:9222"]
}
```

添加后提示用户重载 MCP（Cursor 设置 → MCP → Reload）。