快照

🌐 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] [ref=e3]
- textbox "What needs to be done?" [ref=e5]
- list [ref=e8]:
  - listitem [ref=e9]:
    - checkbox "Toggle Todo" [ref=e10]
    - text: Buy groceries
  - listitem [ref=e13]:
    - checkbox "Toggle Todo" [ref=e14]
    - text: Water flowers
- contentinfo [ref=e18]:
  - text: 2 items left
  - link "All" [ref=e20]
  - link "Active" [ref=e21]
  - link "Completed" [ref=e22]

每个元素都会得到一个唯一的 ref（例如，ref=e5）。作用于某个元素的工具会把该 ref 当作它们的 target 使用：

🌐 Each element gets a unique ref (e.g., ref=e5). Tools that act on an element take that ref as their target:

browser_type  { target: "e5", text: "headphones" }
browser_click { target: "e10" }
browser_click { target: "e20" }

目标元素

🌐 Targeting elements

作用于元素的工具使用 target，它可以接受以下任意形式：

🌐 Tools that act on an element take a target, which accepts either form:

• 一个 ref — e12，或者对于第一个 iframe 内的元素是 f1e12。这就是快照打印出来的内容，也是你通常应该传递的。
• 选择器 — 任何 Playwright 选择器或定位器字符串，例如 getByRole('button', { name: 'Submit' })、#submit 或 text=Sign in。当你已经知道元素并且想跳过快照往返时，这很有用。

如果引用过时，工具会报错 Ref <ref> not found in the current page snapshot. Try capturing new snapshot.

属性	详情
格式	e 后跟一个数字，可选择性地以帧 ID (e1、e15、f2e7) 为前缀
范围	在单个快照中唯一
生命周期	直到页面变化有效
分配	分配给可访问性树展示的每个节点，而不仅仅是可交互的节点

按需快照

🌐 On-demand snapshots

大多数工具在每次操作后都会自动返回最新的快照，所以大模型总是有最新的页面状态。使用 browser_snapshot 可以显式地捕获它。

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

参数	类型	是否必填	描述
target	字符串	否	只快照该元素的子树
depth	数字	否	限制快照树的深度
boxes	布尔值	否	将每个元素的边界框作为 [box=x,y,width,height] 包含，CSS 像素，相对于视口
filename	字符串	否	将快照保存到文件而不是在响应中返回

→ browser_snapshot { depth: 2 }
→ browser_snapshot { target: "e8" }        // just the todo list subtree
→ browser_snapshot { boxes: true }         // add bounding boxes

快照模式也可以通过 --snapshot-mode=none 全局设置，以阻止工具将快照附加到响应中，通过 --snapshot-boxes 始终包含边界框。

🌐 Snapshot mode can also be set globally with --snapshot-mode=none to stop tools from attaching snapshots to responses, and --snapshot-boxes to always include bounding boxes.

正在搜索快照

🌐 Searching a snapshot

browser_find 会搜索当前页面的快照，只返回匹配的节点以及几行周围的上下文，每个节点都显示在从树根开始的路径下。在一个大页面上，当你只需要找到一个元素及其引用时，这比捕获整个快照要省很多资源。

参数	类型	必填	描述
text	字符串	否	要搜索的纯文本（不区分大小写的子串匹配）
regex	字符串	否	正则表达式。默认区分大小写；可用斜杠封装以添加标志，例如 /error/i

只提供 text 或 regex 中的一个。

🌐 Provide exactly one of text or regex.

→ browser_find { text: "Deep Target Link" }

  Found 1 match for "Deep Target Link":

  - main [ref=e2]:
    - region "Sidebar" [ref=e3]:
      - navigation "Primary" [ref=e4]:
        - list [ref=e5]:
          ...
          - listitem [ref=e16]:
            - link "Deep Target Link" [ref=e17]

→ browser_click { target: "e17" }

周围环境中的空缺用 ... 标记。

🌐 Gaps in the surrounding context are marked with ....

带截图的快照

🌐 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

	快照	截图
令牌成本	低 —— 仅文本	高 —— 包含图片令牌
精确度	精确 —— 引用指向特定元素	近似 —— 需要猜坐标
速度	立即 —— 文本解析	较慢 —— 视觉模型推断
可靠性	确定性 —— 相同结构 = 相同交互	可变 —— 布局变化会破坏坐标
视觉模型	不需要	需要

最佳实践

🌐 Best practices

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