---

名称：Agent Browser
描述：一个基于 Rust 的快速无头浏览器自动化 CLI（支持 Node.js 回退），允许 AI 代理通过结构化命令实现页面导航、点击、输入和快照截取。
使用场景：

• 自动化网页交互
• 从页面提取结构化数据
• 程序化表单填写
• 网页 UI 测试
  元数据：{"clawdbot":{"emoji":"🌐","requires":{"bins":["node","npm"]}}}
  允许使用的工具：Bash(agent-browser:*)

使用 agent-browser 实现浏览器自动化

安装指南

推荐通过 npm 安装

npm install -g agent-browser  
agent-browser install  
agent-browser install --with-deps  

源码编译安装

git clone https://github.com/vercel-labs/agent-browser  
cd agent-browser  
pnpm install  
pnpm build  
agent-browser install  

快速入门

agent-browser open <url>        # 导航至指定页面  
agent-browser snapshot -i       # 获取带引用标识的交互元素  
agent-browser click @e1         # 通过引用标识点击元素  
agent-browser fill @e2 "文本"   # 通过引用标识填写输入框  
agent-browser close             # 关闭浏览器  

核心工作流

1. 导航：agent-browser open <url>
2. 快照：agent-browser snapshot -i（返回带有 @e1、@e2 等引用标识的元素）
3. 使用快照中的引用标识进行交互
4. 页面导航或 DOM 发生重大变更后重新获取快照

命令

导航控制

agent-browser open <url>      # 打开指定网址
agent-browser back            # 后退
agent-browser forward         # 前进
agent-browser reload          # 刷新页面
agent-browser close           # 关闭浏览器

页面快照（分析）

agent-browser snapshot            # 完整无障碍访问树
agent-browser snapshot -i         # 仅交互元素（推荐）
agent-browser snapshot -c         # 紧凑输出格式
agent-browser snapshot -d 3       # 限制深度为3层
agent-browser snapshot -s "#main" # 限定CSS选择器范围

交互操作（使用快照中的@ref引用）

agent-browser click @e1           # 点击元素
agent-browser dblclick @e1        # 双击元素
agent-browser focus @e1           # 聚焦元素
agent-browser fill @e2 "文本"     # 清空并输入文本
agent-browser type @e2 "文本"     # 直接输入文本（不清空）
agent-browser press Enter         # 按键操作
agent-browser press Control+a     # 组合键操作
agent-browser keydown Shift       # 长按按键
agent-browser keyup Shift         # 释放按键
agent-browser hover @e1           # 悬停元素
agent-browser check @e1           # 勾选复选框
agent-browser uncheck @e1         # 取消勾选
agent-browser select @e1 "值"     # 选择下拉选项
agent-browser scroll down 500     # 滚动页面
agent-browser scrollintoview @e1  # 滚动至元素可见
agent-browser drag @e1 @e2        # 拖放操作
agent-browser upload @e1 file.pdf # 文件上传

信息获取

agent-browser get text @e1        # 获取元素文本
agent-browser get html @e1        # 获取内部HTML
agent-browser get value @e1       # 获取输入值
agent-browser get attr @e1 href   # 获取元素属性
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      # 检查是否勾选

截图与PDF

agent-browser screenshot          # 截图输出到stdout
agent-browser screenshot path.png # 保存截图文件
agent-browser screenshot --full   # 整页截图
agent-browser pdf output.pdf      # 保存为PDF

屏幕录制

agent-browser record start ./demo.webm    # 开始录制（使用当前URL状态）
agent-browser click @e1                   # 执行操作
agent-browser record stop                 # 停止并保存视频
agent-browser record restart ./take2.webm # 重启新录制

录制会创建全新上下文但保留会话中的cookies/存储数据。若未指定URL，则自动返回当前页面。制作演示时建议先探索页面，再开始录制。

等待控制

agent-browser wait @e1                     # 等待元素出现
agent-browser wait 2000                    # 等待毫秒数
agent-browser wait --text "成功"           # 等待文本出现
agent-browser wait --url "/dashboard"      # 等待URL匹配
agent-browser wait --load networkidle      # 等待网络空闲
agent-browser wait --fn "window.ready"     # 等待JS条件成立

鼠标控制

agent-browser mouse move 100 200      # 移动鼠标坐标
agent-browser mouse down left         # 按下左键
agent-browser mouse up left           # 释放左键
agent-browser mouse wheel 100         # 滚轮滚动

语义定位器（替代@ref引用）

agent-browser find role button click --name "提交"
agent-browser find text "登录" click
agent-browser find label "邮箱" fill "user@test.com"
agent-browser find first ".item" click
agent-browser find nth 2 "a" text

浏览器设置

agent-browser set viewport 1920 1080      # 设置视窗尺寸
agent-browser set device "iPhone 14"      # 模拟设备
agent-browser set geo 37.7749 -122.4194   # 设置地理位置
agent-browser set offline on              # 切换离线模式
agent-browser set headers '{"X-Key":"v"}' # 设置HTTP头
agent-browser set credentials user pass   # HTTP基础认证
agent-browser set media dark              # 模拟暗色模式

Cookies与存储

agent-browser cookies                     # 获取所有cookies
agent-browser cookies set name value      # 设置cookie
agent-browser cookies clear               # 清除cookies
agent-browser storage local               # 获取本地存储
agent-browser storage local key           # 获取指定键值
agent-browser storage local set k v       # 设置存储值
agent-browser storage local clear         # 清空存储

网络控制

agent-browser network route <url>              # 拦截请求
agent-browser network route <url> --abort      # 阻断请求
agent-browser network route <url> --body '{}'  # 模拟响应
agent-browser network unroute [url]            # 取消拦截
agent-browser network requests                 # 查看请求记录
agent-browser network requests --filter api    # 过滤请求

标签页与窗口

agent-browser tab                 # 列出标签页
agent-browser tab new [url]       # 新建标签页
agent-browser tab 2               # 切换至第2个标签页
agent-browser tab close           # 关闭当前标签页
agent-browser window new          # 新建窗口

框架控制

agent-browser frame "#iframe"     # 切换至iframe框架
agent-browser frame main          # 返回主框架

对话框处理

agent-browser dialog accept [text]  # 接受对话框
agent-browser dialog dismiss        # 取消对话框

JavaScript执行

agent-browser eval "document.title"   # 执行JavaScript代码

状态管理

agent-browser state save auth.json    # 保存会话状态
agent-browser state load auth.json    # 加载保存状态

示例：表单提交

agent-browser open https://example.com/form
agent-browser snapshot -i
# 输出显示：文本框 "Email" [ref=e1]，文本框 "Password" [ref=e2]，按钮 "Submit" [ref=e3]

agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser snapshot -i  # 检查结果

示例：使用保存的状态进行认证

# 首次登录
agent-browser open https://app.example.com/login
agent-browser snapshot -i
agent-browser fill @e1 "username"
agent-browser fill @e2 "password"
agent-browser click @e3
agent-browser wait --url "/dashboard"
agent-browser state save auth.json

# 后续会话：加载保存的状态
agent-browser state load auth.json
agent-browser open https://app.example.com/dashboard

会话（并行浏览器）

agent-browser --session test1 open site-a.com
agent-browser --session test2 open site-b.com
agent-browser session list

JSON 输出（用于解析）

添加 --json 参数以生成机器可读的输出：

agent-browser snapshot -i --json
agent-browser get text @e1 --json

调试

agent-browser open example.com --headed              # 显示浏览器窗口
agent-browser console                                # 查看控制台消息
agent-browser console --clear                        # 清空控制台
agent-browser errors                                 # 查看页面错误
agent-browser errors --clear                         # 清空错误
agent-browser highlight @e1                          # 高亮元素
agent-browser trace start                            # 开始记录跟踪
agent-browser trace stop trace.zip                   # 停止并保存跟踪
agent-browser record start ./debug.webm              # 从当前页面开始录制
agent-browser record stop                            # 保存录制
agent-browser --cdp 9222 snapshot                    # 通过 CDP 连接

故障排除

• 如果在 Linux ARM64 上未找到命令，请使用 bin 文件夹中的完整路径。
• 如果找不到元素，请使用 snapshot 找到正确的 ref。
• 如果页面未加载，请在导航后添加等待命令。
• 使用 --headed 查看浏览器窗口以进行调试。

选项

• --session <name> 使用隔离会话。
• --json 提供 JSON 输出。
• --full 截取完整页面截图。
• --headed 显示浏览器窗口。
• --timeout 设置命令超时时间，单位为毫秒。
• --cdp <port> 通过 Chrome DevTools Protocol 连接。

注意事项

• refs 在每个页面加载时是稳定的，但在导航后会发生变化。
• 总是在导航后进行 snapshot 以获取新的 refs。
• 在输入字段中使用 fill 而不是 type，以确保清除现有文本。

报告问题

• 技能问题：在 https://github.com/TheSethRose/Agent-Browser-CLI 提交问题。
• agent-browser CLI 问题：在 https://github.com/vercel-labs/agent-browser 提交问题。