agent-browser

面向 AI 代理的浏览器自动化 CLI。紧凑的文本输出最大限度地减少上下文使用。100% 原生 Rust。

npm install -g agent-browser      # all platforms
brew install agent-browser        # macOS
agent-browser install             # Download Chrome (first time)

# or try without installing
npx agent-browser open example.com

功能特性¶

• 代理优先：紧凑的文本输出比 JSON 使用更少的 token，专为 AI 上下文效率而设计
• 基于 Ref：快照返回带有 refs 的可访问性树，用于确定性元素选择
• 功能完整：50+ 命令，涵盖导航、表单、截图、网络、存储、文件、标签页、框架和调试
• 可观测：内置视频录制、流式、调试、性能分析和差异比较工具
• 现代应用：网络控制、React 与 Web Vitals、初始化脚本、Next.js + Vercel和 eve 扩展工作流均拥有一流文档
• 有状态：会话、配置文件、认证状态、Cookie、存储、代理和安全控制支持长时间运行的代理
• 跨平台：macOS、Linux、Windows，提供原生二进制文件

兼容工具¶

Claude Code、Cursor、GitHub Copilot、OpenAI Codex、Google Gemini、opencode，以及任何能够运行 shell 命令的代理。

示例¶

# Navigate and get snapshot
agent-browser open example.com
agent-browser snapshot -i

# Output:
# - heading "Example Domain" [ref=e1]
# - link "More information..." [ref=e2]

# Interact using refs
agent-browser click @e2
agent-browser screenshot page.png
agent-browser close

为什么使用 refs？¶

snapshot 命令返回一个紧凑的可访问性树，其中每个元素都有一个唯一的 ref，例如 @e1、@e2。这提供了：

• 上下文高效：文本输出使用约 200-400 个 token，而完整 DOM 需要约 3000-5000 个
• 确定性：Ref 指向快照中的确切元素
• 快速：无需重新查询 DOM
• AI 友好：LLM 可以自然地解析文本输出

架构¶

客户端-守护进程架构，实现最佳性能：

1. Rust CLI：解析命令，与守护进程通信
2. 原生守护进程：使用直接 CDP 的纯 Rust 守护进程，通过 Chrome DevTools Protocol 管理 Chrome

守护进程会在命令之间自动启动并持续运行。默认情况下，它会保存已配置的恢复状态，关闭其无头浏览器，并在一个小时没有命令或仪表盘输入后退出。如果没有 --restore 或其他恢复键，关闭时会丢弃临时浏览器状态和打开的标签页。有头浏览器、Safari 和 iOS WebDriver 会话，以及用户附加的浏览器不受默认超时限制；提供商拥有的云浏览器不在此豁免之列。使用 --idle-timeout <time> 或 AGENT_BROWSER_IDLE_TIMEOUT_MS 来调整超时时间，使用 0 来禁用它。

平台¶

适用于 macOS（ARM64、x64）、Linux（ARM64、x64）和 Windows（x64）的原生 Rust 二进制文件。