playwriter (Remorses)

Let your agents control your own Chrome, via CLI or MCP. Your logins, extensions, cookies — already there.

其他浏览器MCP会生成一个新的Chrome——没有登录，没有扩展，机器人检测器会立即标记，内存加倍。剧作家连接到 您正在运行的浏览器 相反。一个Chrome扩展，完整的Playwright API，你已经登录的一切。

安装

1. 安装扩展 来自Chrome网上商店

1. 单击选项卡上的扩展图标→ 连接时变为绿色

1. 安装CLI并开始自动化浏览器：

   npm i -g playwriter
   playwriter -s 1 -e 'await page.goto("https://example.com")'

1. 安装该技能，以便您的代理知道如何使用Playwriter：

   npx -y skills add remorses/playwriter

快速开始

playwriter browser start  # starts Chrome for Testing/Chromium with bundled Playwriter extension
playwriter session new  # creates stateful sandbox, outputs session id (e.g. 1)
playwriter -s 1 -e 'await page.goto("https://example.com")'
playwriter -s 1 -e 'console.log(await snapshot({ page }))'
playwriter -s 1 -e 'await page.locator("aria-ref=e5").click()'

提示： 始终使用单引号 -e 防止bash进行解释 $、回溯，以及 \ 在你的JS代码中。在JS中为字符串使用双引号。

命令行用法

每节课都有 孤立状态。浏览器选项卡为 共享 跨届会议。

# Browser management
playwriter browser start             # auto-finds Chrome for Testing or Chromium, with recording flags enabled
playwriter browser start /path/to/browser-binary

# Session management
playwriter session new              # creates stateful sandbox, outputs id (e.g. 1)
playwriter session list             # show sessions + state keys
playwriter session reset        # fix connection issues

# Execute (always use -s)
playwriter -s 1 -e 'await page.goto("https://example.com")'
playwriter -s 1 -e 'await page.click("button")'
playwriter -s 1 -e 'console.log(await page.title())'

创建自己的页面以避免其他代理的干扰：

playwriter -s 1 -e 'state.myPage = await context.newPage(); await state.myPage.goto("https://example.com")'

多行：

playwriter -s 1 -e $'
const title = await page.title();
console.log({ title, url: page.url() });
'

例子

作用域中的变量： page, context, state （在通话之间持续）， require，以及Node.js全局变量。

将数据保持在状态：

playwriter -e "state.users = await page.$$eval('.user', els => els.map(e => e.textContent))"
playwriter -e "console.log(state.users)"

拦截网络请求：

playwriter -e "state.requests = []; page.on('response', r => { if (r.url().includes('/api/')) state.requests.push(r.url()) })"
playwriter -e "await Promise.all([page.waitForResponse(r => r.url().includes('/api/')), page.click('button')])"
playwriter -e "console.log(state.requests)"

设置断点并调试：

playwriter -e "state.cdp = await getCDPSession({ page }); state.dbg = createDebugger({ cdp: state.cdp }); await state.dbg.enable()"
playwriter -e "state.scripts = await state.dbg.listScripts({ search: 'app' }); console.log(state.scripts.map(s => s.url))"
playwriter -e "await state.dbg.setBreakpoint({ file: state.scripts[0].url, line: 42 })"

实时编辑页面代码：

playwriter -e "state.cdp = await getCDPSession({ page }); state.editor = createEditor({ cdp: state.cdp }); await state.editor.enable()"
playwriter -e "await state.editor.edit({ url: 'https://example.com/app.js', oldString: 'const DEBUG = false', newString: 'const DEBUG = true' })"

带有标签的屏幕截图：

playwriter -e "await screenshotWithAccessibilityLabels({ page })"

MCP设置

建议使用熟练的CLI（上述步骤4）。有关直接MCP服务器配置，请参阅 MCP.md.

视觉标签

Vimium风格的标签，用于AI代理识别元素：

await screenshotWithAccessibilityLabels({ page })
// Returns screenshot + accessibility snapshot with aria-ref selectors
await page.locator('aria-ref=e5').click()

颜色编码：黄色=链接，橙色=按钮，珊瑚色=输入，粉色=复选框，桃色=滑块，鲑鱼色=菜单，琥珀色=标签。

比较

vs剧作家MCP

注： Playwriter视频录制 比剧作家录像效率高100倍，发送 每帧的base64图像.

Vs浏览器

vs反重力（Jetski）

vs克劳德浏览器扩展

vs内置Chrome CDP(--remote-debugging-port)

Chrome浏览器 --remote-debugging-port 标志显示了一个持久的“由自动化软件控制”的横幅，代理无法忽略。每当你使用浏览器时，它都会在你的工作流程中间弹出。Playwriter默默运行——代理在没有任何确认对话框的情况下自主工作，因此您永远不会被打扰。

建筑

+---------------------+     +-------------------+     +-----------------+
|   BROWSER           |     |   LOCALHOST       |     |   MCP CLIENT    |
|                     |     |                   |     |                 |
|  +---------------+  |     | WebSocket Server  |     |  +-----------+  |
|  |   Extension   |  :19988         |     |  | AI Agent  |  |
|  +-------+-------+  | WS  |                   |     |  +-----------+  |
|          |          |     |  /extension       |     |        |        |
|    chrome.debugger  |     |       |           |     |        v        |
|          v          |     |       v           |     |  +-----------+  |
|  +---------------+  |     |  /cdp/:id  |  execute  |  |
|  | Tab 1 (green) |  |     +-------------------+  WS |  +-----------+  |
|  | Tab 2 (green) |  |                               |        |        |
|  | Tab 3 (gray)  |  |     Tab 3 not controlled      |  Playwright API |
+---------------------+     (no extension click)      +-----------------+

远程访问

通过互联网在远程计算机上控制Chrome浏览器 特拉福罗 隧道：

在主机上：

npx -y traforo -p 19988 -t my-machine -- npx -y playwriter serve --token 

远程：

export PLAYWRITER_HOST=https://my-machine-tunnel.traforo.dev
export PLAYWRITER_TOKEN=
playwriter -s 1 -e 'await page.goto("https://example.com")'

也可以在没有traforo的局域网上工作(PLAYWRITER_HOST=192.168.1.10).使用案例的完整指南（远程Mac mini、用户支持、多机控制）： docs/remote-access.md

安全

• 仅限本地：上的WebSocket服务器 localhost:19988
• 原产地验证：只允许我们的扩展ID（浏览器不能欺骗Origin）
• 明确同意：仅显示您单击扩展图标的选项卡
• 可视化自动化：Chrome在受控选项卡上显示自动化横幅
• 无远程访问：恶意网站无法连接

剧作家API

以编程方式连接（无需CLI）：

import { chromium } from 'playwright-core'
import { startPlayWriterCDPRelayServer, getCdpUrl } from 'playwriter'

const server = await startPlayWriterCDPRelayServer()
const browser = await chromium.connectOverCDP(getCdpUrl())
const page = browser.contexts()[0].pages()[0]

await page.goto('https://example.com')
await page.screenshot({ path: 'screenshot.png' })
// Don't call browser.close() - it closes the user's Chrome
server.close()

或者连接到正在运行的服务器：

npx -y playwriter serve --host 127.0.0.1

const browser = await chromium.connectOverCDP('http://127.0.0.1:19988')

故障排除

查看中继服务器日志以调试问题：

playwriter logfile  # prints the log file path
# typically: ~/.playwriter/relay-server.log

中继日志包含扩展、MCP和WebSocket服务器日志。同时还创建了一个单独的CDP JSONL日志（请参见 playwriter logfile).两者都会在每次服务器启动时重新创建。

示例：按方向+方法汇总CDP流量计数：

jq -r '.direction + "\t" + (.message.method // "response")' ~/.playwriter/cdp.jsonl | uniq -c

支持

如果Playwriter对您有用，请考虑 赞助该项目.

已知问题

• 如果所有页面都返回 about:blank，重新启动Chrome（Chrome中的错误 chrome.debugger API
• 浏览器可能会在连接时切换到灯光模式(剧作家问题)