🖥️ Agent-Browser 技术原理与能力分析

🔧 技术架构原理

agent-browser find role button click --name "Submit"
agent-browser find label "Email" fill "test@test.com"
agent-browser find text "Sign In" click

agent-browser snapshot  # 获取带 refs 的可访问性树
agent-browser click @e2   # 通过 ref 点击元素

agent-browser --session agent1 open site-a.com
agent-browser --session agent2 open site-b.com
agent-browser session list  # 列出所有会话

⚡ 核心能力一览

📋 详细命令分类

1. 核心操作命令

agent-browser open <url>           # 打开URL（核心命令）
agent-browser click <sel>          # 点击元素
agent-browser fill <sel> <text>    # 填入文本（清空后）
agent-browser type <sel> <text>    # 输入文本（追加）
agent-browser press <key>          # 按键（Enter、Tab等）
agent-browser hover <sel>          # 悬停
agent-browser scroll <dir> [px]    # 滚动
agent-browser screenshot [path]     # 截图
agent-browser snapshot              # 获取可访问性树（AI最佳）
agent-browser close                 # 关闭浏览器

2. 信息获取命令

agent-browser get text <sel>       # 获取文本内容
agent-browser get html <sel>        # 获取HTML
agent-browser get value <sel>       # 获取输入框值
agent-browser get attr <sel> <attr> # 获取属性
agent-browser get title              # 获取页面标题
agent-browser get url                # 获取当前URL
agent-browser get count <sel>       # 统计元素数量
agent-browser get box <sel>         # 获取元素位置尺寸
agent-browser get styles <sel>      # 获取计算样式

3. 状态检查命令

agent-browser is visible <sel>    # 检查是否可见
agent-browser is enabled <sel>     # 检查是否启用
agent-browser is checked <sel>      # 检查是否勾选

4. 语义定位命令（AI友好）

agent-browser find role button click --name "提交"
agent-browser find text "登录" click
agent-browser find label "邮箱" fill "test@test.com"
agent-browser find placeholder "请输入" type "内容"
agent-browser find testid "submit-btn" click
agent-browser find first "li" click
agent-browser find nth 2 "a" text

5. 等待命令

agent-browser wait <selector>           # 等待元素出现
agent-browser wait 3000                 # 等待毫秒
agent-browser wait --text "欢迎"          # 等待文本出现
agent-browser wait --url "**/dash"       # 等待URL匹配
agent-browser wait --load networkidle    # 等待网络空闲
agent-browser wait --fn "window.ready"   # 等待JS条件

6. 网络控制命令

agent-browser network route <url> --abort           # 阻止请求
agent-browser network route <url> --body {"ok":true}  # Mock响应
agent-browser network requests --filter api            # 查看API请求

7. 浏览器设置命令

agent-browser set viewport 1920 1080    # 设置视口
agent-browser set device "iPhone 14"      # 设备模拟
agent-browser set geo 39.9 116.4          # 地理位置
agent-browser set offline on               # 离线模式
agent-browser set headers '{"X-Test":"1"}' # 自定义请求头
agent-browser set media dark               # 暗黑模式

8. 状态保存与恢复

agent-browser state save auth.json    # 保存登录状态
agent-browser state load auth.json       # 恢复登录状态
agent-browser state list                 # 列出保存的状态

9. 对比与测试命令

agent-browser diff snapshot                  # 对比快照
agent-browser diff screenshot --baseline b.png  # 视觉diff
agent-browser diff url https://v1.com https://v2.com  # URL对比

10. 调试与分析命令

agent-browser console                # 查看控制台日志
agent-browser errors                   # 查看页面错误
agent-browser trace start             # 开始性能追踪
agent-browser trace stop              # 停止追踪
agent-browser profiler start          # 开始性能分析
agent-browser highlight <sel>        # 高亮元素

🎯 典型使用场景

🔐 登录与鉴权操作

# 打开登录页
agent-browser open https://example.com/login

# 输入账号（多种定位方式）
agent-browser find label "邮箱" fill "your@email.com"
agent-browser find label "密码" fill "123456"

# 或通过占位符定位
agent-browser find placeholder "请输入邮箱" fill "your@email.com"

# 或使用传统CSS选择器
agent-browser fill "#email" "your@email.com"
agent-browser fill "#password" "123456"

# 点击登录按钮
agent-browser find role button click --name "登录"
agent-browser click "button[type=submit]"

# 截图确认登录结果
agent-browser screenshot login-result.png

# 打开登录页
agent-browser open https://example.com/login

# 截图查看二维码（手动扫码）
agent-browser screenshot qrcode.png

# 等待扫码登录完成
agent-browser wait --text "已登录"  # 等待成功提示

# 登录成功后保存状态
agent-browser state save logged-in.json

# 以后可直接恢复登录态
agent-browser state load logged-in.json

# 手动设置Cookie
agent-browser cookies set "session_id" "xxx"
agent-browser cookies set "token" "yyyy"

# 查看当前Cookie
agent-browser cookies

# 清除Cookie
agent-browser cookies clear

# 登录成功后保存状态
agent-browser state save my-account.json

# 查看保存的状态列表
agent-browser state list

# 加载状态（自动恢复登录）
agent-browser state load my-account.json

# 重命名状态
agent-browser state rename my-account.json work-account.json

# 清除状态
agent-browser state clear my-account.json

# 清除所有状态
agent-browser state clear --all

# HTTP Basic Auth
agent-browser set credentials username password

# 自定义请求头（Bearer Token等）
agent-browser set headers '{"Authorization":"Bearer xxx"}'

# 查看页面元素定位
agent-browser snapshot  # 获取可访问性树

📦 安装方式

# 推荐：全局安装（性能最佳）
npm install -g agent-browser
agent-browser install  # 下载Chromium

# 快速尝试
npx agent-browser install
npx agent-browser open example.com

# macOS
brew install agent-browser
agent-browser install

# 从源码构建
git clone https://github.com/vercel-labs/agent-browser
cd agent-browser
pnpm install && pnpm build && pnpm build:native
pnpm link --global

💡 与传统方案的对比