agent-browser

用途

agent-browser 是一款面向 AI 智能体的浏览器自动化命令行工具。它直接通过 Chrome DevTools Protocol（CDP）驱动 Chrome/Chromium，用于让智能体与网站交互，例如导航页面、填写表单、点击按钮、截图等。

安装

支持三种安装方式：

• npm i -g agent-browser
• brew install agent-browser
• cargo install agent-browser

安装后运行 agent-browser install 下载 Chrome。

核心工作流

每次浏览器自动化遵循固定模式：

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

主要能力

• 命令链式执行：可用 && 在单次 shell 调用中串联命令，浏览器通过后台守护进程在命令间保持状态。
• 认证处理：提供多种方式，包括从用户浏览器导入认证状态、持久化 profile、会话名称自动保存/恢复、加密的 auth vault，以及手动保存/加载状态文件。
• 快照与交互：snapshot -i 列出交互元素及引用；支持 click、fill、type、select、check、press、键盘输入、滚动等。
• 信息获取：get text、get url、get title、get cdp-url。
• 等待：等待元素、网络空闲、URL 模式、毫秒、文本出现或消失、元素隐藏。
• 下载：触发下载并等待完成，或设置默认下载目录。
• 网络：查看已跟踪请求、阻止匹配请求、录制 HAR。
• 视口与设备模拟：设置视口尺寸、retina 缩放、模拟设备。
• 捕获：截图（全页、标注、自定义目录与格式）、保存 PDF。
• 剪贴板：读取、写入、复制、粘贴。
• 差异对比：对比当前与上次快照、与保存文件、像素级截图差异、对比两个 URL。
• 批量执行：通过管道传入 JSON 数组一次执行多条命令，支持出错即停。
• 并行会话：用 --session 并行操作多个站点，并列出会话。
• 连接已有 Chrome：通过 --auto-connect 或 --cdp 端口连接。
• 颜色方案：暗色模式支持。
• 视觉调试：有头模式、元素高亮、打开 DevTools、会话录制、性能分析。
• 本地文件：以 file:// 打开本地 PDF、HTML。
• iOS 模拟器：列出设备、在指定设备上启动 Safari，支持 tap、fill、swipe 等手势。

使用方式示例

表单提交：

agent-browser open https://example.com/signup
agent-browser snapshot -i
agent-browser fill @e1 "Jane Doe"
agent-browser click @e5
agent-browser wait --load networkidle

通过 auth vault 保存并使用凭据：

echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin
agent-browser auth login github

会话持久化：

agent-browser --session-name myapp open https://app.example.com/login
agent-browser close
agent-browser --session-name myapp open https://app.example.com/dashboard

适用场景

需要让 AI 智能体自主完成网页任务的场景，例如填写与提交表单、登录后操作应用、数据提取、响应式测试、页面差异校验、录制网络请求等。

限制与注意事项

• iOS 模拟器功能依赖 macOS 与 Xcode，需安装 Appium 及 xcuitest 驱动。
• 状态文件以明文保存会话令牌，需加入 .gitignore 并及时删除；可通过设置 AGENT_BROWSER_ENCRYPTION_KEY 实现静态加密。
• 安全功能均为可选开启；默认情况下不限制导航、操作或输出。可启用内容边界标记、域名允许列表、操作策略文件与输出上限。
• auth vault 操作会绕过操作策略，但域名允许列表仍生效。