chrome-devtools

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Chrome DevTools Agent Skill

Browser automation via executable Puppeteer scripts. All scripts output JSON for easy parsing.

通过可执行的Puppeteer脚本实现浏览器自动化。所有脚本均输出JSON格式，便于解析。

Quick Start

快速开始

CRITICAL: Always check

pwd

before running scripts.

重要提示：运行脚本前务必检查

pwd

。

Installation

安装

Step 1: Install System Dependencies (Linux/WSL only)

步骤1：安装系统依赖（仅Linux/WSL）

On Linux/WSL, Chrome requires system libraries. Install them first:

bash

pwd  # Should show current working directory
cd .claude/skills/chrome-devtools/scripts
./install-deps.sh  # Auto-detects OS and installs required libs

Supports: Ubuntu, Debian, Fedora, RHEL, CentOS, Arch, Manjaro

macOS/Windows: Skip this step (dependencies bundled with Chrome)

在Linux/WSL系统中，Chrome需要依赖系统库。请先安装这些库：

bash

pwd  # 显示当前工作目录
cd .claude/skills/chrome-devtools/scripts
./install-deps.sh  # 自动检测操作系统并安装所需库

支持：Ubuntu、Debian、Fedora、RHEL、CentOS、Arch、Manjaro

macOS/Windows用户：跳过此步骤（Chrome已捆绑依赖）

Step 2: Install Node Dependencies

步骤2：安装Node依赖

bash

undefined

bash

undefined

Preferred: Using bun (faster)

推荐方式：使用bun（速度更快）

bun install # Installs puppeteer, debug, yargs

bun install # 安装puppeteer、debug、yargs

Alternative: Using npm

替代方式：使用npm

npm install

undefined

npm install

undefined

Step 3: Install ImageMagick (Optional, Recommended)

步骤3：安装ImageMagick（可选，推荐）

ImageMagick enables automatic screenshot compression to keep files under 5MB:

macOS:

bash

brew install imagemagick

Ubuntu/Debian/WSL:

bash

sudo apt-get install imagemagick

Verify:

bash

magick -version  # or: convert -version

Without ImageMagick, screenshots >5MB will not be compressed (may fail to load in Gemini/Claude).

ImageMagick可自动压缩截图，确保文件大小不超过5MB：

macOS：

bash

brew install imagemagick

Ubuntu/Debian/WSL：

bash

sudo apt-get install imagemagick

验证：

bash

magick -version  # 或：convert -version

如果未安装ImageMagick，大于5MB的截图将不会被压缩（可能无法在Gemini/Claude中加载）。

Test

测试

bash

bun navigate.js --url https://example.com

bash

bun navigate.js --url https://example.com

Output: {"success": true, "url": "https://example.com", "title": "Example Domain"}

输出：{"success": true, "url": "https://example.com", "title": "Example Domain"}

undefined

undefined

Available Scripts

可用脚本

All scripts are in

.claude/skills/chrome-devtools/scripts/

CRITICAL: Always check

pwd

before running scripts.

所有脚本位于

.claude/skills/chrome-devtools/scripts/

目录下

重要提示：运行脚本前务必检查

pwd

。

Script Usage

脚本使用说明

```
./scripts/README.md
```

```
./scripts/README.md
```

Core Automation

核心自动化脚本

```
navigate.js
```
- Navigate to URLs
```
screenshot.js
```
- Capture screenshots (full page or element)
```
click.js
```
- Click elements
```
fill.js
```
- Fill form fields
```
evaluate.js
```
- Execute JavaScript in page context

```
navigate.js
```
- 导航至指定URL
```
screenshot.js
```
- 捕获截图（整页或指定元素）
```
click.js
```
- 点击元素
```
fill.js
```
- 填充表单字段
```
evaluate.js
```
- 在页面上下文执行JavaScript

Analysis & Monitoring

分析与监控脚本

```
snapshot.js
```
- Extract interactive elements with metadata
```
console.js
```
- Monitor console messages/errors
```
network.js
```
- Track HTTP requests/responses
```
performance.js
```
- Measure Core Web Vitals + record traces

```
snapshot.js
```
- 提取带元数据的交互元素
```
console.js
```
- 监控控制台消息/错误
```
network.js
```
- 追踪HTTP请求/响应
```
performance.js
```
- 测量核心Web指标并记录追踪数据

Usage Patterns

使用模式

Single Command

单命令执行

bash

pwd  # Should show current working directory
cd .claude/skills/chrome-devtools/scripts
bun screenshot.js --url https://example.com --output ./docs/screenshots/page.png

Important: Always save screenshots to

./docs/screenshots

directory.

bash

pwd  # 应显示当前工作目录
cd .claude/skills/chrome-devtools/scripts
bun screenshot.js --url https://example.com --output ./docs/screenshots/page.png

注意：请始终将截图保存至

./docs/screenshots

目录。

Automatic Image Compression

自动图片压缩

Screenshots are automatically compressed if they exceed 5MB to ensure compatibility with Gemini API and Claude Code (which have 5MB limits). This uses ImageMagick internally:

bash

undefined

如果截图超过5MB，系统会自动压缩以确保兼容Gemini API和Claude Code（二者均有5MB大小限制）。此功能内部使用ImageMagick：

bash

undefined

Default: auto-compress if >5MB

默认：超过5MB时自动压缩

bun screenshot.js --url https://example.com --output page.png

Custom size threshold (e.g., 3MB)

自定义大小阈值（例如3MB）

bun screenshot.js --url https://example.com --output page.png --max-size 3

Disable compression

禁用压缩

bun screenshot.js --url https://example.com --output page.png --no-compress


**Compression behavior:**
- PNG: Resizes to 90% + quality 85 (or 75% + quality 70 if still too large)
- JPEG: Quality 80 + progressive encoding (or quality 60 if still too large)
- Other formats: Converted to JPEG with compression
- Requires ImageMagick installed (see imagemagick skill)

**Output includes compression info:**
```json
{
  "success": true,
  "output": "/path/to/page.png",
  "compressed": true,
  "originalSize": 8388608,
  "size": 3145728,
  "compressionRatio": "62.50%",
  "url": "https://example.com"
}

bun screenshot.js --url https://example.com --output page.png --no-compress


**压缩规则：**
- PNG格式：先调整至原大小的90%并设置质量为85（如果仍过大则调整至75%并设置质量为70）
- JPEG格式：设置质量为80并启用渐进式编码（如果仍过大则设置质量为60）
- 其他格式：转换为JPEG格式并进行压缩
- 需要提前安装ImageMagick（详见ImageMagick技能文档）

**输出包含压缩信息：**
```json
{
  "success": true,
  "output": "/path/to/page.png",
  "compressed": true,
  "originalSize": 8388608,
  "size": 3145728,
  "compressionRatio": "62.50%",
  "url": "https://example.com"
}

Chain Commands (reuse browser)

链式命令（复用浏览器）

bash

undefined

bash

undefined

Keep browser open with --close false

保持浏览器打开：--close false

bun navigate.js --url https://example.com/login --close false bun fill.js --selector "#email" --value "user@example.com" --close false bun fill.js --selector "#password" --value "secret" --close false bun click.js --selector "button[type=submit]"

undefined

undefined

Parse JSON Output

解析JSON输出

bash

undefined

bash

undefined

Extract specific fields with jq

使用jq提取特定字段

bun performance.js --url https://example.com | jq '.vitals.LCP'

Save to file

保存至文件

bun network.js --url https://example.com --output /tmp/requests.json

undefined

bun network.js --url https://example.com --output /tmp/requests.json

undefined

Execution Protocol

执行规范

Working Directory Verification

工作目录验证

BEFORE executing any script:

Check current working directory with
```
pwd
```
Verify in
```
.claude/skills/chrome-devtools/scripts/
```
directory
If wrong directory,
```
cd
```
to correct location
Use absolute paths for all output files

Example:

bash

pwd  # Should show: .../chrome-devtools/scripts

执行任何脚本之前：

使用
```
pwd
```
检查当前工作目录
确认位于
```
.claude/skills/chrome-devtools/scripts/
```
目录下
如果目录错误，使用
```
cd
```
切换至正确位置
所有输出文件使用绝对路径

示例：

bash

pwd  # 应显示：.../chrome-devtools/scripts

If wrong:

如果目录错误：

cd .claude/skills/chrome-devtools/scripts

undefined

cd .claude/skills/chrome-devtools/scripts

undefined

Output Validation

输出验证

AFTER screenshot/capture operations:

Verify file created with
```
ls -lh <output-path>
```
Read screenshot using Read tool to confirm content
Check JSON output for success:true
Report file size and compression status

Example:

bash

bun screenshot.js --url https://example.com --output ./docs/screenshots/page.png
ls -lh ./docs/screenshots/page.png  # Verify file exists

截图/捕获操作完成后：

使用
```
ls -lh <output-path>
```
验证文件已创建
使用读取工具查看截图内容以确认有效性
检查JSON输出中的
```
success:true
```
字段
报告文件大小和压缩状态

示例：

bash

bun screenshot.js --url https://example.com --output ./docs/screenshots/page.png
ls -lh ./docs/screenshots/page.png  # 验证文件存在

Then use Read tool to visually inspect

然后使用读取工具进行视觉检查


5. Restart working directory to the project root.


5. 将工作目录重置为项目根目录。

Error Recovery

错误恢复

If script fails:

Check error message for selector issues
Use snapshot.js to discover correct selectors
Try XPath selector if CSS selector fails
Verify element is visible and interactive

Example:

bash

undefined

如果脚本执行失败：

检查错误信息，确认是否为选择器问题
使用
```
snapshot.js
```
查找正确的选择器
如果CSS选择器失败，尝试使用XPath选择器
验证元素是否可见且可交互

示例：

bash

undefined

CSS selector fails

CSS选择器执行失败

bun click.js --url https://example.com --selector ".btn-submit"

Error: waiting for selector ".btn-submit" failed

错误信息：waiting for selector ".btn-submit" failed

Discover correct selector

查找正确的选择器

bun snapshot.js --url https://example.com | jq '.elements[] | select(.tagName=="BUTTON")'

Try XPath

尝试XPath选择器

bun click.js --url https://example.com --selector "//button[contains(text(),'Submit')]"

undefined

bun click.js --url https://example.com --selector "//button[contains(text(),'Submit')]"

undefined

Common Options

通用选项

All scripts support:

```
--headless false
```
- Show browser window (default: true)
```
--close false
```
- Keep browser open after script
```
--timeout 30000
```
- Timeout in milliseconds (default: 30000)
```
--help
```
- Show script-specific help

所有脚本均支持：

```
--headless false
```
- 显示浏览器窗口（默认值：true）
```
--close false
```
- 脚本执行后保持浏览器打开
```
--timeout 30000
```
- 超时时间（毫秒，默认值：30000）
```
--help
```
- 显示脚本专属帮助信息

Troubleshooting

故障排查

Browser fails to launch (Linux):

bash

./install-deps.sh  # Install missing system libraries

Large screenshots:

Enable ImageMagick for automatic compression
Use
```
--max-size
```
to set custom threshold
Or capture specific element instead of full page

Element not found:

Use
```
snapshot.js
```
first to discover selectors
Check if element is dynamically loaded (wait longer)
Try XPath if CSS fails

Script not found:

Verify you're in the correct directory
Check script name spelling
Use absolute path:
```
bun /path/to/scripts/navigate.js
```

浏览器启动失败（Linux系统）：

bash

./install-deps.sh  # 安装缺失的系统库

大尺寸截图问题：

安装ImageMagick以启用自动压缩
使用
```
--max-size
```
设置自定义大小阈值
或者捕获指定元素而非整页截图

元素未找到：

先使用
```
snapshot.js
```
查找正确的选择器
检查元素是否为动态加载（可延长超时时间）
如果CSS选择器失败，尝试使用XPath选择器

脚本未找到：

确认当前处于正确的目录
检查脚本名称拼写
使用绝对路径：
```
bun /path/to/scripts/navigate.js
```