playwriter

用途

Playwriter 是“运行中浏览器”的浏览器自动化技能。它把智能体连接到用户真实工作流中已经打开的 Chrome/Chromium，而不是新开一个干净、一次性的浏览器。因此它适合需要认证流程、依赖扩展的页面以及长期标签页上下文的场景，但可复现性不如全新会话的浏览器工具。

何时使用

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

用户已经打开的浏览器
现有登录、Cookie 或受信任设备状态
依赖浏览器扩展的工作流
passkey / SSO / MFA 密集、需要人工登录交接的流程
人与智能体共享同一浏览器、需要实时标签页连续性
使用运行中浏览器为 Claude / Codex / Gemini 提供基于 MCP 的浏览器控制

默认不要用于：

CI 风格的可重复浏览器检查
不应触碰用户真实浏览器配置的全新会话验证
适合 browser-harness 的简单抓取或确定性表单检查
需要最强隔离或最少用户状态耦合的任务

快速路由规则

需要用户已打开的浏览器 → playwriter
需要现有登录 / Cookie / 扩展 → playwriter
需要干净、可复现、一次性会话 → browser-harness
需要无头验证 / 截图对比 / 隔离检查 → browser-harness
需要托管或云端浏览器基础设施 → 特定提供商或云浏览器技能

使用方式

第 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 可以启动带 Playwriter 扩展的 Chrome for Testing / Chromium。
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 为智能体提供传输层；Playwriter 仍负责浏览器/会话行为。
会话复用、浏览器可见性和标签页同意仍属于 Playwriter 的职责，而非 MCP 的职责。

安全与预期

playwriter 是特权模式，因为它可以接触用户的真实浏览器会话。
仅在确实需要会话复用时优先使用它。
由于标签页、扩展和人都可能改变状态，其可复现性预期低于干净的隔离浏览器。
手动登录 / MFA / 验证码交接在这一路径中是正常的；不要假装完全自主是必然的。
干净地分离或重置；不要假定杀掉用户浏览器是安全的。

故障排查

无响应：确认扩展已安装并在目标标签页上启用
标签页/页面状态错误：重新运行 snapshot({ page })，点击前确认处于预期标签页
会话陈旧/损坏：playwriter session reset <id>
引号破坏 JavaScript：对 -e 输入使用 heredoc
需要可重复的隔离自动化：改用 browser-harness
浏览器状态过于混乱/有人为干扰：启动新会话或使用全新会话浏览器工具

示例

示例 1：已登录 SaaS 工作流

提示：“使用我已登录的 Chrome 更新一个 Jira 工单，无需重新认证。”

预期技能行为：选择 playwriter，说明运行中浏览器复用，创建会话，先观察再操作。

示例 2：干净浏览器验证

提示：“在 CI 中运行可重复的无头结账测试并对比截图。”

预期技能行为：从 playwriter 转向 browser-harness 或其他全新会话工具，因为隔离比会话复用更重要。

示例 3：MCP 浏览器桥接

提示：“将 Codex 或 Claude 连接到我已打开的浏览器，使其能使用我当前的标签页和 Cookie。”

预期技能行为：选择 playwriter，说明 MCP 配置，并明确运行中浏览器的前提。

最佳实践

选择 playwriter 是因为浏览器状态重要，而不是因为出现了“浏览器”这个词。
在任何可能命中错误标签页或陈旧 UI 状态的操作之前，先执行 snapshot({ page })。
每次有意义的操作后重新快照；实时浏览器状态比隔离自动化状态漂移更快。
对非平凡 JavaScript 使用 heredoc，避免 shell 引号问题。
将手动登录 / MFA / 验证码交接视为这一路径中的正常情况。
报告为何需要运行中浏览器，以及何时使用全新会话工具会更安全。

限制

属于特权模式，可接触用户真实浏览器会话。
可复现性低于干净隔离浏览器。
手动登录、MFA、验证码交接可能不可避免。
不适合 CI 风格可重复检查、全新会话验证、简单抓取或确定性表单检查。
不应假定可以安全地终止用户浏览器。