## 项目概述

playwright-cli 是微软推出的一个命令行工具，用于执行常见的 Playwright 浏览器自动化操作。它允许用户录制和生成 Playwright 代码、检查选择器、截图等。该工具专为现代编码代理（如 Claude Code、GitHub Copilot）设计，通过 CLI 和 SKILLS 提供高效、token 节约的浏览器交互方式。

## 核心功能

- **Token 高效**：不强制将页面数据加载到 LLM 上下文中，减少 token 消耗。
- **丰富的命令集**：支持打开浏览器、导航、点击、输入、截图、PDF 导出、标签页管理、存储状态管理、网络请求模拟、DevTools 操作等。
- **会话管理**：支持多个浏览器会话，可持久化配置文件，通过 `-s` 参数或环境变量指定会话。
- **可视化仪表盘**：`playwright-cli show` 命令提供实时会话监控和控制界面。
- **SKILLS 集成**：可安装技能供编码代理使用，提高自动化效率。

## 适用与不适用场景

**适用场景**：
- 编码代理需要执行浏览器自动化任务（如测试、数据抓取）。
- 需要快速生成 Playwright 测试代码或定位器。
- 需要监控和调试浏览器会话。

**不适用场景**：
- 需要持久化、有状态的复杂自动化循环（此时建议使用 Playwright MCP）。
- 需要丰富的页面结构内省和迭代推理的场景（MCP 更合适）。

## 技术架构与依赖

- **语言**：JavaScript
- **运行时**：Node.js 18 或更高版本
- **依赖**：Playwright 库（核心依赖），以及可选的编码代理（如 Claude Code、GitHub Copilot）
- **许可证**：Apache-2.0

## 安装与快速开始

### 安装

```bash
npm install -g @playwright/cli@latest
playwright-cli --help
```

### 安装技能

```bash
playwright-cli install --skills
```

### 无技能操作

直接让代理使用 CLI，它会自行读取 `playwright-cli --help` 获取命令信息。

## 典型使用方法

### 基本操作

```bash
playwright-cli open https://demo.playwright.dev/todomvc/ --headed
playwright-cli type "Buy groceries"
playwright-cli press Enter
playwright-cli screenshot
```

### 会话管理

```bash
playwright-cli -s=example open https://example.com --persistent
playwright-cli list
playwright-cli close-all
```

### 监控仪表盘

```bash
playwright-cli show
```

### 生成定位器

```bash
playwright-cli generate-locator e15
```

## 配置与部署要点

- **配置文件**：支持 JSON 配置文件，默认加载 `.playwright/cli.config.json`，可通过 `--config` 指定。
- **环境变量**：支持多种环境变量配置，如 `PLAYWRIGHT_MCP_BROWSER`、`PLAYWRIGHT_MCP_HEADLESS`、`PLAYWRIGHT_MCP_VIEWPORT_SIZE` 等。
- **持久化**：使用 `--persistent` 保存浏览器配置文件，或通过 `--profile` 指定自定义目录。
- **网络限制**：可通过配置限制允许/阻止的源，增强安全性。

## 限制、风险与许可证

- **限制**：不适用于需要持久状态和复杂推理的自动化场景；默认无头模式，需 `--headed` 显示浏览器。
- **风险**：浏览器自动化可能涉及安全风险，建议限制网络访问和文件访问权限。
- **许可证**：Apache-2.0

## 官方链接

- [GitHub 仓库](https://github.com/microsoft/playwright-cli)
- [Playwright MCP](https://github.com/microsoft/playwright-mcp)
- [Playwright 文档](https://playwright.dev/docs/api/class-browsertype#browser-type-launch-persistent-context)

## 信息来源和分析时间

- 信息来源：GitHub 仓库 README、CONTRIBUTING.md、最新发布信息（v0.1.18，2026-08-06）
- 分析时间：2026-08-06