SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场agent-browser

agent-browser

测试与质量

查看项目

更新于 10-16 02:24

技能介绍

用途

agent-browser 是一个 CLI 优先的无头 CDP 浏览器自动化工具，不使用浏览器扩展，也不依赖像素级截图。它适合脚本化网页工作流、适合 CI 的浏览器测试，以及希望用 shell 命令而非 GUI 交互的基于会话的抓取场景。

主要能力

  • 导航：open（别名 goto、navigate）、back、forward、reload、close（别名 quit、exit）、connect（通过 CDP 端口连接）。open 支持 https://、http://、file://、about:、data://，未提供协议时自动补全 https://。
  • 快照分析：snapshot 可输出完整无障碍树，-i 仅交互元素（推荐），-c 紧凑输出，-d 限制深度，-s 按 CSS 选择器限定范围。
  • 交互：click、dblclick、focus、fill（清空后输入）、type（不清空输入）、press（按键，别名 key）、keydown、keyup、hover、check、uncheck、select（单选或多选）、scroll、scrollintoview（别名 scrollinto）、drag、upload。交互使用快照返回的 @refs。
  • 获取信息：get text、get html、get value、get attr、get title、get url、get count、get box、get styles。
  • 状态检查：is visible、is enabled、is checked。
  • 截图与 PDF：screenshot 支持视口截图、全页截图（--full）、指定元素截图，可保存到文件或自动保存到 tmp；pdf 可保存为 PDF。注意 v0.9.1 中 screenshot 要求第一个位置参数为 CSS 选择器，视口截图使用 "body"，省略选择器会报 Validation error。
  • 视频录制：record start、record stop、record restart。录制会创建新上下文但保留会话的 Cookie/存储；未提供 URL 时自动返回当前页面。建议先探索再开始录制以获得流畅演示。
  • 等待：wait 支持等待元素、毫秒数、文本（--text/-t）、URL 模式（--url/-u）、网络空闲（--load networkidle/-l）、JS 条件（--fn/-f）。
  • 鼠标控制：mouse move、mouse down、mouse up、mouse wheel。
  • 语义定位器：find 支持 role、text（可 --exact）、label、placeholder、alt、title、testid、first、last、nth。
  • 浏览器设置：set viewport、set device、set geo（别名 geolocation）、set offline、set headers、set credentials（别名 auth）、set media（可组合 dark/light 与 reduced-motion）。
  • Cookie 与存储：cookies（获取/设置/清除）、storage local（获取全部/获取指定键/设置/清除）。
  • 网络：network route（拦截、--abort 阻断、--body 模拟响应）、network unroute、network requests（可 --filter 过滤）。
  • 标签页与窗口：tab（列出/新建/切换/关闭）、window new。
  • iframe：frame 切换，frame main 返回主框架。
  • 对话框：dialog accept、dialog dismiss。
  • JavaScript：eval 执行 JS。

使用方式

快速开始：

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

核心工作流：导航 → 快照（返回 @e1、@e2 等 refs）→ 使用快照中的 refs 交互 → 导航或 DOM 重大变化后重新快照。

全局选项：--session（隔离会话）、--json（JSON 输出便于解析）、--headed（显示浏览器窗口）、--full（全页截图）、--cdp（通过 CDP 连接）、-p/--provider（云浏览器提供商）、--proxy（代理服务器）、--headers（限定到 URL 源的 HTTP 头）、--executable-path（自定义浏览器可执行文件）、--extension（加载扩展，可重复）、--help、--version。

代理支持示例：

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、AGENT_BROWSER_EXECUTABLE_PATH、AGENT_BROWSER_EXTENSIONS、AGENT_BROWSER_PROVIDER、AGENT_BROWSER_STREAM_PORT、AGENT_BROWSER_HOME。

表单提交示例：

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。

调试：--headed 显示窗口、--cdp 或 connect 通过 CDP 连接、console 查看控制台消息（--clear 清除）、errors 查看页面错误（--clear 清除）、highlight 高亮元素、trace start/stop 记录并保存 trace、record start/stop 录制视频。

适用场景

  • 脚本化网页工作流与自动化操作
  • 适合 CI 的浏览器测试
  • 基于会话的数据抓取
  • 表单填写与提交
  • 截图、PDF 与视频录制
  • 需要代理、地理位置测试或轮换代理的场景
  • 需要并行会话或状态持久化的场景

限制

  • 资料未提供安装命令、收费与价格信息、平台支持范围、性能或效果数据，这些内容暂未提供。
  • v0.9.1 中 screenshot 要求第一个位置参数为 CSS 选择器，省略会报 Validation error。
  • 视频录制会创建新上下文（但保留 Cookie/存储）。
  • 交互依赖快照返回的 refs，导航或 DOM 重大变化后需重新快照。

深入文档与模板

参考资料：references/snapshot-refs.md（ref 生命周期、失效规则、故障排查）、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