Agent Browser Clawdbot

核心用法

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

核心用法

agent-browser 是专为 AI Agent 设计的 Headless 浏览器自动化 CLI 工具，通过无障碍树快照（accessibility tree snapshot）和引用标识符（refs）实现确定性元素选择，解决了传统浏览器工具依赖视觉选择器（CSS/XPath）的脆弱性问题。

关键工作流程：
1. 使用 agent-browser open <url> 打开页面
2. 执行 agent-browser snapshot -i --json 获取交互元素快照及 refs 映射
3. 通过 @e2 等引用标识符精确操作：click、fill、select 等
4. 页面变化后重新快照，形成闭环

核心能力矩阵：

• 导航控制：open/back/forward/reload/close
• 确定性交互：click/fill/type/hover/check/select/press/scroll/drag（全部支持 ref-based）
• 状态查询：text/html/value/attr/title/url/visible/enabled/checked
• 智能等待：元素/时间/文本/URL/network/自定义函数
• 会话隔离：--session 参数支持多浏览器上下文并行
• 状态持久化：save/load cookies 与 localStorage，跳过重复登录
• 网络控制：路由拦截、请求 Mock、广告过滤
• 多标签/框架：tab 切换、iframe 穿透

显著优点

1. 确定性自动化：基于无障碍树 refs 的元素选择不受 DOM 结构变化影响，比 CSS/XPath 稳定 10 倍以上
2. AI 原生设计：JSON 输出格式、--json 全局支持，完美适配 LLM 解析与决策
3. 性能优化：Headless 模式、-c 紧凑模式、深度限制 -d，专为高频 Agent 调用优化
4. 会话管理：原生支持多用户并行测试（admin/user 隔离），状态可序列化复用
5. 生产级可靠性：Vercel Labs 官方维护，Chromium 内核，网络等待策略完善

潜在缺点与局限性

1. 无视觉能力：无法截图分析、OCR 识别、视觉验证（需搭配内置 browser 工具）
2. Node.js 依赖：需 npm 全局安装，Chromium 下载体积较大（~100MB）
3. SPA 复杂度：某些重度动态框架（React/Vue 复杂状态）需精细的 wait --load networkidle 配合
4. ref 稳定性限制：极端动态页面（实时重排）可能导致 refs 失效，需重新快照
5. 调试门槛：纯 Headless 调试困难，需 --headed 模式辅助开发

适合人群

• AI Agent 开发者：构建自主浏览、数据提取、表单填报的 Agent 工作流
• 自动化测试工程师：需要比 Selenium/Playwright 更轻量、更 LLM 友好的方案
• 爬虫开发者：绕过传统选择器，通过语义化无障碍树稳定抓取
• 多账号运营：利用 session 隔离实现批量账号管理

常规风险

• 反检测风险：Headless Chromium 可能被高级反爬识别，需配合代理池、指纹伪装
• 状态泄露风险：state save 文件包含敏感 cookies，需加密存储与权限管控
• 网络 Mock 误用：--body 篡改 API 响应可能导致业务逻辑异常，仅限测试环境
• 资源占用：多 session 并行会线性增加内存消耗，需合理规划并发数

安全评估结论

本 Skill 为纯 Markdown 文档，无可执行代码，通过 CLS-Certify 六维深度扫描（评分 95/100，等级 S）。来源为 Vercel Labs（T2 可信组织），无敏感信息泄露、无恶意依赖、无危险函数。外部 URL 均指向 github.com、google.com 等可信域名。