Shotlist 实战指南：用代码管理 AI Agent 的文档截图

背景

使用 AI 编码工具时，一个被反复提到的痛点是文档截图维护。每次 UI 变更，你都得重新截图、拖拽文件、修改 README——而下次更新时一切又过时了。

Shotlist 是一个 Python CLI 工具，它用一份 shotlist.yaml 配置描述「截什么、怎么截」，然后通过一条命令自动生成所有截图。它不只是一个截图工具——它为 AI Agent 提供了一种文档证明（proof）机制：当 Claude Code、Codex 或 Cursor 修改了 UI 或 CLI 行为后，它能自动截图并验证结果。

项目 GitHub：varmabudharaju/shotlist（MIT 协议）

安装与环境

pip install shotlist             # 安装 shotlist 命令
playwright install chromium      # 一次性下载浏览器

系统要求：Python 3.11+，macOS（原生终端截图）或任何 OS（Web/渲染截图均可）。

安装后验证：

shotlist --help                  # 查看所有可用命令

实战场景 1：为 README 生成 Web 页面截图

最常用的场景是给 README 中的 Web 页面保留下截图。创建一个 .shotlist.yaml：

output:
  dir: docs/screenshots
  readme: README.md              # 自动将  注入 README

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, full_page: false, alt: "设置页面" }

执行：

shotlist run

Shotlist 会自动启动你的开发服务器，等待端口就绪，截图，然后关闭服务器。截图会保存在 docs/screenshots/ 目录下，并且 README.md 中会自动插入对应的 标签。

如果你只需要重新截某个页面，可以用 --only 参数：

shotlist run --only dashboard

实战场景 2：CLI 截图与多步骤会话

对于 CLI 工具，Shotlist 支持原生终端截图（macOS 上的真实 Terminal.app 窗口）和渲染截图（跨平台的 PTY→HTML→PNG 管线）。

output:
  dir: docs/screenshots
  readme: README.md

shots:
  - name: cli-help
    kind: cli
    command: "mytool --help"
    alt: "完整帮助信息"

渲染模式（跨平台、CI 可用）会自动绘制一个终端样式的卡片。如果你需要截图一个多步骤操作流程——例如启动服务、执行命令、查看结果——使用 session 模式：

shots:
  - name: dev-session
    kind: session
    steps:
      - { command: "cd myapp && npm run build", wait_ms: 5000 }
      - { command: "ls -la dist/", wait_ms: 2000 }

Session 模式的好处是状态保持——每个步骤的 shell 状态（当前目录、环境变量）会延续到下一步，就像在同一个终端里操作一样。

实战场景 3：与 Claude Code 集成

Shotlist 自带了一个 Claude 集成（integrations/claude/ 目录），包含两部分：

1. /shotlist Skill：Claude Code 可以直接调用这个 skill，它会自动检测你的项目结构、检查路由和帮助输出，然后为你生成 .shotlist.yaml 并执行它。

2. 自动快照钩子：当开发服务器启动时，自动拍摄一张「诚实快照」——不保证完美，但可以作为一份实时记录。

与 AI Agent 配合的核心价值在于：AI Agent 修改代码后，Shotlist 能自动证明修改没有破坏 UI。开发者可以在 CI 流程中配置：

name: shotlist-check
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: pip install shotlist && playwright install chromium
      - run: shotlist run
      - run: shotlist check  # 与已提交的基线对比

shotlist check 会对比当前截图与已提交的基线。如果有非预期变化，它会输出差异报告并失败构建。确认是正常变更后，可以用 shotlist check --update 接受新基线。

四种截图类型对比

最佳实践

1. 一人配置，团队复用：.shotlist.yaml 提交到仓库，所有人用同一份配置产生一致的截图
2. 与 AI Agent 配合最有效：让 Claude/Cursor/Codex 在修改 UI 后自动执行 shotlist run 和 shotlist check
3. CI 中的 shotlist check 优先：在 PR 流程中加入截图基线检查，比人工 review UI 变更更可靠
4. --no-report 跳过报告生成：如果在 CI 中只需要 PNG 文件，用 shotlist run --no-report 加速
5. 版本化截图目录：使用 --version v2 为不同发布版本的截图创建独立子目录，便于回溯

总结

Shotlist 将文档截图从「一次性的手工操作」转变为「可重复、可审计的自动化流程」。对于 AI Agent 工作流来说，它填补了一个关键空白——让 AI Agent 不仅能修改代码，还能自动提供修改后的视觉证据。

如果你正在使用 Claude Code、Codex 或 Cursor，并且厌倦了反复手工截图的工作，试试在你的仓库里加一份 .shotlist.yaml。

相关链接：

• GitHub 仓库
• PyPI 包
• 配方手册（docs/recipes.md）