核心用法
agent-browser 是面向 AI Agent 场景优化的浏览器自动化工具，核心创新在于可访问性树快照（Accessibility Tree Snapshot）机制。与传统 CSS Selector 或 XPath 不同，该工具将页面交互元素解析为结构化 JSON，并为每个元素分配稳定引用编号（如 @e2），实现语义化、确定性的元素选择。
典型工作流：
1. open 打开目标页面
2. snapshot -i --json 生成交互元素快照（-i 过滤可交互元素，--json 输出结构化数据）
3. AI 解析 JSON 中的 refs 字段，获取元素引用编号
4. 使用 @ref 语法执行点击、填充、滚动等操作
5. 页面变化后重新 snapshot，获取新引用
关键能力矩阵：
| 场景 | 命令示例 |
|------|---------|
| 导航控制 | `open`, `back`, `reload` |
| 元素交互 | `click @e2`, `fill @e3 "text"`, `hover @e4` |
| 状态查询 | `is visible @e2`, `get text @e1 --json` |
| 等待策略 | `wait --load networkidle`, `wait --text "Ready"` |
| 会话隔离 | `--session admin` / `--session user` |
| 状态持久 | `state save auth.json` / `state load auth.json` |
| 网络管控 | `network route "**/ads/*" --abort` |
| 多标签/帧 | `tab new`, `frame @e5` |
显著优点
1. 确定性元素定位：引用编号基于可访问性树，不受 DOM 结构变化、动态 class 名影响，显著降低 flaky test 概率
2. AI 友好输出：--json 模式输出结构化数据，便于 LLM 直接解析，无需复杂的 HTML 清洗
3. 多会话并行：内置 session 机制，支持同一时刻模拟多个独立用户（如 admin + user 并发测试）
4. 状态复用：cookies、localStorage、sessionStorage 可持久化，跳过重复登录流程
5. 网络级控制：支持请求拦截、mock、阻断广告/追踪脚本
6. 性能优化：headless 模式运行，无 GUI 开销；--compact 与深度限制减少数据传输量
潜在缺点与局限性
| 局限 | 说明 |
|------|------|
| 视觉能力缺失 | 不提供截图分析能力（需配合内置浏览器工具） |
| 浏览器扩展 | 不支持插件/扩展集成 |
| 学习成本 | 需理解可访问性树概念，与传统 Selector 思维不同 |
| 快照刷新机制 | 页面变化后必须重新执行 snapshot，否则引用失效 |
| 复杂手势 | drag、scroll 等操作坐标基于引用元素，精细轨迹控制受限 |
| 生态成熟度 | 相比 Puppeteer/Playwright 社区资源较少 |
适合人群
- AI Agent 开发者：构建需要浏览器自动化的 LLM 工作流
- 自动化测试工程师：编写稳定、低维护成本的 E2E 测试
- 爬虫开发者：需要绕过简单反爬、处理 SPA 动态渲染
- 多账号运营：需隔离 session 的社交媒体/电商平台自动化
常规风险
- 引用失效风险：页面跳转或 AJAX 刷新后，旧引用编号失效，必须重新 snapshot
- 状态泄露风险：session 隔离依赖进程级隔离，非严格沙箱，敏感场景需额外验证
- 网络mock陷阱：
--body参数若传入无效 JSON 可能导致请求异常，建议前置校验 - 等待策略误配：
networkidle在慢接口场景可能超时，需搭配合理wait时间 - 存储持久化：
state save明文存储 cookies，多用户环境注意文件权限