使用 agent-browser 进行浏览器自动化

安装

npm 推荐方式

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

源码安装

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

快速开始

bash
agent-browser open # 导航到页面
agent-browser snapshot -i # 获取带引用的可交互元素
agent-browser click @e1 # 通过引用点击元素
agent-browser fill @e2 text # 通过引用填写输入框
agent-browser close # 关闭浏览器

核心工作流程

1. 1. 导航：agent-browser open
2. 快照：agent-browser snapshot -i（返回带有 @e1、@e2 等引用的元素）
3. 使用快照中的引用进行交互
4. 导航或重大 DOM 变化后重新快照

命令

导航

bash
agent-browser open # 导航到 URL
agent-browser back # 后退
agent-browser forward # 前进
agent-browser reload # 刷新页面
agent-browser close # 关闭浏览器

快照（页面分析）

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

交互（使用快照中的 @refs）

bash
agent-browser click @e1 # 点击
agent-browser dblclick @e1 # 双击
agent-browser focus @e1 # 聚焦元素
agent-browser fill @e2 text # 清空并输入
agent-browser type @e2 text # 不清空直接输入
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 value # 选择下拉菜单
agent-browser scroll down 500 # 滚动页面
agent-browser scrollintoview @e1 # 将元素滚动到可视区域
agent-browser drag @e1 @e2 # 拖放
agent-browser upload @e1 file.pdf # 上传文件

获取信息

bash
agent-browser get text @e1 # 获取元素文本
agent-browser get html @e1 # 获取 innerHTML
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 # 获取边界框

检查状态

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

截图与 PDF

bash
agent-browser screenshot # 截图输出到标准输出
agent-browser screenshot path.png # 保存到文件
agent-browser screenshot --full # 全页面截图
agent-browser pdf output.pdf # 保存为 PDF

视频录制

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

录制会创建新的上下文，但保留会话中的 cookie/存储。如果未提供 URL，会自动返回当前页面。为获得流畅的演示效果，请先探索页面，再开始录制。

等待

bash
agent-browser wait @e1 # 等待元素
agent-browser wait 2000 # 等待毫秒数
agent-browser wait --text Success # 等待文本
agent-browser wait --url /dashboard # 等待 URL 模式
agent-browser wait --load networkidle # 等待网络空闲
agent-browser wait --fn window.ready # 等待 JS 条件

鼠标控制

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

语义定位器（替代引用）

bash
agent-browser find role button click --name Submit
agent-browser find text Sign In click
agent-browser find label Email fill user@test.com
agent-browser find first .item click
agent-browser find nth 2 a text

浏览器设置

bash
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 # 模拟配色方案

Cookie 与存储

bash
agent-browser cookies # 获取所有 cookie
agent-browser cookies set name value # 设置 cookie
agent-browser cookies clear # 清除 cookie
agent-browser storage local # 获取所有 localStorage
agent-browser storage local key # 获取特定键
agent-browser storage local set k v # 设置值
agent-browser storage local clear # 清除所有

网络

bash
agent-browser network route # 拦截请求
agent-browser network route --abort # 阻止请求
agent-browser network route --body {} # 模拟响应
agent-browser network unroute [url] # 移除路由
agent-browser network requests # 查看跟踪的请求
agent-browser network requests --filter api # 过滤请求

标签页与窗口

bash
agent-browser tab # 列出标签页
agent-browser tab new [url] # 新建标签页
agent-browser tab 2 # 切换到标签页
agent-browser tab close # 关闭标签页
agent-browser window new # 新建窗口

框架

bash
agent-browser frame #iframe # 切换到 iframe
agent-browser frame main # 返回主框架

对话框

bash
agent-browser dialog accept [text] # 接受对话框
agent-browser dialog dismiss # 关闭对话框

JavaScript

bash
agent-browser eval document.title # 运行 JavaScript

状态管理

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

示例：表单提交

bash
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 # 检查结果

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

bash

登录一次

后续会话：加载保存的状态