Agent Browser

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

核心工作流程

每次浏览器自动化都遵循以下模式：

1. 导航：agent-browser open <url> 2. 快照：agent-browser snapshot -i（获取元素引用，如 @e1、@e2） 3. 交互：使用引用进行点击、填充、选择 4. 重新快照：导航或 DOM 变化后，获取新的引用

agent-browser open https://example.com/form
agent-browser snapshot -i
# 输出：@e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit"

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  # 检查结果

命令链式调用

命令可以通过 && 在单个 shell 调用中链式连接。浏览器通过后台守护进程在命令之间持久存在，因此链式调用是安全的，并且比单独调用更高效。

# 在一次调用中链式连接打开 + 等待 + 快照
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i

# 链式连接多个交互
agent-browser fill @e1 "user@example.com" && agent-browser fill @e2 "password123" && agent-browser click @e3

# 导航并截图
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png

何时使用链式调用：当你不需要在继续之前读取中间命令的输出时使用 &&（例如：打开 + 等待 + 截图）。当你需要先解析输出时，请单独运行命令（例如：快照以发现引用，然后使用这些引用进行交互）。

基本命令

# 导航
agent-browser open <url>              # 导航（别名：goto, navigate）
agent-browser close                   # 关闭浏览器

# 快照
agent-browser snapshot -i             # 带引用的交互式元素（推荐）
agent-browser snapshot -i -C          # 包含光标交互式元素（带 onclick 或 cursor:pointer 的 div）
agent-browser snapshot -s "#selector" # 限定到 CSS 选择器范围

# 交互（使用快照中的 @refs）
agent-browser click @e1               # 点击元素
agent-browser click @e1 --new-tab     # 点击并在新标签页打开
agent-browser fill @e2 "text"         # 清空并输入文本
agent-browser type @e2 "text"         # 不清空直接输入文本
agent-browser select @e1 "option"     # 选择下拉选项
agent-browser check @e1               # 勾选复选框
agent-browser press Enter             # 按键
agent-browser keyboard type "text"    # 在当前焦点处输入（无需选择器）
agent-browser keyboard inserttext "text"  # 插入文本（不触发按键事件）
agent-browser scroll down 500         # 滚动页面
agent-browser scroll down 500 --selector "div.content"  # 在特定容器内滚动

# 获取信息
agent-browser get text @e1            # 获取元素文本
agent-browser get url                 # 获取当前 URL
agent-browser get title               # 获取页面标题

# 等待
agent-browser wait @e1                # 等待元素
agent-browser wait --load networkidle # 等待网络空闲
agent-browser wait --url "**/page"    # 等待 URL 模式
agent-browser wait 2000               # 等待毫秒数

# 下载
agent-browser download @e1 ./file.pdf          # 点击元素触发下载
agent-browser wait --download ./output.zip     # 等待任何下载完成
agent-browser --download-path ./downloads open <url>  # 设置默认下载目录

# 捕获
agent-browser screenshot              # 截图到临时目录
agent-browser screenshot --full       # 全页面截图
agent-browser screenshot --annotate   # 带编号元素标签的注释截图
agent-browser pdf output.pdf          # 保存为 PDF

# 差异对比（比较页面状态）
agent-browser diff snapshot                          # 比较当前与上一次快照
agent-browser diff snapshot --baseline before.txt    # 比较当前与保存的文件
agent-browser diff screenshot --baseline before.png  # 视觉像素差异
agent-browser diff url <url1> <url2>                 # 比较两个页面
agent-browser diff url <url1> <url2> --wait-until networkidle  # 自定义等待策略
agent-browser diff url <url1> <url2> --selector "#main"  # 限定到元素范围

常见模式

表单提交

agent-browser open https://example.com/signup
agent-browser snapshot -i
agent-browser fill @e1 "Jane Doe"
agent-browser fill @e2 "jane@example.com"
agent-browser select @e3 "California"
agent-browser check @e4
agent-browser click @e5
agent-browser wait --load networkidle

使用认证保险库进行身份验证（推荐）

# 保存凭证一次（使用 AGENT_BROWSER_ENCRYPTION_KEY 加密）
# 推荐：通过 stdin 管道传输密码以避免 shell 历史记录暴露
echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin

# 使用保存的配置文件登录（LLM 永远看不到密码）
agent-browser auth login github

# 列出/显示/删除配置文件
agent-browser auth list
agent-browser auth show github
agent-browser auth delete github

使用状态持久化进行身份验证

# 登录一次并保存状态
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

会话持久化

# 在浏览器重启之间自动保存/恢复 cookies 和 localStorage
agent-browser --session-name myapp open https://app.example.com/login
# ... 登录流程 ...
agent-browser close  # 状态自动保存到 ~/.agent-browser/sessions/

# 下次使用时，状态自动加载
agent-browser --session-name myapp open https://app.example.com/dashboard

# 静态加密状态
export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)
agent-browser --session-name secure open https://app.example.com

# 管理保存的状态
agent-browser state list
agent-browser state show myapp-default.json
agent-browser state clear myapp
agent-browser state clean --older-than 7

数据提取

agent-browser open https://example.com/products
agent-browser snapshot -i
agent-browser get text @e5           # 获取特定元素文本
agent-browser get text body > page.txt  # 获取所有页面文本

# JSON 输出用于解析
agent-browser snapshot -i --json
agent-browser get text @e1 --json

并行会话

agent-browser --session site1 open https://site-a.com
agent-browser --session site2 open https://site-b.com

agent-browser --session site1 snapshot -i
agent-browser --session site2 snapshot -i

agent-browser session list

连接到现有 Chrome

# 自动发现启用了远程调试的运行中 Chrome
agent-browser --auto-connect open https://example.com
agent-browser --auto-connect snapshot

# 或使用明确的 CDP 端口
agent-browser --cdp 9222 snapshot

配色方案（深色模式）

# 通过标志持久启用深色模式（适用于所有页面和新标签页）
agent-browser --color-scheme dark open https://example.com

# 或通过环境变量
AGENT_BROWSER_COLOR_SCHEME=dark agent-browser open https://example.com

# 或在会话期间设置（对后续命令持久）
agent-browser set media dark

可视化浏览器（调试）

agent-browser --headed open https://example.com
agent-browser highlight @e1          # 高亮元素
agent-browser record start demo.webm # 录制会话
agent-browser profiler start         # 启动 Chrome DevTools 性能分析
agent-browser profiler stop trace.json # 停止并保存性能分析（路径可选）

本地文件（PDF、HTML）

# 使用 file:// URL 打开本地文件
agent-browser --allow-file-access open file:///path/to/document.pdf
agent-browser --allow-file-access open file:///path/to/page.html
agent-browser screenshot output.png

iOS 模拟器（Mobile Safari）

# 列出可用的 iOS 模拟器
agent-browser device list

# 在特定设备上启动 Safari
agent-browser -p ios --device "iPhone 16 Pro" open https://example.com

# 与桌面端相同的工作流程 - 快照、交互、重新快照
agent-browser -p ios snapshot -i
agent-browser -p ios tap @e1          # 点击（click 的别名）
agent-browser -p ios fill @e2 "text"
agent-browser -p ios swipe up         # 移动端特有手势

# 截图
agent-browser -p ios screenshot mobile.png

# 关闭会话（关闭模拟器）
agent-browser -p ios close

要求：macOS 配备 Xcode，Appium（npm install -g appium && appium driver install xcuitest）

真实设备：如果预先配置，可与物理 iOS 设备一起使用。使用 --device "<UDID>"，其中 UDID 来自 xcrun xctrace list devices。

安全性

所有安全功能都是可选的。默认情况下，agent-browser 对导航、操作或输出没有任何限制。

内容边界（推荐用于 AI 代理）

启用 --content-boundaries 以在页面源输出周围包装标记，帮助 LLM 区分工具输出和不可信的页面内容：

export AGENT_BROWSER_CONTENT_BOUNDARIES=1
agent-browser snapshot
# 输出：
# --- AGENT_BROWSER_PAGE_CONTENT nonce=<hex> origin=https://example.com ---
# [accessibility tree]
# --- END_AGENT_BROWSER_PAGE_CONTENT nonce=<hex> ---

域名白名单

限制导航到受信任的域名。像 *.example.com 这样的通配符也会匹配裸域名 example.com。对未允许域名的子资源请求、WebSocket 和 EventSource 连接也会被阻止。包含你的目标页面依赖的 CDN 域名：

export AGENT_BROWSER_ALLOWED_DOMAINS="example.com,*.example.com"
agent-browser open https://example.com        # 允许
agent-browser open https://malicious.com       # 阻止

操作策略

使用策略文件来限制破坏性操作：

export AGENT_BROWSER_ACTION_POLICY=./policy.json

示例 policy.json：

{"default": "deny", "allow": ["navigate", "snapshot", "click", "scroll", "wait", "get"]}

认证保险库操作（auth login 等）绕过操作策略，但域名白名单仍然适用。

输出限制

防止大页面的上下文溢出：

export AGENT_BROWSER_MAX_OUTPUT=50000

差异对比（验证变更）

在执行操作后使用 diff snapshot 来验证它是否产生了预期的效果。这将当前的辅助功能树与会话中最后一次快照进行比较。

# 典型工作流程：快照 -> 操作 -> 差异
agent-browser snapshot -i          # 获取基线快照
agent-browser click @e2            # 执行操作
agent-browser diff snapshot        # 查看变更（自动与上一次快照比较）

用于视觉回归测试或监控：

# 保存基线截图，然后稍后比较
agent-browser screenshot baseline.png
# ... 时间流逝或进行更改 ...
agent-browser diff screenshot --baseline baseline.png

# 比较预发布环境与生产环境
agent-browser diff url https://staging.example.com https://prod.example.com --screenshot

diff snapshot 输出使用 + 表示添加，- 表示删除，类似于 git diff。diff screenshot 生成差异图像，变更的像素以红色高亮显示，并附带不匹配百分比。

超时和慢速页面

本地浏览器的默认 Playwright 超时为 25 秒。可以使用 AGENT_BROWSER_DEFAULT_TIMEOUT 环境变量覆盖此值（以毫秒为单位）。对于慢速网站或大页面，使用显式等待而不是依赖默认超时：

# 等待网络活动稳定（最适合慢速页面）
agent-browser wait --load networkidle

# 等待特定元素出现
agent-browser wait "#content"
agent-browser wait @e1

# 等待特定 URL 模式（在重定向后有用）
agent-browser wait --url "**/dashboard"

# 等待 JavaScript 条件
agent-browser wait --fn "document.readyState === 'complete'"

# 等待固定时长（毫秒）作为最后手段
agent-browser wait 5000

在处理持续缓慢的网站时，在 open 之后使用 wait --load networkidle 来确保页面完全加载后再进行快照。如果特定元素渲染缓慢，使用 wait <selector> 或 wait @ref 直接等待它。

会话管理和清理

当同时运行多个代理或自动化时，始终使用命名会话以避免冲突：

# 每个代理获得自己独立的会话
agent-browser --session agent1 open site-a.com
agent-browser --session agent2 open site-b.com

# 检查活动会话
agent-browser session list

完成后始终关闭浏览器会话以避免进程泄漏：

agent-browser close                    # 关闭默认会话
agent-browser --session agent1 close   # 关闭特定会话

如果上一个会话未正确关闭，守护进程可能仍在运行。在开始新工作之前使用 agent-browser close 来清理它。

引用生命周期（重要）

当页面变化时，引用（@e1、@e2 等）会失效。在以下情况后始终重新快照：

• 点击导航的链接或按钮
• 表单提交
• 动态内容加载（下拉菜单、模态框）

agent-browser click @e5              # 导航到新页面
agent-browser snapshot -i            # 必须重新快照
agent-browser click @e1              # 使用新引用

注释截图（视觉模式）

使用 --annotate 截取带有交互式元素上覆盖编号标签的截图。每个标签 [N] 映射到引用 @eN。这也会缓存引用，因此你可以立即与元素交互，无需单独快照。

agent-browser screenshot --annotate
# 输出包括图像路径和图例：
#   [1] @e1 button "Submit"
#   [2] @e2 link "Home"
#   [3] @e3 textbox "Email"
agent-browser click @e2              # 使用注释截图中的引用点击

在以下情况使用注释截图：

• 页面有未标记的图标按钮或仅视觉元素
• 你需要验证视觉布局或样式
• 存在 Canvas 或图表元素（对文本快照不可见）
• 你需要对元素位置进行空间推理

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

当引用不可用或不可靠时，使用语义定位器：

agent-browser find text "Sign In" click
agent-browser find label "Email" fill "user@test.com"
agent-browser find role button click --name "Submit"
agent-browser find placeholder "Search" type "query"
agent-browser find testid "submit-btn" click

JavaScript 执行（eval）

使用 eval 在浏览器上下文中运行 JavaScript。Shell 引用可能会破坏复杂表达式 -- 使用 --stdin 或 -b 来避免问题。

# 简单表达式可以使用常规引用
agent-browser eval 'document.title'
agent-browser eval 'document.querySelectorAll("img").length'

# 复杂 JS：使用 --stdin 和 heredoc（推荐）
agent-browser eval --stdin <<'EVALEOF'
JSON.stringify(
  Array.from(document.querySelectorAll("img"))
    .filter(i => !i.alt)
    .map(i => ({ src: i.src.split("/").pop(), width: i.width }))
)
EVALEOF

# 替代方案：base64 编码（避免所有 shell 转义问题）
agent-browser eval -b "$(echo -n 'Array.from(document.querySelectorAll("a")).map(a => a.href)' | base64)"

为什么这很重要：当 shell 处理你的命令时，内部双引号、[!] 字符（历史扩展）、反引号和 $() 都可能在 JavaScript 到达 agent-browser 之前破坏它。--stdin 和 -b 标志完全绕过 shell 解释。

经验法则：

• 单行，无嵌套引号 -> 使用单引号的常规 eval 'expression' 即可
• 嵌套引号、箭头函数、模板字面量或多行 -> 使用 eval --stdin <<'EVALEOF'
• 编程/生成的脚本 -> 使用 eval -b 和 base64

配置文件

在项目根目录创建 agent-browser.json 以持久化设置：

{
  "headed": true,
  "proxy": "http://localhost:8080",
  "profile": "./browser-data"
}

优先级（从低到高）：~/.agent-browser/config.json < ./agent-browser.json < 环境变量 < CLI 标志。使用 --config <path> 或 AGENT_BROWSER_CONFIG 环境变量指定自定义配置文件（如果缺失/无效则退出并报错）。所有 CLI 选项映射到 camelCase 键（例如 --executable-path -> "executablePath"）。布尔标志接受 true/false 值（例如 --headed false 覆盖配置）。来自用户和项目配置的扩展是合并的，而不是替换。

深入文档

即用模板

./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

认证模式

登录流程、会话持久化、OAuth、2FA 和已认证浏览。

相关文档：session-management.md 了解状态持久化详情，SKILL.md 快速入门。

目录

• 基本登录流程
• 保存认证状态
• 恢复认证
• OAuth / SSO 流程
• 双因素认证
• HTTP Basic Auth
• 基于 Cookie 的认证
• Token 刷新处理
• 安全最佳实践

基本登录流程

# 导航到登录页面
agent-browser open https://app.example.com/login
agent-browser wait --load networkidle

# 获取表单元素
agent-browser snapshot -i
# 输出: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Sign In"

# 填写凭据
agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"

# 提交
agent-browser click @e3
agent-browser wait --load networkidle

# 验证登录成功
agent-browser get url  # 应该是仪表板，而不是登录页

保存认证状态

登录后，保存状态以便复用：

# 首先登录（见上文）
agent-browser open https://app.example.com/login
agent-browser snapshot -i
agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait --url "**/dashboard"

# 保存认证状态
agent-browser state save ./auth-state.json

恢复认证

通过加载保存的状态跳过登录：

# 加载保存的认证状态
agent-browser state load ./auth-state.json

# 直接导航到受保护页面
agent-browser open https://app.example.com/dashboard

# 验证已认证
agent-browser snapshot -i

OAuth / SSO 流程

处理 OAuth 重定向：

# 启动 OAuth 流程
agent-browser open https://app.example.com/auth/google

# 自动处理重定向
agent-browser wait --url "**/accounts.google.com**"
agent-browser snapshot -i

# 填写 Google 凭据
agent-browser fill @e1 "user@gmail.com"
agent-browser click @e2  # 下一步按钮
agent-browser wait 2000
agent-browser snapshot -i
agent-browser fill @e3 "password"
agent-browser click @e4  # 登录

# 等待重定向回来
agent-browser wait --url "**/app.example.com**"
agent-browser state save ./oauth-state.json

双因素认证

通过手动干预处理 2FA：

# 使用凭据登录
agent-browser open https://app.example.com/login --headed  # 显示浏览器
agent-browser snapshot -i
agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"
agent-browser click @e3

# 等待用户手动完成 2FA
echo "请在浏览器窗口中完成 2FA..."
agent-browser wait --url "**/dashboard" --timeout 120000

# 2FA 完成后保存状态
agent-browser state save ./2fa-state.json

HTTP Basic Auth

对于使用 HTTP Basic Authentication 的网站：

# 在导航前设置凭据
agent-browser set credentials username password

# 导航到受保护的资源
agent-browser open https://protected.example.com/api

基于 Cookie 的认证

手动设置认证 Cookie：

# 设置认证 cookie
agent-browser cookies set session_token "abc123xyz"

# 导航到受保护页面
agent-browser open https://app.example.com/dashboard

Token 刷新处理

针对有过期 Token 的会话：

#!/bin/bash
# 处理 token 刷新的包装脚本

STATE_FILE="./auth-state.json"

# 尝试加载现有状态
if [[ -f "$STATE_FILE" ]]; then
    agent-browser state load "$STATE_FILE"
    agent-browser open https://app.example.com/dashboard

    # 检查会话是否仍然有效
    URL=$(agent-browser get url)
    if [[ "$URL" == *"/login"* ]]; then
        echo "会话已过期，重新认证..."
        # 执行全新登录
        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 "$STATE_FILE"
    fi
else
    # 首次登录
    agent-browser open https://app.example.com/login
    # ... 登录流程 ...
fi

安全最佳实践

1. 永远不要提交状态文件 - 它们包含会话令牌

   echo "*.auth-state.json" >> .gitignore

2. 使用环境变量存储凭据

   agent-browser fill @e1 "$APP_USERNAME"
   agent-browser fill @e2 "$APP_PASSWORD"

3. 自动化完成后清理

   agent-browser cookies clear
   rm -f ./auth-state.json

4. 在 CI/CD 中使用短期会话

   # 不要在 CI 中持久化状态
   agent-browser open https://app.example.com/login
   # ... 登录并执行操作 ...
   agent-browser close  # 会话结束，不保留任何内容

命令参考

agent-browser 所有命令的完整参考文档。如需快速入门和常见用法，请参阅 SKILL.md。

导航

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 选择器

交互（使用快照中的 @refs）

agent-browser click @e1           # 点击
agent-browser click @e1 --new-tab # 点击并在新标签页打开
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 # 上传文件

获取信息

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      # 检查是否已勾选

截图和 PDF

agent-browser screenshot          # 保存到临时目录
agent-browser screenshot path.png # 保存到指定路径
agent-browser screenshot --full   # 完整页面
agent-browser pdf output.pdf      # 保存为 PDF

视频录制

agent-browser record start ./demo.webm    # 开始录制
agent-browser click @e1                   # 执行操作
agent-browser record stop                 # 停止并保存视频
agent-browser record restart ./take2.webm # 停止当前录制 + 开始新录制

等待

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         # 滚动滚轮

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

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  # 浅色模式 + 减少动画

Cookie 和存储

agent-browser cookies                     # 获取所有 Cookie
agent-browser cookies set name value      # 设置 Cookie
agent-browser cookies clear               # 清除 Cookie
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        # 取消对话框

JavaScript

agent-browser eval "document.title"          # 仅支持简单表达式
agent-browser eval -b "<base64>"             # 任意 JavaScript（Base64 编码）
agent-browser eval --stdin                   # 从标准输入读取脚本

使用 -b/--base64 或 --stdin 以确保可靠执行。Shell 转义中的嵌套引号和特殊字符容易出错。

# Base64 编码你的脚本，然后：
agent-browser eval -b "ZG9jdW1lbnQucXVlcnlTZWxlY3RvcignW3NyYyo9Il9uZXh0Il0nKQ=="

# 或者使用 heredoc 标准输入执行多行脚本：
cat <<'EOF' | agent-browser eval --stdin
const links = document.querySelectorAll('a');
Array.from(links).map(a => a.href);
EOF

状态管理

agent-browser state save auth.json    # 保存 Cookie、存储、认证状态
agent-browser state load auth.json    # 恢复已保存的状态

全局选项

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 --proxy-bypass <hosts>  # 绕过代理的主机
agent-browser --headers <json> ...    # 作用域为 URL 源的 HTTP 请求头
agent-browser --executable-path <p>   # 自定义浏览器可执行文件
agent-browser --extension <path> ...  # 加载浏览器扩展（可重复使用）
agent-browser --ignore-https-errors   # 忽略 SSL 证书错误
agent-browser --help                  # 显示帮助（-h）
agent-browser --version               # 显示版本（-V）
agent-browser <command> --help        # 显示命令的详细帮助

调试

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 profiler start              # 开始 Chrome DevTools 性能分析
agent-browser profiler stop trace.json    # 停止并保存性能分析

环境变量

AGENT_BROWSER_SESSION="mysession"            # 默认会话名称
AGENT_BROWSER_EXECUTABLE_PATH="/path/chrome" # 自定义浏览器路径
AGENT_BROWSER_EXTENSIONS="/ext1,/ext2"       # 逗号分隔的扩展路径
AGENT_BROWSER_PROVIDER="browserbase"         # 云浏览器提供商
AGENT_BROWSER_STREAM_PORT="9223"             # WebSocket 流端口
AGENT_BROWSER_HOME="/path/to/agent-browser"  # 自定义安装位置

性能分析

在浏览器自动化过程中捕获 Chrome DevTools 性能配置文件，用于性能分析。

相关文档: commands.md 完整命令参考，SKILL.md 快速入门。

目录

• 基础性能分析
• 性能分析器命令
• 分类
• 使用场景
• 输出格式
• 查看性能配置文件
• 限制

基础性能分析

# 启动性能分析
agent-browser profiler start

# 执行操作
agent-browser navigate https://example.com
agent-browser click "#button"
agent-browser wait 1000

# 停止并保存
agent-browser profiler stop ./trace.json

性能分析器命令

# 使用默认分类启动性能分析
agent-browser profiler start

# 使用自定义跟踪分类启动
agent-browser profiler start --categories "devtools.timeline,v8.execute,blink.user_timing"

# 停止性能分析并保存到文件
agent-browser profiler stop ./trace.json

分类

--categories 标志接受逗号分隔的 Chrome 跟踪分类列表。默认分类包括：

• devtools.timeline -- 标准 DevTools 性能跟踪
• v8.execute -- JavaScript 执行时间
• blink -- 渲染器事件
• blink.user_timing -- performance.mark() / performance.measure() 调用
• latencyInfo -- 输入延迟跟踪
• renderer.scheduler -- 任务调度和执行
• toplevel -- 广泛的基础事件

还包括多个 disabled-by-default-* 分类，用于详细的 timeline、调用堆栈和 V8 CPU 性能分析数据。

使用场景

诊断页面加载缓慢

agent-browser profiler start
agent-browser navigate https://app.example.com
agent-browser wait --load networkidle
agent-browser profiler stop ./page-load-profile.json

分析用户交互性能

agent-browser navigate https://app.example.com
agent-browser profiler start
agent-browser click "#submit"
agent-browser wait 2000
agent-browser profiler stop ./interaction-profile.json

CI 性能回归检查

#!/bin/bash
agent-browser profiler start
agent-browser navigate https://app.example.com
agent-browser wait --load networkidle
agent-browser profiler stop "./profiles/build-${BUILD_ID}.json"

输出格式

输出为 Chrome Trace Event 格式的 JSON 文件：

{
  "traceEvents": [
    { "cat": "devtools.timeline", "name": "RunTask", "ph": "X", "ts": 12345, "dur": 100, ... },
    ...
  ],
  "metadata": {
    "clock-domain": "LINUX_CLOCK_MONOTONIC"
  }
}

metadata.clock-domain 字段根据主机平台设置（Linux 或 macOS）。在 Windows 上此字段被省略。

查看性能配置文件

将输出的 JSON 文件加载到以下任一工具中：

• Chrome DevTools: Performance 面板 > Load profile (Ctrl+Shift+I > Performance)
• Perfetto UI: https://ui.perfetto.dev/ -- 拖放 JSON 文件
• Trace Viewer: 任何 Chromium 浏览器中的 chrome://tracing

限制

• 仅适用于基于 Chromium 的浏览器（Chrome、Edge）。不支持 Firefox 或 WebKit。
• 性能分析处于活动状态时，跟踪数据会在内存中累积（上限为 500 万个事件）。在关注区域结束后应及时停止性能分析。
• 停止时的数据收集有 30 秒超时限制。如果浏览器无响应，停止命令可能会失败。

代理支持

用于地理位置测试、避免速率限制和企业网络环境的代理配置。

相关文档: commands.md 查看全局选项，SKILL.md 快速入门。

目录

• 基本代理配置
• 需要认证的代理
• SOCKS 代理
• 代理绕过
• 常见用例
• 验证代理连接
• 故障排除
• 最佳实践

基本代理配置

使用 --proxy 标志或通过环境变量设置代理：

# 通过 CLI 标志
agent-browser --proxy "http://proxy.example.com:8080" open https://example.com

# 通过环境变量
export HTTP_PROXY="http://proxy.example.com:8080"
agent-browser open https://example.com

# HTTPS 代理
export HTTPS_PROXY="https://proxy.example.com:8080"
agent-browser open https://example.com

# 同时设置两者
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"
agent-browser open https://example.com

需要认证的代理

对于需要身份验证的代理：

# 在 URL 中包含凭据
export HTTP_PROXY="http://username:password@proxy.example.com:8080"
agent-browser open https://example.com

SOCKS 代理

# SOCKS5 代理
export ALL_PROXY="socks5://proxy.example.com:1080"
agent-browser open https://example.com

# 带认证的 SOCKS5
export ALL_PROXY="socks5://user:pass@proxy.example.com:1080"
agent-browser open https://example.com

代理绕过

使用 --proxy-bypass 或 NO_PROXY 跳过特定域名的代理：

# 通过 CLI 标志
agent-browser --proxy "http://proxy.example.com:8080" --proxy-bypass "localhost,*.internal.com" open https://example.com

# 通过环境变量
export NO_PROXY="localhost,127.0.0.1,.internal.company.com"
agent-browser open https://internal.company.com  # 直连
agent-browser open https://external.com          # 通过代理

常见用例

地理位置测试

#!/bin/bash
# 使用不同地区的代理测试网站

PROXIES=(
    "http://us-proxy.example.com:8080"
    "http://eu-proxy.example.com:8080"
    "http://asia-proxy.example.com:8080"
)

for proxy in "${PROXIES[@]}"; do
    export HTTP_PROXY="$proxy"
    export HTTPS_PROXY="$proxy"

    region=$(echo "$proxy" | grep -oP '^\w+-\w+')
    echo "测试地区: $region"

    agent-browser --session "$region" open https://example.com
    agent-browser --session "$region" screenshot "./screenshots/$region.png"
    agent-browser --session "$region" close
done

轮换代理用于数据抓取

#!/bin/bash
# 轮换代理列表以避免速率限制

PROXY_LIST=(
    "http://proxy1.example.com:8080"
    "http://proxy2.example.com:8080"
    "http://proxy3.example.com:8080"
)

URLS=(
    "https://site.com/page1"
    "https://site.com/page2"
    "https://site.com/page3"
)

for i in "${!URLS[@]}"; do
    proxy_index=$((i % ${#PROXY_LIST[@]}))
    export HTTP_PROXY="${PROXY_LIST[$proxy_index]}"
    export HTTPS_PROXY="${PROXY_LIST[$proxy_index]}"

    agent-browser open "${URLS[$i]}"
    agent-browser get text body > "output-$i.txt"
    agent-browser close

    sleep 1  # 礼貌延迟
done

企业网络访问

#!/bin/bash
# 通过企业代理访问内部网站

export HTTP_PROXY="http://corpproxy.company.com:8080"
export HTTPS_PROXY="http://corpproxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1,.company.com"

# 外部网站通过代理
agent-browser open https://external-vendor.com

# 内部网站绕过代理
agent-browser open https://intranet.company.com

验证代理连接

# 检查你的 apparent IP
agent-browser open https://httpbin.org/ip
agent-browser get text body
# 应该显示代理的 IP，而不是你的真实 IP

故障排除

代理连接失败

# 先测试代理连通性
curl -x http://proxy.example.com:8080 https://httpbin.org/ip

# 检查代理是否需要认证
export HTTP_PROXY="http://user:pass@proxy.example.com:8080"

通过代理时的 SSL/TLS 错误

某些代理会执行 SSL 检查。如果遇到证书错误：

# 仅用于测试 - 生产环境不推荐
agent-browser open https://example.com --ignore-https-errors

性能缓慢

# 仅在必要时使用代理
export NO_PROXY="*.cdn.com,*.static.com"  # 直接访问 CDN

最佳实践

1. 使用环境变量 - 不要硬编码代理凭据 2. 合理设置 NO_PROXY - 避免将本地流量路由到代理 3. 自动化前先测试代理 - 用简单请求验证连通性 4. 优雅处理代理故障 - 为不稳定的代理实现重试逻辑 5. 大规模抓取时轮换代理 - 分散负载并避免被封禁

会话管理

支持多个隔离的浏览器会话，具备状态持久化和并发浏览功能。

相关文档：authentication.md 了解登录模式，SKILL.md 快速入门指南。

目录

• 命名会话
• 会话隔离属性
• 会话状态持久化
• 常见模式
• 默认会话
• 会话清理
• 最佳实践

命名会话

使用 --session 标志来隔离浏览器上下文：

# 会话 1：认证流程
agent-browser --session auth open https://app.example.com/login

# 会话 2：公开浏览（独立的 cookies 和存储）
agent-browser --session public open https://example.com

# 命令按会话隔离
agent-browser --session auth fill @e1 "user@example.com"
agent-browser --session public get text body

会话隔离属性

每个会话拥有独立的：

• Cookies
• LocalStorage / SessionStorage
• IndexedDB
• 缓存
• 浏览历史
• 打开的标签页

会话状态持久化

保存会话状态

# 保存 cookies、存储和认证状态
agent-browser state save /path/to/auth-state.json

加载会话状态

# 恢复已保存的状态
agent-browser state load /path/to/auth-state.json

# 继续使用已认证的会话
agent-browser open https://app.example.com/dashboard

状态文件内容

{
  "cookies": [...],
  "localStorage": {...},
  "sessionStorage": {...},
  "origins": [...]
}

常见模式

已认证会话复用

#!/bin/bash
# 保存一次登录状态，多次复用

STATE_FILE="/tmp/auth-state.json"

# 检查是否有已保存的状态
if [[ -f "$STATE_FILE" ]]; then
    agent-browser state load "$STATE_FILE"
    agent-browser open https://app.example.com/dashboard
else
    # 执行登录
    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 --load networkidle

    # 保存以备后用
    agent-browser state save "$STATE_FILE"
fi

并发抓取

#!/bin/bash
# 并发抓取多个网站

# 启动所有会话
agent-browser --session site1 open https://site1.com &
agent-browser --session site2 open https://site2.com &
agent-browser --session site3 open https://site3.com &
wait

# 从每个会话提取内容
agent-browser --session site1 get text body > site1.txt
agent-browser --session site2 get text body > site2.txt
agent-browser --session site3 get text body > site3.txt

# 清理
agent-browser --session site1 close
agent-browser --session site2 close
agent-browser --session site3 close

A/B 测试会话

# 测试不同的用户体验
agent-browser --session variant-a open "https://app.com?variant=a"
agent-browser --session variant-b open "https://app.com?variant=b"

# 对比结果
agent-browser --session variant-a screenshot /tmp/variant-a.png
agent-browser --session variant-b screenshot /tmp/variant-b.png

默认会话

当省略 --session 时，命令使用默认会话：

# 这些命令使用同一个默认会话
agent-browser open https://example.com
agent-browser snapshot -i
agent-browser close  # 关闭默认会话

会话清理

# 关闭特定会话
agent-browser --session auth close

# 列出活动会话
agent-browser session list

最佳实践

1. 语义化命名会话

# 推荐：清晰的目的
agent-browser --session github-auth open https://github.com
agent-browser --session docs-scrape open https://docs.example.com

# 避免：通用名称
agent-browser --session s1 open https://github.com

2. 始终清理资源

# 完成后关闭会话
agent-browser --session auth close
agent-browser --session scrape close

3. 安全处理状态文件

# 不要提交状态文件（包含认证令牌！）
echo "*.auth-state.json" >> .gitignore

# 使用后删除
rm /tmp/auth-state.json

4. 为长时间会话设置超时

# 为自动化脚本设置超时
timeout 60 agent-browser --session long-task get text body

快照和引用

精简的元素引用，可大幅减少 AI 代理的上下文使用量。

相关文档：完整命令参考请参阅 commands.md，快速入门请参阅 SKILL.md。

目录

• 引用的工作原理
• 快照命令
• 使用引用
• 引用的生命周期
• 最佳实践
• 引用表示法详解
• 故障排除

引用的工作原理

传统方法：

完整 DOM/HTML → AI 解析 → CSS 选择器 → 操作（约 3000-5000 tokens）

agent-browser 方法：

精简快照 → 分配 @refs → 直接交互（约 200-400 tokens）

快照命令

# 基本快照（显示页面结构）
agent-browser snapshot

# 交互式快照（-i 标志）- 推荐
agent-browser snapshot -i

快照输出格式

Page: Example Site - Home
URL: https://example.com

@e1 [header]
  @e2 [nav]
    @e3 [a] "Home"
    @e4 [a] "Products"
    @e5 [a] "About"
  @e6 [button] "Sign In"

@e7 [main]
  @e8 [h1] "Welcome"
  @e9 [form]
    @e10 [input type="email"] placeholder="Email"
    @e11 [input type="password"] placeholder="Password"
    @e12 [button type="submit"] "Log In"

@e13 [footer]
  @e14 [a] "Privacy Policy"

使用引用

获取引用后，即可直接进行交互：

# 点击 "Sign In" 按钮
agent-browser click @e6

# 填写邮箱输入框
agent-browser fill @e10 "user@example.com"

# 填写密码
agent-browser fill @e11 "password123"

# 提交表单
agent-browser click @e12

引用的生命周期

重要提示：当页面发生变化时，引用会失效！

# 获取初始快照
agent-browser snapshot -i
# @e1 [button] "Next"

# 点击触发页面变化
agent-browser click @e1

# 必须重新获取快照以获取新的引用！
agent-browser snapshot -i
# @e1 [h1] "Page 2"  ← 现在是不同的元素了！

最佳实践

1. 交互前始终先获取快照

# 正确做法
agent-browser open https://example.com
agent-browser snapshot -i          # 先获取引用
agent-browser click @e1            # 使用引用

# 错误做法
agent-browser open https://example.com
agent-browser click @e1            # 引用还不存在！

2. 页面导航后重新获取快照

agent-browser click @e5            # 导航到新页面
agent-browser snapshot -i          # 获取新的引用
agent-browser click @e1            # 使用新的引用

3. 动态变化后重新获取快照

agent-browser click @e1            # 打开下拉菜单
agent-browser snapshot -i          # 查看下拉菜单项
agent-browser click @e7            # 选择项目

4. 对特定区域获取快照

对于复杂页面，可以只对特定区域获取快照：

# 仅对表单区域获取快照
agent-browser snapshot @e9

引用表示法详解

@e1 [tag type="value"] "text content" placeholder="hint"
│    │   │             │               │
│    │   │             │               └─ 附加属性
│    │   │             └─ 可见文本
│    │   └─ 显示的关键属性
│    └─ HTML 标签名
└─ 唯一引用 ID

常见模式

@e1 [button] "Submit"                    # 带文本的按钮
@e2 [input type="email"]                 # 邮箱输入框
@e3 [input type="password"]              # 密码输入框
@e4 [a href="/page"] "Link Text"         # 锚点链接
@e5 [select]                             # 下拉选择框
@e6 [textarea] placeholder="Message"     # 文本域
@e7 [div class="modal"]                  # 容器（相关时显示）
@e8 [img alt="Logo"]                     # 图片
@e9 [checkbox] checked                   # 已选中的复选框
@e10 [radio] selected                    # 已选中的单选按钮

故障排除

"Ref not found" 错误

# 引用可能已变化 - 重新获取快照
agent-browser snapshot -i

快照中看不到元素

# 向下滚动以显示元素
agent-browser scroll down 1000
agent-browser snapshot -i

# 或等待动态内容加载
agent-browser wait 1000
agent-browser snapshot -i

元素过多

# 对特定容器获取快照
agent-browser snapshot @e5

# 或使用 get text 仅提取文本内容
agent-browser get text @e5

视频录制

将浏览器自动化过程录制为视频，用于调试、文档记录或验证。

相关文档: commands.md 查看完整命令参考，SKILL.md 查看快速入门。

目录

• 基础录制
• 录制命令
• 使用场景
• 最佳实践
• 输出格式
• 限制说明

基础录制

# 开始录制
agent-browser record start ./demo.webm

# 执行操作
agent-browser open https://example.com
agent-browser snapshot -i
agent-browser click @e1
agent-browser fill @e2 "test input"

# 停止并保存
agent-browser record stop

录制命令

# 开始录制到文件
agent-browser record start ./output.webm

# 停止当前录制
agent-browser record stop

# 重启新录制（停止当前 + 开始新录制）
agent-browser record restart ./take2.webm

使用场景

调试失败的自动化

#!/bin/bash
# 录制自动化过程用于调试

agent-browser record start ./debug-$(date +%Y%m%d-%H%M%S).webm

# 运行你的自动化
agent-browser open https://app.example.com
agent-browser snapshot -i
agent-browser click @e1 || {
    echo "点击失败 - 查看录制"
    agent-browser record stop
    exit 1
}

agent-browser record stop

文档生成

#!/bin/bash
# 录制工作流用于文档

agent-browser record start ./docs/how-to-login.webm

agent-browser open https://app.example.com/login
agent-browser wait 1000  # 暂停以便观察

agent-browser snapshot -i
agent-browser fill @e1 "demo@example.com"
agent-browser wait 500

agent-browser fill @e2 "password"
agent-browser wait 500

agent-browser click @e3
agent-browser wait --load networkidle
agent-browser wait 1000  # 展示结果

agent-browser record stop

CI/CD 测试证据

#!/bin/bash
# 录制 E2E 测试运行作为 CI 产物

TEST_NAME="${1:-e2e-test}"
RECORDING_DIR="./test-recordings"
mkdir -p "$RECORDING_DIR"

agent-browser record start "$RECORDING_DIR/$TEST_NAME-$(date +%s).webm"

# 运行测试
if run_e2e_test; then
    echo "测试通过"
else
    echo "测试失败 - 已保存录制"
fi

agent-browser record stop

最佳实践

1. 添加暂停以提高清晰度

# 放慢速度以便人类观看
agent-browser click @e1
agent-browser wait 500  # 让观看者看到结果

2. 使用描述性文件名

# 在文件名中包含上下文信息
agent-browser record start ./recordings/login-flow-2024-01-15.webm
agent-browser record start ./recordings/checkout-test-run-42.webm

3. 在错误情况下处理录制

#!/bin/bash
set -e

cleanup() {
    agent-browser record stop 2>/dev/null || true
    agent-browser close 2>/dev/null || true
}
trap cleanup EXIT

agent-browser record start ./automation.webm
# ... 自动化步骤 ...

4. 结合截图使用

# 录制视频并捕获关键帧
agent-browser record start ./flow.webm

agent-browser open https://example.com
agent-browser screenshot ./screenshots/step1-homepage.png

agent-browser click @e1
agent-browser screenshot ./screenshots/step2-after-click.png

agent-browser record stop

输出格式

• 默认格式: WebM (VP8/VP9 编解码器)
• 兼容所有现代浏览器和视频播放器
• 压缩但高质量

限制说明

• 录制会给自动化增加少量开销
• 大型录制可能占用大量磁盘空间
• 某些无头环境可能存在编解码器限制