# Playwright浏览器自动化技能

`浏览器自动化` `Playwright` `MCP` `OpenClaw` `Node.js`

# OpenClaw 的 Playwright 浏览器技能

一个功能强大的浏览器自动化技能，基于 Playwright 构建，通过 MCP 协议为 OpenClaw 提供 101 个完整的浏览器操作能力。

[![Windows](https://img.shields.io/badge/Windows-支持-blue.svg)](WINDOWS_GUIDE.md)
[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
[![Playwright](https://img.shields.io/badge/Playwright-1.40%2B-orange.svg)](https://playwright.dev/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](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 社区打造**