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

快速入门

agent-browser open <url>        # 打开指定网页
agent-browser snapshot -i       # 获取可交互元素及其引用（refs）
agent-browser click @e1         # 通过引用点击元素
agent-browser fill @e2 "text"   # 通过引用填写输入框
agent-browser close             # 关闭浏览器

核心工作流程

1. 导航：agent-browser open <url>
2. 快照：agent-browser snapshot -i（返回带有引用如 @e1、@e2 的元素）
3. 使用快照中获取的引用进行操作
4. 导航或 DOM 发生显著变化后重新执行快照

命令

导航

agent-browser open <url>      # 打开指定 URL（别名：goto, navigate）
                              # 支持协议：https://, http://, file://, about:, data://
                              # 若未指定协议，自动补全为 https://
agent-browser back            # 后退
agent-browser forward         # 前进
agent-browser reload          # 刷新页面
agent-browser close           # 关闭浏览器（别名：quit, exit）
agent-browser connect 9222    # 通过 CDP 端口连接浏览器

快照（页面分析）

agent-browser snapshot            # 获取完整的可访问性树
agent-browser snapshot -i         # 仅获取可交互元素（推荐使用）
agent-browser snapshot -c         # 紧凑输出格式
agent-browser snapshot -d 3       # 限制深度为 3 层
agent-browser snapshot -s "#main" # 限定作用域至 CSS 选择器

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

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         # 按下按键（别名：key）
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 select @e1 "a" "b"  # 多选选项
agent-browser scroll down 500     # 滚动页面（默认向下滚动 300px）
agent-browser scrollintoview @e1  # 将元素滚动到可视区域（别名：scrollinto）
agent-browser drag @e1 @e2        # 拖拽元素
agent-browser upload @e1 file.pdf # 上传文件

获取信息

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         # 获取元素边界框信息
agent-browser get styles @e1      # 获取计算后的样式（字体、颜色、背景等）

检查状态

agent-browser is visible @e1      # 检查元素是否可见
agent-browser is enabled @e1      # 检查元素是否启用
agent-browser is checked @e1      # 检查是否被选中

截图与 PDF 输出

agent-browser screenshot          # 保存到临时目录
agent-browser screenshot path.png # 保存到指定路径
agent-browser screenshot --full   # 保存整页截图
agent-browser pdf output.pdf      # 保存为 PDF 文件

视频录制

agent-browser record start ./demo.webm    # 开始录制（使用当前页面和状态）
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 "Success"        # 等待文本出现（别名：-t）
agent-browser wait --url "**/dashboard"    # 等待 URL 匹配模式（别名：-u）
agent-browser wait --load networkidle      # 等待网络空闲（别名：-l）
agent-browser wait --fn "window.ready"     # 等待 JavaScript 条件成立（别名：-f）

鼠标控制

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

语义定位器（替代引用的方式）

agent-browser find role button click --name "Submit"
agent-browser find text "Sign In" click
agent-browser find text "Sign In" click --exact      # 仅精确匹配
agent-browser find label "Email" fill "user@test.com"
agent-browser find placeholder "Search" type "query"
agent-browser find alt "Logo" click
agent-browser find title "Close" click
agent-browser find testid "submit-btn" click
agent-browser find first ".item" click
agent-browser find last ".item" click
agent-browser find nth 2 "a" hover

浏览器设置

agent-browser set viewport 1920 1080          # 设置视口大小
agent-browser set device "iPhone 14"          # 模拟设备
agent-browser set geo 37.7749 -122.4194       # 设置地理位置（别名：geolocation）
agent-browser set offline on                  # 切换离线模式
agent-browser set headers '{"X-Key":"v"}'     # 添加额外 HTTP 头
agent-browser set credentials user pass       # 设置 HTTP 基本认证（别名：auth）
agent-browser set media dark                  # 模拟深色主题
agent-browser set media light reduced-motion  # 浅色主题 + 减少动画

Cookies 与存储

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         # 清空全部

### Network

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 # 过滤 API 请求

### Tabs & Windows

agent-browser tab # 列出所有标签页

agent-browser tab new [url] # 新建标签页

agent-browser tab 2 # 切换到指定索引的标签页

agent-browser tab close # 关闭当前标签页

agent-browser tab close 2 # 关闭指定索引的标签页

agent-browser window new # 新建窗口

### Frames

agent-browser frame "#iframe" # 切换到 iframe

agent-browser frame main # 返回主框架

### Dialogs

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

agent-browser dialog dismiss # 取消对话框

### JavaScript

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

## 全局选项

agent-browser --session <name> ... # 使用独立的浏览器会话

agent-browser --json ... # 输出 JSON 格式，便于程序解析

agent-browser --headed ... # 显示浏览器窗口（非无头模式）

agent-browser --full ... # 截取完整页面截图（-f）

agent-browser --cdp <port> ... # 通过 Chrome DevTools Protocol 连接

agent-browser -p <provider> ... # 使用云浏览器服务提供商（--provider）

agent-browser --proxy <url> ... # 使用代理服务器

agent-browser --headers <json> ... # 为 URL 的源设置 HTTP 头信息

agent-browser --executable-path <p> # 指定自定义浏览器可执行文件路径

agent-browser --extension <path> ... # 加载浏览器扩展（可重复使用）

agent-browser --help # 显示帮助信息（-h）

agent-browser --version # 显示版本号（-V）

agent-browser <command> --help # 查看特定命令的详细帮助

### 代理支持

agent-browser --proxy http://proxy.com:8080 open example.com

agent-browser --proxy http://user:pass@proxy.com:8080 open example.com

agent-browser --proxy socks5://proxy.com:1080 open example.com

## 环境变量

AGENT_BROWSER_SESSION="mysession" # 默认会话名称

AGENT_BROWSER_EXECUTABLE_PATH="/path/chrome" # 自定义浏览器路径

AGENT_BROWSER_EXTENSIONS="/ext1,/ext2" # 以逗号分隔的扩展路径列表

AGENT_BROWSER_PROVIDER="your-cloud-browser-provider" # 云浏览器服务提供商（如 browseruse 或 browserbase）

AGENT_BROWSER_STREAM_PORT="9223" # WebSocket 流媒体端口

AGENT_BROWSER_HOME="/path/to/agent-browser" # 自定义安装路径（用于 daemon.js）

## 示例：表单提交

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 --headed open example.com # 显示浏览器窗口

agent-browser --cdp 9222 snapshot # 通过 CDP 端口连接

agent-browser connect 9222 # 替代方式：使用 connect 命令

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 # 保存录制内容

## 深入文档

关于高级用法和最佳实践，请参考以下资料：

| 参考文档 | 说明 |
|--------|------|
| [references/snapshot-refs.md](references/snapshot-refs.md) | 快照引用生命周期、失效规则、故障排查 |
| [references/session-management.md](references/session-management.md) | 并行会话、状态持久化、并发抓取策略 |
| [references/authentication.md](references/authentication.md) | 登录流程、OAuth、双因素认证处理、状态复用 |
| [references/video-recording.md](references/video-recording.md) | 录制操作流程用于调试与文档编写 |
| [references/proxy-support.md](references/proxy-support.md) | 代理配置、地理测试、轮换代理设置 |

## 可直接使用的模板

适用于常见场景的工作流脚本：

| 模板 | 描述 |
|------|------|
| [templates/form-automation.sh](templates/form-automation.sh) | 带有验证的表单自动填写 |
| [templates/authenticated-session.sh](templates/authenticated-session.sh) | 登录一次，重复使用会话状态 |
| [templates/capture-workflow.sh](templates/capture-workflow.sh) | 内容提取并生成截图 |

使用方法：

./templates/form-automation.sh https://example.com/form

./templates/authenticated-session.sh https://app.example.com/login

./templates/capture-workflow.sh https://example.com ./output

## HTTPS 证书错误处理

对于使用自签名或无效证书的网站：

agent-browser open https://localhost:8443 --ignore-https-errors