opencode/skill/agent-browser/SKILL.md

name, description

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

浏览器自动化工具 agent-browser

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

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

快速开始

安装检查

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

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

# 下载 Chromium 浏览器
agent-browser install

核心工作流程（4步法）

# 使用 agent-browser
1. agent-browser open <url>
2. agent-browser snapshot -i
3. agent-browser click @e1    
4. agent-browser fill @e2 "文本"

核心工作流程详解

1. 导航到页面

agent-browser open https://example.com

2. 获取页面快照（推荐使用交互模式）

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. 页面变化后重新快照

页面发生重大变化（导航、表单提交等）后，需要重新获取快照：

agent-browser snapshot -i  # 重新获取新的 refs

命令参考

导航命令

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）

快照命令（页面分析）

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）

# 基础交互
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  # 滚动元素到可见区域

获取信息

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         # 获取边界框

检查状态

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

截图命令

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

等待命令

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）

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：手动登录流程（推荐用于首次）

# 导航到登录页面
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：加载已保存状态（后续使用）

# 加载保存的认证状态
agent-browser state load auth.json

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

方法3：HTTP Headers 认证（跳过登录界面）

# 为特定域名设置认证头
agent-browser open https://api.example.com --headers '{"Authorization": "Bearer <token>"}'

方法4：Cookies 管理

# 设置 cookie
agent-browser cookies set session_id "abc123"

# 查看所有 cookies
agent-browser cookies

高级功能

无头/有头模式

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

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

无头模式特点：

• 后台运行 Chromium
• 不占用屏幕空间
• 更快的执行速度
• 适合自动化测试和 AI Agent 使用

会话隔离

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

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

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

JSON 输出（适合机器解析）

agent-browser snapshot -i --json
agent-browser get text @e1 --json
agent-browser is visible @e2 --json

自定义浏览器可执行文件

# 使用自定义 Chromium 路径
agent-browser --executable-path /path/to/chromium open example.com

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

CDP 模式（连接现有浏览器）

# 连接通过 Chrome DevTools Protocol 运行的浏览器
agent-browser --cdp 9222 snapshot

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

调试工具

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

示例场景

示例1：表单提交

# 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：带认证的完整流程

# 首次：登录并保存状态
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：数据提取

# 提取列表数据
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：并行测试

# 会话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" 错误

# 错误原因：agent-browser 未安装
# 解决方案：运行安装命令
npm install -g agent-browser
agent-browser install

2. "Unsupported token @e1" 错误

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

3. 元素找不到

# 检查元素是否存在
agent-browser is visible @e1

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

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

4. 登录状态丢失

# 重新登录并保存状态
agent-browser state save auth.json

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

5. 页面加载缓慢

# 增加等待时间
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