agent-browser 技能

真正为 AI 智能体打造的浏览器自动化工具。由 Vercel Labs 专门为 LLM 驱动的工作流构建。

为什么这比替代方案更好

1. 确定性引用（游戏规则改变者）

传统工具的问题：

• CSS 选择器在网站更改时会失效
• XPath 脆弱且难以阅读
• 基于坐标的点击在响应式布局上失败
• 基于视觉的方法速度慢且成本高

agent-browser 的解决方案：

# 1. 获取带有稳定引用的快照
agent-browser snapshot -i --json
# 输出: - button "Submit" [ref=e2]

# 2. 永久使用该引用 — 它指向确切的元素
agent-browser click @e2

• 引用是确定性的 — @e2 始终指向快照中的同一元素
• 无需重新查询 DOM — 直接引用更快、更可靠
• 针对 AI 优化 — LLM 自然地解析无障碍树，而不是 CSS 混合体

2. 无障碍树 > 截图/HTML

传统工具提供原始 HTML（嘈杂）或截图（需要视觉模型）。

agent-browser 提供无障碍树 — 人类（或屏幕阅读器）感知的干净、语义化表示：

- heading "Billing" [level=1]
- link "Make a payment" [ref=e10]
- button "Submit" [ref=e2]
- textbox "Email" [ref=e3]

• 语义角色（button、link、textbox、heading）
• 人类可读的标签
• 层次结构
• 完美适配 LLM 理解

3. 为 AI 智能体构建

功能	传统工具	agent-browser
元素定位	脆弱的选择器	确定性引用
页面理解	原始 HTML	无障碍树
输出格式	文本日志	结构化 JSON
速度	慢（每个命令启动完整浏览器）	快（守护进程持久化）
AI 集成	事后补充	专用构建

4. 快速架构

• Rust CLI — 原生二进制文件，即时命令解析
• Node.js 守护进程 — 浏览器在命令之间保持活跃
• 首次命令： ~2秒（守护进程启动）
• 后续命令： ~100毫秒

前置条件

npm install -g agent-browser
agent-browser install  # 下载 Chromium（约30秒）

核心 AI 工作流

为 LLM 智能体设计的工作流：

# 步骤 1：导航
agent-browser open https://example.com

# 步骤 2：获取结构化快照（AI "看到" 页面）
agent-browser snapshot -i --json

# 步骤 3：AI 从 JSON 中选择引用，执行操作
agent-browser click @e2
agent-browser fill @e3 "test@example.com"

# 步骤 4：更改后重新快照（状态验证）
agent-browser snapshot -i --json

# 步骤 5：完成
agent-browser close

命令

导航

agent-browser open example.com
agent-browser open example.com --json            # JSON 响应
agent-browser open example.com --headed          # 可见浏览器

快照（杀手级功能）

agent-browser snapshot                           # 完整无障碍树
agent-browser snapshot -i                        # 仅交互元素（更快）
agent-browser snapshot -i --json                 # 用于 AI 解析的 JSON
agent-browser snapshot -i -c -d 5 --json         # 紧凑，深度限制

交互（使用确定性引用）

agent-browser click @e2                          # 点击元素 @e2
agent-browser fill @e3 "text"                    # 填充并清空
agent-browser type @e3 "text"                    # 输入而不清空
agent-browser press Enter                        # 按键
agent-browser hover @e4                          # 悬停

状态验证

agent-browser get text @e1                       # 获取元素文本
agent-browser get url                            # 当前 URL
agent-browser is visible @e2                     # 检查可见性

会话管理

agent-browser --session login open site.com      # 隔离会话
agent-browser --profile ~/.myprofile open site   # 持久化 cookies
agent-browser close                              # 清理

选择器策略（按可靠性排名）

1. 引用（最佳 - 使用这些）

# 来自快照输出 — 确定且稳定
agent-browser click @e2
agent-browser fill @e3 "text"

2. 语义定位器（良好）

agent-browser find role button click --name "Submit"
agent-browser find label "Email" fill "test@test.com"

3. CSS 选择器（适用于静态站点）

agent-browser click "#submit"
agent-browser click ".btn-primary"

4. 文本/XPath（最后手段）

agent-browser click "text=Submit"
agent-browser click "xpath=//button[1]"

快照选项

控制 AI "看到" 的内容：

标志	用途
-i	仅交互元素（按钮、链接、输入）— 推荐
-C	包含光标交互元素（onclick、cursor:pointer）
-c	紧凑（移除空的结构元素）
-d <n>	限制树深度
-s <sel>	范围限制到 CSS 选择器（例如 #main）
--json	机器可读的 JSON 输出 — AI 必需

推荐的 AI 命令：

agent-browser snapshot -i -c --json

选项

标志	描述
--json	带有 success/data/error 结构的 JSON 输出
--headed	显示浏览器窗口（用于调试）
--session <name>	隔离的浏览器会话
--profile <path>	用于 cookies/登录的持久化配置文件
--cdp <port>	通过 DevTools 协议连接到现有 Chrome
--headers <json>	按源设置认证头

示例：完整登录流程

# 开始
agent-browser open https://portal.aeronetpr.com

# 获取页面结构
SNAPSHOT=$(agent-browser snapshot -i --json)
# AI 解析 JSON：看到 textbox @e1（用户名）、textbox @e2（密码）、button @e3（登录）

# 执行登录
agent-browser fill @e1 "username"
agent-browser fill @e2 "password"
agent-browser click @e3

# 验证成功（等待导航，重新快照）
sleep 2
agent-browser snapshot -i --json

# 完成
agent-browser close

AI 智能体技巧

1. 始终使用 --json — 结构化输出比文本更容易解析
2. 使用 -i 标志 — 仅交互快照更小、更快、更干净
3. 操作后重新快照 — 验证状态按预期更改
4. 信任引用胜过选择器 — 快照中的 @e2 > 可能会改变的 #id
5. 当引用过期时使用语义定位器 — find role button click 很健壮
6. 会话持久化 — 一次 open，多个命令，一次 close

与其他工具的比较

工具	最适合	agent-browser 的优势
Puppeteer/Playwright	开发测试	为人类构建；选择器脆弱
Selenium	传统测试	慢、重、基于选择器
browser-use	Python 智能体	agent-browser 有更好的引用系统
截图 + 视觉	视觉任务	agent-browser 快 10 倍，便宜 100 倍
OpenClaw browser 工具	简单任务	agent-browser 更好地处理复杂流程

何时使用此技能

在以下情况使用 agent-browser：

• 自动化多步骤 Web 工作流
• 填写复杂表单
• 需要可靠、可重复的自动化
• 处理动态/现代 Web 应用
• 成本重要（无视觉 API 调用）

在以下情况使用 OpenClaw 内置浏览器工具：

• 简单的单页检查
• 需要快速截图
• Chrome 中已有经过身份验证的会话

资源

• Vercel Labs 仓库： https://github.com/vercel-labs/agent-browser
• 此技能仓库： https://github.com/clawdbrunner/skill-agent-browser