用途：对本地开发服务器或静态 HTML 文件截图，底层为 shot-scraper（Playwright 封装）。涉及多张图片时优先使用仓库内提交的 shots.yml，便于随 UI 变化重新生成。
安装：pipx install shot-scraper（需先装 pipx）；再执行 shot-scraper install 下载 Chromium；用 shot-scraper --version 验证。若提示 command not found，运行 pipx ensurepath 后重开终端。
主要能力：shot-scraper URL 单张截图；shot-scraper multi shots.yml 按 YAML 批量；shot-scraper pdf URL 导出 PDF；shot-scraper auth URL auth.json 保存登录会话；shot-scraper accessibility URL 导出无障碍树 JSON。常用参数：-o 输出文件名（- 为 stdout）；-w/-h 视口宽高（省略 -h 为整页）；-s/--selector-all 截取首个/全部匹配元素；-p 选择器内边距；--retina 2 倍像素比；--quality N 存为 JPEG；--wait N 或 --wait-for "expr" 等待；-j "js" 截图前执行 JS；-a auth.json 复用登录；-i/--devtools 交互调试。
用法示例：shot-scraper http://localhost:3000 -o homepage.png；shot-scraper index.html -o preview.png；shot-scraper http://localhost:3000 -w 1200 -h 630 -o og.png；shot-scraper http://localhost:3000 -s ".hero" -p 20 --retina -o hero@2x.png；shot-scraper http://localhost:3000 --wait-for "document.querySelector('.loaded')" -o app.png。未指定尺寸时可用：README 主图 1280×800；文档截图 1200 宽、省略高度；社交/OG 图 1200×630；移动/平板 375/768 宽、812/1024 高。
限制与注意：shot-scraper install 是独立第二步，仅 pipx install 不会带浏览器引擎；--quality 会强制输出 JPEG，即使扩展名为 .png；--retina 使输出像素翻倍，会破坏 1200×630 等固定尺寸目标；shots.yml 中单张的 auth: 键会被静默忽略，应整批传 -a auth.json；省略 -h 时高度随内容变化，前后对比图应显式设 -h；YAML 的 server: 进程覆盖整批运行并在结束时关闭；整页截图会掩盖小缺陷，建议用 -s 加 -p 截取区域；截图不适合做像素级回归比对，回归门禁宜用 Percy、Chromatic 或 Playwright 的 toHaveScreenshot。常见故障：连接被拒说明端口无服务；空白或加载动画说明 SPA 未水合，优先用 --wait-for；选择器无匹配可用 -i 排查；重页面超时可提高 --timeout；CI 失败常因未执行 shot-scraper install。