opencode/skill/agent-browser/SKILL.md

---
name: ab
description: 浏览器自动化工具，用于网页测试、表单填写、截图、数据提取等
---

# 浏览器自动化工具 agent-browser

ab是 agent-browser 的缩写，它是一个为 AI 代理设计的无头浏览器自动化 CLI 工具，基于 Rust 和 Playwright 构建。支持快速导航、元素交互、页面截图、数据提取等功能。

注意：必须使用 agent-browser 全称作为命令关键字。

## 快速开始

### 安装检查
agent-browser 默认已安装。如果遇到 "command not found" 错误，请运行以下命令安装：

```bash
# 全局安装
npm install -g agent-browser

# 下载 Chromium 浏览器
agent-browser install
```

### 核心工作流程（4步法）
```bash
# 使用 agent-browser
1. agent-browser open <url>
2. agent-browser snapshot -i
3. agent-browser click @e1    
4. agent-browser fill @e2 "文本"
```

## 核心工作流程详解

### 1. 导航到页面
```bash
agent-browser open https://example.com
```

### 2. 获取页面快照（推荐使用交互模式）
```bash
agent-browser snapshot -i  # 仅显示交互元素（按钮、输入框、链接）
```

**输出示例：**
```
- link "Learn more" [ref=e1]
- textbox "Email" [ref=e2]
- button "Submit" [ref=e3]
```

### 3. 使用 Refs 进行交互
快照中的 `[ref=e1]`、`[ref=e2]` 等是元素的唯一引用标识，**推荐使用 refs 而非 CSS 选择器**：
- **确定性**：ref 指向快照中的确切元素
- **快速**：无需重新查询 DOM
- **AI 友好**：适合 LLM 处理

### 4. 页面变化后重新快照
页面发生重大变化（导航、表单提交等）后，需要重新获取快照：
```bash
agent-browser snapshot -i  # 重新获取新的 refs
```

## 命令参考

### 导航命令
```bash
agent-browser open <url>      # 导航到 URL（或：ab open <url>）
agent-browser back            # 后退（或：ab back）
agent-browser forward         # 前进（或：ab forward）
agent-browser reload          # 重新加载页面（或：ab reload）
agent-browser close           # 关闭浏览器（或：ab close）
```

### 快照命令（页面分析）
```bash
agent-browser snapshot        # 完整可访问性树（或：ab snapshot）
agent-browser snapshot -i     # 仅交互元素（推荐）（或：ab snapshot -i）
agent-browser snapshot -c     # 紧凑输出（移除空结构元素）（或：ab snapshot -c）
agent-browser snapshot -d 3   # 限制深度为 3 级（或：ab snapshot -d 3）
agent-browser snapshot -s "#main"  # 限定到 CSS 选择器范围（或：ab snapshot -s "#main"）
```

### 交互命令（使用 @refs）
```bash
# 基础交互
agent-browser click @e1           # 单击
agent-browser dblclick @e1        # 双击
agent-browser fill @e2 "文本"     # 清空并填写
agent-browser type @e2 "文本"     # 不清空直接输入
agent-browser press Enter         # 按键（支持组合键 Control+a）
agent-browser hover @e1           # 悬停
agent-browser focus @e1           # 聚焦

# 表单操作
agent-browser check @e1           # 勾选复选框
agent-browser uncheck @e1         # 取消勾选
agent-browser select @e1 "值"     # 选择下拉选项
agent-browser upload @e1 file1.jpg  # 上传文件

# 滚动
agent-browser scroll down 500     # 向下滚动 500px
agent-browser scrollintoview @e1  # 滚动元素到可见区域
```

### 获取信息
```bash
agent-browser get text @e1        # 获取元素文本
agent-browser get value @e1       # 获取输入框值
agent-browser get html @e1        # 获取 innerHTML
agent-browser get attr @e1 id     # 获取属性
agent-browser get title           # 获取页面标题
agent-browser get url             # 获取当前 URL
agent-browser get count ".item"   # 计数匹配元素
agent-browser get box @e1         # 获取边界框
```

### 检查状态
```bash
agent-browser is visible @e1      # 检查是否可见
agent-browser is enabled @e1      # 检查是否启用
agent-browser is checked @e1      # 检查是否勾选
```

### 截图命令
```bash
agent-browser screenshot          # 截图到标准输出
agent-browser screenshot page.png  # 保存到文件
agent-browser screenshot --full   # 完整页面截图
```

### 等待命令
```bash
agent-browser wait @e1                     # 等待元素可见
agent-browser wait 2000                    # 等待毫秒数
agent-browser wait --text "成功"           # 等待文本出现
agent-browser wait --url "*/dashboard"     # 等待 URL 模式匹配
agent-browser wait --load networkidle      # 等待网络空闲

# 加载状态选项：load, domcontentloaded, networkidle
```

### 语义化定位器（替代 refs）
```bash
agent-browser find role button click --name "提交"
agent-browser find text "登录" click
agent-browser find label "邮箱" fill "user@test.com"
agent-browser find placeholder "请输入" fill "内容"
agent-browser find first ".item" click
agent-browser find nth 2 "a" text
```

## 认证与状态管理

### 方法1：手动登录流程（推荐用于首次）
```bash
# 导航到登录页面
agent-browser open https://example.com/login

# 填写表单
agent-browser snapshot -i
# 输出显示：textbox "邮箱" [ref=e1], textbox "密码" [ref=e2], button "登录" [ref=e3]

agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"
agent-browser click @e3

# 等待登录成功
agent-browser wait --url "*/dashboard"

# 保存认证状态（重要！）
agent-browser state save auth.json
```

### 方法2：加载已保存状态（后续使用）
```bash
# 加载保存的认证状态
agent-browser state load auth.json

# 直接访问受保护页面
agent-browser open https://example.com/dashboard
```

### 方法3：HTTP Headers 认证（跳过登录界面）
```bash
# 为特定域名设置认证头
agent-browser open https://api.example.com --headers '{"Authorization": "Bearer <token>"}'
```

### 方法4：Cookies 管理
```bash
# 设置 cookie
agent-browser cookies set session_id "abc123"

# 查看所有 cookies
agent-browser cookies
```

## 高级功能

### 无头/有头模式
```bash
# 默认：无头模式（无界面）
agent-browser open example.com

# 有头模式：显示浏览器窗口（适合调试）
agent-browser --headed open example.com
```

**无头模式特点**：
- 后台运行 Chromium
- 不占用屏幕空间
- 更快的执行速度
- 适合自动化测试和 AI Agent 使用

### 会话隔离
```bash
# 创建独立会话
agent-browser --session user1 open site-a.com
agent-browser --session user2 open site-b.com

# 查看活动会话
agent-browser session list

# 每个会话独立：
# - 浏览器实例
# - Cookies 和存储
# - 导航历史
# - 认证状态
```

### JSON 输出（适合机器解析）
```bash
agent-browser snapshot -i --json
agent-browser get text @e1 --json
agent-browser is visible @e2 --json
```

### 自定义浏览器可执行文件
```bash
# 使用自定义 Chromium 路径
agent-browser --executable-path /path/to/chromium open example.com

# 环境变量方式
AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium agent-browser open example.com
```

### CDP 模式（连接现有浏览器）
```bash
# 连接通过 Chrome DevTools Protocol 运行的浏览器
agent-browser --cdp 9222 snapshot

# 可控制：Electron 应用、启用远程调试的 Chrome、WebView2 等
```

### 调试工具
```bash
agent-browser console            # 查看控制台消息
agent-browser errors             # 查看页面错误
agent-browser console --clear    # 清空控制台
agent-browser errors --clear     # 清空错误
agent-browser highlight @e1      # 高亮显示元素
```

## 示例场景

### 示例1：表单提交
```bash
# 1. 导航到表单页面
agent-browser open https://example.com/form

# 2. 获取交互元素快照
agent-browser snapshot -i
# 输出：textbox "邮箱" [ref=e1], textbox "密码" [ref=e2], button "提交" [ref=e3]

# 3. 填写并提交表单
agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"
agent-browser click @e3

# 4. 等待结果并验证
agent-browser wait --load networkidle
agent-browser snapshot -i  # 检查结果
```

### 示例2：带认证的完整流程
```bash
# 首次：登录并保存状态
agent-browser open https://app.example.com/login
agent-browser fill "#email" "username"
agent-browser fill "#password" "password123"
agent-browser click "#submit"
agent-browser wait --url "**/dashboard"
agent-browser state save app-auth.json

# 后续使用：加载状态
agent-browser state load app-auth.json
agent-browser open https://app.example.com/dashboard

# 执行操作
agent-browser snapshot -i
agent-browser click @e1
```

### 示例3：数据提取
```bash
# 提取列表数据
agent-browser open https://example.com/products
agent-browser wait --load networkidle

# 获取所有产品标题
for i in $(seq 1 10); do
  agent-browser get text "@e$i" --json
done

# 或使用 CSS 选择器
agent-browser get text ".product-title"
```

### 示例4：并行测试
```bash
# 会话1：用户A
agent-browser --session userA open site.com
agent-browser --session userA fill "#email" "userA@test.com"
agent-browser --session userA fill "#password" "passA123"

# 会话2：用户B（同时运行）
agent-browser --session userB open site.com
agent-browser --session userB fill "#email" "userB@test.com"
agent-browser --session userB fill "#password" "passB123"
```

## 最佳实践

### 1. 优先使用 Refs
- 从 `snapshot -i` 获取 refs
- 使用 `@e1`、`@e2` 而非 CSS 选择器
- 页面变化后重新快照获取新 refs

### 2. 合理使用等待
- 页面加载：`wait --load networkidle`
- 元素出现：`wait @e1`
- 文本出现：`wait --text "成功"`
- 避免硬编码 sleep，使用条件等待

### 3. 状态管理策略
- 首次登录后使用 `state save`
- 后续使用 `state load` 避免重复登录
- 敏感操作使用 `--session` 隔离

### 4. 错误处理
- 检查元素是否存在：`is visible @e1`
- 查看控制台日志：`console`
- 调试时使用 `--headed` 模式

### 5. 性能优化
- 使用 `-i` 参数限制快照输出
- 批量操作使用循环
- 合理使用等待避免超时

## 故障排除

### 常见问题

**1. "command not found: agent-browser" 错误**
```bash
# 错误原因：agent-browser 未安装
# 解决方案：运行安装命令
npm install -g agent-browser
agent-browser install
```

**2. "Unsupported token @e1" 错误**
```bash
# 错误原因：快照后页面已刷新，refs 失效
# 解决方案：重新获取快照
agent-browser snapshot -i
agent-browser click @e1  # 使用新的 ref
```

**3. 元素找不到**
```bash
# 检查元素是否存在
agent-browser is visible @e1

# 等待元素出现
agent-browser wait @e1

# 使用语义化查找
agent-browser find role button click --name "提交"
```

**4. 登录状态丢失**
```bash
# 重新登录并保存状态
agent-browser state save auth.json

# 或设置 cookies
agent-browser cookies set session_id "value"
```

**5. 页面加载缓慢**
```bash
# 增加等待时间
agent-browser wait --load networkidle
agent-browser wait 5000

# 或设置超时
agent-browser set timeout 30000
```

## 平台支持

| 平台 | 原生二进制 | 回退方案 |
|------|-----------|----------|
| macOS ARM64 | ✓ | Node.js |
| macOS x64 | ✓ | Node.js |
| Linux ARM64 | ✓ | Node.js |
| Linux x64 | ✓ | Node.js |
| Windows x64 | ✓ | Node.js |

## 技术架构

agent-browser 采用客户端-守护进程架构：
1. **Rust CLI**（原生二进制）- 解析命令，与守护进程通信
2. **Node.js 守护进程** - 管理 Playwright 浏览器实例
3. **回退方案** - 如果原生二进制不可用，直接使用 Node.js

守护进程在首次命令时自动启动，并在命令间持久化以实现快速后续操作。

**浏览器引擎**：默认使用 Chromium。守护进程也支持通过 Playwright 协议使用 Firefox 和 WebKit。

## 相关资源

- 官方仓库：https://github.com/vercel-labs/agent-browser
- 官方文档：https://agent-browser.dev
- npm 包：https://www.npmjs.com/package/agent-browser

## 许可证

Apache-2.0