agent-browser CLI 入门：快照、ref 与会话

使用 agent-browser 时，先打开页面，读取交互快照，按快照里的 ref 操作，再核对页面结果。如果页面已变化，下一次通过 ref 操作前应重新获取快照。@e3 这样的数字引用只在当前浏览器状态中指向控件，单看数字无法知道它对应哪个按钮。

有用户问，依靠 ref 的流程在频繁更新 DOM 的单页应用中是否可靠。另一位用户建议验证失败是否可见、能否复现。下面的练习分别记录这两件事。 r/ClaudeAI · r/AI_Agents

CLI 与会话怎么配合

CLI 把命令发给后台进程，因此多条命令可以接着使用运行中的浏览器。每条命令都指定同一个 --session，让一个任务在同一会话内继续。快照描述当前标签页；标签页决定操作哪张页面，会话决定命令共享哪一份浏览器状态。

会话文档 · Tabbit 与 agent-browser 对比 · 浏览器 Agent · 浏览器自动化

打开练习页并读快照

使用已安装的 agent-browser 与已配置的浏览器，具体安装方式看官方文档。可在本地保存练习页并通过回环地址提供，也可使用站内练习页。先读快照中的标题和按钮名称。输出里写 ref=e2 时，点击命令使用 @e2。

官方安装 · 快照文档 · 打开练习页

安全运行练习

练习是无账号的普通 HTML。将它保存为 fixture.html，放到没有其他文件的目录里，在另一个终端运行 HTTP 命令。确认页面标题后再用示例 URL。若打开站内练习页，把命令中的回环 URL 换成该地址。

python3 -m http.server 4173 --bind 127.0.0.1

agent-browser --session refs-demo-a open http://127.0.0.1:4173/fixture.html
agent-browser --session refs-demo-a snapshot -i

只读下一步需要的页面信息

选择控件时从 snapshot -i 开始。如果下一步依赖说明文字或错误提示，就读取完整快照或直接查状态。过滤结果没显示的文字可能仍在页面上。页面有重复按钮时，可先核对容器，再限制快照范围。

复现旧 ref 失效

点击替换操作区的按钮。URL 没变，但原来的按钮已经移除。本次 0.41.2 使用旧 @e3 返回退出码 1，并提示找不到原按钮。重新读取状态仍是 Panel B ready，说明预期动作没有发生。

agent-browser --session refs-demo-a click @e2
agent-browser --session refs-demo-a get text '#status'
agent-browser --session refs-demo-a click @e3

Panel B ready
✗ Could not locate element with role=button name=Use original action

重新获取快照并核对结果

新快照给 Use revised action 分配了 @e5，点击后读到 Panel B selected。用 0.26.0 重跑时，新快照把同一个数字 @e3 分配给了替换后的按钮。每次都先看角色和名称。版本和页面不同，ref 数字也可能不同。

agent-browser --session refs-demo-a snapshot -i
agent-browser --session refs-demo-a click @e5
agent-browser --session refs-demo-a get text '#status'

区分三类证据

第一条回执说明点击被接受并改变了面板。错误回执说明旧名称查找失败。最后一次状态读取说明重新观察后完成了另一个动作。这三种结果分别记录，排查时把快照和状态一起保留。

当前实现会保留哪些引用

当前快照文档指出，同一文档内仍存在的 DOM 元素可以保留 ref。节点被替换时，在文档规定的条件下，工具可以按相同角色和名称找唯一匹配。本例完全移除了旧按钮名称，所以这条路径找不到目标。如果页面上有多个同名按钮，先重新观察并加上区域上下文。

给独立任务分配不同会话

按任务命名，例如 refs-demo-a 和 refs-demo-b。实测在独立临时浏览器配置中用第二个会话打开同一 URL，它显示 Panel A ready，第一会话仍显示 Panel B selected。持久状态还要看浏览器配置。两个客户端接入同一个外部浏览器时，单靠会话名不能证明身份隔离。

agent-browser --session refs-demo-b open http://127.0.0.1:4173/fixture.html
agent-browser --session refs-demo-b get text '#status'
agent-browser --session refs-demo-a get text '#status'

浏览器自动化 Agent · 浏览器 Agent 安全 · 接入现有浏览器

实验用的浏览器

两次实测均在 macOS 使用实际 Tabbit Browser Dev 可执行文件和独立临时配置。agent-browser 执行产品实验，文章页面另用 Tabbit CLI 验收。这只是本次通过的一种配置，安装请参照对应平台的官方文档。

选择合适的隔离范围

标签页选择浏览器里的页面，命名会话让多条命令复用同一任务状态，浏览器配置决定本地启动时的数据存放位置。为了重复验证，在单个会话中保持启动配置一致，另一次运行用独立临时配置。当前 CLI 中更改启动配置可能导致浏览器重启。

结束会话并排查失败

先核对结果再关闭对应会话。用 session list 确认还有哪些会话在运行，只关闭自己创建的会话。如果新 ref 仍失效，先核对 URL、标签页，再检查角色、名称、可见性。等待目标页面状态后再行动，不重复点击过时引用。

agent-browser --session refs-demo-a close
agent-browser --session refs-demo-b close
agent-browser session list

首次任务验收清单 · 排查浏览器错误

Secholar.L

Tabbit 增长与内容

Secholar.L 专注 AI 浏览器与 Agent 工作流的实操写作,基于真实调研对比工具,引用可验证的一手来源。