用途
agent-browser 是一个基于 Rust 的无头浏览器自动化 CLI，并提供 Node.js 回退方案，用于让 AI 智能体以结构化命令操作网页：导航、点击、输入、快照页面等。
安装
推荐使用 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 # 获取带 ref 的交互元素
agent-browser click @e1 # 按 ref 点击元素
agent-browser fill @e2 "text" # 按 ref 填充输入框
agent-browser close # 关闭浏览器
核心工作流：导航（open）→ 快照（snapshot -i，返回 @e1、@e2 等 ref）→ 使用快照中的 ref 交互 → 导航或 DOM 发生重大变化后重新快照。
主要能力
导航：open、back、forward、reload、close。
快照（页面分析）：snapshot（完整可访问性树）、snapshot -i（仅交互元素，推荐）、snapshot -c（紧凑输出）、snapshot -d 3（限制深度）、snapshot -s "#main"（限定 CSS 选择器范围）。
交互（使用快照中的 @ref）：click、dblclick、focus、fill（清空并输入）、type（不清空直接输入）、press（按键）、press Control+a（组合键）、keydown、keyup、hover、check、uncheck、select、scroll、scrollintoview、drag、upload。
获取信息：get text、get html、get value、get attr、get title、get url、get count、get box。
检查状态：is visible、is enabled、is checked。
截图与 PDF：screenshot（输出到 stdout 或文件）、screenshot --full（整页）、pdf output.pdf。
视频录制：record start ./demo.webm、record stop、record restart ./take2.webm。录制会创建全新上下文，但保留当前会话的 cookies/storage；未提供 URL 时自动返回当前页面。建议先探索再开始录制以获得流畅演示。
等待：wait @e1（等待元素）、wait 2000（等待毫秒）、wait --text "Success"、wait --url "/dashboard"、wait --load networkidle、wait --fn "window.ready"。
鼠标控制：mouse move、mouse down、mouse up、mouse wheel。
语义定位（ref 的替代方案）：find role button click --name "Submit"、find text "Sign In" click、find label "Email" fill "user@test.com"、find first ".item" click、find nth 2 "a" text。
浏览器设置：set viewport、set device、set geo、set offline、set headers、set credentials、set media。
Cookies 与存储：cookies（获取/设置/清除）、storage local（获取/设置/清除）。
网络：network route（拦截/阻断/模拟响应）、network unroute、network requests（查看/过滤请求）。
标签页与窗口：tab（列出/新建/切换/关闭）、window new。
框架：frame "#iframe"、frame main。
对话框：dialog accept、dialog dismiss。
JavaScript：eval "document.title"。
状态管理：state save auth.json、state load auth.json。
使用示例
表单提交：
agent-browser open https://example.com/form
agent-browser snapshot -i
# 输出显示：textbox "Email" [ref=e1], textbox "Password" [ref=e2], button "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 # 开始记录 trace
agent-browser trace stop trace.zip # 停止并保存 trace
agent-browser record start ./debug.webm # 从当前页面录制
agent-browser record stop # 保存录制
agent-browser --cdp 9222 snapshot # 通过 CDP 连接
故障排查
- 在 Linux ARM64 上若找不到命令，请使用 bin 文件夹中的完整路径。
- 若找不到元素，使用 snapshot 查找正确的 ref。
- 若页面未加载，在导航后添加 wait 命令。
- 使用 --headed 查看浏览器窗口进行调试。
选项
- --session：使用隔离会话。
- --json：提供 JSON 输出。
- --full：整页截图。
- --headed：显示浏览器窗口。
- --timeout：设置命令超时（毫秒）。
- --cdp：通过 Chrome DevTools Protocol 连接。
注意事项
- ref 在单次页面加载内稳定，但导航后会变化。
- 导航后务必重新快照以获取新 ref。
- 输入框建议使用 fill 而非 type，以确保清空已有文本。
报告问题
- Skill 问题：在 https://github.com/TheSethRose/Agent-Browser-CLI 提交 issue。
- agent-browser CLI 问题：在 https://github.com/vercel-labs/agent-browser 提交 issue。