让 AI 编程助手真正"上手"操作浏览器，是 agent 工具链里被反复验证的需求：登录站点、填表单、点按钮、截图取证、抓数据、跑端到端测试。传统路径是把 Playwright 交给模型——让它写脚本、运行、看报错、改脚本，循环往复，慢且脆弱，token 也烧得凶。
vercel-labs 出品的 agent-browser 给出了另一种答案：一个专为 AI agent 设计的浏览器自动化 CLI。Rust 原生二进制、直连 CDP 协议、以"无障碍树快照 + @eN 元素引用"为核心交互原语，不依赖 Playwright 或 Puppeteer。在 skills.sh 上它已累计超过一百万次安装。本文按"概述 → 核心设计 → 安装上手 → 命令全景 → 技能体系 → 进阶能力 → 注意事项"组织全文。
1、概述
agent-browser 的官方定位是 "Browser automation CLI for AI agents"——注意定语是 for AI agents，它不是给人写的 Selenium 替代品，而是给 Cursor、Claude Code、Codex、Continue、Windsurf 这类编程助手用的"浏览器之手"。
它有几个鲜明的身份特征：
- 出品方 vercel-labs，Apache-2.0 开源
- 原生 Rust CLI，不是 Node.js 包装层
- 通过 CDP 直连 Chrome/Chromium，零 Playwright 依赖
- 交互原语是无障碍树快照与紧凑的
@eN元素引用 - 内置会话管理、认证保险库、状态持久化与视频录制
- 附带可观测性 Dashboard，独立运行在 4848 端口
这些特征共同指向一个目标：让 agent 与网页的每一次交互都快、省 token、可复现。
2、核心设计：无障碍树与元素引用
agent-browser 最值得理解的设计，是它选择"喂给模型什么"。DOM 太大，截图太贵，它选了第三条路——无障碍树（accessibility tree）。
典型工作流是一套"拍快照 → 拿引用 → 做操作"的循环：
agent-browser snapshot # 获取带元素引用的无障碍树
agent-browser click @e2 # 按引用点击
agent-browser fill @e3 "test@example.com" # 按引用填充
agent-browser get text @e1 # 按引用取文本
snapshot 输出的无障碍树里，每个可交互元素都带一个紧凑引用（如 @e1、@e2），后续命令直接用引用定位，不需要 CSS 选择器或 XPath。对 LLM 而言，无障碍树天然比 DOM 小一个数量级，语义也更贴近"这是一个按钮""这是一个输入框"——模型读得快，也读得懂。
传统选择器依然支持，作为兜底手段：
agent-browser click "#submit"
agent-browser find role button click --name "Submit"
另一个贴心的细节：click 在目标被遮挡时会尽早失败，并报告遮挡元素——比如弹出的Cookie 授权横幅盖住了按钮。此时先关闭遮挡物，重新 snapshot 再重试原引用即可。这种"早失败、给线索"的错误设计，正是为 agent 的自主纠错循环准备的。
3、安装与快速上手
推荐全局安装原生二进制，首次运行时下载 Chrome：
npm install -g agent-browser
agent-browser install # 首次使用：从 Chrome for Testing 下载浏览器
agent-browser install 从 Chrome for Testing 下载浏览器——这是 Google 官方的自动化专用渠道。如果机器上已有 Chrome、Brave 甚至 Playwright 装过的浏览器，会被自动检测复用，无需重复下载。
四种安装方式一览：
| 方式 | 命令 | 适用场景 |
|---|---|---|
| npm 全局 | npm install -g agent-browser |
通用推荐 |
| Homebrew | brew install agent-browser |
macOS |
| Cargo | cargo install agent-browser |
Rust 用户 |
| 源码构建 | pnpm build && pnpm build:native |
参与开发 |
Linux 下如缺系统库，执行 agent-browser install --with-deps 一并补齐；升级用 agent-browser upgrade，它会自动识别当初的安装方式（npm、Homebrew 或 Cargo）并选择对应的更新命令。源码构建才需要 Node.js 24+ 与 Rust，日常使用完全不需要。
最短可用流程如下：
agent-browser open example.com
agent-browser screenshot page.png
agent-browser close
4、命令全景
核心命令覆盖了浏览器操作的完整动词表，全部以子命令形式暴露：
agent-browser open # 启动浏览器（不导航，停在 about:blank）
agent-browser open <url> # 启动并导航（别名 goto、navigate）
agent-browser read [url] # 抓取 agent 可读文本，或读当前页 DOM
agent-browser click <sel> # 点击元素（--new-tab 在新标签打开）
agent-browser type <sel> <text> # 向元素键入文本
agent-browser fill <sel> <text> # 清空后填充
agent-browser press <key> # 按键：Enter、Tab、Control+a
键盘操作做了细粒度拆分，满足不同场景的真实性需求：
keyboard type模拟真实按键序列，作用于当前焦点keyboard inserttext直接插入文本，不触发按键事件keydown与keyup支持按住不放，用于组合键与长按
截图也有工程细节：headless 模式下会自动隐藏原生滚动条，保证图像输出的一致性；需要保留滚动条时，启动时传 --hide-scrollbars false。
5、技能体系：文档随版本走
agent-browser 的 SKILL.md 本身只是一份"发现存根"（discovery stub）——它不堆砌用法，而是指引 agent 在执行任何命令前，先从 CLI 动态拉取与安装版本严格一致的工作流文档：
agent-browser skills get core # 核心工作流、常见模式与排障
agent-browser skills get core --full # 附完整命令参考与模板
agent-browser skills list # 列出当前版本全部技能
这个设计很聪明：文档由 CLI 自己提供，永远匹配已安装版本，指令不会陈旧。仓库里的静态文件无法随发布更新，而"从工具本身读取用法"让文档天然保鲜。
除核心技能外，还有一组面向特定场景的专项技能：
electron：自动化 Electron 桌面应用（VS Code、Slack、Discord、Figma、Notion、Spotify）slack：Slack 工作区自动化，查未读、发消息、搜会话dogfood：探索性测试、QA、bug 猎捕derive-client：录制 HAR 并为一个站点推导出独立的 API 客户端vercel-sandbox：在 Vercel Sandbox 微虚拟机中运行agentcore：使用 AWS Bedrock AgentCore 云端浏览器
6、进阶能力：会话与可观测
生产级的浏览器自动化不止"能点能填"，agent-browser 补齐了状态与观测两翼。
会话体系支持多标签页管理、状态持久化与恢复——agent 可以在长任务中挂起浏览器、稍后续跑。认证保险库（authentication vault）安全保管各类站点的登录态，避免每次任务都重走登录流程；配合状态持久化，"登录一次、长期复用"成为默认体验。视频录制则把整个操作过程录成可回放的证据，QA 与审计场景直接受益。
可观测性 Dashboard 独立于浏览器会话运行在 4848 端口，也可通过代理地址 https://dashboard.agent-browser.localhost 访问。会话标签页、状态与流量在内部代理转发，无需暴露各会话端口——对远程与容器化环境尤其友好。
7、注意事项
工程上值得肯定的三点：Rust 原生二进制带来毫秒级启动；CDP 直连避免了 Playwright 运行时的体积与版本纠葛；无障碍树路线让上下文开销显著低于 DOM 或视觉方案。
使用中有两个易踩的点：
点击报"被遮挡"不是 bug 而是特性——先处理遮挡元素（通常是授权弹窗或横幅），再重新
snapshot获取新引用后重试。快照引用是瞬时的，页面变化后旧引用会失效。
另外，npm install agent-browser 的项目级安装会把版本锁进 package.json，适合团队统一版本；个人全局安装则随 upgrade 保持最新。
8、总结
agent-browser 把"AI 操作浏览器"这件事从"让模型写 Playwright 脚本"升级为原生命令直调：无障碍树快照喂给模型的是精炼语义而非冗长 DOM，@eN 引用让每次交互短促确定，Rust 二进制与 CDP 直连保证了速度，技能体系让文档与版本永不脱节，会话与认证保险库则把它从演示工具推向生产。
- 核心原语：
snapshot出无障碍树，@eN引用做交互 - 双选择器：引用优先，传统 CSS 与 role 选择器兜底
- 安装简单：npm 一条命令，浏览器自动检测或下载
- 技能自服务：
skills get core拿到与版本一致的完整工作流 - 场景外延：Electron 应用、Slack、云端浏览器、HAR 导出客户端
- 生产配套：会话、认证保险库、视频录制、4848 观测面板
对于想让 Cursor、Claude Code 等 AI 编程助手真正接管"登录、填表、点按钮、抓数据、跑测试"这类浏览器任务的开发者，建议先 npm i -g agent-browser && agent-browser install 跑通一次 open → snapshot → click 循环，再把 skills get core 的内容交给你的 agent——之后它会自己学会这双手。
