文档截图总过期？Shotlist 把截图写成代码，一键重新生成

你有没有遇到过这种情况：花了一下午截图、命名、嵌入 README，第二天 UI 改了，截图全废了。没人注意到，直到用户提了个 Issue：「这里的截图和实际界面不一样啊。」

手动截图这件事，做一次容易，但要让截图持续更新，几乎不可能。每个界面调整、每个文案改动，都意味着重新走一遍截图流程——打开浏览器、定位页面、截图、裁剪、命名、替换。

但截图真的需要这样「手工劳动」吗？

问题根源：截图是一次性的

文档截图的痛点在于截图和代码之间没有绑定关系。你截了一张 dashboard 的图，存为 Screen Shot 2026-06-26 at 14.30.22.png，然后在 README 里 引用了它。一个月后 dashboard 页面改了，但那张图还是一个月前的样子。

更糟糕的是，没有人会主动去更新那些过期的截图。开发者忙着写新功能，文档维护者看不到代码变更对截图的影响——直到有用户抱怨。

这正是 Shotlist 想要解决的问题。

Shotlist 是什么

Shotlist 是一个开源的 Python CLI 工具（MIT 协议），它的核心理念是把截图当作代码来管理。你只需在一个 .shotlist.yaml 文件中描述要截什么、怎么启动应用，然后一条 shotlist run 命令就能重新生成全部截图。

项目发布于 2026-06-26，由 Varma Budharaju 开发，目前处于早期阶段但功能完整。

快速上手

安装非常简单：

pip install shotlist
playwright install chromium      # 浏览器截图需要

然后初始化配置文件：

shotlist init

编辑生成的 .shotlist.yaml，定义你的截图清单：

output:
  dir: docs/screenshots

app:
  command: "npm run dev"
  ready: { url: http://localhost:5173, timeout: 30 }

shots:
  - { name: dashboard, kind: web, url: http://localhost:5173/dashboard, full_page: true, alt: "Dashboard" }
  - { name: settings,  kind: web, url: http://localhost:5173/settings, alt: "Settings" }
  - { name: cli-help,  kind: cli, command: "mytool --help", alt: "帮助信息" }

最后运行：

shotlist run

Shotlist 会自动启动你的应用、等待就绪、截图、然后关闭应用——全部自动化。

四种截图类型

Shotlist 支持四种截图类型，覆盖了文档场景中的大部分需求：

• web：用 Playwright 驱动 Chromium 截取网页，支持到完整页面滚动截图
• cli·native（仅 macOS）：截取真实 Terminal.app 窗口，保留你的字体和主题
• cli·rendered（跨平台，CI 可用）：将命令输出绘制为带样式的终端卡片
• session：在持久终端会话中执行多步操作，每步截图一次，适合演示有状态的操作流程

其中最亮眼的是 session 类型——你可以启动一个后台进程、执行一系列命令，每步都截图，最后自动清理。这对于展示 API 调用流程、CLI 工作流或者多步骤操作特别有用。

在 CI 中保持截图不过期

Shotlist 的杀手功能是 shotlist check 命令：

shotlist check         # 重新截图，和已提交的基线比对，不一致就报错
shotlist check --update # 接受当前截图作为新基线
shotlist check --diff DIR  # 生成对比图（基线 / 当前 / 差异）

你可以把 shotlist run && shotlist check 加到 CI 流水线中——当 UI 变更导致截图变化时，CI 自动报错。开发者看到失败后，要么更新截图基线，要么意识到 UI 变更的意外影响。

这样截图就从一个「手工任务」变成了「自动化验证」的一部分，和单元测试一样作为代码质量的保障。

证明报告与流水线产物

每次 shotlist run 还会生成：

• index.html：自包含的截图画廊，可以直接打开作为测试证据报告
• manifest.json：机器可读的运行记录，可作为 CI 产物使用

这意味着不仅在本地能看到截图效果，在 CI 中也能生成可分享的报告。加 --no-report 可以关闭报告生成。

与 Claude 的集成

Shotlist 附带了一个可选的 Claude 集成（在 integrations/claude/ 目录下），包括一个 /shotlist skill——它自动检查你的项目、分析路由和命令，生成 .shotlist.yaml 并运行。

不过需要注意的是：Shotlist 的核心引擎是纯确定性程序，不依赖 AI 来截图。AI 只负责创建配置文件那一步，截图过程快、可重复，CI 中也不需要大模型参与。

实际使用场景

文档截图维护

这是最核心的场景。在你的项目根目录放一个 .shotlist.yaml，描述所有文档需要的截图，然后 CI 每次部署时检查截图是否一致。UI 变更时，CI 会提醒你更新截图，而不是等着被用户发现。

测试证据 / 验收证明

对于需要证明功能正常工作的场景（尤其是远程工作或外包项目），可以用 session 类型录制一个完整的功能流程截图，生成 index.html 作为证据报告。

博客教程截图

写技术博客时，一张清晰的终端截图比文字说明有力得多。cli·rendered 模式可以在任何操作系统上生成统一样式的终端截图，Linux 和 Windows 用户也无需担心。

版本化截图集

运行 shotlist run --version v2 可以把截图输出到版本化子目录中，方便跨版本对比。

与其他工具的对比

Shotlist 的独特定位在于把网页截图、终端截图、CLI 会话截图的全部能力整合到一个配置文件中，而且不需要任何云服务。每个 UI 改动的代价从「手动截 10 张图」降为「运行 shotlist check --update」。

值得注意的设计细节

• 就绪探测：在截图前用 HTTP/TCP/日志行等方式确认应用已启动，不会截到半加载的页面
• 进程组清理：应用在独立进程组中运行，即使崩溃或 Ctrl-C 也不会留下孤儿进程
• README 自动拼接：output.readme 配置可以将 标签直接拼接到 README 文件中，配置文件和截图集代码仓库一起维护
• 自举验证：Shotlist 自己的 README 截图就是用 Shotlist 生成的，实际验证了工具本身在 CI 中的可靠性

结语

截图是技术文档中不可或缺的一部分，但传统的手动截图方式在持续迭代的项目中几乎是不可维护的。Shotlist 提供了一个优雅的解决方案——把截图变成代码，让 CI 来保证它们不会过期。

对于开源项目维护者、技术文档作者和重视产品质量的团队来说，把 Shotlist 纳入文档工作流是一个低成本高回报的改进。它不能替代好看的 UI 设计，但能确保 UI 的视觉表现永远反映在文档中。

相关链接：

• Shotlist GitHub 仓库
• Shotlist 使用示例与菜谱
• Shotlist 管道集成说明
• Shotlist 设计文档