ai-proj-helper/skills-dev/agent-browser-plugin/skills/SKILL.md

---
name: agent-browser
description: 浏览器自动化技能。用于网页交互、E2E冒烟测试、需求验收验证、前端开发验证、截图对比。基于 Vercel agent-browser CLI。
---

# agent-browser

浏览器自动化 CLI，专为 AI Agent 设计。当用户需要与网页交互时使用：导航页面、填写表单、点击按钮、截图、提取数据、测试 Web 应用、自动化浏览器任务。

当用户提到以下关键词时自动激活：浏览器自动化、打开网页、截图、网页测试、冒烟测试、E2E 验证、页面检查、agent-browser。

## 前置条件

```bash
npm i -g agent-browser    # 安装 CLI
agent-browser install      # 下载 Chrome
```

---

## 核心工作流（snapshot-ref 模式）

1. **导航** 到 URL
2. **snapshot** 获取可交互元素（返回 `@e1`, `@e2` 等引用）
3. **交互** 使用元素引用
4. **重新 snapshot** DOM 变化后刷新引用

```bash
agent-browser open https://example.com/form
agent-browser snapshot -i
agent-browser fill @e1 "user@example.com"
agent-browser click @e3
agent-browser wait --load networkidle
```

---

## 命令参考

### 导航与控制
- `open <url>` – 打开网页
- `goto <url>` – 在会话内跳转
- `close` – 关闭浏览器
- `wait <condition>` – 等待元素/网络/JS 条件

### 页面检查
- `snapshot -i` – 获取可交互元素及引用（推荐）
- `snapshot` – 完整无障碍树
- `get text|html|value @e1` – 提取元素内容
- `get title|url` – 获取页面标题/URL
- `screenshot [path]` – 截图
- `screenshot --annotate` – 带元素标注的截图

### 交互操作
- `click @e1` / `dblclick @e1` – 单击/双击
- `fill @e1 "text"` – 清空并输入
- `type @e1 "text"` – 追加输入
- `select @e1 "option"` – 下拉选择
- `check @e1` – 勾选/取消勾选
- `press Enter` – 按键
- `hover @e1` – 悬停
- `scroll down 500` – 滚动
- `upload @e1 /path` – 上传文件
- `drag @e1 @e2` – 拖放

### 高级功能
- `eval 'code'` – 执行 JavaScript
- `diff snapshot` – 对比前后页面状态
- `set viewport 1920 1080` – 设置视口
- `set device "iPhone 14"` – 移动端模拟
- `find role <role> click --name "Label"` – 语义定位器
- `network mock <pattern> --body '...'` – 网络请求模拟
- `cookies get/set/clear` – Cookie 管理
- `storage get/set/clear` – localStorage 管理

---

## 认证与会话持久化

### Auth Vault（推荐）
```bash
agent-browser auth save myapp
agent-browser open https://myapp.com --auth myapp
```

### 持久化 Profile
```bash
agent-browser open https://site.com --profile ~/.myapp-profile
```

### 命名会话
```bash
agent-browser open https://site.com --session-name myapp
```

### 状态文件
```bash
agent-browser open https://site.com --state ./auth.json --save-state
```

---

## 命令链式调用

不需要中间输出时用 `&&` 串联：
```bash
agent-browser open https://example.com && \
  agent-browser wait --load networkidle && \
  agent-browser screenshot page.png
```

需要解析输出（如 snapshot 获取 ref）时分开执行。

---

## 与其他技能结合

### 结合 dev-test（E2E 冒烟测试）

在 dev-test 的 Gate 4（E2E 冒烟测试）中使用：

```bash
# 1. 打开本地前端
agent-browser open http://localhost:3000 --session-name e2e-test

# 2. 验证页面加载
agent-browser snapshot -i
agent-browser screenshot /tmp/e2e-home.png

# 3. 测试登录流程
agent-browser fill @e1 "admin@example.com"
agent-browser fill @e2 "password"
agent-browser click @e3
agent-browser wait --load networkidle

# 4. 验证登录成功
agent-browser get title  # 应包含 "Dashboard"
agent-browser screenshot /tmp/e2e-dashboard.png

# 5. 清理
agent-browser close
```

### 结合 req（需求验收验证）

PRD 评审后实际操作验证需求是否实现：

```bash
# 根据 PRD 验收标准逐项检查
agent-browser open http://localhost:3000/feature-page
agent-browser snapshot -i
# 按验收标准操作对应元素...
agent-browser screenshot /tmp/req-verify.png
```

### 结合 dev-coding（前端开发即时验证）

开发完组件后立即打开页面验证：

```bash
agent-browser open http://localhost:3000/new-page
agent-browser snapshot -i           # 检查渲染的元素
agent-browser screenshot --annotate /tmp/dev-check.png  # 带标注截图
```

### 结合 ops-tools（部署后验证）

部署后快速检查页面是否正常：

```bash
agent-browser open https://ai.pipexerp.com
agent-browser wait --load networkidle
agent-browser get title
agent-browser screenshot /tmp/deploy-check.png
agent-browser close
```

---

## 注意事项

- **Ref 生命周期**：导航或 DOM 变化后引用失效，必须重新 snapshot
- **超时**：默认 25 秒，通过 `AGENT_BROWSER_DEFAULT_TIMEOUT` 环境变量调整
- **会话隔离**：用 `--session-name` 实现并行自动化
- **安全**：支持域名白名单、操作策略、内容边界
- **输出格式**：用 `--json` 获取机器可读输出