1. 项目定位与用途
agent-browser 是一个专为 AI 代理设计的浏览器自动化命令行工具，核心定位是提供轻量、快速的浏览器控制能力。它通过原生 Rust 实现并编译为二进制文件，直接使用 Chrome DevTools Protocol 与浏览器通信，避免了 Node.js 运行时的开销。主要用途包括：为 AI 代理提供网页操作接口、执行自动化测试、进行数据抓取、录制和回放用户交互等。工具输出带引用的可访问性快照，便于 AI 模型解析页面结构并执行精确操作。
项目档案命令行工具
agent-browser 浏览器自动化 CLI 工具 - AI 代理专用 | 安装使用指南与命令详解
vercel-labs/agent-browser：agent-browser 是专为 AI 代理设计的轻量级浏览器自动化 CLI 工具，基于 Rust 实现并通过 Chrome DevTools本页整理它解决什么问题、适用场景、安装方式和使用方法。
AI 总结
agent-browser 是专为 AI 代理设计的轻量级浏览器自动化 CLI 工具，基于 Rust 实现并通过 Chrome DevTools Protocol 直接控制浏览器，提供快速、高效的原生二进制执行环境，无需 Playwright 等重型依赖。
中文项目介绍
agent-browser 是由 Vercel Labs 开发的浏览器自动化命令行工具，专为 AI 代理场景优化。它采用 Rust 语言编写，编译为原生二进制文件，通过 Chrome DevTools Protocol (CDP) 与浏览器直接通信，实现了轻量、高效的浏览器控制能力。
传统浏览器自动化方案如 Playwright 或 Puppeteer 通常需要完整的 Node.js 运行时和较大的依赖体积，这对于需要快速启动、低资源占用的 AI 代理场景不够理想。agent-browser 通过原生 Rust 实现和 CDP 直连，避免了这些 heavyweight 依赖，提供了更快的启动速度和更小的部署 footprint。
工具支持完整的浏览器操作集，包括页面导航、元素交互（点击、填充、悬停等）、键盘输入、截图、PDF 生成、可访问性快照等。其独特的快照功能输出带引用的可访问性树，特别适合 AI 模型理解和操作。此外还支持运行时流式传输、CDP 连接、文件上传等高级功能。
适用于 AI 驱动的网页自动化任务、端到端测试、数据抓取与监控、用户行为录制回放等场景。可通过 npm、Homebrew、Cargo 或源码编译安装，并自动管理 Chrome 浏览器依赖，支持 Linux、macOS 和 Windows 平台。
详细信息与使用说明
2. 解决的问题
agent-browser 解决了 AI 代理在浏览器自动化场景中的几个核心问题：一是传统方案（如 Playwright、Puppeteer）依赖 Node.js 环境且体积较大，不适合资源受限的部署环境；二是现有工具的操作反馈（如选择器）对 AI 模型不够友好，需要更结构化的页面表示；三是需要更快的启动速度和更低的内存占用以适应高并发代理任务。通过 Rust 原生实现、CDP 直连和可访问性树快照，agent-browser 提供了更高效、更 AI 友好的自动化方案。
3. 适用场景
agent-browser 适用于以下场景：AI 代理自动浏览网页并执行表单填写、点击、搜索等交互任务；网页功能与 UI 的自动化测试；结构化数据抓取与页面内容监控；用户行为录制与回放；需要快速启动、低资源占用的浏览器自动化任务。工具特别适合需要与 AI 模型（如大语言模型）集成的场景，因其快照输出格式便于模型解析和决策。不适用于需要跨浏览器兼容性测试（仅支持 Chrome 系浏览器）或需要浏览器扩展支持的场景。
4. 安装方式
agent-browser 提供多种安装方式：全局 npm 安装（推荐）：npm install -g agent-browser；本地项目依赖：npm install agent-browser；Homebrew（macOS）：brew install agent-browser；Cargo（Rust）：cargo install agent-browser；从源码编译：git clone 仓库后执行 pnpm install、pnpm build、pnpm build:native 和 pnpm link --global。Linux 用户需额外运行 agent-browser install --with-deps 安装系统依赖。首次使用任何安装方式后，都需要运行 agent-browser install 从 Chrome for Testing 下载浏览器二进制文件。
5. 使用方式
基本使用流程：agent-browser open <url> 导航到目标页面；agent-browser snapshot 获取带引用的可访问性树；agent-browser click @e2 通过快照中的引用点击元素；agent-browser fill @e3 "text" 填充表单；agent-browser get text @e1 获取元素文本；agent-browser screenshot page.png 截图；agent-browser close 关闭浏览器。除引用外，也支持传统 CSS 选择器（如 agent-browser click "#submit"）和基于角色的选择器（如 agent-browser find role button click --name "Submit"）。完整命令列表包括导航、交互、键盘、滚动、拖拽、上传、PDF 生成、JavaScript 执行、CDP 连接和流式传输等。
6. 实现特点与架构
agent-browser 采用 Rust 编写核心逻辑，确保高性能和内存安全。架构上分为 CLI 前端（Rust 二进制）和浏览器控制后端，通过 Chrome DevTools Protocol 通信。关键模块包括：命令解析（cli/src/commands.rs）、浏览器操作（cli/src/native/actions.rs）、CDP 协议集成（cli/src/native/cdp/）、元素识别（cli/src/native/element.rs）、快照生成（cli/src/native/snapshot.rs）、截图（cli/src/native/screenshot.rs）和流式传输（cli/src/native/stream/）。构建系统使用 Cargo 编译 Rust 代码，Docker 处理跨平台构建，Node.js 脚本协调版本同步和发布。文档站点基于 Next.js，使用 MDX、Tailwind CSS 和 Shadcn UI 构建。
思维导图
agent-browser
CLI 核心
Rust 原生实现
命令解析与分发
参数验证与标志处理
浏览器控制
Chrome DevTools Protocol
浏览器实例管理
CDP 连接与通信
操作命令
导航（open/goto）
元素交互（click/fill/hover）
键盘输入（type/keyboard）
截图与快照
高级操作（drag/upload/scroll）
选择器系统
CSS 选择器
可访问性引用（@ref）
角色选择器（role button）
快照与输出
可访问性树生成
元素引用分配
标注截图
PDF 导出
流式与连接
运行时 WebSocket 流
CDP 连接模式
网络请求监控
依赖管理
Chrome 自动下载
版本检测与升级
系统依赖安装（Linux）
构建与发布
Cargo 编译
Docker 跨平台构建
npm 包发布
常见问题
agent-browser 和 Playwright/Puppeteer 有什么区别？
agent-browser 是原生 Rust CLI 工具，通过 CDP 直接控制浏览器，无需 Node.js 运行时，体积更小、启动更快，专为 AI 代理场景优化。而 Playwright/Puppeteer 是 Node.js 库，依赖较重，更适合复杂测试框架集成。
如何安装和配置 agent-browser？
支持多种安装方式：npm install -g agent-browser（推荐）、brew install agent-browser、cargo install agent-browser 或从源码编译。首次使用需运行 agent-browser install 自动下载 Chrome for Testing 浏览器二进制文件。Linux 用户可能需要额外依赖：agent-browser install --with-deps。
agent-browser 支持哪些浏览器操作？
支持完整操作集：页面导航（open）、元素点击（click）、表单填充（fill）、键盘输入（type/keyboard）、悬停（hover）、滚动（scroll）、拖拽（drag）、文件上传（upload）、截图（screenshot）、PDF 导出（pdf）、可访问性快照（snapshot）、JavaScript 执行（eval）、CDP 连接（connect）以及运行时流式传输（stream）。
快照（snapshot）功能有什么特别之处？
快照生成带引用的可访问性树（Accessibility Tree），每个可交互元素都有唯一 @ 引用（如 @e1、@e2）。这种格式特别适合 AI 模型解析页面结构并执行精确操作，是 agent-browser 为 AI 代理场景优化的核心特性。也可使用传统 CSS 选择器。
agent-browser 是否支持跨平台？
是的，支持 Linux、macOS 和 Windows 平台。通过 npm、Homebrew、Cargo 安装的版本已预编译对应平台二进制文件。从源码编译时，可使用 pnpm build:linux、pnpm build:macos、pnpm build:windows 或 pnpm build:all-platforms 脚本进行跨平台构建，Docker 用于 Linux 和 Windows 的编译环境。