注意事项

自动安装： 已预装 agent-browser 和 Chromium, 能直接使用，默认headless模式。

1. 1. 进程清理：使用完毕后，清理残留进程

1. 2. Session 隔离：多任务使用 --session 避免冲突
2. Profile 持久化：需要保存登录状态时使用 --profile
3. Ref 有效期：页面刷新后 refs 失效，需要重新 snapshot
4. 资源释放：长时间运行后记得 close 关闭浏览器

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

快速开始

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

核心工作流程

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

命令

导航

bash
agent-browser open # 导航到 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 端口连接浏览器

快照（页面分析）

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 # 按键（别名：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 # 上传文件

获取信息

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 # 获取边界框
agent-browser get styles @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 # 停止当前录制并开始新录制

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

等待

bash
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）

鼠标控制

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

语义定位器（refs 的替代方案）

bash
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

浏览器设置

bash
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 与存储

bash
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 # 清除所有

网络

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 tab close 2 # 按索引关闭标签页
agent-browser window new # 新建窗口

框架

bash
agent-browser frame