playwright-cli

https://github.com/microsoft/playwright-cli

Playwright CLI with SKILLS

This package provides CLI interface into Playwright. If you are using coding agents, that is the best fit.

• CLI: Modern coding agents increasingly favor CLI–based workflows exposed as SKILLs over MCP because CLI invocations are more token-efficient: they avoid loading large tool schemas and verbose accessibility trees into the model context, allowing agents to act through concise, purpose-built commands. This makes CLI + SKILLs better suited for high-throughput coding agents that must balance browser automation with large codebases, tests, and reasoning within limited context windows.

• MCP: MCP remains relevant for specialized agentic loops that benefit from persistent state, rich introspection, and iterative reasoning over page structure, such as exploratory automation, self-healing tests, or long-running autonomous workflows where maintaining continuous browser context outweighs token cost concerns. Learn more about Playwright MCP.

• Token-efficient. Does not force page data into LLM.

agent是如何调用playwright cli来完成浏览器操作的？

这是一个非常专业且切中要害的问题。在当前的 AI Agent 架构中，Playwright CLI 已经成为连接“大语言模型（LLM）推理能力”与“真实浏览器操作”的关键桥梁。

根据你提供的引用指令以及 Playwright CLI 的设计原理，Agent 调用 Playwright 完成浏览器操作的过程，本质上是一个**“观察-决策-行动”**的循环。

简单来说，Agent 并不是直接“看”屏幕，而是通过命令行交互和**快照文件（Snapshot）**来间接控制浏览器。

以下我将结合 playwright-cli 的具体机制，为你拆解这个过程的详细步骤：

核心原理：Token 效率与技能调用

根据文档介绍，Playwright CLI 的核心优势在于Token 效率。

• 传统方式（MCP/Accessibility Tree）： 需要把整个网页的 DOM 结构（可能非常巨大）塞进 LLM 的上下文窗口，成本极高。
• CLI 方式： Agent 只需要调用简短的命令（如 playwright-cli click e15），无需加载庞大的页面结构数据。

详细执行流程：一步一步拆解

当 Agent 接收到指令 Use playwright skills to test https://demo.playwright.dev/todomvc/ 时，它会按以下步骤运作：

第一步：初始化与环境感知

Agent 首先会启动 Playwright CLI 并打开目标 URL，同时获取当前页面的“状态快照”。

• Agent 执行的动作（Action）：

  playwright-cli open https://demo.playwright.dev/todomvc/
  

• 系统反馈（Observation）：
  CLI 工具会返回一个结构化的快照（Snapshot）。这个快照不是图片，而是一个包含页面元信息和关键元素引用的文本文件（YAML/JSON）。
  • 内容示例：
    • Page Title: TodoMVC
    • Element e1: <input id="new-todo"> (用于输入新任务)
    • Element e2: <button>Submit</button> (假设存在)
    • 注：快照中会为每个可交互元素生成唯一的 ID（如 e1, e2...）。

第二步：决策与元素定位

Agent 阅读第一步返回的快照文本，理解页面结构。

• 思考（Thought）： “根据快照，要添加待办事项，我需要找到输入框。快照显示 ID 为 new-todo 的输入框对应引用 ID 是 e1。”
• 规划（Plan）： “接下来我要向 e1 输入文本，然后按回车键。”

第三步：执行交互（核心操作）

Agent 利用快照中获得的元素引用 ID，直接调用 CLI 命令进行操作。

• Agent 执行的动作（Action）：

  playwright-cli fill e1 "Buy groceries"
  

  或者更简单的模拟键盘操作：

  playwright-cli type "Buy groceries"
  playwright-cli press Enter
  

• 底层逻辑： Agent 不需要知道元素的 CSS 路径或 XPath，它只需要使用上一步快照中分配的 ID e1。这极大地简化了 LLM 的工作。

第四步：验证与断言（处理成功/失败）

这是实现“Take screenshots for all successful and failing scenarios”的关键。Agent 需要判断操作是否生效。

• 检查点（Assertion）：
  Agent 会再次调用 playwright-cli snapshot 获取新状态。
  • 成功场景： 快照中出现了包含文本 Buy groceries 的 <li> 列表项（例如 e21）。
  • 失败场景： 如果快照中没有找到对应文本，或者出现了错误提示框（如 e99），Agent 就判定为失败。
• 截图动作：
  根据你的指令，无论成功或失败，Agent 都会紧接着调用截图命令：

  # 假设判定为成功，截取成功画面
  playwright-cli screenshot success_todos.png
  
  # 或者在判定失败时截取错误画面
  playwright-cli screenshot error_state.png
  

第五步：循环与清理

• Agent 会重复上述“快照 -> 决策 -> 操作”的循环，完成所有测试步骤（如添加多个任务、勾选完成、删除等）。
• 最后，根据指令要求，Agent 可能会调用 playwright-cli close 关闭浏览器。

总结：Agent 与 CLI 的协作表

为了让你更直观地理解，我整理了以下对照表：

关键点补充

1. Session 机制： 在整个过程中，CLI 使用 -s=[name] 参数来保持会话（Session）。这确保了 Cookie 和 LocalStorage 在多次命令调用间保持一致，让 Agent 能像真人一样连续操作。
2. Headed 模式： 如果你在开发调试 Agent，可以加 --headed 参数，这样你就能亲眼看到浏览器按照 Agent 的指令自动点击和输入，非常震撼。

通过这种机制，Agent 就像一个拥有“手”和“眼”的数字员工，利用 Playwright CLI 作为它的肢体，精准地完成了网页测试任务。

-----------------------------------------------------------------------------

针对你提供的引用内容，我将重点解释 Playwright CLI 与 Playwright MCP 的核心区别，以及为什么在 Agent（智能体）架构中，CLI 被认为是更优的方案。

由于我无法直接插入动态图片，我将使用结构化图表和代码块模拟图示来为你直观展示其工作原理。

1. 核心对比：CLI vs MCP

根据引用内容，Playwright 提供了两种与浏览器交互的方式。对于使用 Coding Agents（代码智能体） 的场景，CLI 是首选。

2. 深度解析：为什么 CLI 更适合 Agent？

引用中提到的核心概念是 Token Efficiency（Token 效率）。以下是详细的原理拆解：

🚀 机制 A：Playwright CLI 的“极简主义”工作流

CLI 的设计哲学是**“最小化上下文污染”**。它不强迫 LLM（大语言模型）去阅读整个网页的 HTML 结构。

• 工作步骤：

  1. Agent 决策：Agent 决定要点击某个元素。
  2. CLI 调用：Agent 发送指令 playwright-cli click e15。
  3. 执行：CLI 工具直接在浏览器中找到 ID 为 e15 的元素并点击。
  4. 反馈：CLI 返回操作结果（成功/失败），而不是返回整个页面的 DOM 树。

• 图解：

    [LLM Agent] 
        | (指令: "点击 e15")
        v
    [Playwright CLI] ——(直接操作浏览器)——> [Browser]
        |
        v
    [结果: Success] (无冗余页面数据)

优势：这种方式非常适合高吞吐量的编码代理，因为它释放了宝贵的上下文窗口空间，让 Agent 可以专注于处理大型代码库或复杂的业务逻辑，而不是被网页标签淹没。

🧠 机制 B：Playwright MCP 的“深度介入”工作流

MCP 的设计哲学是**“最大化的感知”**。它允许模型与页面进行迭代式的推理。

• 工作步骤：

  1. 状态获取：MCP 将当前页面的可访问性树（Accessibility Tree）完整传输给 LLM。
  2. 模型推理：LLM “阅读” 整个页面结构，分析哪里可以点击。
  3. 执行动作：LLM 生成动作指令，MCP 执行。
  4. 循环：页面变化后，再次传输树状结构，进行下一轮推理。

• 图解：

    [LLM Agent] 
        | (接收: 整个页面的DOM/AT树 ~ 几十万字节)
        v
    [思考: "我要点这里"] 
        | (指令: "点击 X")
        v
    [Playwright MCP] ——(操作浏览器)——> [Browser]

适用性：虽然消耗资源，但 MCP 适合探索性任务（如：从未见过的网页，需要模型自己摸索怎么用）或自愈测试（当元素找不到时，模型可以重新分析页面结构来寻找替代路径）。

3. 总结与建议

引用文档中的结论非常明确：

• 如果你是 Coding Agent（代码智能体）：

  • 选择 CLI。因为它通过 SKILLs 的方式暴露功能，更加Token 高效。它避免了将大型工具 Schema 和冗长的可访问性树加载到模型上下文中。
  • 典型命令：playwright-cli install --skills。

• 如果你是 Specialized Agentic Loops（专业级智能体循环）：

  • 选择 MCP。如果你的任务需要模型对页面结构进行丰富的内省和迭代推理（例如复杂的 RPA 流程、自我修复的测试脚本），那么 MCP 的持久状态和深度感知能力是值得付出 Token 代价的。