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 的运行遵循一个严格的循环逻辑：
-
环境准备：通过
open打开 URL 或使用state load加载已有的登录状态（Cookies、LocalStorage） 。 -
生成快照（关键步骤）：使用
snapshot -i提取当前视图中的可交互元素 。
- 此时，后端会扫描 Accessibility Tree（无障碍树），捕捉按钮、输入框、链接等。
- 分配唯一的
@eX引用 ID。
-
原子交互：AI 发送基于引用的指令（如
fill @e2 "text"） 。 -
状态失效与刷新：
- 重要原理：一旦页面发生跳转或 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. 典型工作流示例（以表单提交为例）
- 指令：
agent-browser open <url>-> 启动无头浏览器并导航。 - 指令：
agent-browser snapshot -i-> 解析 HTML，返回给 Agent：@e1: [input] Email, @e2: [button] Submit。 - 指令：
agent-browser fill @e1 "test@me.com"-> 查找@e1对应的内部元素并注入文本。 - 指令：
agent-browser click @e2-> 触发提交。
指令：agent-browser wait --load networkidle -> 确保页面加载完成后再进行下一次快照 。
6. 常用指令
open <url>：导航至特定网址
back / forward / reload：控制浏览器前进、后退或重新加载页面 。
close：彻底关闭当前浏览器实例或会话 。
--session：在内存里开辟了一块独立的、带标签的存储空间。snapshot -i：最常用命令。仅提取交互式元素（如按钮、输入框）并分配 @e1, @e2 等引用 ID 。
snapshot -s "#selector"：将快照范围缩小到特定的 CSS 选择器区域
snapshot -d <depth>：限制快照的 DOM 树深度 。click @e1：点击指定元素 。
fill @e1 "text"：先清空再输入文本（常用于表单） 。
type @e1 "text"：直接追加输入而不清空原有内容 。
hover @e1 / focus @e1：悬停或聚焦元素 。
select @e1 "value"：操作下拉菜单选择指定项 。get text @e1：获取元素的纯文本内容 。
get attr @e1 <name>：获取特定属性值（如 href 或 src）。
get url / title：获取当前页面的 URL 或标题 。
is visible / enabled @e1：校验元素是否可见或可用 。state save <path>：将当前内存中的 Cookies 和 LocalStorage 导出为 JSON 文件（默认会话保存在内存中）
state load <path>：从 JSON 文件加载之前的认证状态，实现免密登录 。
cookies set / clear：手动设置或清除特定的 Cookie 。screenshot --full <path>：拍摄全屏截图并保存为图像 。
pdf <path>：将当前页面渲染并保存为 PDF 文档 。
record start / stop：录制操作过程的 WebM 视频，用于后续审计或 Debug 。
--headed (全局标志)：运行命令时显式弹出浏览器窗口进行人工观测 。