快照

🌐 Snapshots

Playwright MCP 使用可访问性快照而不是截图。与页面交互的每个工具都会返回一个包含可交互引用的可访问元素结构化树。

🌐 Playwright MCP uses accessibility snapshots instead of screenshots. Every tool that interacts with the page returns a structured tree of accessible elements with refs for interaction.

快照格式

🌐 Snapshot format

- heading "todos" [level=1]
- textbox "What needs to be done?" [ref=e5]
- listitem:
  - checkbox "Toggle Todo" [ref=e10]
  - text: "Buy groceries"
- listitem:
  - checkbox "Toggle Todo" [ref=e14]
  - text: "Water flowers"
- contentinfo:
  - text: "2 items left"
  - link "All" [ref=e20]
  - link "Active" [ref=e21]
  - link "Completed" [ref=e22]

每个交互元素都有一个唯一的 ref（例如，ref=e5）。LLM 使用这些 ref 进行交互：

🌐 Each interactive element gets a unique ref (e.g., ref=e5). The LLM uses these refs to interact:

browser_type   { ref: "e5", text: "headphones" }    → type into search
browser_click  { ref: "e10" }                       → check the checkbox
browser_click  { ref: "e20" }                       → click the "All" link

元素引用

🌐 Element refs

Refs 在单个快照中是稳定的——同一个元素在页面未变化时总是拥有相同的 ref。导航或 DOM 更新后，该工具会返回一个带有新 refs 的新快照。

🌐 Refs are stable within a single snapshot — the same element always has the same ref until the page changes. After navigation or DOM updates, the tool returns a fresh snapshot with new refs.

属性	详情
格式	e 后跟一个数字（例如，e1、e15、e203）
范围	在单个快照中唯一
生命周期	有效直到下一次页面更改
分配	只有交互元素才会获得引用（按钮、链接、输入框等）

按需快照

🌐 On-demand snapshots

使用 browser_snapshot 来按需捕捉页面状态。大多数工具也会在每次操作后自动返回快照，因此 LLM 始终拥有最新的页面状态。

🌐 Use browser_snapshot to capture the page state on demand. Most tools also return a snapshot automatically after each action, so the LLM always has up-to-date page state.

带截图的快照

🌐 Snapshots with screenshots

对于视觉上下文重要的页面（画布应用、图表、图片密集的布局），将快照与截图结合使用：

🌐 For pages where visual context matters (canvas apps, charts, image-heavy layouts), combine snapshots with screenshots:

Take a snapshot and a screenshot of the current page.

LLM 获取用于交互的结构化可访问性树和用于理解布局的视觉截图。有关使用截图进行基于坐标的交互，请参见 视觉模式。

🌐 The LLM gets both the structured accessibility tree for interaction and the visual screenshot for understanding layout. See Vision Mode for coordinate-based interaction using screenshots.

为什么选择快照而不是截图

🌐 Why snapshots over screenshots

	快照	截图
令牌消耗	约 200-400 令牌	约 3000-5000 令牌（视觉模型）
精确度	精确 — 引用指向具体元素	大致 — 需要猜测坐标
速度	即时 — 文本解析	较慢 — 视觉模型推断
可靠性	确定性 — 相同结构 = 相同交互	不稳定 — 布局变化会导致坐标失效
视觉模型	不需要	需要

最佳实践

🌐 Best practices

1. 使用 refs，而不是选择器 — 来自快照的 refs 比 CSS 选择器更可靠，因为它们指向 LLM 刚刚看到的确切元素
2. 导航后重新快照 — 当页面变化时，引用会失效
3. 结合截图 — 当需要在结构化数据旁边提供视觉上下文时
4. 检查对话框 — 如果工具报告有对话框打开，请在执行其他操作之前处理它