# 默认按亮色偏好渲染，全页高清截图
python3 scripts/capture.py https://example.com /tmp/example.png

# 指定暗色偏好
python3 scripts/capture.py https://example.com /tmp/example-dark.png --color-scheme dark

本地开发服务

页面存在入场动画或接口请求时，留出额外渲染时间：

python3 scripts/capture.py http://localhost:5173 /tmp/home.png \
  --width 1440 --height 900 --scale 2 --wait 2000

本地 HTML 文件

file:/// 后必须是绝对路径：

python3 scripts/capture.py "file:///Users/name/project/dist/index.html" \
  /tmp/page.png --wait 500

仅截取首屏

python3 scripts/capture.py https://example.com /tmp/viewport.png \
  --width 390 --height 844 --scale 3 --no-full-page

等待 SPA 网络稳定

python3 scripts/capture.py http://localhost:3000 /tmp/app.png \
  --wait-until networkidle --wait 1000

参数

参数	说明
`url`	网页 URL；可省略，默认 `http://localhost:2020/`
`output`	PNG 输出路径；可省略，默认当前目录 `screenshot.png`
`--scale N`	设备像素比，默认 `4`；值越大图片越清晰、文件越大
`--width N`	视口宽度，默认 `1280`
`--height N`	视口高度，默认 `900`
`--wait MS`	导航完成后的额外等待时间，默认 `5000`；动态页面可调大
`--timeout MS`	导航超时，默认 `45000`
`--wait-until load\	domcontentloaded\	networkidle\	commit`	导航完成条件，默认 `load`
`--color-scheme dark\	light`	模拟系统深浅色偏好，默认 `light`
`--full-page` / `--no-full-page`	是否截取完整页面；默认全页，后者仅截取当前视口
`--visible`	显示 Chromium 窗口，方便排查渲染问题

工作流

确认目标 URL 可访问；本地文件使用绝对 file:/// URL
根据目标画面选定输出路径和视口尺寸
动态内容未稳定时，加 --wait 或改用 --wait-until networkidle
执行截图后，检查 stdout 中的 PNG 路径和图像尺寸

输出约定

输出格式为 PNG
未存在的输出父目录会自动创建
默认全页截图，保留页面完整纵向内容
默认 1280×900 逻辑视口、4x 设备像素比，图片实际像素会随页面和 scale 增大
不修改网页源码，也不上传页面内容

故障排查

现象	处理
`缺少 Playwright`	执行 `python3 -m pip install playwright`
Chromium 找不到	执行 `python3 -m playwright install chromium`
页面超时	检查 URL；适当提高 `--timeout`，或改 `--wait-until domcontentloaded`
截图缺少异步内容	增大 `--wait`；必要时使用 `--visible` 检查页面
图片过大	降低 `--scale`，或加 `--no-full-page`

Agent 注意

用户没有给出路径时，输出到临时目录，避免覆盖项目已有文件
优先截图本地开发服务；本地 HTML 必须转为绝对 file:/// URL
截图完成后反馈绝对 PNG 路径；不要把二进制图片内容粘进回复

npx skills add gitbyeos/open-part-skills --skill html-cut