434 lines
11 KiB
Markdown
434 lines
11 KiB
Markdown
# Playwright浏览器自动化技能
|
||
|
||
`浏览器自动化` `Playwright` `MCP` `OpenClaw` `Node.js`
|
||
|
||
# OpenClaw 的 Playwright 浏览器技能
|
||
|
||
一个功能强大的浏览器自动化技能，基于 Playwright 构建，通过 MCP 协议为 OpenClaw 提供 101 个完整的浏览器操作能力。
|
||
|
||
[](WINDOWS_GUIDE.md)
|
||
[](https://nodejs.org/)
|
||
[](https://playwright.dev/)
|
||
[](LICENSE)
|
||
|
||
中文文档 | [English](README_EN.md)
|
||
|
||
## ✨ 特性
|
||
|
||
- 🌐 **完整的浏览器控制** - 支持 Chromium、Firefox、WebKit
|
||
- 📱 **设备模拟** - 模拟 iPhone、Android 等移动设备
|
||
- 🎯 **智能选择器** - CSS、ARIA、文本、标签等多种选择方式
|
||
- 📸 **截图和录制** - 页面截图、元素截图、PDF 生成、视频录制
|
||
- 🌍 **网络控制** - 请求拦截、响应模拟、离线模式
|
||
- 🔍 **内容提取** - 文本、HTML、链接、属性等
|
||
- ⚡ **性能监控** - 页面性能指标、控制台日志
|
||
- 🎨 **高级功能** - Cookie 管理、LocalStorage、地理位置、时间控制
|
||
|
||
## 📦 安装
|
||
|
||
### 前置要求
|
||
|
||
- Node.js 18 或更高版本
|
||
- npm 或 yarn
|
||
- Windows 10/11、macOS 或 Linux
|
||
|
||
### 安装方式
|
||
|
||
#### 方式一：下载发行版（推荐，适合普通用户）
|
||
|
||
**最简单的安装方式！** 下载预编译的独立包，无需构建，开箱即用。
|
||
|
||
**Windows 用户：**
|
||
1. 下载 [playwright-browser-skill-windows-v2.1.0.zip](https://github.com/91fapiao-cn/playwright-browser-skill/releases)
|
||
2. 解压到任意目录
|
||
3. 双击运行 `auto-deploy.cmd`（推荐）或 `auto-deploy.ps1`
|
||
4. 重启 OpenClaw，开始使用！
|
||
|
||
**注意：** 推荐使用 `.cmd` 文件，大部分 Windows 电脑默认禁止运行 PowerShell 脚本。
|
||
|
||
**Mac/Linux 用户：**
|
||
1. 下载 [playwright-browser-skill-macos-linux-v2.1.0.tar.gz](https://github.com/91fapiao-cn/playwright-browser-skill/releases)
|
||
2. 解压：`tar -xzf playwright-browser-skill-macos-linux-v2.1.0.tar.gz`
|
||
3. 进入目录并运行：`chmod +x auto-deploy.sh && ./auto-deploy.sh`
|
||
4. 重启 OpenClaw，开始使用！
|
||
|
||
**发行版优势：**
|
||
- ✅ 无需 `npm install`，节省时间
|
||
- ✅ 无需构建，开箱即用
|
||
- ✅ 包含完整依赖，离线可用
|
||
- ✅ 一键自动部署
|
||
- ✅ 适合非开发者用户
|
||
|
||
#### 方式二：从源码安装（适合开发者）
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
git clone https://github.com/91fapiao-cn/playwright-browser-skill.git
|
||
cd playwright-browser-skill
|
||
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 安装浏览器驱动
|
||
npm run install-browsers
|
||
|
||
# 构建项目
|
||
npm run build
|
||
```
|
||
|
||
## 🚀 使用方法
|
||
|
||
### 一键自动部署（推荐）
|
||
|
||
我们提供了跨平台的自动部署脚本，支持中英文版本，可以自动检测 OpenClaw 配置路径并完成所有配置：
|
||
|
||
#### Windows (PowerShell) - 推荐
|
||
|
||
```powershell
|
||
# 中文版
|
||
.\auto-deploy.ps1
|
||
|
||
# 英文版
|
||
.\auto-deploy-en.ps1
|
||
|
||
# 跳过构建（如果已构建）
|
||
.\auto-deploy.ps1 -SkipBuild
|
||
|
||
# 指定自定义路径
|
||
.\auto-deploy.ps1 -OpenClawPath "C:\custom\path\.openclaw"
|
||
```
|
||
|
||
#### Windows (CMD)
|
||
|
||
```cmd
|
||
REM 中文版
|
||
auto-deploy.cmd
|
||
|
||
REM 英文版
|
||
auto-deploy-en.cmd
|
||
|
||
REM 跳过构建
|
||
auto-deploy.cmd --skip-build
|
||
|
||
REM 指定自定义路径
|
||
auto-deploy.cmd --openclaw-path "C:\custom\path\.openclaw"
|
||
```
|
||
|
||
#### Mac/Linux
|
||
|
||
```bash
|
||
# 添加执行权限（首次使用）
|
||
chmod +x auto-deploy.sh auto-deploy-en.sh
|
||
|
||
# 中文版
|
||
./auto-deploy.sh
|
||
|
||
# 英文版
|
||
./auto-deploy-en.sh
|
||
|
||
# 跳过构建
|
||
./auto-deploy.sh --skip-build
|
||
|
||
# 指定自定义路径
|
||
./auto-deploy.sh --openclaw-path "/custom/path/.openclaw"
|
||
```
|
||
|
||
**自动部署功能：**
|
||
- ✅ 自动检测 OpenClaw 配置路径
|
||
- ✅ 自动构建项目（可选跳过）
|
||
- ✅ 自动部署 Skill 文件
|
||
- ✅ 自动配置 MCP 服务器
|
||
- ✅ 自动备份现有配置
|
||
- ✅ 支持自定义安装路径
|
||
|
||
📖 [查看详细部署文档](AUTO_DEPLOY_README.md)
|
||
|
||
### 手动部署
|
||
|
||
如果需要手动部署，请参考以下步骤：
|
||
|
||
#### 1. 部署 Skill 文件
|
||
|
||
```bash
|
||
# Windows
|
||
copy skill-package\skills\SKILL.md %USERPROFILE%\.openclaw\skills\playwright-browser\
|
||
|
||
# macOS/Linux
|
||
cp skill-package/skills/SKILL.md ~/.openclaw/skills/playwright-browser-skill/
|
||
```
|
||
|
||
#### 2. 配置 MCP 服务器
|
||
|
||
在 `~/.openclaw/settings/mcp.json` 中添加：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"playwright-browser": {
|
||
"command": "node",
|
||
"args": ["<项目路径>/dist/mcp-server.js"],
|
||
"disabled": false,
|
||
"autoApprove": ["browser_launch", "browser_goto", "browser_close"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 3. 重启 OpenClaw
|
||
|
||
重启 OpenClaw 以加载新的技能。
|
||
|
||
#### 4. 在 OpenClaw 中启用技能
|
||
|
||
重启后，在 OpenClaw 对话中输入：
|
||
|
||
```
|
||
请使用 Playwright Browser Skill 技能来访问互联网和控制浏览器
|
||
```
|
||
|
||
或者直接测试：
|
||
|
||
```
|
||
使用 Playwright Browser Skill 启动浏览器并访问 example.com
|
||
```
|
||
|
||
这样 OpenClaw 就会知道使用这个技能来处理所有浏览器相关的任务。
|
||
|
||
## 📚 工具列表
|
||
|
||
### 浏览器管理（8 个）
|
||
- `browser_launch` - 启动浏览器
|
||
- `browser_close` - 关闭浏览器
|
||
- `browser_new_page` - 创建新页面
|
||
- `browser_switch_page` - 切换页面
|
||
- 更多...
|
||
|
||
### 页面导航（4 个）
|
||
- `browser_goto` - 导航到 URL
|
||
- `browser_go_back` - 返回上一页
|
||
- `browser_go_forward` - 前进
|
||
- `browser_reload` - 刷新页面
|
||
|
||
### 元素交互（12 个）
|
||
- `browser_click` - 点击元素
|
||
- `browser_fill` - 填写表单
|
||
- `browser_type` - 输入文本
|
||
- `browser_select` - 选择下拉框
|
||
- 更多...
|
||
|
||
### 内容提取（11 个）
|
||
- `browser_get_text` - 获取文本
|
||
- `browser_get_html` - 获取 HTML
|
||
- `browser_get_links` - 获取链接
|
||
- 更多...
|
||
|
||
[查看完整工具列表](skill-package/skills/SKILL.md)
|
||
|
||
## 💡 使用示例
|
||
|
||
### 无头模式说明
|
||
|
||
浏览器支持两种运行模式：
|
||
|
||
**有界面模式（headless: false）** - 推荐用于调试和开发
|
||
```javascript
|
||
browser_launch({ "headless": false }) // 显示浏览器窗口
|
||
```
|
||
|
||
**无头模式（headless: true）** - 推荐用于生产环境和自动化
|
||
```javascript
|
||
browser_launch({ "headless": true }) // 后台运行，不显示窗口
|
||
// 或者省略参数，默认为无头模式
|
||
browser_launch()
|
||
```
|
||
|
||
**无头模式优势：**
|
||
- ⚡ 更快的执行速度
|
||
- 💾 更低的资源占用
|
||
- 🔒 适合服务器环境
|
||
- 🤖 适合批量自动化任务
|
||
|
||
### 基础网页访问
|
||
|
||
```javascript
|
||
// 1. 启动浏览器（有界面模式，便于观察）
|
||
browser_launch({ "headless": false })
|
||
|
||
// 2. 访问网页
|
||
browser_goto({ "url": "https://example.com" })
|
||
|
||
// 3. 获取标题
|
||
browser_get_title()
|
||
|
||
// 4. 截图
|
||
browser_screenshot({ "path": "screenshot.png", "fullPage": true })
|
||
|
||
// 5. 关闭浏览器
|
||
browser_close()
|
||
```
|
||
|
||
### 无头模式自动化示例
|
||
|
||
```javascript
|
||
// 无头模式运行，适合自动化任务
|
||
browser_launch({ "headless": true })
|
||
browser_goto({ "url": "https://example.com" })
|
||
browser_get_title()
|
||
browser_screenshot({ "path": "screenshot.png" })
|
||
browser_close()
|
||
```
|
||
|
||
### 表单填写
|
||
|
||
```javascript
|
||
// 使用有界面模式便于调试
|
||
browser_launch({ "headless": false })
|
||
browser_goto({ "url": "https://example.com/login" })
|
||
browser_fill({ "selector": "#username", "value": "user@example.com" })
|
||
browser_fill({ "selector": "#password", "value": "password123" })
|
||
browser_click({ "selector": "button[type='submit']" })
|
||
browser_wait_for_selector({ "selector": ".dashboard" })
|
||
browser_close()
|
||
```
|
||
|
||
### 数据抓取
|
||
|
||
```javascript
|
||
// 数据抓取推荐使用无头模式，速度更快
|
||
browser_launch({ "headless": true })
|
||
browser_goto({ "url": "https://example.com/products" })
|
||
browser_count({ "selector": ".product-item" })
|
||
browser_get_links()
|
||
browser_evaluate({
|
||
"script": "Array.from(document.querySelectorAll('.price')).map(e => e.textContent)"
|
||
})
|
||
browser_close()
|
||
```
|
||
|
||
[查看更多示例](skill-package/skills/SKILL.md#使用示例)
|
||
|
||
## 🧪 测试
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
npm test
|
||
|
||
# 运行基础测试
|
||
npm run test:basic
|
||
|
||
# 运行高级测试
|
||
npm run test:advanced
|
||
|
||
# 运行交互测试
|
||
npm run test:interaction
|
||
|
||
# 运行 MCP 服务器测试
|
||
npm run test:mcp
|
||
```
|
||
|
||
## 📖 文档
|
||
|
||
- [配置指南](CONFIGURATION_GUIDE.md) - 无头模式、浏览器选项等详细配置说明
|
||
- [自动部署指南](AUTO_DEPLOY_README.md) - 跨平台自动部署详细说明 | [English](AUTO_DEPLOY_README_EN.md)
|
||
- [完整工具文档](skill-package/skills/SKILL.md) - 所有 101 个工具的详细说明
|
||
- [Windows 使用指南](WINDOWS_GUIDE.md) - Windows 平台特定说明
|
||
- [Mac/Linux 使用指南](MAC_LINUX_GUIDE.md) - Mac 和 Linux 平台特定说明
|
||
- [快速开始指南](QUICK_START_WINDOWS.md) - 快速上手教程
|
||
- [API 文档](API.md) - API 参考
|
||
- [架构说明](ARCHITECTURE.md) - 项目架构
|
||
|
||
## 🔧 开发
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
playwright-browser-skill/
|
||
├── src/
|
||
│ ├── index.ts # 核心功能实现
|
||
│ ├── mcp-server.ts # MCP 服务器
|
||
│ └── tools-registry.ts # 工具注册表
|
||
├── skill-package/
|
||
│ ├── skills/
|
||
│ │ └── SKILL.md # 技能定义文件
|
||
│ └── settings/
|
||
│ └── mcp.json # MCP 配置示例
|
||
├── test/ # 测试文件
|
||
├── examples/ # 示例代码
|
||
└── docs/ # 文档
|
||
```
|
||
|
||
### 构建
|
||
|
||
```bash
|
||
# 开发模式（监听文件变化）
|
||
npm run dev
|
||
|
||
# 生产构建
|
||
npm run build
|
||
```
|
||
|
||
## 🌍 平台支持
|
||
|
||
| 平台 | 状态 | 说明 |
|
||
|------|------|------|
|
||
| Windows 10/11 | ✅ 完全支持 | 已测试 |
|
||
| macOS | ✅ 完全支持 | 理论支持 |
|
||
| Linux | ✅ 完全支持 | 理论支持 |
|
||
|
||
## 🤝 贡献
|
||
|
||
欢迎贡献！请查看 [贡献指南](CONTRIBUTING.md)。
|
||
|
||
## 📝 更新日志
|
||
|
||
### v2.1.0（2026）
|
||
- 🚀 新增跨平台自动部署脚本
|
||
- 🔍 自动检测 OpenClaw 配置路径
|
||
- 💾 自动备份现有配置
|
||
- 📦 支持自定义安装路径
|
||
- 📚 完整的自动部署文档
|
||
|
||
### v2.1.0（2026）
|
||
- ✨ 新增 13 个高级工具（从 88 个增加到 101 个）
|
||
- 🎯 完善键盘鼠标控制（mouseDown、mouseUp、keyboardInsertText）
|
||
- 🔍 增强选择器功能（getByAltText、getByTitle）
|
||
- ⏱️ 完整时间控制（pauseClock、resumeClock）
|
||
- 📊 代码覆盖率支持（getCoverage、stopCoverage）
|
||
- 🌐 地理位置管理（clearGeolocation、touchscreenTap）
|
||
- ⏳ 高级等待功能（waitForFunction、waitForLoadState）
|
||
- 📈 总体覆盖率从 69% 提升到 88%
|
||
|
||
### v2.0.0（2026）
|
||
- ✨ 新增 88 个完整的浏览器操作工具
|
||
- 📚 完整的中文文档
|
||
- 🪟 Windows 平台完整支持
|
||
- 🎯 智能选择器支持
|
||
- 📸 截图和录制功能
|
||
- 🌍 网络控制和模拟
|
||
|
||
### v1.0.0
|
||
- 🎉 初始版本
|
||
|
||
## 📄 许可证
|
||
|
||
MIT License - 详见 [LICENSE](LICENSE) 文件
|
||
|
||
## 🙏 致谢
|
||
|
||
- [Playwright](https://playwright.dev/) - 强大的浏览器自动化框架
|
||
- [OpenClaw](https://openclaw.ai/) - AI 助手平台
|
||
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP 协议
|
||
|
||
## 📞 支持
|
||
|
||
- 📧 邮箱：91fapiao@gmail.com
|
||
- 🐛 问题反馈：[GitHub Issues](https://github.com/91fapiao-cn/playwright-browser-skill/issues)
|
||
- 💬 讨论：[GitHub Discussions](https://github.com/91fapiao-cn/playwright-browser-skill/discussions)
|
||
|
||
## ⭐ Star 历史
|
||
|
||
如果这个项目对你有帮助，请给它一个 Star！
|
||
|
||
---
|
||
|
||
**用 ❤️ 为 OpenClaw 社区打造** |