agent-browser-commands

Agent Browser — 命令参考

内部参考。 对于浏览器自动化任务，请将 agent-browser skill 作为入口。

---

导航

命令	说明	适用场景
open <url>	导航至 URL（支持 chrome:// 和 chrome-extension://）	所有任务起点
back / forward	浏览器历史记录	多页流程回溯
reload	刷新页面	强制刷新状态
close	关闭浏览器	任务结束清理

---

发现

命令	说明	适用场景
snapshot	包含引用的无障碍树	获取交互元素引用
snapshot -i	仅显示交互元素	聚焦可操作元素
snapshot -c	精简模式（减少噪音）	大页面减少输出噪音
snapshot -d <n>	限制树的深度	只看顶层结构
snapshot -s <sel>	限定 CSS 选择器范围	弹窗/局部区域聚焦

---

交互

命令	说明	适用场景
click @e1	点击元素	按钮/链接触发
dblclick @e1	双击元素	可编辑单元格/选中文本
fill @e1 "text"	清除并填充输入框	表单输入（替换原值）
type @e1 "text"	输入但不清除（追加内容）	追加内容/受控组件
keyboard type "text"	在获得焦点的元素中输入——每个字符都会触发 keydown/keypress/input/keyup，但无法可靠触发 document 级别的 keydown 监听器；对于作用于 document 的事件处理器，请使用 eval dispatchEvent(new KeyboardEvent(...))	焦点已在目标时输入
keyboard inserttext "text"	绕过所有键盘事件插入文本（不会触发 keydown/keypress/keyup）	绕过键盘事件拦截直接插入文本
press <key>	按下指定按键：Enter、Tab、Control+a、ArrowDown	提交表单/快捷键/方向键
focus @e1	聚焦元素	聚焦后再使用 keyboard type
check @e1 / uncheck @e1	复选框/单选按钮	复选框/单选操作
select @e1 "option"	选择下拉选项	<select> 下拉菜单
hover @e1	将鼠标悬停在元素上	触发悬停菜单/Tooltip
drag @e1 @e2	将源元素拖到目标元素上——使用 Playwright 基于指针的拖拽；适用于基于鼠标事件的可拖拽库（Sortable.js、jQueryUI）。不会派发 HTML5 DragEvent（dragstart/dragover/drop）；对于 HTML5 Drag API，请使用 eval 手动派发 DragEvent	看板排序/指针拖拽
upload @e1 <file>	上传文件	文件上传表单
download @e1 <path>	点击元素下载文件	导出按钮触发下载
scroll down	滚动页面（上/下/左/右）	触发懒加载/加载更多
scroll down --selector ".modal"	在指定容器内滚动	弹窗内容滚动
scrollintoview @e1	将元素滚动至可视区域	元素不在视口时，点击前使用

对话框

命令	说明	适用场景
dialog accept	接受警告/确认对话框	确认操作类弹窗
dialog accept "text"	输入内容并接受提示对话框	在 Prompt 中输入后确认
dialog dismiss	关闭/取消对话框	取消操作/关闭 alert
dialog status	检查当前是否有对话框打开	断言弹窗是否存在

---

鼠标（精细控制）

在像素坐标处派发指针/鼠标事件。适用于画布、绘图应用和基于 CSS/指针事件的可拖拽组件。不会触发 HTML5 Drag API 事件（dragstart/dragover/drop）——这些事件需要使用 eval DragEvent。

命令	说明	适用场景
mouse move <x> <y>	将鼠标移动至指定坐标	画布/绘图应用
mouse down [btn]	按下鼠标按钮	拖拽起点
mouse up [btn]	松开鼠标按钮	拖拽终点
mouse wheel <dy> [dx]	滚动滚轮	精确滚动量控制

---

获取信息

命令	说明	适用场景
get text @e1	获取元素文本	断言显示内容
get html @e1	获取内部 HTML	复杂结构检查
get value @e1	获取输入框的值	验证表单当前值
get attr @e1 href	获取属性	检查链接/data 属性
get title / get url	页面信息	导航后验证路由
get count "selector"	统计匹配元素的数量	断言列表条目数量
get box @e1	获取边界框（x、y、width、height）	精确坐标/截图裁剪
get styles @e1	获取计算后的样式	CSS 样式调试
get cdp-url	当前页面的 CDP WebSocket URL	高级 CDP 调试

---

状态检查

命令	描述	适用场景
is visible @e1	检查是否可见	元素显示断言
is enabled @e1	检查是否启用	按钮可交互断言
is checked @e1	检查是否已选中	复选框状态断言

---

等待

命令	描述	适用场景
wait @e1	等待元素出现	异步内容渲染
wait @e1 --state hidden	等待元素消失	Loading spinner 消失
wait @e1 --state detached	等待元素从 DOM 中移除	弹窗关闭后继续
wait 1000	等待指定毫秒数	CSS 过渡动画完成
wait --load networkidle	等待网络空闲	页面加载/导航后
wait --url "**/dashboard"	等待 URL 匹配模式	登录后跳转验证
wait --fn "window.ready"	等待 JavaScript 表达式返回真值	自定义加载完成信号
wait --text "Welcome"	等待页面出现指定文本	异步文字渲染
wait --download [path]	等待下载完成	触发下载后等待完成

---

截图

命令	描述	适用场景
screenshot [path]	截取屏幕	当前视口快照
screenshot --full	截取完整页面	完整页面记录/证据
screenshot --annotate	带编号标签的标注截图	Bug 报告/文档截图
pdf <path>	保存为 PDF	生成可打印报告

截图选项：--screenshot-dir <path>（默认目录）、--screenshot-quality <0-100>（JPEG）、--screenshot-format png|jpeg

---

差异与视觉回归

diff snapshot

agent-browser diff snapshot                         # vs last snapshot in session
agent-browser diff snapshot --baseline before.txt   # vs saved snapshot file
agent-browser diff snapshot -s ".sidebar"           # scope to selector
agent-browser diff snapshot -c -d 3                 # compact + depth limit

适用场景：检测 DOM 结构变化，对比前后差异

diff screenshot

agent-browser diff screenshot --baseline before.png
agent-browser diff screenshot --baseline before.png --output diff.png --threshold 0.1
agent-browser diff screenshot --baseline before.png -s "#main-content" --full

适用场景：视觉回归测试，--threshold 0~1（默认为 0.1，数值越小越严格）

diff url

agent-browser diff url https://staging.example.com https://prod.example.com
agent-browser diff url https://v1.example.com https://v2.example.com --screenshot --full
agent-browser diff url <u1> <u2> --wait-until networkidle

适用场景：跨环境/版本对比，使用 --screenshot 同时对比截图

---

调试

命令	描述	适用场景
inspect	打开 Chrome DevTools（CLI 仍可使用）	交互式调试
console	查看控制台日志	查看 JS 输出
console --pattern "err"	筛选控制台日志	快速定位错误日志
console --clear	清空控制台日志缓冲区	重置观察窗口
errors	查看 JavaScript 错误	最先检查，覆盖 80% 的问题
errors --clear	清空错误缓冲区	重置错误计数
highlight <sel>	直观高亮元素	可视化确认定位
network requests	查看所有网络请求	全量 API 调用记录
network requests --filter "api"	按 URL 模式筛选	聚焦特定接口
network requests --type xhr,fetch	按资源类型筛选	只看 XHR/Fetch
network requests --method POST	按 HTTP 方法筛选	只看写操作
network requests --status 4xx	按状态码筛选	快速查找失败请求
network requests --clear	清空网络日志	重置记录
network request <requestId>	查看完整请求及响应正文	查看完整 payload
network har start [path]	开始 HAR 录制	完整网络追踪起点
network har stop	停止并保存 HAR 文件	导出供 DevTools 分析
trace start [path]	开始录制 Playwright 跟踪	Playwright 调试追踪
trace stop	停止跟踪	使用 Playwright Trace Viewer 打开
profiler start [path]	启动 Chrome DevTools 性能分析器	性能分析
profiler stop	停止性能分析器	导出性能报告
record start <path> [url]	开始录制视频（WebM）	录制演示/Bug 复现
record stop	停止并保存视频	保存视频
record restart <path> [url]	停止当前录制并开始新的录制	重新录制（重拍）
eval "JS code"	执行 JavaScript	自定义查询/状态注入
clipboard read	读取剪贴板内容	验证复制结果
clipboard write "text"	写入剪贴板	注入剪贴板数据
clipboard copy <sel>	将元素文本复制到剪贴板	提取内容
clipboard paste <sel>	将剪贴板内容粘贴到元素中	粘贴到输入框

---

网络模拟

命令	描述	适用场景
network route "**/*.png" --abort	拦截匹配的请求	屏蔽图片/广告，加快加载
network route "**/api/**" --body '{"ok":true}'	模拟响应正文	测试特定 API 响应
network unroute [url]	移除路由（未指定 URL 时移除全部路由）	恢复真实网络

---

存储

命令	描述	适用场景
cookies	查看所有 Cookie	会话状态检查
cookies set <name> <val> --domain example.com --secure --httpOnly	设置 Cookie	注入 Auth 令牌
cookies clear	清除所有 Cookie	重置会话状态
storage local	查看 localStorage	查看持久化数据
storage local get <key>	获取 localStorage 键	读取特定 key
storage local set <key> <val>	设置 localStorage 键	注入 token/配置
storage local clear	清除 localStorage	重置前端状态
storage session get <key>	SessionStorage（相同 API）	会话级数据操作

---

标签页

命令	描述	适用场景
tab new	打开新标签页	多标签流程
tab list	列出当前浏览器上下文中的所有标签页	查看已知标签
tab <n>	按索引切换标签页（从 0 开始）	切换到目标标签
tab close <n>	按索引关闭标签页	关闭辅助标签

target="_blank" 限制：点击 target="_blank" 链接时，浏览器可能会在新的 BrowserContext 中打开页面，agent-browser 的 tab list 只跟踪当前 context 内的标签页。如果新标签页没有出现在 tab list 中，请改用 tab new + open <url> 手动管理。

---

会话

命令	描述	适用场景
session	显示当前会话名称	确认当前会话
session list	列出活动会话	多会话并发查看

---

Auth Vault

保存并重复使用登录凭据，避免每次 E2E 运行时都手动登录：

# Save once
agent-browser auth save myapp --url http://localhost:5173/login --username admin --password secret

# Reuse in any test (auto-fills and submits login form)
agent-browser auth login myapp

# Manage
agent-browser auth list
agent-browser auth show myapp
agent-browser auth delete myapp

凭据使用 AES-256-GCM 加密（AGENT_BROWSER_ENCRYPTION_KEY）。建议使用 --password-stdin 而不是 --password，以避免凭据暴露在 Shell 历史记录中。

---

批量执行

通过标准输入以 JSON 数组的形式执行多条命令，比依次调用 Shell 更高效：

echo '[["fill","@e1","[email protected]"],["fill","@e2","pass"],["click","@e3"]]' | agent-browser batch
agent-browser batch --bail   # stop on first error (default: continue all)

---

确认

对于需要明确批准的操作（设置了 --confirm-actions 时）：

命令	描述	适用场景
confirm <id>	批准待处理的操作	审批写操作
deny <id>	拒绝待处理的操作	拒绝危险操作

---

设备 / 模拟

命令	描述	适用场景
set viewport <w> <h>	设置视口大小	响应式测试
set viewport <w> <h> <scale>	设置视口及设备像素比	Retina 屏测试
set device "iPhone 15 Pro"	预设设备模拟	移动端完整模拟
set geo <lat> <lng>	设置地理位置	地理位置功能测试
set offline [on|off]	切换离线模式（务必使用 set offline off 恢复）	PWA/离线模式测试
set headers <json>	设置作用于页面源的 HTTP 标头	注入 Authorization
set credentials <user> <pass>	HTTP 基本身份验证	Basic Auth 站点
set media dark	暗色模式	暗色主题测试
set media dark reduced-motion	暗色模式 + 减少动态效果	无障碍测试

iOS Simulator（需要 Xcode + Appium）：使用 -p ios 标志

agent-browser -p ios open http://localhost:3000
agent-browser -p ios --device "iPhone 15 Pro" snapshot
agent-browser -p ios device list
agent-browser -p ios swipe up

---

安装与设置

命令	描述	适用场景
install	下载 Chromium（首次设置）	首次安装
install --with-deps	同时安装系统依赖（Linux）	Linux CI 环境
upgrade	将 agent-browser 升级到最新版本（仅限 npm；Homebrew：brew upgrade agent-browser）	版本更新

---

语义定位器（find）

优先于 CSS 选择器使用，可在 UI 重构后继续生效：

agent-browser find role button click --name "Submit"
agent-browser find role link click --name "Learn More"
agent-browser find role button click --name "Submit" --exact   # exact name match
agent-browser find text "Sign In" click
agent-browser find label "Email" fill "[email protected]"
agent-browser find placeholder "Search..." type "query"
agent-browser find testid "submit-button" click
agent-browser find alt "Company logo" click
agent-browser find first "button.primary" click
agent-browser find last "a.link" click
agent-browser find nth 2 ".card" hover     # 0-based index

有效的 find 子命令：role、text、label、placeholder、alt、title、testid、first、last、nth ❌ 不存在 find ref。

使用快照中的 Ref

snapshot 会返回类似 [ref=e3] 的 ref。这些 ref 可以直接与操作命令搭配使用，而不是通过 find 使用：

# ✅ Direct ref usage
agent-browser click @e3
agent-browser fill @e3 "hello"
agent-browser hover @e3

# ✅ Refs in assertions
agent-browser is visible @e3
agent-browser get text @e3
agent-browser get value @e3

# ❌ Wrong — ref is not a find subcommand
agent-browser find ref e3 fill "hello"

---

全局选项

选项	描述
--headed	显示浏览器窗口；也可通过 AGENT_BROWSER_HEADED=1 设置
--engine chrome|lightpanda	浏览器引擎；也可通过 AGENT_BROWSER_ENGINE 设置
-p, --provider <name>	浏览器提供方：ios、browserbase、kernel、browseruse、browserless
--cdp <port>	通过 CDP 连接到 Chrome
--auto-connect	自动发现正在运行的 Chrome
--profile <path>	持久化浏览器配置文件（重复使用身份验证信息）
--session <name>	隔离会话
--session-name <name>	自动保存／恢复 cookies 和 localStorage
--state <path>	从 JSON 加载存储状态
--download-path <path>	默认下载目录；也可通过 AGENT_BROWSER_DOWNLOAD_PATH 设置
--headers '{"Authorization":"Bearer token"}'	身份验证标头
--proxy "http://127.0.0.1:7890"	代理服务（也会读取 HTTP_PROXY／HTTPS_PROXY／ALL_PROXY 环境变量作为备用值）
--proxy-bypass "localhost,*.internal"	绕过代理（也会读取 NO_PROXY 环境变量）
--color-scheme dark|light	配色方案偏好
--ignore-https-errors	忽略 TLS 证书错误
--allow-file-access	允许访问 file:// URL
--user-agent <ua>	自定义 User-Agent
--allowed-domains <list>	限制为已批准的域名（安全性）；--domain-allowlist 是别名
--action-policy <path>	定义允许／阻止的操作类别的 JSON 文件
--confirm-actions <list>	需要确认的操作类别
--confirm-interactive	在 TTY 中显示交互式确认提示
--content-boundaries	在页面输出中添加边界标记（便于解析 --max-output）
--max-output <chars>	将页面输出截断为 N 个字符；也可通过 AGENT_BROWSER_MAX_OUTPUT 设置
--json	JSON 输出
--full / -f	完整页面（截图）
--annotate	带注释的输出
--debug	调试输出

关键环境变量

变量	描述
AGENT_BROWSER_HEADED=1	显示浏览器窗口
AGENT_BROWSER_ENGINE=chrome|lightpanda	浏览器引擎（chrome 为默认值）
AGENT_BROWSER_NATIVE=1	⚠️ 旧版别名——接受但未在 0.22+ 中记录；建议省略（chrome 引擎为默认值）
AGENT_BROWSER_DEFAULT_TIMEOUT	默认操作超时时间，单位为 ms（默认值：25000）
AGENT_BROWSER_MAX_OUTPUT	页面输出的最大字符数
AGENT_BROWSER_STREAM_PORT	在指定端口启用 WebSocket 流式传输（例如：9223）
AGENT_BROWSER_IDLE_TIMEOUT_MS	空闲 N ms 后自动关闭守护进程
AGENT_BROWSER_ENCRYPTION_KEY	用于加密 Auth Vault 的 64 字符十六进制 AES-256-GCM 密钥
AGENT_BROWSER_SCREENSHOT_DIR	默认截图输出目录

---