shot-scraper：CLI --help 即是 Agent Skill · 干货攻略

• 链接: https://x.com/simonw/status/2082828424243212708
• 分类: x-tips
• 来源: X @simonw
• 作者: Jay
• 更新: 2026-08-23
• 仓库: simonw/shot-scraper

这是什么

shot-scraper 是 Simon Willison 开源的一个 CLI 工具，核心功能有三块：

1. 截图 — 对任意 URL 截图，PNG/JPEG 可选，支持区域选择、Retina 分辨率、透明背景
2. 网页抓取 — 用 JavaScript 在页面内执行，提取任意内容
3. 视频录制 — 2026 年 6 月 30 日发布的 1.10 版本新增的 shot-scraper video 子命令，通过 YAML storyboard 驱动 Playwright 生成 WebM/MP4 演示视频

仓库地址：simonw/shot-scraper，基于 Playwright 构建，pip 安装，开源协议 MIT。

为什么值得关注

核心理念：把 --help 变成 SKILL.md

这条攻略的核心不是 shot-scraper 本身的功能，而是 Simon Willison 在 2026 年 6 月 30 日博客中提出的一个工具 ergonomics 设计理念：

「CLI 命令的 --help 输出信息足够详细时，coding agent 无需任何额外提示词就能直接使用这个工具——这相当于把一个 SKILL.md 文件直接打包进了工具本身。」

他的具体做法是：让 GPT-5.5 xhigh（运行在 Codex Desktop 中）读取以下提示词：

Review the changes on this branch.
cd to ~/dev/shot-scraper and run the command "uv run shot-scraper video --help"
Now use that new video command to record a video demo...

也就是说：只需要告诉 agent「运行 uvx shot-scraper video --help」，然后把输出交给 agent，agent 就能理解 video 子命令的全部用法，包括 YAML storyboard 的结构、各种 action 类型（click、fill、pause、screenshot 等）以及 --mp4 转换等选项——不需要额外的手册或 skill 文件。

这个模式的价值

• 极低接入成本：开发者只需要把 --help 写详细，agent 就能用，不需要维护单独的 skill 文档
• 自文档化（Self-documenting）：--help 本身就是工具的使用说明，永远和代码版本同步
• 可验证：agent 可以直接运行 --help 并执行工具，行为和文档一致

Simon Willison 在 showboat and rodney 项目中也用过同样的模式。

核验过程

本攻略基于以下来源编写：

核验结论：

• shot-scraper 1.10 发布时间：2026 年 6 月 30 日（官方 release notes 确认）
• video 子命令支持的动作类型（click、fill、type、press、pause、wait_for、screenshot 等）：来自官方文档，与 release notes 描述一致
• --help 输出详细到可直接驱动 agent 这一主张：来自 Simon Willison 本人博客，AI Weekly 独立报道确认
• 安装方式：pip install shot-scraper + shot-scraper install：README 确认
• Playwright 依赖：README 确认，release notes 提及 playwright-python 1.61.0 解锁了 screencast 视频宽屏支持

上手步骤

安装

# pip 安装
pip install shot-scraper

# 安装 Chromium 浏览器（Playwright 依赖）
shot-scraper install

基础截图

shot-scraper https://example.com/
# 输出：example-com.png

用 --help 让 Agent 直接理解工具

最关键的一步：告诉 agent 执行以下命令，然后直接把输出内容作为上下文：

uvx shot-scraper video --help
# 或者（如果你已全局安装）
shot-scraper video --help

输出的帮助信息会包含：

• storyboard.yml 文件结构（output、url、viewport、cursor 等顶层字段）
• 所有 scene action 类型（click、fill、pause、screenshot、wait_for 等）
• --mp4 转换、-o 输出覆盖等选项

录制一个演示视频（完整示例）

创建 storyboard.yml：

output: demo.webm
url: https://shot-scraper.datasette.io/en/stable/
viewport:
  width: 1280
  height: 720
cursor: true
wait_for: "text=Quick start"
scenes:
  - name: Open installation docs
    do:
      - click: ".sidebar-tree a[href='installation.html']"
      - wait_for: 'h1:has-text("Installation")'
      - screenshot: installation.png
      - pause: 1

运行录制：

shot-scraper video storyboard.yml
# 输出 demo.webm

# 可选：同时输出 MP4（需要 ffmpeg）
shot-scraper video storyboard.yml --mp4
# 输出 demo.webm 和 demo.mp4

在 agent 工作流中集成

# 给 agent 的 prompt 可以极简：
# "Run `uvx shot-scraper video --help` to understand how to use the video command,
#  then create a storyboard.yml that records a demo of [your feature]."

agent 读取 --help 输出后，可以独立完成：编写 storyboard YAML、启动本地开发服务器、录制视频。

坑与适用边界

坑

1. --mp4 依赖 ffmpeg：如果系统未安装 ffmpeg，该选项会报错但 WebM 文件仍会正常生成。
2. Playwright 视频有固定黑边历史问题：shot-scraper 文档提到早期 Playwright 视频有白帧问题，在 playwright-python 1.61.0（2026 年）修复了 800px 固定宽度限制后，才真正可用。
3. server: 块启动延迟：文档建议 server 启动后等待 1 秒再操作，shot-scraper 会在 server 启动后自动等待。
4. sh: / python: 失败会导致整条命令退出：1.10 起，非零 exit code 会中断录制。

适用边界

• 适用场景：为 Web 应用功能录制演示视频、在 CI 中自动截图、用 agent 自动生成 PR 演示
• 不适用场景：复杂交互（需要多标签页协作）、无头模式外的 GUI 交互
• 这个 --help 即 skill 模式的适用边界：仅当工具的 --help 输出足够详细时才成立——需要开发者主动在 --help 中描述 YAML 结构、action 语义、默认值等。

一句话结论

shot-scraper 1.10 的 video 子命令不仅是一个视频录制工具，更重要的是它示范了一种零成本 agent 工具接入规范：把 --help 写详细，agent 就能直接用——让工具本身成为自己的 SKILL.md。