shotbox

shotbox

为 AI Agent、脚本或 CI 提供真实图形程序的视觉、听觉和操作能力。

Agent 在带窗口的程序中工作时，看不到也听不到它。shotbox 会在独立的隔离会话中运行程序，使用 X11 或 Wayland，并让驱动程序的一方进行观察、聆听和操作：读取无障碍树、截取屏幕截图、录制程序播放的声音、按按钮名称点击、输入文字、按住按键和游戏手柄按钮，并等待程序真正就绪。然后测量发现的问题：屏幕阅读器无法读出的名称、对比度、Tab 顺序、与参考图相比发生变化的像素、闪烁的位置、跟随指针的速度、声音中断的位置，以及程序使用的资源。 它运行的任何内容都不会意外影响你的桌面或扬声器；使用 --net loopback 时，也不会影响你的网络。

使用 shotbox 制作：每个场景都是隔离会话中的一个 play 脚本，由 shotbox record 录制。含声音。

claude mcp add shotbox -- shotbox mcp --allow ~/src/app/shotbox-programs

不使用 Agent 时，可以在命令行中使用同一会话：

shotbox shoot editor.png --window 'Text Editor' -- gnome-text-editor notes.md

实用示例，从检查代码变更到对游戏进行冒烟测试： docs/recipes.md。与其他 GUI 驱动工具的区别： docs/comparison.md。

面向 Agent

shotbox mcp --allow PROGRAMS 会通过 Model Context Protocol（stdio）向 Agent 提供隔离会话。它可以启动会话，从 PROGRAMS 列表中启动程序（每行一个 NAME = COMMAND，除此之外不允许其他内容），然后：

• 读取无障碍树并截取屏幕截图，截图会以图像形式返回；
• 按节点名称点击、按键、输入文字并操作游戏手柄；
• 等待窗口、界面静止和播报；
• 检查无障碍问题、测量对比度并遍历 Tab 顺序；
• 录制会话播放的内容，并聆听声音中断的位置。

这些功能足以让 Agent 在 GUI 中检查自己的变更、通过游玩测试游戏、审查屏幕阅读器听到的内容，或在每次都相同的会话中重现错误报告。无障碍树是轻量的观察方式，只需一两千个 token 的文本；只有像素才能说明的内容则需要查看屏幕截图。Agent 无法运行列表之外的任何程序，服务器停止时，其会话也会停止。

其用途、工具和构建方式：docs/mcp.md。

如果 Agent 从自己的 Shell 中运行程序，程序就会在你的桌面上运行：窗口会显示在屏幕上，声音会通过扬声器播放，即使是在 xvfb-run 下运行的浏览器，也会找到你的 Wayland 显示器。若要让程序在会话中运行，请将以下内容加入项目的 CLAUDE.md 或 AGENTS.md，也可以加入你自己的文件：

## Graphical programs, browsers and sound

Never run a graphical program, a browser (headless too) or anything that
makes sound straight on this machine: it reaches my desktop and speakers.
Run it in a shotbox session:

- a picture: `shotbox shoot OUT.png --window RE -- COMMAND`
- a script or a test suite with windows: `shotbox run [--audio] -- COMMAND`
- with none, a headless browser say: `shotbox exec [--audio] -- COMMAND`;
  the shotbox package's `sealed()` seals a browser's environment, but
  not the speakers
- a session to come back to: `shotbox start --name NAME`, then
  `shotbox spawn --session NAME -- COMMAND`, and `shotbox stop NAME`

Not `xvfb-run`: it lets `WAYLAND_DISPLAY` and the session bus through. A
server started for a test listens on 127.0.0.1, not 0.0.0.0.

为什么

检查变更的 Agent、README 的截图，以及 CI 中的测试，都需要同样的东西，而每个项目都在重复实现：

• 隔离。 不会意外泄露你的任何内容，程序执行的任何操作也不会传到你的桌面或扬声器；bubblewrap 可以创建沙箱（如果无法创建，它会说明原因）：隔离说明。
• 就绪，而非等待。 等待的是具体事件：窗口映射、端口开放、文件写入、终端屏幕上出现文本，或画面稳定。不会用 sleep 6 然后祈祷。
• 确定性。 使用 Xvfb 上的 X11、GTK 软件渲染器、LANG=C.UTF-8、TZ=UTC，文本光标不闪烁（GTK、Qt 6.5 和浏览器的光标；同时关闭 GTK 动画），GTK 4 的文本按其颜色绘制，采用其手册所述的字体渲染方式，而非 GTK 版本自动渲染时更淡的颜色（了解更多），并且 PNG 中不含时间戳。每次结果都相同，但不等同于桌面环境：与桌面环境的差异。
• 清理彻底。 每个程序都在自己的进程组中运行，退出时会终止整个进程组：只向包装脚本发送信号会导致其子进程继续运行。

安装

在 Debian 上，安装所有命令和选项所需的内容：

sudo apt install xvfb xauth dbus-daemon imagemagick x11-utils python3-gi gir1.2-vte-2.91 \
  at-spi2-core gir1.2-atspi-2.0 python3-gi-cairo gir1.2-pango-1.0 libglib2.0-bin pipewire \
  wireplumber ffmpeg bubblewrap libfaketime
pipx install --system-site-packages shotbox

--system-site-packages 允许它使用系统的 PyGObject，shotbox term 和 --a11y 都需要它；也可以运行 pip install shotbox。或者从检出目录运行：ln -s "$PWD/bin/shotbox" ~/.local/bin/shotbox。

shotbox doctor 会逐行说明已安装和缺少的内容，以及如何获取。每个命令和选项所需的内容见：所需内容。

无需安装 Python 包：它使用标准库和这些工具。Wayland 会话还需要更多内容；参见 Wayland。

在 Ubuntu 的 GitHub Actions 作业中，该 Action 会安装它及其运行所需的内容，安装版本与所用的发布版（或分支）一致；各项功能所需内容按名称指定（未设置时全部关闭），并允许 bubblewrap 创建沙箱，而 Ubuntu 的 AppArmor 会对其加以限制：

- uses: mishan/[email protected]
  with:
    a11y: true        # --a11y and `shotbox a11y`
    speak: true       # `shotbox a11y speak`: Orca, and what a11y installs
    term: true        # `shotbox term`
    # wayland, audio, record, gamepads and clock too
- run: shotbox shoot app.png --window 'My App' -- ./my-app

快速了解

shotbox shoot app.png --window 'My App' -- ./my-app          # a picture, once it's up
shotbox shoot app.png --twice --window 'My App' -- ./my-app  # the same every time?
shotbox compare ref.png app.png --diff diff.png              # what changed, and where
shotbox run -- ./take-pictures.sh       # a script that waits, clicks and captures inside
shotbox exec --audio -- npx playwright test        # sealed, with no display
shotbox start --name ed --a11y          # a session to come back to
shotbox spawn --session ed -- gnome-text-editor
shotbox --session ed a11y click Open
shotbox --session ed capture open.png
shotbox stop ed

命令

命令	功能
shoot	运行程序、等待并截图；--twice 可验证截图结果是否一致
run	在隔离会话中运行命令并等待，然后以该命令的状态码退出
exec	功能相同，但不显示界面：用于无头浏览器、测试套件
start, spawn, stop, sessions	启动持久会话、运行其中的程序、停止程序、列出会话
term	打开可截图的终端
wait	等待窗口、端口、文件、画面静止、图像、变化或日志行
capture	截图，或连续拍摄一组截图
record	录制视频、声音或两者
key, type, click, move, scroll, drag	按键、输入文字、操作指针；也支持按住
park, focus	将指针移到一旁；将键盘焦点交给窗口
play	按同一时钟播放定时输入脚本
latency	测量绘制内容跟随指针的速度
flicker	查找屏幕上闪烁或忽明忽暗的部分
pad	操作虚拟游戏手柄
a11y, wait announce, wait node	无障碍树：读取、检查、Tab 顺序、按名称点击、对比度、播报，以及显示指定节点
compare	逐图或逐目录统计不同的像素
vision	查看色盲者所见的图像
listen	检查录音的音量、削波和音频丢失
mcp	通过 MCP 为 Agent 创建会话
doctor	检查当前有哪些命令所需的依赖

会话支持的选项包括 --wayland、--a11y、--audio、 --gamepads、--net loopback、--identity、--clock、--dark 等： 会话选项。

密封范围

会话可防止程序意外访问你的桌面，但无法防止有意为之的程序：

• 会话的环境会根据允许列表重新构建；HOME 和所有 XDG 目录都是临时目录。
• 会话拥有独立的显示服务、会话总线和系统总线；使用 --a11y 和 --audio 时，也会拥有独立的辅助功能总线和声音服务器；声音服务器不会播放到任何地方。会话没有打印机（但可以访问 localhost:631 上的 CUPS，除非使用 --net loopback）。--machine-bus 会让会话使用计算机的系统总线和打印机。
• 如果 bubblewrap 能创建沙箱（无法创建时会说明），会话就无法访问计算机的声音设备，也无法访问桌面上的 Wayland、PulseAudio、PipeWire 和总线套接字。
• 除非使用 --net loopback，否则会话可以访问你的网络；除非使用 --identity，否则会话会显示你的用户名和主机名；除非使用 --clock，否则会话会使用真实时间。
• 未密封的部分：临时主目录以外的文件、X 服务器以及其他进程。

完整说明，以及每个选项的覆盖范围和限制： docs/sealed.md。

辅助功能

--a11y 会启动会话专属的辅助功能（AT-SPI）总线，以便读取和检查屏幕阅读器会读出的内容。不使用该选项时，会话没有辅助功能总线：系统会告知 GTK 不要尝试查找。无论是否使用该选项，都不会触碰桌面的总线。

shotbox a11y 会打印树结构，检查其中没有可读名称的节点，遍历 Tab 顺序，按名称点击并测量对比度；支持 GTK、Qt、AccessKit 的工具包和 Chromium。各项命令、实现方式，以及每项检查能说明和无法说明的内容： docs/accessibility.md。

Wayland

--wayland 会让会话使用 Wayland：程序在无头 sway 下运行，通过软件绘制，而不是运行在 Xvfb 上。--xwayland 会为会话添加一个 Xwayland 和 DISPLAY，这样 X 客户端就能像在 Wayland 桌面上一样运行；对于使用 --env GDK_BACKEND=x11 创建的 GTK 程序也是如此。

需要 sway 和 grim；使用 --xwayland 需要 Xwayland，使用 record 需要 wf-recorder：sudo apt install sway grim xwayland wf-recorder。为何选择 sway、它如何集成，以及与 X11 的区别： docs/wayland.md。

文档

• 命令：每条命令和会话选项、各自的要求、 资源使用情况和时钟
• 密封内容
• 示例：完整示例
• 对比：与其他驱动 GUI 的工具进行对比
• MCP：Agent 可用的工具及其构建方式
• 无障碍
• Wayland
• 与桌面环境的差异：绘制、窗口管理器、动画、语言、缩放、输入、测量
• 游戏手柄
• Python：shotbox.Session 和 here()，用于驱动显示器本身的脚本
• Node：用于通过 Playwright 检查浏览器的辅助工具
• 贡献：测试
• 行为准则、 安全和 无障碍
• 发布
• 更新日志

许可证

MIT。请参阅 LICENSE。