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 依赖

# 首选：使用 bun（更快）
bun install  # 安装 puppeteer、debug、yargs

# 替代：使用 npm
npm install

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

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

macOS：

brew install imagemagick

Ubuntu/Debian/WSL：

sudo apt-get install imagemagick

验证：

magick -version  # 或：convert -version

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

测试

bun 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
bun screenshot.js --url https://example.com --output ./docs/screenshots/page.png

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

自动图像压缩

如果截图超过 5MB，将自动压缩以确保与 Gemini API 和 Claude Code（有 5MB 限制）兼容。内部使用 ImageMagick：

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

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

# 禁用压缩
bun 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 保持浏览器打开
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]"

解析 JSON 输出

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

# 保存到文件
bun 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 <output-path> 验证文件已创建
使用 Read 工具读取截图以确认内容
检查 JSON 输出中的 success:true
报告文件大小和压缩状态

示例：

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

错误恢复

如果脚本失败：

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

示例：

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

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

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

常用选项

所有脚本支持：

--headless false - 显示浏览器窗口（默认：true）
--close false - 脚本后保持浏览器打开
--timeout 30000 - 超时时间（毫秒）（默认：30000）
--help - 显示脚本特定帮助

故障排除

浏览器启动失败（Linux）：

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

大截图：

启用 ImageMagick 进行自动压缩
使用 --max-size 设置自定义阈值
或捕获特定元素而非全页

元素未找到：

首先使用 snapshot.js 发现选择器
检查元素是否动态加载（等待更长时间）
如果 CSS 失败，尝试 XPath

脚本未找到：

验证是否在正确目录
检查脚本名称拼写
使用绝对路径：bun /path/to/scripts/navigate.js