01 · 这件事

50,413 星,一个把浏览器拆成命令的 Rust CLI

它解决的是「agent 怎么操作浏览器」,没有顺手解决「agent 该被允许操作什么」。

vercel-labs/agent-browser 的仓库描述只有一句:Browser automation CLI for AI agents。它挂在 Vercel Labs 组织下,主页指向 agent-browser.dev,默认分支是 main。

2026-11-13 用 api.github.com 核对:50,413 星、3,509 fork、570 个未结条目,Apache-2.0,主语言 Rust,建于 2026-01-11,最近一次推送就在核对当天。

身份字段先列成表。下面所有数字都来自同一份仓库接口与仓库内文件,不引用第三方榜单给的估算值。

字段核对值
仓库 / 描述vercel-labs/agent-browser · Browser automation CLI for AI agents
星标 / fork50,413 / 3,509
未结条目570
创建 / 最近推送2026-01-11 / 2026-11-13
许可 / 主语言Apache-2.0 / Rust
默认分支 / 主页main / agent-browser.dev

当前版本是 v0.43.0,2026-11-12 发布,package.json 的 version 字段也是 0.43.0。这次 release 挂了 7 个平台二进制,从 darwin-arm64 到 win32-x64.exe 都在,最小的一个约 17.7 MB。

但它还没到 1.0。CHANGELOG.md 里有 120 个版本标题,最上面是 0.43.0,最下面是 0.7.0;releases 首页 30 条覆盖 2026-07-13 到 11-12。四个月发 30 版,这不是一个功能冻结的仓库。

先给结论:星标量级和版本号成熟度是两件事。读它该盯的是机制与边界,不是收藏数。

02 · 核心机制

一步一条命令,页面用 ref 代替坐标

它省的不是浏览器启动时间,是每一步要喂给模型的页面上下文。

README 把流程写得很短:snapshot 返回紧凑文本形式的可访问性树,每个元素带一个 @e1 这样的引用;agent 对引用下命令,再读一次页面确认结果,如此循环。浏览器在命令之间保持打开,每一步只是一次短 shell 调用。

官方给的 example.com 快照只有一行 - link "Learn more" [ref=e1]。对模型来说,读一行文本与读一张截图再定位像素,是两种完全不同的负担。

这条机制有个硬约束:ref 只在生成它的那次快照里有效。README 明确要求,导航或 DOM 变化之后必须重新 snapshot,不能沿用旧引用。

动作也不假装成功。目标被隐藏、禁用、位于视口之外,或被同意横幅一类元素盖住时,click 会失败而不是回报成功。README 给的解法同样是先处理遮挡物,再取新快照重试。

命令发给后台 daemon:首次命令时启动,通过 Chrome DevTools Protocol 控制浏览器。每个 --session 各有自己的 daemon 与浏览器;无命令一小时后,默认关掉 headless 浏览器并退出,配了会话持久化时先保存状态。

官方 quick start 的五步可以原样列成表,每一步的输入输出都能单独打印出来。

步骤命令作用
1agent-browser open example.com打开页面,浏览器保持存活
2agent-browser snapshot -i只列可交互元素,各带 ref
3agent-browser click @e1按快照里的引用交互
4agent-browser get url读结果,确认动作生效
5agent-browser close收掉本次会话

把五步连起来看,它其实是把一次浏览器会话拆成了可重放的 shell 序列。每一步都有可打印的输入输出,排查时不必回放录像。

03 · 关键细节与数据

四层规模都能数出来,7 个平台三处对齐

命令、配置、文档、技能四层各自有清单,平台数量还在三处文件里完全对得上。

README 的命令表分 11 组,把反引号里的命令逐项数完是 69 个。最多的两组是 Interact 的 16 个、Debug and performance 的 9 个。这张表值得先看分组,再钻单个命令。

命令组命令数命令组命令数
Navigate and read8Tabs, frames, dialogs3
Interact16Debug and performance9
Wait1Sessions and auth6
Capture5Agents and integrations7
Page and network state7Observe2
Setup5合计69

配置文件 agent-browser.schema.json 定义了 53 个属性。文档站 docs/content/docs 下有 31 个 .mdx 页面;随 CLI 发货的技能参考在 skill-data/core/references,共 10 份 .md 文件。

规模数字分散在几个目录里,集中列一张表,比在正文里连着报数清楚。

对象核对值
README 命令表11 组 / 69 个命令
配置 schema53 个属性
文档站 docs/content/docs31 个 .mdx 页面
技能参考 references10 份 .md
core/SKILL.md16,527 字节
references/commands.md53,243 字节
CHANGELOG.md94,959 字节 / 120 个版本标题
Rust / TypeScript 字节数5,288,069 / 347,662
releases 首页30 条,2026-07-13 至 11-12

平台数字三处一致,是这次核对里最硬的一处:README 的 Platforms 段、package.json 的 7 条 optionalDependencies、v0.43.0 release 的 7 个 assets,都是 macOS 两种、Linux 四种、Windows 一种。

v0.43.0 的发布说明里,两条改进都冲着同一处瓶颈:可访问名为空或与同快照里别的 ref 重名时,给 ref 补上图标、data-testid、name 或 id 提示;大页面快照改成只解析一次可访问性树。引用不稳定,这套机制就跑不动。

仓库自己也留了量具。benchmarks 的 agent-loop 场景是 snapshot、click、snapshot 三步,full-workflow 是 7 条命令序列;evals 里单列了 context-footprint 类别,测 CLI 与 MCP 两种接法的上下文占用。

这几处加起来说明,作者把「上下文究竟省了多少」当成可测量指标,而不只是 README 上的一句口号。

04 · 怎么用

两条命令装完,配置却要写对文件才生效

上手成本几乎全在安装,真正的坑在配置文件放在哪个路径。

安装路径不止一条:npm 全局装、Homebrew 装、Linux 加 --with-deps 补系统库,或者不装直接 npx。下面按用途列常用命令,命令本身都出自 README。

命令用途
npm install -g agent-browser全局安装 CLI
agent-browser install首次下载 Chrome for Testing
agent-browser open example.com打开页面
agent-browser snapshot -i取可交互元素与 ref
agent-browser skills get core取随版本的核心工作流
npx skills add vercel-labs/agent-browser给 agent harness 装发现桩
agent-browser mcp以 stdio 起 MCP 服务

技能是跟着 CLI 版本走的。npx skills add 装进来的 skills/agent-browser/SKILL.md 只有 3,306 字节,是个发现桩;AGENTS.md 明确禁止往这个文件写功能内容,真正的工作流在 skill-data/core/SKILL.md,16,527 字节。

桩文件只做一件事:让 agent 先跑 agent-browser skills get core。这样技能说明永远和已装 CLI 同版本,不会教到还没发布的新命令。

配置有三条路:用户级 ~/.agent-browser/config.json、用 --config 或环境变量显式指定的文件,以及自动发现的 ./agent-browser.json。第三条只被信任 11 个展示类字段,其余键一律忽略并给出警告。

引擎与浏览器也能换。--engine 可选 chrome、lightpanda、obscura;云浏览器 provider 列了 Browserbase、Browserless、Browser Use、Kernel、AgentCore。给 MCP 客户端用则是 agent-browser mcp。

开源的是 CLI 与本地驱动,云浏览器是另一笔账。版本口径也要留意:npm 包的 engines.node 写的是 22 以上,README 却说从源码构建需要 Node.js 24 或更高、pnpm 11 和 Rust。

05 · 冷思考

默认不设防,白名单写错地方等于没写

这个仓库最该先读的不是 quick start,是安全文档的第一段。

docs/content/docs/security.mdx 原文写明:导航、动作与输出控制都是 opt-in,默认情况下 agent-browser 对导航、动作和输出不施加任何限制。

allowedDomains、actionPolicy、confirmActions、contentBoundaries 都在那 53 个配置属性里,但默认都不开,需要逐项开启。

更隐蔽的是配置发现规则。schema 与 security.mdx 都写了:自动发现的 ./agent-browser.json 只接受 headed、json、debug 等 11 个字段。

域名白名单、动作策略、扩展、初始化脚本这些统统忽略并警告。把 allowedDomains 写进项目配置,等于没写。

要真正生效,得放进用户级 config,或用 --config 显式加载一个受信任文件。对把 agent 放进 CI 或生产任务的团队,这条路径差异比少记一个命令重要得多。

还有几处默认值得单独记:实验性 WebMCP 对本地启动的 Chrome 默认开启,要用 noWebmcp 或对应环境变量关掉;schema 里同时存在 eval、ignoreHttpsErrors、allowFileAccess、initScripts 这类高权限开关。

成熟度也别用星标代替。0.43.0 加 120 个版本段说明迭代极快,570 个未结条目说明收敛没完成;daemon 空闲一小时退出,长任务得自己把 idleTimeout 设为 0 或显式续期。Node 版本要求两处不一致,也说明文档同步仍有缝。

它把「agent 能不能操作浏览器」做成了可验收的工程件,把「该不该让它操作」完整留给了使用者。50,413 星买不来一条默认生效的白名单;在打开第一个页面之前,先把那份用户级配置写好。

数据核对:全部走 api.github.com 的仓库接口、文件内容与目录清单,不引用短视频口播里的数字。

核对时间 2026-11-13;本文未安装、未运行该 CLI,仅作学习归档。

去看原始仓库

vercel-labs/agent-browser:用可访问性树与 ref 把浏览器拆成一条条 shell 命令的 Rust CLI。

前往 GitHub

相关平台

#开源项目 #浏览器自动化 #Agent 工具链