---
name: agent-browser
description: 浏览器自动化工具，用于 AI 代理的网页操作。当用户说"打开浏览器"、"访问网页"、"抓取页面"、"填写表单"、"点击按钮"、"截图"、"网页自动化"时调用此技能。
allowed-tools:
  - shell
  - execute_command
  - read_file
  - write_file
license: Apache-2.0
compatibility: v1.0.0
---

# Agent Browser - 浏览器自动化技能

## 概述

`agent-browser` 是 Vercel Labs 开发的浏览器自动化 CLI 工具，专为 AI 代理设计。基于 Chrome/Playwright，支持完整的网页交互功能。

**官方文档**: https://agent-browser.dev  
**GitHub**: https://github.com/vercel-labs/agent-browser

## 安装

```bash
# 全局安装（推荐）
npm install -g agent-browser
agent-browser install  # 首次下载 Chrome

# 或使用 npx（无需安装）
npx agent-browser install
```

## 核心工作流程

### 1. 打开网页
```bash
agent-browser open <url>
# 示例
agent-browser open https://example.com
```

### 2. 获取页面快照（AI 推荐）
```bash
# 获取可访问性树和元素引用
agent-browser snapshot -i

# 输出示例：
# - heading "Example Domain" [ref=e1] [level=1]
# - button "Submit" [ref=e2]
# - textbox "Email" [ref=e3]
# - link "Learn more" [ref=e4]
```

### 3. 使用引用交互
```bash
agent-browser click @e2                   # 点击按钮
agent-browser fill @e3 "test@example.com" # 填写输入框
agent-browser get text @e1               # 获取文本
agent-browser hover @e4                  # 悬停链接
```

### 4. 截图
```bash
agent-browser screenshot page.png        # 保存截图
agent-browser screenshot --full           # 全页面截图
agent-browser screenshot --annotate       # 带编号标签的截图
```

### 5. 关闭浏览器
```bash
agent-browser close
```

## 常用命令

### 页面导航
```bash
agent-browser open <url>                # 打开 URL
agent-browser back                       # 后退
agent-browser forward                     # 前进
agent-browser reload                     # 刷新
```

### 元素交互
```bash
agent-browser click <sel>               # 点击元素
agent-browser dblclick <sel>             # 双击
agent-browser hover <sel>                # 悬停
agent-browser focus <sel>                # 聚焦
agent-browser fill <sel> <text>         # 清空并填写
agent-browser type <sel> <text>         # 追加输入
agent-browser press <key>               # 按键（Enter, Tab, Control+a）
agent-browser select <sel> <value>      # 下拉选择
agent-browser check <sel>               # 勾选
agent-browser scroll <dir> [px]         # 滚动（up/down/left/right）
```

### 获取信息
```bash
agent-browser get text <sel>            # 获取文本
agent-browser get html <sel>            # 获取 HTML
agent-browser get value <sel>          # 获取输入值
agent-browser get attr <sel> <attr>    # 获取属性
agent-browser get title                 # 获取标题
agent-browser get url                   # 获取 URL
agent-browser get count <sel>          # 计数元素
```

### 状态检查
```bash
agent-browser is visible <sel>         # 是否可见
agent-browser is enabled <sel>         # 是否可用
agent-browser is checked <sel>         # 是否勾选
```

### 语义定位器（AI 推荐）
```bash
# 按 ARIA 角色查找
agent-browser find role button click --name "Submit"
agent-browser find role link text --name "More"

# 按文本查找
agent-browser find text "Sign In" click

# 按标签查找
agent-browser find label "Email" fill "test@test.com"

# 按占位符查找
agent-browser find placeholder "Search..." fill "query"

# 按 testid 查找
agent-browser find testid "submit-btn" click

# 位置选择
agent-browser find first ".item" click
agent-browser find last "a" click
agent-browser find nth 2 "a" text
```

### 等待
```bash
agent-browser wait <selector>          # 等待元素可见
agent-browser wait <ms>                # 等待毫秒
agent-browser wait --text "Welcome"    # 等待文本出现
agent-browser wait --url "**/dash"     # 等待 URL 匹配
agent-browser wait --load networkidle  # 等待网络空闲
```

### 网络拦截
```bash
agent-browser network route <url> --abort      # 阻止请求
agent-browser network route <url> --body '<json>' # Mock 响应
agent-browser network requests                   # 查看请求
```

### 键盘操作
```bash
agent-browser keyboard type "Hello"            # 键盘输入
agent-browser keyboard inserttext "text"       # 直接插入文本
agent-browser keydown <key>                    # 按键按下
agent-browser keyup <key>                     # 按键释放
```

### 鼠标操作
```bash
agent-browser mouse move <x> <y>              # 移动鼠标
agent-browser mouse down [button]             # 鼠标按下
agent-browser mouse up [button]               # 鼠标释放
agent-browser mouse wheel <dy> [dx]          # 滚轮滚动
```

### 剪贴板
```bash
agent-browser clipboard read                  # 读取
agent-browser clipboard write "Hello"         # 写入
```

## 选择器类型

### 引用（推荐用于 AI）
```
@e1, @e2, @e3  # 来自 snapshot 的元素引用
```

### CSS 选择器
```bash
agent-browser click "#submit"
agent-browser click ".class-name"
agent-browser click "div > button"
```

### 文本和 XPath
```bash
agent-browser click "text=Submit"
agent-browser click "xpath=//button"
```

## 会话管理

```bash
# 多会话隔离
agent-browser --session session1 open site-a.com
agent-browser --session session2 open site-b.com

# 持久化配置
agent-browser --profile ~/.myapp-profile open myapp.com

# 自动保存/恢复状态
agent-browser --session-name myapp open twitter.com
```

## 认证管理

```bash
# 从已有 Chrome 导入认证状态
agent-browser --auto-connect state save ./auth.json
agent-browser --state ./auth.json open app.com

# 或者用 session-name 自动持久化
agent-browser --session-name myapp state load ./auth.json
```

## 调试功能

```bash
agent-browser --headed                    # 显示浏览器窗口
agent-browser console                     # 查看控制台消息
agent-browser errors                      # 查看页面错误
agent-browser highlight <sel>             # 高亮元素
agent-browser inspect                     # 打开 DevTools
```

## 选项

| 选项 | 说明 |
|------|------|
| `--session <name>` | 使用隔离会话 |
| `--profile <path>` | 持久化浏览器配置目录 |
| `--state <path>` | 加载存储状态文件 |
| `--headers <json>` | 设置 HTTP 头 |
| `--headed` | 显示浏览器窗口 |
| `--json` | JSON 输出（AI 推荐） |
| `--annotate` | 带编号标签的截图 |
| `--cdp <port>` | 通过 CDP 连接 |
| `--allowed-domains` | 限制允许的域名 |
| `--max-output <n>` | 最大输出字符数 |

## 最佳实践

### AI 推荐的交互流程
```bash
# 1. 打开并获取快照
agent-browser open example.com
agent-browser snapshot -i --json   # AI 解析树和引用

# 2. AI 从快照识别目标元素
# 3. 使用引用执行操作
agent-browser click @e2
agent-browser fill @e3 "input text"

# 4. 页面变化后重新获取快照
agent-browser snapshot -i --json
```

### 命令链
```bash
# 使用 && 链接多个命令
agent-browser open example.com && agent-browser wait --load networkidle && agent-browser snapshot -i

# 管道输入批量命令
echo '[["open","https://example.com"],["snapshot","-i"],["click","@e1"]]' | agent-browser batch --json
```

### 处理弹窗
```bash
agent-browser dialog accept                    # 接受弹窗
agent-browser dialog dismiss                    # 拒绝弹窗
agent-browser dialog status                   # 检查弹窗状态
```

### 标签页操作
```bash
agent-browser tab                     # 列出标签
agent-browser tab new [url]          # 新建标签
agent-browser tab 1                   # 切换到标签 1
agent-browser tab close [n]          # 关闭标签
```

## 注意事项

1. **首次使用**: 需要运行 `agent-browser install` 下载 Chrome
2. **超时**: 默认操作超时 25 秒，可通过 `AGENT_BROWSER_DEFAULT_TIMEOUT` 调整
3. **安全**: 敏感操作使用 `--confirm-actions eval,download` 确认
4. **会话**: 不同会话有独立的 cookies、历史、认证状态
5. **引用稳定性**: 每次 `snapshot` 后引用可能变化，需重新获取

## 故障排除

```bash
# 查看帮助
agent-browser --help

# 调试模式
agent-browser open example.com --debug

# 安装 Chrome
agent-browser install

# 升级
agent-browser upgrade
```
