内容
<div align="center">
<img src="docs/img/hero.png" width="720" alt="agent-browser: 高效的浏览器自动化工具">
<br>
单可执行文件 · 跨平台 · 专为AI智能体优化的引擎（无Playwright、无Puppeteer、无Node）
<br><br>
[](LICENSE)
[](https://go.dev)
[](https://github.com/dondai1234/agent-browser/actions/workflows/test.yml)
[](https://goreportcard.com/report/github.com/dondai1234/agent-browser)
[](https://modelcontextprotocol.io)
<br>
<img src="docs/img/flow.svg" width="780" alt="意图优先的流程：智能体指定操作，工具解析并执行，返回判决结果">
</div>
---
> 为**使用它的智能体**而构建，而不是为人类构建。智能体指定它想要的操作（`执行 "登录"`）；工具解析并执行它，返回一个**判决结果**。快照是密集的参考线，而不是ARIA转储。每个操作返回一个**增量**（发生了什么变化）加上一个一行语义结果。结构化数据以**JSON**形式返回，而不是200个引用来重建。操作日志从智能体的上下文中**卸载**。
## 为什么选择agent-browser
大型浏览器MCP服务器在每个步骤都会给智能体增加负担。agent-browser v2在v1的高效引擎上添加了一个**认知层**（意图优先的操作、判决结果、结构化提取、会话内存），因此智能体可以将令牌花费在任务上，而不是用于解释页面。
与两个最大的浏览器自动化MCP服务器进行对比：
| | **agent-browser v2** | Playwright MCP | Chrome DevTools MCP |
|---|:--:|:--:|:--:|
| Hacker News快照 | **~1,200令牌** | ~14,700令牌 | ~9,800令牌 |
| GitHub仓库快照 | **~1,250令牌** | ~21,600令牌 | ~20,800令牌 |
| 连接成本（工具定义+指令） | **~3,650令牌**（20个工具） | ~3,442令牌（22个工具） | ~5,000令牌（26+个工具） |
| Saucedemo登录（真实任务，所有成功） | **~154令牌**（意图优先） | ~1,714令牌 | ~1,483令牌 |
<div align="center">
<img src="docs/img/tokens.svg" width="760" alt="柱状图：saucedemo登录令牌成本，agent-browser ~154 vs Chrome DevTools ~1,483 vs Playwright ~1,714">
</div>
在Playwright MCP的连接成本范围内，比Chrome DevTools MCP更轻，并且**您还可以获得这三项功能**：意图优先的`执行`、`判决`和`提取`/`历史记录`。在真实任务上的差距约为10倍：上面的登录操作是`导航` + 三个`执行`调用（命名字段，命名按钮）而不是查找、填充、查找、点击、重新查看、重新查看。
<sub>连接成本：agent-browser v2 ~3,650令牌（20个工具，包括`重置`恢复工具）；Playwright MCP ~3,442令牌（来自jdhodges.com的真实Claude Code每个工具的分解）；Chrome DevTools MCP ~5,000令牌（配置/版本不同，变动范围~5k-17k，使用低端）。快照大小 + 登录任务通过在实时页面上运行每个服务器测量（Windows，headless，2026-06）；登录操作是通过意图优先的`执行`（导航简短 + 3次执行）与竞争对手的按引用流程完成的，所有三个都成功。数字是近似值；每任务行是决定性的比较。</sub>
## v2新增功能（认知层）
<div align="center">
<img src="docs/img/cognition.png" width="780" alt="认知层在chromedp引擎上：执行/判决/提取/历史记录在快照和增量之上">
</div>
- **`执行` - 意图优先的操作。** 传送控件的名称（`执行 "登录"`，`执行 "用户名" value=x`）；本地启发式解析它（无LLM，无每次调用成本），执行适合其角色的操作（点击/填充/选择），并返回判决结果 + 增量。折叠查找 + 点击/填充 + 查看为一个调用。模糊匹配返回排名候选（它从不猜测）- 使用`nth`或`role`消歧义，或使用`点击`/`填充`按引用。
- **每次操作的判决结果。** `导航到...` / `对话框打开：...` / `状态：添加到购物车` / `更改：+1 -1 ~1` / `无可见效果` / `挑战：...`。对于非导航操作，还包括触发的XHR/Fetch响应（`网络：/api/cart 200`）- “我的点击是否命中API”的循环，已关闭，无需重新查看。
- **`查看 level=brief` - 页面理解。** 一个~50令牌的页面简报：页面类型（登录表单/列表/文章/对话框），身份验证状态（已登录/匿名/阻止），顶部主要操作带有引用，区域，计数。无需扫描引用即可定位。
- **`提取` - 结构化数据，而不是引用解析。** `提取表格`（行，JSON；如果第一行是标题，则为对象），`提取链接`（`[{text,href}]`），`提取列表`，`提取表单`（`[{ref,role,name,value}]`来自缓存树 - 将其反馈给`执行`/`填充`），`提取文章`（主要内容文本）。
- **`历史记录` - 会话内存卸载到上下文之外。** 一个步骤/操作/判决结果/URL的滚动日志。查询它（`last=N`，`errors=true`）以在长流程后重新定位，而不是在上下文窗口中携带记录。
v1的按引用工具（`点击`/`填充`/`选择`/`悬停`/`按键`）仍然存在，当您有引用或需要非默认操作时。v2是附加的。
## v2.2新增功能（可靠性+优化）
与[charlotte](https://github.com/TickTockBent/charlotte)的实时对比（最接近的直接竞争对手 - 相同的令牌高效、AX树优先的理论）提出了三项具体改进。v2.2发布了这三项改进：
- **URL稳定的重新排序的更准确判决结果。** 点击重新排序*相同的*DOM节点（产品排序，过滤器，SPA重新渲染）曾经读取“无可见效果”，因为后端ID集未更改。v2.2为每个树添加了顺序敏感的内容签名；重新排序现在报告**“页面更新（URL稳定；例如排序/过滤/SPA重新渲染）- 调用see刷新引用”**。元素级更改仍然优先。
- **`nth`从末尾开始。** `执行`/`查找`消歧义现在接受负数：`nth=-1` = N个相同按钮中的最后一个，`-2` = 第二个最后一个。需要添加最昂贵的N个相同“添加到购物车”按钮的案例，无需计数。
- **CSS选择器逃生舱。** `查找`/`点击`/`填充`/`执行`现在采用`选择器="<css>"`来访问a11y树无法访问的元素（自定义`div[role=widget]`，带有处理器的表示性span）- 一个纯a11y树工具会丢失到CSS选择器工具的地方。`查找选择器`返回带有`sel=`的`[css]`行，您可以将其传回；操作路径重用真正的鼠标点击 + 原生值设置器填充，因此可靠性与引用路径匹配。
实时比较（修正）：agent-browser在往返（少33-50％的调用）、响应权重（小5-80倍）、判决结果和点击可靠性方面获胜。charlotte的点击saucedemo的React“添加到购物车”返回成功**无效果**（验证：空购物车，导航到新的`/cart.html`后）- 静默失败。charlotte真正的独家优势：结构化`diff`、会话/cookie管理和拖放。完整报告：`charlotte-vs-agent-browser-report.md`. 完整实时套件绿色（651s，0失败）；`govulncheck` 0可达。
## v2.1新增功能（稳定引用 + 诚实基准）
- **稳定引用。** 引用曾经是位置性的（`r1..rN`按树顺序），在每次快照时重新分配，因此页面重新渲染会默默地将旧引用重新定位到*不同的*控件 - 智能体点击错误的控件却不知道。现在相同的DOM节点在重新渲染时保持相同的引用（每个选项卡的`backendNodeID -> ref`映射，具有单调计数器），因此您持有的引用在页面突变后仍然有效。映射在导航时清除（新页面=新引用），但计数器保持单调，因此早期页面的过时引用无法与当前引用冲突 - 您得到一个干净的`引用未找到；调用查看`而不是静默错误。已在实时环境中验证（`TestStableRefsAcrossReRender`，负验证）。
- **任务成功率基准。** 快照大小很容易衡量；成功率基准才是真正的衡量标准。`bench/successtoken`在本地fixtures上运行5个多步骤任务（登录，搜索+提取，表单填充+选择+提交，多页面导航，延迟列表滚动）与`@playwright/mcp`进行对比，具有确定性的脚本智能体，因此比较公平且可复制。结果（2026-06-23）：两个5/5（100％）成功，**agent-browser 1142令牌 vs playwright-mcp 2337令牌**（约2倍更少，成功率相等）。参见`bench/successtoken/README.md`.
| | **agent-browser v2.1** | Playwright MCP |
|---|:--:|:--:|
| 任务成功率（5个多步骤任务） | **5/5（100％）** | 5/5（100％） |
| 所有5个任务的总工具I/O令牌 | **~1,142令牌** | ~2,337令牌 |
| 成功率每令牌 | **~228令牌** | ~467令牌 |
<sub>工具I/O令牌=（发送参数JSON + 返回文本）/ 4，对确定性脚本智能体的总和。相同的fixtures，相同的结束状态断言。每个工具使用自己的高效路径（agent-browser `执行`+`读取`；playwright-mcp `快照`+`类型`+`点击`）。运行`go run ./bench/successtoken/ -compare`以复制。</sub>
### v2.1.1：丑陋ARIA白名单强化
审阅者指出，角色白名单仅限于页面的ARIA清洁度：在一个凌乱的SPA中，装饰性的`div[role=button]`广告和`span[role=button]`没有任何处理程序会提升到语义树中，而静态白名单无法区分它们与真正的控件。v2.1.1删除**未命名且不可聚焦**的交互元素 - 原生`<button>`/`<a>`/`<input>`始终可聚焦，因此真正的图标按钮和无标签输入框保留；命名自定义小部件保留，即使不可聚焦；仅无名称、不可聚焦的“按钮”（装饰性div / 广告槽）被删除。诚实限制：命名垃圾（10x“点击这里”）保留，因为判断名称质量是智能体的任务。`bench/aria_mess`针对11个丑陋ARIA病理学运行快照，并报告白名单保留的内容；测量前后，`decorative-role-button` 8->3引用，`ad-slot-divs` 9->1，`messy-spa` 36->30，保留真正的图标按钮和无标签输入框。完整实时套件绿色（无实际控件被丢弃）。
## 安装
需要[Go](https://go.dev) 1.26+ 和 Chrome/Chromium（自动发现）。
```sh
go install github.com/dondai1234/agent-browser/v2/cmd/agent-browser@latest
```
验证安装并更新：
```sh
agent-browser --version # 检查已安装的版本
go install github.com/dondai1234/agent-browser/v2/cmd/agent-browser@latest # 重新运行以更新
```
### 或者：让你的智能体安装它
将此提示复制到Claude Code、Cursor、Copilot Chat、Windsurf或任何具有shell + MCP配置访问权限的智能体，并让它执行其余操作：
```
安装agent-browser MCP服务器并将其连接到此客户端：
1. 运行： go install github.com/dondai1234/agent-browser/v2/cmd/agent-browser@latest
2. 验证： agent-browser --version （期望“agent-browser v2.0.0”或更新版本）
3. 查找您正在运行的智能体框架（Opencode、OpenClaw、Hermes Agent等）并定位其MCP配置。
4. 添加一个名为“agent-browser”的stdio MCP服务器：命令“agent-browser”，参数["mcp"]。
5. 确认它连接，然后告诉我它已就绪。
```
## 连接到你的智能体
将其添加到任何MCP客户端：
```json
{
"mcpServers": {
"agent-browser": { "command": "agent-browser", "args": ["mcp"] }
}
}
```
Cursor、Claude Code、Claude Desktop、Windsurf、VS Code Copilot、opencode、Hermes Agent和OpenClaw都支持此形状（VS Code使用`"servers"`而不是`"mcpServers"`）。准备好粘贴的配置和每个客户端的文件路径位于[`examples/`](examples/README.md）。Claude Code一行：`claude mcp add agent-browser -- agent-browser mcp`.
> 如果您的客户端报告`spawn agent-browser ENOENT`，它无法在其PATH上找到二进制文件 - 在`command`中使用绝对路径：`$(go env GOPATH)/bin/agent-browser`（在Windows上追加`.exe`）。
## 智能体工作流（v2：意图优先）```
navigate https://saucedemo.com level=brief → 页面：登录表单 | 身份验证：匿名 | 操作：r3按钮“登录”
act "用户名" value="standard_user" → 执行“用户名”-> [r4] 文本框（填充）| 判决结果：已更改
act "密码" value="secret_sauce" → 执行“密码”-> [r5] 文本框（填充）| 判决结果：已更改
act "登录" → 执行“登录”-> [r3] 按钮（点击）| 判决结果：导航到/inventory.html
提取表单 → [{"ref":"r4","role":"textbox","name":"用户名"}, ...]
where → url / page / auth / last action / scroll position
```
命名控件，获取判决结果。你很少在操作后调用`see` - 判决结果和增量告诉你发生了什么。按引用模式（`find`然后`click r12`）仍然有效，当您需要精度时。
## 工具（20）
`navigate`（打开/返回/前进/重载）· `see`（简要/最小/摘要/完整）· `find` · `extract`（表格/链接/列表/表单/文章）· `read`（链接引用包括`href`）· `click` · `act`· `act`（意图优先）· `fill`（单个或 `{ref:value}`映射）· `select` · `scroll`（按像素或`ref`；报告位置）· `wait`（url/text/gone条件）· `screenshot`（视口/全页/参考）· `eval` · `tabs` · `upload` · `press_key` · `hover` · `history` · `where` · `reset`（重启浏览器 - 从卡住的标签页或崩溃的浏览器中恢复）
每个工具的描述都是手工制作的，以便准确地告诉智能体要传递什么，它返回什么，以及需要注意的事项。`act`通过本地启发式（无LLM）解析名称；`press_key`触发原生按键事件（Enter提交表单）；`hover`触发CSS `:hover`；`select`匹配选项的值*或*可见文本；`scroll`告诉你是否继续滚动；`eval`涵盖了其他类型工具无法暴露的内容（canvas，计算状态，历史记录，cookie，控制台错误）。
