核心用法
agent-browser 是一款面向AI Agent设计的Headless浏览器自动化CLI工具，采用独特的可访问性树快照 + ref引用机制替代传统CSS/XPath选择器，实现人机协同的确定性交互。
典型工作流
1. 导航与快照：agent-browser open URL → agent-browser snapshot -i --json
2. AI解析JSON：从返回的refs对象识别目标元素（如@e2代表Submit按钮）
3. 精确交互：click @e2、fill @e3 "text"等ref-based命令
4. 状态重采样：页面变化后重新snapshot获取最新refs
关键特性
- 会话隔离：
--session参数支持多浏览器实例并行（如同时模拟admin/user） - 状态持久化：
state save/load跳过重复登录流程 - 网络控制：路由拦截、请求mock、响应篡改
- 多上下文：标签页切换、iframe穿透
- 等待策略：支持元素、文本、URL、网络空闲、自定义函数等多维等待
显著优点
| 维度 | 优势 |
|------|------|
| **确定性** | ref机制消除动态DOM导致的 flaky tests |
| **可解释性** | 快照包含元素角色(role)和可访问名称(name)，便于AI理解页面结构 |
| **性能** | 纯CLI无GUI开销，适合高频自动化 |
| **工程化** | 内置session管理、状态持久化、CI/CD友好 |
| **来源** | Vercel Labs官方维护，技术栈现代 |
潜在局限
- 视觉盲区：Headless模式无法直接截图分析，需显式调用
screenshot命令 - 学习成本：ref-based范式与传统Selenium/Playwright选择器逻辑不同
- 生态锁定：专属于agent-browser的ref系统，迁移成本较高
- 依赖管理：需预装Chromium，Linux环境需处理系统依赖
适合人群
- 构建复杂多步骤Agent工作流的开发者
- 需要高稳定性浏览器自动化的测试工程师
- 追求CLI性能、无需视觉反馈的后端场景
- 同时模拟多用户角色的并发测试场景
常规风险
- 数据泄露：
state save可能持久化敏感cookie/session，需妥善管理JSON文件权限 - 会话混淆：多session并行时若未显式指定
--session，可能操作错误上下文 - 网络mock副作用：路由拦截可能影响页面正常功能，需精确匹配规则
- ref失效：页面重大结构变化后旧ref可能指向错误元素，需重新snapshot