playwriter

playwriter

Playwriter 是一项用于正在运行的浏览器的浏览器自动化技能。它会将 Agent 连接到已融入用户实际工作流的 Chrome/Chromium，而不是启动一个全新的临时浏览器。因此，它适用于需要身份验证的流程、依赖扩展程序的页面，以及需要长期保留标签页上下文的场景；但与全新会话的浏览器工具相比，其可复现性较差。

何时使用此技能

当任务需要以下一项或多项功能时，使用 playwriter：

• 用户已打开的浏览器
• 现有登录状态、Cookie 或受信任设备状态
• 依赖扩展程序的工作流
• 密钥 / SSO / MFA 密集型流程，且人工接管登录切实可行
• 人与 Agent 在同一浏览器中共享的实时标签页连续性
• 使用 MCP，通过正在运行的浏览器控制 Claude / Codex / Gemini

以下情况不要默认使用 playwriter：

• 类 CI 的可重复浏览器检查
• 不应触及用户真实浏览器配置文件的全新会话验证
• 适用于 browser-harness 的简单抓取或确定性表单检查
• 需要最强隔离或尽量减少与用户状态耦合的任务

快速选择规则

如果任务需要……	使用
用户已打开的浏览器	playwriter
现有登录状态 / Cookie / 扩展程序	playwriter
干净、可复现的一次性会话	browser-harness
无头验证 / 截图差异比较 / 隔离检查	browser-harness
托管式或云端浏览器基础设施	特定提供商或云浏览器技能

使用说明

第 1 步：选择合适的浏览器运行时

仅当需要复用正在运行的浏览器时，才使用 playwriter。如果任务实际需要的是干净的一次性浏览器或类 CI 的可复现性，请改用 browser-harness。

第 2 步：遵循核心工作流

始终遵循相同的循环：

1. 准备正在运行的浏览器桥接
2. 创建或选择会话
3. 先观察，使用 snapshot({ page })
4. 执行一次操作
5. 再次观察，然后再执行下一项操作

第 1 步：安装扩展程序和 CLI

# install the CLI
npm install -g playwriter
# or use it without global install
npx playwriter@latest --help

安装 Playwriter Chrome 扩展程序，然后点击要控制的标签页上的扩展程序图标。在确认自动化功能可用前，应确保标签页显示已连接 / 绿色状态。

第 2 步：启动浏览器支持并创建会话

使用上游的浏览器 / 会话流程，不要含糊地假设“扩展程序会自动启动一切”：

# start the managed browser/runtime if needed
playwriter browser start

# create a stateful sandbox session
playwriter session new

# inspect current sessions
playwriter session list

说明：

• playwriter browser start 可以启动 Chrome for Testing / Chromium，并使 Playwriter 扩展程序可用。
• playwriter session new 会创建一个有状态沙盒并返回会话 ID。
• 浏览器标签页是共享的，但会话状态彼此隔离。

第 3 步：观察 → 操作 → 再观察

# navigate
playwriter -s 1 -e 'await page.goto("https://example.com")'

# observe current page state
playwriter -s 1 -e 'console.log(await snapshot({ page }))'

# act using a fresh aria-ref from the snapshot
playwriter -s 1 -e 'await page.locator("aria-ref=e5").click()'

# observe again after the action
playwriter -s 1 -e 'console.log(await snapshot({ page }))'

规则：

• 页面导航或 DOM 发生重大变化后，不要继续使用旧的 aria-ref 值。
• 文本结构足以满足需求时，优先使用 snapshot({ page })，而非截图。
• 仅在需要视觉证据时使用截图或录制。

高价值命令模式

导航和状态

playwriter browser start
playwriter session new
playwriter session list
playwriter session reset 1
playwriter session delete 1

在会话中执行 Playwright 代码

# basic navigation
playwriter -s 1 -e 'await page.goto("https://github.com")'

# fill + submit
playwriter -s 1 -e 'await page.fill("#search", "playwriter"); await page.keyboard.press("Enter")'

# save reusable state between calls
playwriter -s 1 -e 'state.lastUrl = page.url(); state.heading = await page.textContent("h1")'
playwriter -s 1 -e 'console.log(state.lastUrl, state.heading)'

安全地使用多行代码

playwriter -s 1 -e "$(cat <<'EOF'
const title = await page.title();
state.title = title;
console.log(await snapshot({ page }));
EOF
)"

如果 JavaScript 代码中的引号容易出错，请使用 heredoc。

MCP 集成

当模型客户端需要为正在运行的浏览器提供浏览器工具时，使用 Playwriter；如果它只需要任意浏览器工具，则无需使用。

MCP 配置示例

{
  "mcpServers": {
    "playwriter": {
      "command": "npx",
      "args": ["-y", "playwriter@latest"]
    }
  }
}

常见用途：

• Claude / Codex / Gemini 可以通过 MCP 调用 Playwriter。
• MCP 为 Agent 提供传输层；浏览器 / 会话的行为仍由 Playwriter 管理。
• 会话复用、浏览器可见性和标签页授权仍属于 Playwriter 的职责，而非 MCP 的职责。

安全性与预期

• playwriter 属于特权模式，因为它可以访问用户的真实浏览器会话。
• 只有确实需要复用会话时，才优先选择它。
• 由于标签页、扩展程序和用户都可能改变状态，其可复现性低于干净、隔离的浏览器。
• 在此模式下，手动交接登录 / MFA / CAPTCHA 属于正常情况；不要假设能够保证完全自主操作。
• 请妥善断开连接或重置；不要认为可以安全地强行关闭用户的浏览器。

故障排查

问题	检查内容
没有响应	确认扩展程序已安装，并已在目标标签页中启用
标签页 / 页面状态不正确	重新运行 snapshot({ page })，并在点击前确认当前处于预期标签页
会话过期 / 损坏	playwriter session reset <id>
引号导致 JavaScript 出错	使用 heredoc 传入 -e 输入
需要可重复的隔离式自动化	改用 browser-harness
浏览器状态过于混乱 / 受到用户干扰	启动新会话，或使用全新会话的浏览器工具

示例

示例 1：已登录的 SaaS 工作流

• 提示词：“使用我已登录的 Chrome 更新 Jira 工单，无需重新进行身份验证。”
• 预期技能行为：选择 playwriter，说明会复用正在运行的浏览器，创建会话，先观察再操作。

示例 2：干净的浏览器验证

• 提示词：“在 CI 中运行可重复的无头结账测试，并比较截图。”
• 预期技能行为：改用 browser-harness 或其他全新会话工具，而不是 playwriter，因为隔离比会话复用更重要。

示例 3：MCP 浏览器桥接

• 提示词：“将 Codex 或 Claude 连接到我已经打开的浏览器，以便使用我当前的标签页和 Cookie。”
• 预期技能行为：选择 playwriter，说明 MCP 配置，并明确指出操作依赖正在运行的浏览器。

最佳实践

1. 因浏览器状态很重要而选择 playwriter，而不是因为出现了“browser”一词。
2. 在执行任何可能作用于错误标签页或过期 UI 状态的操作前，先运行 snapshot({ page })。
3. 每次有实质性操作后都重新获取快照；实时浏览器状态的变化比隔离式自动化状态更快。
4. 对于复杂的 JavaScript，使用 heredoc，避免 shell 引号问题。
5. 将手动交接登录 / MFA / CAPTCHA 视为此模式下的正常情况。
6. 说明为何需要使用正在运行的浏览器，以及何时使用全新会话工具会更安全。

参考资料

此技能的深入文档：

• 模式与路由
• 会话工作流
• MCP 集成

主要来源：

• https://raw.githubusercontent.com/remorses/playwriter/main/README.md
• https://playwright.dev/docs/auth
• https://playwright.dev/docs/api/class-browsertype#browser-type-connect-over-cdp
• https://modelcontextprotocol.io/introduction

输出要求

使用此技能时，请报告：

• 选择 playwriter 而非全新会话浏览器工具的原因
• 会话 / 运行时假设
• 执行的关键操作
• 捕获的证据（snapshot、截图、录制、日志）
• 遇到的任何手动交接或身份验证相关限制