snapshot / @refs：打开页面、点击、填写与截图

你将得到什么

• 一次针对 example.com 的完整会话：打开 → 快照 → 按 ref 交互 → 截图 → 关闭
• 理解 a11y snapshot + @eN refs 为何比整页 DOM 更省上下文
• 知道点击被遮挡时的官方处理方式

为什么用 refs？

官网说明：snapshot 返回紧凑可访问性树，每个元素带唯一 ref（如 @e1、@e2）：

官方还给出量级对比：约 200–400 tokens vs 完整 DOM 约 3000–5000。

步骤 1：打开页面并拍 snapshot

agent-browser open example.com
agent-browser snapshot -i

官网示例输出形态（元素编号以你本机当次 snapshot 为准）：

- heading "Example Domain" [ref=e1]
- link "More information..." [ref=e2]

README Quick Start 也可用不带 -i 的 agent-browser snapshot；-i 为文档站示例中的交互/精简开关，以你安装版本 --help 为准。

对照结果：

• 输出中出现 Example Domain 相关 heading / link
• 每个可操作节点带 [ref=eN]

查看标题与 URL（可选）：

agent-browser get title
agent-browser get url

应分别看到类似 Example Domain 与包含 example.com 的地址。

步骤 2：按 ref 点击与读取

假设 snapshot 里「More information...」是 @e2（以你输出为准）：

agent-browser click @e2

对照结果：

• 导航到 IANA 相关说明页（或该链接的目标页）
• 若失败并提示另一元素挡住点击点（同意横幅、弹层等）：先对覆盖层操作或关闭它，再 重新 snapshot，用新的 @eN 重试——官方明确要求刷新 snapshot，勿复用旧 ref

读取某节点文本（ref 换成你树里的 heading）：

agent-browser get text @e1

对照结果：打印该节点可见文本，非空。

步骤 3：填写示例（表单页时）

Quick Start 示范填邮箱（仅当 snapshot 中确有对应输入框 ref，例如 @e3）：

agent-browser fill @e3 "test@example.com"

对照结果：该输入框值为你填入的邮箱（可用 agent-browser get value @e3 复核）。

也支持传统选择器（官方补充）：

agent-browser click "#submit"
agent-browser fill "#email" "test@example.com"
agent-browser find role button click --name "Submit"

本课仍优先 snapshot refs，便于 agent 确定性操作。

步骤 4：截图并关闭会话

agent-browser screenshot page.png
agent-browser close

对照结果：

• 当前目录（或命令指定路径）出现 page.png
• close 后会话结束；需要时可用 agent-browser close --all 关掉全部会话

无路径时官方会存到临时目录；也可用：

agent-browser screenshot --screenshot-dir ./shots
agent-browser screenshot --if-changed

--if-changed 可在画面未变时跳过写盘，节省 agent token（README 推荐）。

推荐整段抄写（官方 Quick Start）

agent-browser open example.com
agent-browser snapshot
agent-browser click @e2
agent-browser fill @e3 "test@example.com"
agent-browser get text @e1
agent-browser screenshot page.png
agent-browser close

注意：@e2 / @e3 / @e1 必须来自你刚跑出的 snapshot；Example Domain 页通常没有邮箱框，fill 行在真实表单页再执行。

架构速记（便于排错）

官方架构：

1. Rust CLI：解析命令，与 daemon 通信
2. Native Daemon：纯 Rust，经 CDP 管理 Chrome

daemon 在命令间保持；默认空闲约一小时后保存可恢复状态并退出（可用 --idle-timeout / AGENT_BROWSER_IDLE_TIMEOUT_MS 调整，0 禁用）。排错时可检查 daemon 是否仍在、或重新 open。

本课检查清单

• open example.com + snapshot 看到带 ref 的树
• 至少一次成功的 click @eN（或按提示处理遮挡后重试）
• screenshot 产出图片且 close 正常

延伸

• 适配 Claude Code / Cursor / Copilot / Codex 等：凡能跑 shell 的 agent 均可调用本 CLI（产品页 Works with）
• 更多命令见 README「Commands」：pdf、eval、connect <port>、会话与代理等

来源

• https://agent-browser.dev/
• https://github.com/vercel-labs/agent-browser/blob/main/README.md
• 站内工具页：https://www.kun.net/tools/agent-browser/