Playwright 外接工具实战

这一页讲的是：在 --xtra 模式下，怎么把浏览器当成一个可交互、可取证、可排障的外部执行面来用。

重点不是记住底层工具名，而是搞清楚三件事：

浏览器协作适合解决什么问题
一条稳定链路通常怎么走
遇到表单、弹窗、标签页、网络异常时该怎么收口

先判断是不是这页的范围

你想在 mind --xtra 里打开网页、点页面、填表单、截图、查请求：看这里
你想看数据库类外接工具：去看 DBHub 外接工具实战
你想看设备/UI 自动化而不是浏览器自动化：去看设备与 UI 实战
你只想看 --xtra 的入口、配置文件位置和模式边界：先回 README

配置单格式

外接服务配置统一采用下面这种 HTTP 接入结构：

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

支持字段：

字段	类型	说明
`url`	`string`	必填。浏览器外接服务地址。
`enabled`	`boolean`	可选。是否启用，默认 `true`。
`transport`	`string`	可选。支持 `streamable_http` 或 `sse`。
`headers`	`object`	可选。附加请求头。
`timeout_sec`	`number`	可选。请求超时秒数。
`sse_read_timeout_sec`	`number`	可选。SSE 读取超时秒数。
`terminate_on_close`	`boolean`	可选。`streamable_http` 下是否在关闭时通知远端终止。
`notes`	`string`	可选。备注，不参与运行逻辑。

补充：

这套配置单是通用外接 MCP 结构，不只限于 Playwright
enabled: false 时，该服务不会参与本轮外接模式
如果 transport 省略，通常按 streamable_http 处理；url 以 /sse 结尾时会自动推断为 sse

连接配置

最小示例：

mind --xtra "打开 example.com，搜索 pricing，然后截图"

最小接入顺序

推荐按下面 4 步走：

1. 先准备浏览器二进制

npx playwright install chromium

这一步不是绝对强制，但建议先做。这样第一次跑外接服务时不会临时下载浏览器，体验和排障都会更稳。

2. 启动 Playwright MCP HTTP 服务

npx @playwright/mcp@latest --port 8931

3. 配置外接服务

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

4. 通过 `--xtra` 使用

mind --xtra "打开目标网页，抓取当前页面快照并总结关键字段"

使用心智模型

浏览器类外接能力最稳的思路，不是“盲点点击”，而是：

打开页面
先读取页面结构
再做点击、输入、切换、上传这类动作
必要时补截图、补控制台、补网络请求

所以工程上最常见的收口顺序是：

打开页面 -> 读取结构 -> 做动作 -> 等待稳定 -> 再次读取/截图 -> 查看网络或控制台

能力总览

浏览器协作大致可以分成 6 组。

1. 页面与会话

适合：

打开一个站点
返回上一页
新开标签页
切换标签页
关闭浏览器或当前标签页
调整窗口尺寸做响应式验证

典型自然语言：

打开 https://example.com 并等待页面稳定
回到上一页，再重新抓取列表页
新开一个标签页打开 staging，保留当前生产页不动
把窗口调到窄屏后重新截图

2. 页面理解与留证

适合：

读取页面结构
识别标题、按钮、输入框、表单块
截图留证
比较操作前后的页面变化

典型自然语言：

抓取当前页面结构，并总结标题、主按钮和导航
对当前页面截图，保留完整证据
对比提交前后页面是否出现成功提示

3. 点击、悬停与键盘动作

适合：

点击按钮、链接、菜单
悬停打开浮层或二级菜单
用回车、Tab、Escape、方向键补动作
处理纯键盘可达场景

典型自然语言：

点击登录按钮
悬停到头像菜单，查看是否有退出入口
输入后按 Enter 提交
按 Escape 关闭当前弹窗

4. 表单与上传

适合：

单字段输入
一次填完整表单
选择下拉项
上传文件
处理浏览器原生确认框

典型自然语言：

填写登录表单：用户名 admin，密码 123456
把环境下拉框切到 staging
上传 reports/monthly.csv 到当前表单
如果弹出确认框，选择确认

5. 拖拽与复杂交互

适合：

拖拽排序
拖动任务卡
滑块操作
拖放上传

典型自然语言：

把第一列任务卡拖到 Done 列
把本地测试文件拖到上传区

6. 网络与调试

适合：

看页面发了哪些请求
查看某条请求的详情
检查前端控制台报错
读取页面内变量或局部状态

典型自然语言：

列出当前页面请求，重点看 /api/ 开头的接口
把刚才失败的用户详情接口展开看响应详情
读取控制台消息，检查是否有 error 或 warning
读取 localStorage 里的 tenant 字段

常见工作流

打开页面并理解结构

适合：首次进入一个页面，想先看结构和主操作点。

mind --xtra "打开 https://example.com，抓取当前页面结构，并总结主标题、主按钮和顶部导航"

搜索并进入结果页

适合：搜索框驱动的站点、后台管理台、文档站。

mind --xtra "打开目标站点，在搜索框里输入 payroll，进入结果页后等待稳定，再总结页面主信息"

登录并留证

适合：登录页、后台入口、带欢迎页的控制台。

mind --xtra "打开登录页，填写账号和密码，提交后等待首页稳定，再截图留证"

表单提交后定位失败原因

适合：创建工单、发布配置、提交审批。

mind --xtra "打开工单创建页，填写表单并提交；如果失败，读取控制台和网络请求，定位原因"

双标签页对比

适合：生产和 staging 对比、不同租户对比、改版前后对比。

mind --xtra "打开生产环境首页，再新开标签页打开 staging，对比两边 header、导航和首屏按钮差异"

稳定执行建议

先读结构，再交互，不要一上来就靠截图猜
表单提交后别立刻断言，先等页面稳定
一旦怀疑页面请求异常，先看网络，再看控制台
做留证时，结构快照和截图最好一起保留
标签页越多，后续上下文越容易混乱；能关就关

参考来源

Playwright MCP 入门与配置：playwright.dev
Playwright MCP 工具列表：Docker MCP Catalog
Playwright MCP capability/tool 分类：playwright.dev

Playwright 外接工具实战

先判断是不是这页的范围

配置单格式

连接配置

最小接入顺序

1. 先准备浏览器二进制

2. 启动 Playwright MCP HTTP 服务

3. 配置外接服务

4. 通过 --xtra 使用

使用心智模型

能力总览

1. 页面与会话

2. 页面理解与留证

3. 点击、悬停与键盘动作

4. 表单与上传

5. 拖拽与复杂交互

6. 网络与调试

常见工作流

打开页面并理解结构

搜索并进入结果页

登录并留证

表单提交后定位失败原因

双标签页对比

稳定执行建议

参考来源

4. 通过 `--xtra` 使用