人工智能大模型代码智能体AI Agent桌面应用后端前端CLI【免费下载链接】ZCodeZCode 是 AI 编程工作台提供桌面应用、浏览器界面和终端 Agent。本仓库包含客户端、后端服务、共享 UI以及 Agent CLI 与运行时源码。项目地址https://gitcode.com/zai-org/ZCode点击查看免费下载导读本文围绕 ZCode 仓库中内置的 agent-browser 浏览器自动化技能见 .agents/skills/agent-browser/references/snapshot-refs.md展开深入讲解其核心设计——用紧凑的 DOM 快照Snapshot替代完整 HTML为每个可交互元素分配唯一引用 IDRef从而让 AI Agent 以极低 Token 成本完成页面理解与精准操作。读完本文你将掌握agent-browser snapshot -i的完整输出格式、e1这类元素引用的生命周期与失效规则、iframe 内元素的引用处理、常见故障排查以及这些机制在 ZCode 内置 Browser Use 插件apps/zcode-cli/packages/browser-use-plugin/README.md中以playwright.domSnapshot()形式落地的实现原理。Snapshot 与 Refs 解决了什么问题在传统浏览器自动化方案中AI Agent 理解页面通常走这样的链路Full DOM/HTML → AI parses → CSS selector → Action (~3000-5000 tokens)完整 DOM/HTML 动辄数万字符AI 需要自行解析标签结构、推断语义、再手工构造 CSS 选择器单次交互的成本高达 30005000 Token且选择器脆弱、页面一变化就失效。agent-browser 的路线则完全不同Compact snapshot → refs assigned → Direct interaction (~200-400 tokens)它先把页面压缩成一份紧凑的可访问性快照自动为每个元素分配e1、e2这样的唯一引用 IDAI 后续只需用click e6、fill e10 ...这类命令直接交互单次交互成本降到 200400 Token约为传统方式的十分之一。这正是 Snapshot 与 Refs 机制的核心价值用一次性的小额快照开销换来后续所有操作的低成本、高确定性。在 ZCode 的浏览器插件实现中这一思想被进一步落实为tab.playwright.domSnapshot()——它返回的是紧凑的 AI/ARIA 树而非页面outerHTML并作为定位元素locator的事实来源见 apps/zcode-cli/packages/browser-use-plugin/docs/overview.md。Snapshot 命令如何获取元素引用基本用法# 基础快照展示页面结构 agent-browser snapshot # 交互式快照-i 参数—— 推荐使用 agent-browser snapshot -i-iinteractive只输出可交互元素并附带引用 ID是 Agent 日常工作最推荐的形态。完整的命令参考中还提供了其他快照变体见 .agents/skills/agent-browser/references/commands.mdagent-browser snapshot # 完整可访问性树 agent-browser snapshot -i # 仅可交互元素推荐 agent-browser snapshot -c # 紧凑输出 agent-browser snapshot -d 3 # 限制深度为 3 层 agent-browser snapshot -s #main # 用 CSS 选择器限定范围快照输出格式详解一次典型快照的输出如下Page: Example Site - Home URL: https://example.com e1 [header] e2 [nav] e3 [a] Home e4 [a] Products e5 [a] About e6 [button] Sign In e7 [main] e8 [h1] Welcome e9 [form] e10 [input typeemail] placeholderEmail e11 [input typepassword] placeholderPassword e12 [button typesubmit] Log In e13 [footer] e14 [a] Privacy Policy输出由三部分组成页面头部Page:标题与URL:地址用于确认当前所处的页面上下文元素引用refse1e14是分配给每个元素的唯一 ID缩进体现 DOM 嵌套层级元素描述方括号内是标签名与关键属性双引号内是可见文本。这种结构对 AI Agent 极其友好——角色、名称、状态、层级关系一目了然无需再解析任何 HTML 标签对。Using Refs拿到引用后直接交互拿到 refs 之后所有操作都变得直接# 点击 Sign In 按钮 agent-browser click e6 # 填充邮箱输入框 agent-browser fill e10 userexample.com # 填充密码输入框 agent-browser fill e11 password123 # 提交表单 agent-browser click e12除了 click 与 fillrefs 还可用于更多交互命令完整清单见 .agents/skills/agent-browser/references/commands.mdagent-browser dblclick e1 # 双击 agent-browser hover e1 # 悬停 agent-browser check e1 # 勾选复选框 agent-browser uncheck e1 # 取消勾选 agent-browser select e1 value # 选择下拉选项可传多个值 agent-browser scrollintoview e1 # 滚动元素到可视区域 agent-browser drag e1 e2 # 拖放 agent-browser upload e1 file.pdf # 上传文件 agent-browser get text e1 # 读取元素文本 agent-browser get html e1 # 读取 innerHTML agent-browser get value e1 # 读取输入框值 agent-browser get attr e1 href # 读取属性 agent-browser get box e1 # 读取边界框ZCode 插件侧的等价实现同样遵循快照事实驱动交互原则browser-use-plugin的 workflow 文档明确要求只用快照中出现过的角色、可访问名称、文本、占位符、data-*、href等事实来构造 Playwright locator严禁凭记忆猜测选择器见 apps/zcode-cli/packages/browser-use-plugin/docs/workflow.md。Ref Lifecycle引用的生命周期与失效规则最重要的规则页面一旦变化所有 refs 立即失效# 获取初始快照 agent-browser snapshot -i # e1 [button] Next # 点击触发了页面跳转 agent-browser click e1 # 必须重新快照才能获得新的 refs agent-browser snapshot -i # e1 [h1] Page 2 ← 同一个 e1 现在指向了完全不同的元素上例清楚展示了失效的本质e1只是本次快照内的序号不是元素的持久身份。页面跳转后 DOM 结构变化e1的绑定对象随之改变。因此 Agent 绝不能跨页面复用记忆中的 refs。ZCode 的 control-browser 技能对这条规则做了更工程化的约束每个逻辑操作批次开始时必须在一个独立的 JS 调用中返回完整的await browser.tabs.list()结果供模型查看然后在下一次 JS 调用中用验证过的 id/url/title 匹配目标标签页——禁止用记忆中的 tab id 或数组位置直接操作见 apps/zcode-cli/packages/browser-use-plugin/skills/control-browser/SKILL.md。这与 refs 失效规则的底层逻辑完全一致Agent 环境没有跨调用的持久绑定一切以最新观测为准。Best Practices快照的正确使用姿势1. 交互之前必须先快照# 正确做法 agent-browser open https://example.com agent-browser snapshot -i # 先拿 refs agent-browser click e1 # 再使用 ref # 错误做法 agent-browser open https://example.com agent-browser click e1 # ref 还不存在必然报错2. 导航之后重新快照agent-browser click e5 # 点击链接跳转新页面 agent-browser snapshot -i # 获取新页面的 refs agent-browser click e1 # 使用新 refs3. 动态内容变化后重新快照agent-browser click e1 # 点击展开下拉菜单 agent-browser snapshot -i # 查看下拉项 agent-browser click e7 # 选择目标项4. 复杂页面只快照特定区域# 只快照表单区域 agent-browser snapshot e9缩小快照范围不仅能降低 Token 消耗还能避免无关元素干扰 Agent 的定位判断。ZCode 侧与之对应的是snapshot -s #selector与 Playwright 的getByRole/getByText/getByLabel等定向 locator——都是用最小观测回答当前问题思想的体现。Ref Notation Details引用符号的完整语法每条快照记录都可以拆解为e1 [tag typevalue] text content placeholderhint │ │ │ │ │ │ │ │ │ └─ 附加属性 │ │ │ └─ 可见文本 │ │ └─ 关键属性 │ └─ HTML 标签名 └─ 唯一引用 ID常见元素模式速查e1 [button] Submit # 带文本的按钮 e2 [input typeemail] # 邮箱输入框 e3 [input typepassword] # 密码输入框 e4 [a href/page] Link Text # 锚点链接 e5 [select] # 下拉框 e6 [textarea] placeholderMessage # 文本域 e7 [div classmodal] # 容器相关时才会出现 e8 [img altLogo] # 图片 e9 [checkbox] checked # 已勾选的复选框 e10 [radio] selected # 已选中的单选按钮这套记法在 ZCode 的 Playwright 快照中同样成立domSnapshot()返回的 AI/ARIA 树包含计算后的角色role、可访问名称accessible name、状态以及展开的 shadow DOM 与 iframe 内容与上述 CLI 快照格式一脉相承见 apps/zcode-cli/packages/browser-use-plugin/docs/workflow.md。Iframes快照自动内联与跨框架操作快照会自动检测并内联 iframe 内容。主框架快照执行时每个Iframe节点都会被解析其子可访问性树直接内联在该节点之下分配给 iframe 内元素的 refs 携带帧上下文因此click、fill、type等交互无需手动切换 frameagent-browser snapshot -i # e1 [heading] Checkout # e2 [Iframe] payment-frame # e3 [input] Card number # e4 [input] Expiry # e5 [button] Pay # e6 [button] Cancel # 直接用 refs 操作 iframe 内的元素 agent-browser fill e3 4111111111111111 agent-browser fill e4 12/28 agent-browser click e5iframe 处理的三个关键细节只展开一层嵌套iframe 内的 iframe 不会被递归展开跨域 iframe 静默跳过阻止可访问性树访问的跨域 iframe 会被直接略过空 iframe 省略无内容或无交互元素的 iframe 不会出现在输出中。若需要将快照限定到单个 iframe先frame ref再snapshot -iagent-browser frame e2 # 切换到支付 iframe agent-browser snapshot -i # 只输出该 iframe 的内容 agent-browser frame main # 切回主框架frame命令支持三种目标元素引用frame e3、CSS 选择器frame #payment-iframe、以及帧名/URL 匹配。ZCode 插件同样遵循iframe 内容自动内联的设计control-browser技能描述中明确提到快照包含 expanded iframe content when available见 apps/zcode-cli/packages/browser-use-plugin/docs/workflow.md。Troubleshooting常见问题与解法Ref not found 错误# ref 可能已随页面变化而失效——重新快照 agent-browser snapshot -iZCode 侧的故障恢复逻辑与之完全对应任何 Playwright 超时、严格模式失败或选择器解析失败后禁止重试同一个 locator必须先取一份新的domSnapshot()再基于快照事实重建 locator见 apps/zcode-cli/packages/browser-use-plugin/docs/browser-troubleshooting.md 与 apps/zcode-cli/packages/browser-use-plugin/docs/workflow.md。元素不在快照中# 先滚动让元素进入可视区域 agent-browser scroll down 1000 agent-browser snapshot -i # 或者等待动态内容加载 agent-browser wait 1000 agent-browser snapshot -i元素太多、快照过大# 只快照指定容器 agent-browser snapshot e5 # 或者用 get text 只做纯文本提取 agent-browser get text e5此外ZCode 的 Browser Use 插件还提供了两个逃生通道用于快照看不见的目标tab.cua坐标路径用于 canvas/自绘控件和tab.dom_cua节点路径node_id来自get_visible_dom()二者可在快照无法覆盖视觉型元素时兜底见 apps/zcode-cli/packages/browser-use-plugin/skills/control-browser/SKILL.md。核心工作流串联从打开页面到完成交互将上述机制串成一条完整链路就是 agent-browser 推荐的标准流程见 .agents/skills/agent-browser/SKILL.md导航agent-browser open url快照agent-browser snapshot -i获得e1、e2等 refs交互用 refs 执行 click、fill、select重新快照导航或 DOM 变化后获取新 refsagent-browser open https://example.com/form agent-browser snapshot -i # 输出: e1 [input typeemail], e2 [input typepassword], e3 [button] Submit agent-browser fill e1 userexample.com agent-browser fill e2 password123 agent-browser click e3 agent-browser wait --load networkidle agent-browser snapshot -i # 检查操作结果命令可以通过在同一 shell 调用中串联浏览器进程在命令之间由后台守护进程保持因此链式调用既安全又高效但当中间命令的输出需要先解析比如快照发现 refs 再据此交互时应分步执行。在 ZCode 插件侧同一工作流以js工具mcp__node_repl__js承载每次调用先运行 bootstrap 初始化agent.browsers随后await tab.playwright.domSnapshot()作为默认观测手段locator 只从快照事实构建操作后用最廉价的观测定向 locator 状态检查或一次新快照确认效果——同一观测周期内最多执行一个有状态变更的动作见 apps/zcode-cli/packages/browser-use-plugin/docs/workflow.md。与 ZCode 内置 Browser Use 插件的关系上文多次出现的domSnapshot()、快照失效恢复、iframe 内联等规则均来自 ZCode 仓库内置的官方浏览器自动化插件 apps/zcode-cli/packages/browser-use-plugin。该插件提供js工具由node_replMCP host 承载、scripts/browser-client.mjs引导模块以及control-browser浏览器驱动技能与web-gui-tester纯 GUI 黑盒测试技能两个技能。control-browser技能把本主题的快照/refs 思想工程化为可执行协议以playwright.domSnapshot()为默认页面观测与 locator 事实来源以快照失效后的重建代替盲目重试以快照足够就不再截图控制 Token 与延迟见 apps/zcode-cli/packages/browser-use-plugin/skills/control-browser/SKILL.md。这份技能文档源自 vercel-labs/agent-browser 并经过 ZCode 本地化改造许可与来源信息见仓库根目录的 THIRD-PARTY-NOTICES.md。如需查看完整命令参考、快速上手与更多深度主题认证、会话管理、录制、性能剖析、代理支持可继续阅读同目录下的 commands.md 与 SKILL.md。总结Snapshot 与 Refs 是 agent-browser 让AI 驱动浏览器变得可行的关键设计一份紧凑快照承担了页面理解的全部成本而ref引用把后续交互简化为确定性命令。用好它的四件事是交互前必快照、页面变化后必重新快照、复杂页面只快照局部、失效时重建而不是硬猜。这套机制在 ZCode 中以playwright.domSnapshot()完整落地并沉淀为control-browser技能中快照事实 → 稳定 locator → 单动作单观测的工程纪律是任何在 ZCode 中构建网页自动化、表单测试或数据提取流程的 Agent 都应当优先掌握的底层能力。赞分享人工智能大模型代码智能体AI Agent桌面应用后端前端CLI【免费下载链接】ZCodeZCode 是 AI 编程工作台提供桌面应用、浏览器界面和终端 Agent。本仓库包含客户端、后端服务、共享 UI以及 Agent CLI 与运行时源码。项目地址https://gitcode.com/zai-org/ZCode点击查看免费下载相关推荐ZCode agent-browser Snapshot 与 Refs 完全指南用紧凑元素引用大幅削减 AI Agent 上下文消耗ZCode agent browser Snapshot 与 Refs 完全指南用紧凑元素引用大幅削减 AI Agent 上下文消耗 导读 本文讲解 ZCodagent-browser 快照与 Refs 机制为 AI Agent 打造的紧凑元素引用体系agent browser 快照与 Refs 机制为 AI Agent 打造的紧凑元素引用体系 在 AI Agent 驱动浏览器时传统的「全量 DOM →浏览器控制CLIAI 应用GUI 自动化开发工具AI 技能MCP 服务open-agents 中 agent-browser 的 Snapshot Refs 工作流用紧凑元素引用把浏览器自动化上下文开销降低一个数量级open agents 中 agent browser 的 Snapshot Refs 工作流用紧凑元素引用把浏览器自动化上下文开销降低一个数量级 age人工智能AI Agent代码智能体Agent 工作流Agent 沙箱工具调用后端前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
