agent-browser

快照

snapshot 命令返回一个紧凑的可访问性树，并带有元素交互的引用（refs）。

选项

通过过滤输出来减小结果体积：

agent-browser snapshot                    # 完整的可访问性树
agent-browser snapshot -i                 # 仅交互元素（推荐）
agent-browser snapshot -i -C              # 包含光标可交互元素
agent-browser snapshot -c                 # 紧凑模式（移除空元素）
agent-browser snapshot -d 3               # 限制树深度为 3 层
agent-browser snapshot -s "#main"         # 限定为 CSS 选择器范围
agent-browser snapshot -i -c -d 5         # 组合多个选项
选项描述
-i, --interactive仅包含交互元素（按钮、链接、输入框）
-C, --cursor包含光标可交互元素（cursor:pointer、onclick、tabindex）
-c, --compact移除空的结构元素
-d, --depth限制树的深度
-s, --selector限定为 CSS 选择器范围

光标可交互元素

许多现代网页应用使用自定义的可点击元素（如 div、span），而非标准的按钮或链接。-C 标志通过检查以下内容来识别这些元素：

  • cursor: pointer CSS 样式
  • onclick 属性或事件处理函数
  • tabindex 属性（键盘可聚焦）
agent-browser snapshot -i -C
# 输出包含：
# @e1 [button] "提交"
# @e2 [link] "了解更多"
# 光标可交互元素：
# @e3 [clickable] "菜单项" [cursor:pointer, onclick]
# @e4 [clickable] "卡片" [cursor:pointer]

输出格式

默认文本输出紧凑且适合 AI 使用：

agent-browser snapshot -i
# 输出：
# @e1 [heading] "示例域名" [level=1]
# @e2 [button] "提交"
# @e3 [input type="email"] placeholder="邮箱"
# @e4 [link] "了解更多"

使用引用（Refs）

快照中的引用可直接映射到命令中：

agent-browser click @e2      # 点击提交按钮
agent-browser fill @e3 "[email protected]"  # 填写邮箱输入框
agent-browser get text @e1        # 获取标题文本

引用生命周期

当页面发生变化时，引用将失效。在导航或 DOM 更新后，请始终重新生成快照：

agent-browser click @e4      # 导航到新页面
agent-browser snapshot -i    # 获取新的引用
agent-browser click @e1      # 使用新的引用

带标注的截图

为了在文本快照之外提供视觉上下文，可以使用 screenshot --annotate 在交互元素上叠加编号标签。每个标签 [N] 对应引用 @eN：

agent-browser screenshot --annotate ./page.png
# -> 截图已保存至 ./page.png
#    [1] @e1 button "提交"
#    [2] @e2 link "首页"
#    [3] @e3 textbox "邮箱"
agent-browser click @e2

带标注的截图也会缓存引用，因此可以立即与元素进行交互。当文本快照不足以满足需求时特别有用——例如未标记的图标、画布内容或视觉布局验证。

最佳实践

  1. 使用 -i 将输出缩小至可操作的元素
  2. 页面变化后重新生成快照以获取最新的引用
  3. 使用 -s 对特定页面区域进行范围限定
  4. 在复杂页面上使用 -d 限制树的深度
  5. 当需要结合引用与视觉上下文时，使用 screenshot --annotate

JSON 输出

用于脚本中的程序化解析：

agent-browser snapshot --json
# {"success":true,"data":{"snapshot":"...","refs":{"e1":{"role":"heading","name":"标题"},...}}}

注意：与文本输出相比，JSON 格式会消耗更多令牌。对于 AI 代理，推荐使用默认的文本格式。