agent-browser 工作机制

agent-browser 的核心定位是一个专为 AI Agent 设计的轻量化浏览器自动化工具。

它的工作原理可以总结为：“结构化快照 + 引用标记（Refs）+ 原子化交互”。

agent-browser 的本质是一个“浏览器抽象层”。它通过将复杂的网页对象化、编号化，把“操作网页”变成了类似于“操作命令行工具”的简单体验。

---

1. 核心创新：基于引用（Ref）的交互模型

传统浏览器自动化（如 Playwright 或 Selenium）通常要求 AI 解析庞大且复杂的 HTML DOM 树，并生成 CSS 或 XPath 选择器。这会导致两个问题：耗费巨大的 Token、AI 容易写错复杂的选择器。

agent-browser 的解决方式：

• Token 压缩：它将复杂的 DOM 树简化为仅包含关键信息的“快照（Snapshot）”。
• 指代消解：它为页面上的每个可交互元素分配一个短小的标签（如 @e1, @e2）。
• 直接映射：AI 只需要下达 click @e1 这样的指令，而不需要知道 @e1 背后的复杂 CSS 路径。

---

2. 工作生命周期：Snapshot-Action 循环

agent-browser 的运行遵循一个严格的循环逻辑：

1. 环境准备：通过 open 打开 URL 或使用 state load 加载已有的登录状态（Cookies、LocalStorage） 。

2. 生成快照（关键步骤）：使用 snapshot -i 提取当前视图中的可交互元素 。

• 此时，后端会扫描 Accessibility Tree（无障碍树），捕捉按钮、输入框、链接等。
• 分配唯一的 @eX 引用 ID。

3. 原子交互：AI 发送基于引用的指令（如 fill @e2 "text"） 。

4. 状态失效与刷新：

• 重要原理：一旦页面发生跳转或 DOM 结构发生重大变化，之前的 Refs（如 @e1）就会失效。
• Agent 必须重新执行 snapshot 获取新的一组 Refs，才能进行下一步交互。

---

3. 会话与持久化原理（Session Management）

它支持多任务并行和身份复用：

• 隔离性：通过 --session <name> 参数，可以在同一台机器上运行多个互不干扰的浏览器实例，每个实例拥有独立的 Cookie 和缓存。
• 状态保存：state save 会将当前的认证信息（如登录后的 Session Cookies）导出为 JSON 文件。
• 绕过登录：在后续任务中通过 state load 直接导入该 JSON，Agent 即可跳过登录流程直接访问保护页面。

---

4. 强大的辅助与调试机制

为了确保 AI 在“看不见”浏览器的情况下也能稳定工作，它提供了多种反馈手段：

• 多模态反馈：支持 screenshot --full（长截图）和 pdf 输出，方便人工审计或 AI 视觉分析 。

• 过程监控：record start/stop 可以录制 WebM 格式的操作视频，这在调试复杂的反爬虫或 UI 自动化时非常有用。

• 网络拦截：通过 network route 模拟 API 返回或拦截特定请求，用于测试异常场景 。

---

5. 典型工作流示例（以表单提交为例）

1. 指令：agent-browser open <url> -> 启动无头浏览器并导航。
2. 指令：agent-browser snapshot -i -> 解析 HTML，返回给 Agent：@e1: [input] Email, @e2: [button] Submit。
3. 指令：agent-browser fill @e1 "test@me.com" -> 查找 @e1 对应的内部元素并注入文本。
4. 指令：agent-browser click @e2 -> 触发提交。
5. 指令：agent-browser wait --load networkidle -> 确保页面加载完成后再进行下一次快照 。

---

6. 常用指令

核心导航与基础操作：

• open ：导航至特定网址
• back / forward / reload：控制浏览器前进、后退或重新加载页面 。
• close：彻底关闭当前浏览器实例或会话 。
• --session：在内存里开辟了一块独立的、带标签的存储空间。
• --session user_123 state load ./user_123_auth.json open https://example.com/dashboard ： 为 user_123 的独立沙盒空间内加载状态，并打开页面 。

快照和引用：

• snapshot -i：最常用命令。仅提取交互式元素（如按钮、输入框）并分配 @e1, @e2 等引用 ID 。
• snapshot -s "#selector"：将快照范围缩小到特定的 CSS 选择器区域
• snapshot -d ：限制快照的 DOM 树深度 。

元素交互：

• click @e1：点击指定元素 。
• fill @e1 "text"：先清空再输入文本（常用于表单） 。
• type @e1 "text"：直接追加输入而不清空原有内容 。
• hover @e1 / focus @e1：悬停或聚焦元素 。
• select @e1 "value"：操作下拉菜单选择指定项 。

信息提取和校验：

• get text @e1：获取元素的纯文本内容 。
• get attr @e1 ：获取特定属性值（如 href 或 src）。
• get url / title：获取当前页面的 URL 或标题 。
• is visible / enabled @e1：校验元素是否可见或可用 。

状态持久化：

• state save ：将当前内存中的 Cookies 和 LocalStorage 导出为 JSON 文件（默认会话保存在内存中）
• state load ：从 JSON 文件加载之前的认证状态，实现免密登录 。
• cookies set / clear：手动设置或清除特定的 Cookie 。

调试和多模态输出

• screenshot --full ：拍摄全屏截图并保存为图像 。
• pdf ：将当前页面渲染并保存为 PDF 文档 。
• record start / stop：录制操作过程的 WebM 视频，用于后续审计或 Debug 。
• --headed (全局标志)：运行命令时显式弹出浏览器窗口进行人工观测 。