name: chrome-devtools description: 使用Puppeteer CLI脚本进行浏览器自动化、调试和性能分析。用于自动化浏览器、截图、分析性能、监控网络流量、网络爬虫、表单自动化和JavaScript调试。 license: Apache-2.0

Chrome DevTools 代理技能

通过可执行的Puppeteer脚本进行浏览器自动化。所有脚本输出JSON以便轻松解析。

快速开始

重要：运行脚本前始终检查pwd。

安装

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

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

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

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

macOS/Windows：跳过此步骤（依赖项与Chrome捆绑）

步骤2：安装Node依赖

npm install  # 安装puppeteer、debug、yargs

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

ImageMagick启用自动截图压缩，以保持文件小于5MB：

macOS：

brew install imagemagick

Ubuntu/Debian/WSL：

sudo apt-get install imagemagick

验证：

magick -version  # 或：convert -version

没有ImageMagick，截图>5MB将不会被压缩（可能在Gemini/Claude中加载失败）。

测试

node navigate.js --url https://example.com
# 输出：{"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 - 测量核心Web指标 + 记录跟踪

使用模式

单命令

pwd  # 应显示当前工作目录
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：

# 默认：如果>5MB则自动压缩
node screenshot.js --url https://example.com --output page.png

# 自定义大小阈值（例如3MB）
node screenshot.js --url https://example.com --output page.png --max-size 3

# 禁用压缩
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"
}

链式命令（重用浏览器）

# 使用--close false保持浏览器打开
node navigate.js --url https://example.com/login --close false
node fill.js --selector "#email" --value "user@example.com" --close false
node fill.js --selector "#password" --value "secret" --close false
node click.js --selector "button[type=submit]"

解析JSON输出

# 使用jq提取特定字段
node performance.js --url https://example.com | jq '.vitals.LCP'

# 保存到文件
node network.js --url https://example.com --output /tmp/requests.json

执行协议

工作目录验证

执行任何脚本前：

用pwd检查当前工作目录
验证在.claude/skills/chrome-devtools/scripts/目录中
如果目录错误，cd到正确位置
对所有输出文件使用绝对路径

示例：

pwd  # 应显示：.../chrome-devtools/scripts
# 如果错误：
cd .claude/skills/chrome-devtools/scripts

输出验证

截图/捕获操作后：

用ls -lh <输出路径>验证文件创建
使用Read工具读取截图以确认内容
检查JSON输出中success:true
报告文件大小和压缩状态

示例：

node screenshot.js --url https://example.com --output ./docs/screenshots/page.png
ls -lh ./docs/screenshots/page.png  # 验证文件存在
# 然后使用Read工具视觉检查

错误恢复

如果脚本失败：

检查错误消息以查找选择器问题
使用snapshot.js发现正确的选择器
如果CSS选择器失败，尝试XPath选择器
验证元素是否可见和可交互

示例：

# CSS选择器失败
node click.js --url https://example.com --selector ".btn-submit"
# 错误：等待选择器".btn-submit"失败

# 发现正确的选择器
node snapshot.js --url https://example.com | jq '.elements[] | select(.tagName=="BUTTON")'

# 尝试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通过：${LCP}ms"
else
  echo "✗ LCP失败：${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到stdout：

{
  "success": true,
  "url": "https://example.com",
  ... // 脚本特定数据
}

错误输出到stderr：

{
  "success": false,
  "error": "错误消息"
}

查找元素

使用snapshot.js发现选择器：

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

故障排除

常见错误

“找不到包’puppeteer’”

运行：在脚本目录中运行npm install

“加载共享库libnss3.so时出错”（Linux/WSL）

缺少系统依赖
修复：在脚本目录中运行./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

“启动浏览器进程失败”

检查系统依赖是否安装（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协议域
Puppeteer快速参考 - 完整的Puppeteer API模式
性能分析指南 - 核心Web指标优化

高级用法

自定义脚本

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

import { getBrowser, getPage, closeBrowser, outputJSON } from './lib/browser.js';
// 您的自动化逻辑

直接CDP访问

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

参见参考文档获取高级模式和完整API覆盖。

ChromeDevTools代理技能Skill chrome-devtools

name: chrome-devtools description: 使用Puppeteer CLI脚本进行浏览器自动化、调试和性能分析。用于自动化浏览器、截图、分析性能、监控网络流量、网络爬虫、表单自动化和JavaScript调试。 license: Apache-2.0