chrome-devtools

Chrome DevTools Agent 技能

通过可执行的 Puppeteer 脚本进行浏览器自动化。所有脚本都会输出 JSON，便于解析。

快速开始

重要：运行脚本前务必检查 pwd。

安装

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

在 Linux/WSL 上，Chrome 需要系统库。请先安装：

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

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

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

步骤 2：安装 Node 依赖

npm install  # Installs puppeteer, debug, yargs

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

ImageMagick 可自动压缩截图，使文件大小保持在 5MB 以下：

macOS：

brew install imagemagick

Ubuntu/Debian/WSL：

sudo apt-get install imagemagick

Windows：

# Option 1: Chocolatey (recommended)
choco install imagemagick

# Option 2: Scoop
scoop install imagemagick

# Option 3: WinGet
winget install ImageMagick.ImageMagick

# Option 4: Manual download from https://imagemagick.org/script/download.php#windows

Fedora/RHEL/CentOS：

sudo dnf install ImageMagick
# or for older versions:
sudo yum install ImageMagick

Arch/Manjaro：

sudo pacman -S imagemagick

验证安装：

# Linux/macOS:
magick -version  # or: convert -version

# Windows:
magick -version
# or: magick.exe -version

未安装 ImageMagick 时，超过 5MB 的截图不会被压缩（可能无法在 Gemini/Claude 中加载）。

测试

node navigate.js --url https://example.com
# Output: {"success": true, "url": "https://example.com", "title": "Example Domain"}

可用脚本

所有脚本均位于 .claude/skills/chrome-devtools/scripts/

重要：运行脚本前务必检查 pwd。

脚本用法

• ./scripts/README.md

核心自动化

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

分析与监控

• snapshot.js - 提取带有元数据的交互元素
• console.js - 监控控制台消息/错误
• network.js - 跟踪 HTTP 请求/响应
• performance.js - 测量 Core Web Vitals 并记录跟踪信息

使用模式

单条命令

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

重要：始终将截图保存到 ./docs/screenshots 目录。

自动图像压缩

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

# Default: auto-compress if >5MB
node screenshot.js --url https://example.com --output page.png

# Custom size threshold (e.g., 3MB)
node screenshot.js --url https://example.com --output page.png --max-size 3

# Disable compression
node screenshot.js --url https://example.com --output page.png --no-compress

压缩行为：

• PNG：缩小至 90% + 质量 85（若仍过大，则缩小至 75% + 质量 70）
• JPEG：质量 80 + 渐进式编码（若仍过大，则使用质量 60）
• 其他格式：转换为 JPEG 并压缩
• 需要安装 ImageMagick（参见 imagemagick 技能）

输出包含压缩信息：

{
  "success": true,
  "output": "/path/to/page.png",
  "compressed": true,
  "originalSize": 8388608,
  "size": 3145728,
  "compressionRatio": "62.50%",
  "url": "https://example.com"
}

链式命令（复用浏览器）

# Keep browser open with --close false
node navigate.js --url https://example.com/login --close false
node fill.js --selector "#email" --value "[email protected]" --close false
node fill.js --selector "#password" --value "secret" --close false
node click.js --selector "button[type=submit]"

解析 JSON 输出

# Extract specific fields with jq
node performance.js --url https://example.com | jq '.vitals.LCP'

# Save to file
node network.js --url https://example.com --output /tmp/requests.json

执行协议

工作目录验证

执行任何脚本之前：

1. 使用 pwd 检查当前工作目录
2. 确认位于 .claude/skills/chrome-devtools/scripts/ 目录
3. 如果目录不正确，使用 cd 切换到正确位置
4. 所有输出文件均使用绝对路径

示例：

pwd  # Should show: .../chrome-devtools/scripts
# If wrong:
cd .claude/skills/chrome-devtools/scripts

输出验证

截图/捕获操作完成后：

1. 使用 ls -lh <output-path> 验证文件已创建
2. 使用 Read 工具读取截图以确认内容
3. 检查 JSON 输出中的 success:true
4. 报告文件大小和压缩状态

示例：

node screenshot.js --url https://example.com --output ./docs/screenshots/page.png
ls -lh ./docs/screenshots/page.png  # Verify file exists
# Then use Read tool to visually inspect

5. 将工作目录切回项目根目录。

错误恢复

如果脚本失败：

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

示例：

# CSS selector fails
node click.js --url https://example.com --selector ".btn-submit"
# Error: waiting for selector ".btn-submit" failed

# Discover correct selector
node snapshot.js --url https://example.com | jq '.elements[] | select(.tagName=="BUTTON")'

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

常见错误

❌ 工作目录错误 → 输出文件会保存到错误位置 ❌ 跳过输出验证 → 可能出现未提示的失败 ❌ 未经测试就使用复杂 CSS 选择器 → 选择器错误 ❌ 未检查元素是否可见 → 超时错误

✅ 运行脚本前务必验证 pwd ✅ 截图后务必验证输出 ✅ 使用 snapshot.js 查找选择器 ✅ 先用简单命令测试选择器

常见工作流

网页抓取

node evaluate.js --url https://example.com --script "
  Array.from(document.querySelectorAll('.item')).map(el => ({
    title: el.querySelector('h2')?.textContent,
    link: el.querySelector('a')?.href
  }))
" | jq '.result'

性能测试

PERF=$(node performance.js --url https://example.com)
LCP=$(echo $PERF | jq '.vitals.LCP')
if (( $(echo "$LCP < 2500" | bc -l) )); then
  echo "✓ LCP passed: ${LCP}ms"
else
  echo "✗ LCP failed: ${LCP}ms"
fi

表单自动化

node fill.js --url https://example.com --selector "#search" --value "query" --close false
node click.js --selector "button[type=submit]"

错误监控

node console.js --url https://example.com --types error,warn --duration 5000 | jq '.messageCount'

脚本选项

所有脚本均支持：

• --headless false - 显示浏览器窗口
• --close false - 保持浏览器打开，以便串联使用
• --timeout 30000 - 设置超时时间（毫秒）
• --wait-until networkidle2 - 等待策略

完整选项请参见 ./scripts/README.md。

输出格式

所有脚本都会将 JSON 输出到标准输出：

{
  "success": true,
  "url": "https://example.com",
  ... // script-specific data
}

错误会输出到标准错误：

{
  "success": false,
  "error": "Error message"
}

查找元素

使用 snapshot.js 查找选择器：

node snapshot.js --url https://example.com | jq '.elements[] | {tagName, text, selector}'

故障排除

常见错误

“Cannot find package 'puppeteer'”

• 在 scripts 目录中运行：npm install

“error while loading shared libraries: libnss3.so”（Linux/WSL）

• 缺少系统依赖项
• 解决方法：在 scripts 目录中运行 ./install-deps.sh
• 手动安装：sudo apt-get install -y libnss3 libnspr4 libasound2t64 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1

“Failed to launch the browser process”

• 检查是否已安装系统依赖项（Linux/WSL）
• 确认 Chrome 已下载：ls ~/.cache/puppeteer
• 尝试运行：npm rebuild，然后运行 npm install

找不到 Chrome

• Puppeteer 会在 npm install 期间自动下载 Chrome
• 如果失败，请手动触发：npx puppeteer browsers install chrome

脚本问题

找不到元素

• 先获取快照以查找正确的选择器：node snapshot.js --url <url>

脚本挂起

• 增加超时时间：--timeout 60000
• 更改等待策略：--wait-until load 或 --wait-until domcontentloaded

截图空白

• 等待页面加载：--wait-until networkidle2
• 增加超时时间：--timeout 30000

脚本权限被拒绝

• 设置为可执行：chmod +x *.sh

截图过大（>5MB）

• 安装 ImageMagick 以自动压缩
• 手动设置更低的阈值：--max-size 3
• 使用 JPEG 格式代替 PNG：--format jpeg --quality 80
• 截取特定元素而非整个页面：--selector .main-content

压缩未生效

• 确认已安装 ImageMagick：magick -version 或 convert -version
• 检查输出 JSON 中的文件是否确实已压缩："compressed": true
• 对于非常大的页面，使用 --selector 仅截取所需区域

参考文档

详细指南见 ./references/：

• CDP 域参考 - 47 个 Chrome DevTools Protocol 域
• Puppeteer 快速参考 - 完整的 Puppeteer API 用法模式
• 性能分析指南 - Core Web Vitals 优化

高级用法

自定义脚本

使用共享库创建自定义脚本：

import { getBrowser, getPage, closeBrowser, outputJSON } from './lib/browser.js';
// Your automation logic

直接访问 CDP

const client = await page.createCDPSession();
await client.send('Emulation.setCPUThrottlingRate', { rate: 4 });

有关高级用法模式和完整 API 覆盖范围，请参见参考文档。

外部资源

• Puppeteer 文档
• Chrome DevTools Protocol
• 脚本 README