名称： agent-browser
描述： 自动化浏览器交互，用于网页测试、表单填写、截图和数据提取。当用户需要导航网站、与网页交互、填写表单、截图、测试Web应用程序或从网页提取信息时使用。
允许工具： Bash(agent-browser:*)
agent-browser open <url> # 导航到页面
agent-browser snapshot -i # 获取带引用标识的交互元素
agent-browser click @e1 # 通过引用标识点击元素
agent-browser fill @e2 "text" # 通过引用标识填写输入框
agent-browser close # 关闭浏览器
agent-browser open <url>agent-browser snapshot -i (返回带有 @e1、@e2 等引用标识的元素)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选择器范围
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 # 滚动页面 (默认: 向下300像素)
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 # 检查是否勾选
agent-browser screenshot # 截图到标准输出
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 "Success" # 等待文本出现 (或 -t)
agent-browser wait --url "**/dashboard" # 等待URL模式匹配 (或 -u)
agent-browser wait --load networkidle # 等待网络空闲 (或 -l)
agent-browser wait --fn "window.ready" # 等待JS条件满足 (或 -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 # 浅色模式 + 减少动画
agent-browser cookies # 获取所有cookies
agent-browser cookies set name value # 设置cookie
agent-browser cookies clear # 清除cookies
agent-browser storage local # 获取所有localStorage
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 # 按索引切换到标签页
agent-browser tab close # 关闭当前标签页
agent-browser tab close 2 # 按索引关闭标签页
agent-browser window new # 新建窗口
agent-browser frame "#iframe" # 切换到iframe
agent-browser frame main # 返回主框架
agent-browser dialog accept [text] # 接受对话框
agent-browser dialog dismiss # 关闭对话框
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协议连接
agent-browser -p <provider> ... # 云浏览器提供商 (--provider)
agent-browser --proxy <url> ... # 使用代理服务器
agent-browser --headers <json> ... # HTTP头 (限定到URL的源)
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 以获得机器可读的输出：
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/session-management.md | 并行会话、状态持久化、并发抓取 |
| references/authentication.md | 登录流程、OAuth、2FA处理、状态复用 |
| references/video-recording.md | 用于调试和文档的录制工作流 |
| references/proxy-support.md | 代理配置、地理测试、轮换代理 |
常见模式的可执行工作流脚本：
| 模板 | 描述 |
|---|---|
| templates/form-automation.sh | 带验证的表单填写 |
| templates/authenticated-session.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
对于使用自签名或无效证书的网站：
agent-browser open https://localhost:8443 --ignore-https-errors