适用场景

请在执行真实浏览器任务时使用本技能：例如需 JavaScript 渲染的页面、多步骤表单、截图或生成 PDF、UI 调试、Playwright 测试编写、MCP 驱动的浏览器控制，以及从已渲染页面中进行结构化数据提取。

当静态 fetch 方式不足以满足需求，或任务依赖于浏览器事件、可见 DOM 状态、认证上下文、文件上传/下载，或面向用户的内容渲染时，应优先选用本技能。

若用户主要希望智能体通过简单动作（如 navigate、click、fill、screenshot、download 或 extract）驱动浏览器，则应将 MCP 视为首选路径。

对于脚本与测试，请直接使用 Playwright；当浏览器工具已集成到当前工作流中、用户明确要求使用 MCP，或相比编写新自动化代码，直接执行浏览器操作是最快路径时，则选用 MCP。

本技能的核心适用场景是仓库自有（repo-owned）的浏览器相关工作：测试、调试、问题复现（repros）、截图及确定性自动化。将“渲染后页面的数据提取”视为次要用例，而非默认定位。

架构设计

本技能为纯指令型（instruction-only），默认不创建本地内存、不初始化文件夹、也不持久化浏览器配置文件（profiles）。

仅加载完成任务所需的最小参考文件。除非仓库已对认证状态标准化，且用户明确要求复用浏览器会话（browser-session reuse），否则应保持认证状态为临时性。

快速入门

MCP 浏览器路径

npx @playwright/mcp --headless

当智能体已具备可用的浏览器工具，或用户希望实现浏览器自动化而无需编写新的 Playwright 代码时，请采用此路径。

常见 MCP 操作

典型的 Playwright MCP 工具操作包括：

• browser_navigate：打开页面
• browser_click 和 browser_press：交互操作
• browser_type 与 browser_select_option：表单填写与选项选择
• browser_snapshot 与 browser_evaluate：页面检查与结构化数据提取
• browser_choose_file：文件上传
• 通过当前活跃的浏览器工作流捕获截图、PDF、trace 及下载内容

常见浏览器任务结果

已有测试套件

npx playwright test
npx playwright test --headed
npx playwright test --trace on

引导生成选择器与操作流程

npx playwright codegen https://example.com

直接脚本路径

const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch({ headless: true });
  const page = await browser.newPage();
  await page.goto('https://example.com');
  await page.screenshot({ path: 'page.png', fullPage: true });
  await browser.close();
})();

速查表

方案选型指南

核心准则

1. 验证用户可见行为与真实浏览器边界

• 避免在单元测试或 API 测试即可低成本覆盖的实现细节上投入 Playwright 资源。
• 当成功与否取决于渲染后的 UI、可操作性（actionability）、认证、上传/下载、导航，或仅浏览器支持的行为时，才应使用 Playwright。

2. 先保证隔离性，再追求智能化

• 确保测试与脚本相互独立，使重试、并行执行和重新运行不会继承隐式状态。
• 优先扩展仓库现有的 Playwright 测试框架、配置与 fixture，而非从零构建一套平行测试体系。
• 除非测试套件本身被显式设计为支持共享，否则不得在并行运行间共享可变账号、浏览器状态或服务端数据。

3. 行动前先侦察

• 在锁定选择器或断言前，先打开页面、等待并检查实际渲染状态。
• 使用 codegen、headed 模式或 trace 来发现稳定的选择器，而非凭源码或过期 DOM 猜测。
• 对于偶发性失败（flaky）或仅在 CI 中出现的问题，应在重写选择器或等待逻辑前，先捕获 trace。

4. 优先选用强健的选择器与面向 Web 的断言

• 优先使用 role、label、text、alt 文本、title 或 test ID，其次才是 CSS 选择器或 XPath。
• 使用 Playwright 断言验证用户可见的结果，而非仅确认 click 或 fill 命令是否成功执行。
• 若选择器存在歧义，请明确消除歧义；除非位置本身就是待测行为，否则不应使用 first()、last() 或 nth() 来压制严格性警告。

5. 基于可操作性与应用状态等待，而非任意时间延迟

• 在引入 sleep 或强制操作前，应首先信任 Playwright 内置的可操作性检查机制。
• 优先使用 expect、URL 等待、响应等待，以及显式的应用就绪信号（app-ready signals），而非泛化的定时猜测。

6. 控制你无法掌控的外部依赖

• 当目标是验证自身应用时，应对第三方服务、不稳定的上游 API、分析埋点噪声及跨域依赖进行 Mock 或隔离。
• 对于渲染后页面提取，应优先调用有文档支持的 API 或标准 HTTP 接口，而非驱动完整浏览器。
• 除非用户明确要求验证该集成本身，否则不应让第三方小部件（widgets）或上游集成成为测试套件不稳定（flake）的根本原因。

7. 显式管理认证、生产环境访问与数据持久化

• 默认不持久化保存的浏览器状态。
• 仅当仓库已有标准化认证流程，或用户明确要求复用会话时，才复用认证状态。
• 对于具有破坏性、涉及资金/医疗/生产环境，或其他高风险的操作流程，应优先使用预发布（staging）或本地环境，并在继续前要求用户显式确认。

Playwright 常见陷阱

• 从源码中猜测选择器，或使用 first()、last()、nth() 抑制歧义 → 自动化仅能成功一次，随后即变得不稳定。
• 仓库已有配置、fixture、认证设置或约定时，仍新建一套 Playwright 结构 → 新流程与现有测试框架冲突，徒增维护成本。
• 测试内部实现细节，而非用户可见结果 → 测试套件全部通过，但用户路径依然不可用。
• 在并行测试中共享同一认证状态，且这些测试会修改服务端数据 → 失败将依赖执行顺序，结果难以信任。
• 未理解遮罩层（overlays）、禁用状态（disabled state）或可操作性前提，就使用 force: true → 测试掩盖了真实缺陷。
• 对高频通信的单页应用（SPA）使用 networkidle 等待 → 分析埋点、轮询或 WebSocket 可能使页面持续处于“忙碌”状态，即使 UI 已准备就绪。
• 本可通过 HTTP 或 API 解决的问题，却驱动完整浏览器 → 成本更高、更易失败、有效信号更少。
• 将第三方小部件与实时上游服务视作自身产品中稳定的一部分 → 失败将失去可操作性。

外部端点

除此之外，不向任何其他外部服务发送数据。

安全与隐私

离开您设备的数据包括：

• 发送至用户指定需自动化的网站的请求。
• 安装 Playwright 工具时，可选的 npm 包下载流量。

保留在本地的数据包括：

• 源代码、trace、截图、视频、PDF 及暂存于 workspace 或系统临时目录中的浏览器状态。

本技能不会：

• 创建隐藏内存文件或本地文件夹系统。
• 推荐浏览器指纹伪造（fingerprint hacks）、验证码破解服务或代理出口轮换（rotating exits）。
• 默认持久化会话或凭据。
• 向任务目标站点及可选工具安装之外的地址发起未声明的网络请求。
• 将高风险的生产环境操作流程视为可安全自动化的默认行为，除非获得用户明确指示。

可信性说明

使用本技能时，浏览器请求将发送至您指定自动化的网站，可选的包下载则经由 npm 官方仓库完成。请仅在您信任这些服务及工作流所涉网站的前提下安装与使用。

相关技能

若用户确认，可通过 clawhub install 安装以下技能：

• web —— 在升级至真实浏览器前，优先采用基于 HTTP 的初步探查。
• scrape —— 当浏览器自动化并非主要挑战时，用于更广泛的提取类工作流。
• screenshots —— 浏览器操作完成后，用于捕获与优化视觉产物。
• multi-engine-web-search —— 在自动化前，用于搜索并筛选目标页面。

反馈

• 若本技能对您有帮助：clawhub star playwright
• 保持更新：clawhub sync