快照

snapshot 命令返回一个紧凑的可访问性树，其中包含用于元素交互的 refs。

选项¶

筛选输出以减小体积：

紧凑快照（-c）保留可见文本、状态文本及其直接祖先。空的兄弟分支会被移除。交互快照（-i）会过滤掉非交互内容。MCP 快照默认使用交互模式；设置 interactive: false 可保留可见文本和状态文本。

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 友好：

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

使用 refs¶

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

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 生命周期¶

存活的 DOM 元素会在多次快照及同文档更新中保留其 refs。替换元素或导航到其页面/iframe 会使 refs 失效，但不会回收 ID。虚拟可访问性节点拥有快照局部的 refs。交互后重新快照以观察变化，导航后务必重新快照：

agent-browser click @e4      # Navigates to new page
agent-browser snapshot -i    # Get fresh refs
agent-browser click @e8      # Use a ref from the new snapshot

当 DOM 节点存在时，ref 会持续指向该节点。如果节点被替换，agent-browser 会回退到具有相同 role 和 name 的那个元素，但仅当该 ref 在其快照中是唯一时才会如此。当存在重复元素导致匹配不明确时，操作会失败且不会执行任何动作。请重新运行 snapshot 并使用新的 ref。

带注释的截图¶

如需在文本快照之外获得视觉上下文，可使用 screenshot --annotate 在交互元素上叠加编号标签。每个标签 [N] 对应 ref @eN：

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

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 在快照和过期 ref 恢复中使用相同的 Iframe 角色。

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

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，请先切换进入该 iframe：

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

最佳实践¶

使用 -i 将输出缩减为可操作元素
页面变化后重新快照以获取最新的 refs
使用 -s 限定到特定页面区域
在复杂页面上使用 -d 限制深度
在需要视觉上下文配合 refs 时，使用 screenshot --annotate

JSON 输出¶

用于脚本中的编程解析：

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

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

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 agen/agent-browser