快照#

snapshot 命令会返回一个紧凑的可访问性树，并附带用于元素交互的 refs。

选项#

可通过过滤输出减少体积：

bash

agent-browser snapshot                    # Full accessibility tree
agent-browser snapshot -i                 # Interactive elements only (recommended)
agent-browser snapshot -c                 # Compact (remove empty elements)
agent-browser snapshot -d 3               # Limit depth to 3 levels
agent-browser snapshot -s "#main"         # Scope to CSS selector
agent-browser snapshot -i -c -d 5         # Combine options

选项	说明
`-i, --interactive`	仅保留交互元素（按钮、链接、输入框）
`-u, --urls`	为链接元素包含 href URL
`-c, --compact`	移除空的结构元素
`-d, --depth`	限制树深度
`-s, --selector`	限定到 CSS 选择器

输出格式#

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

bash

agent-browser snapshot -i
# Output:
# @e1 [heading] "Example Domain" [level=1]
# @e2 [button] "Submit"
# @e3 [input type="email"] placeholder="Email"
# @e4 [link] "Learn more"

使用 ref#

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

bash

agent-browser click @e2      # Click the Submit button
agent-browser fill @e3 "a@b.com"  # Fill the email input
agent-browser get text @e1        # Get heading text

Ref 生命周期#

页面发生变化时 refs 会失效。导航或 DOM 更新后请始终重新获取快照：

bash

agent-browser click @e4      # Navigates to new page
agent-browser snapshot -i    # Get fresh refs
agent-browser click @e1      # Use new refs

标注截图#

如果想在文本快照旁边加入视觉上下文，可以使用 screenshot --annotate 在交互元素上叠加编号标签。每个标签 [N] 都映射到 ref @eN：

在原生模式下，标注截图目前仅适用于基于 CDP 的浏览器路径（Chromium/Lightpanda）。Safari/WebDriver 后端暂不支持 --annotate。

bash

agent-browser screenshot --annotate ./page.png
# -> Screenshot saved to ./page.png
#    [1] @e1 button "Submit"
#    [2] @e2 link "Home"
#    [3] @e3 textbox "Email"
agent-browser click @e2

无头 Chromium 截图会隐藏原生滚动条，以保证图片输出一致。如果想保留原生滚动条，请在启动时传入 --hide-scrollbars false。

标注截图还会缓存 refs，因此你可以立即与元素交互。当文本快照不足以覆盖无文字图标、canvas 内容或视觉布局验证时，这很有用。

Iframe#

快照会自动检测并内联 iframe 内容。主 frame 中的每个 Iframe 节点都会被解析，其子可访问性树会直接包含在其下方。分配给 iframe 内元素的 refs 会携带 frame 上下文，因此无需先切换 frame 也能交互。

bash

agent-browser snapshot -i
# @e1 [heading] "Checkout"
# @e2 [Iframe] "payment-frame"
#   @e3 [input] "Card number"
#   @e4 [button] "Pay"

agent-browser fill @e3 "4111111111111111"
agent-browser click @e4

只会展开一层 iframe 嵌套。阻止访问可访问性树的跨域 iframe 和空 iframe 会被静默省略。

如果想把快照限定到某个单独的 iframe，请先切换进去：

bash

agent-browser frame @e2
agent-browser snapshot -i       # Only elements inside that iframe
agent-browser frame main        # Return to main frame

最佳实践#

Use -i to reduce output to actionable elements
页面变化后重新获取快照，以得到更新后的 refs
使用 -s 限定到特定页面区域
在复杂页面上使用 -d 限制深度
在需要 refs 之外的视觉上下文时使用 screenshot --annotate

JSON 输出#

用于在脚本中进行程序化解析：

bash

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

注意：JSON 比文本输出占用更多 token。默认文本格式更适合 AI 代理。