ProofShot

开源、与 Agent 无关的 CLI 工具，为 AI 编程 Agent 提供“视觉”。 当你的 Agent 构建完功能后，ProofShot 会录制视频证明其功能正常运行。

适用于 Claude Code、Cursor、Codex、Gemini CLI、Windsurf、GitHub Copilot 以及任何可以运行 Shell 命令的 Agent。

---

为什么选择 ProofShot？

AI 编程 Agent 在构建 UI 功能时往往是“盲目”的。它们编写代码，但无法验证结果看起来是否正确、运行是否正常，或者是否抛出了错误。

ProofShot 补齐了这一环节：这是一个开源 CLI，可以接入任何 AI 编程 Agent，为其提供验证工作流——在真实的浏览器中测试、录制视频证据、收集错误，并将所有内容打包供人工审查。

人工可以获得视频录制、关键时刻的截图，以及发现的任何控制台或服务器错误报告。你可以在本地查看这些制品，也可以运行 proofshot pr 将所有内容作为内联评论上传到 GitHub PR 中。无供应商绑定，不依赖云服务。

互动查看器：包含进度条、动作标记和分步时间轴的视频录制界面。

安装

npm install -g proofshot
proofshot install

第一条命令安装 CLI 和 agent-browser（包含 headless Chromium）。第二条命令会自动检测你的 AI 编程工具，并在用户级别安装 ProofShot 技能——它将自动适用于你所有的项目。

工作原理

三步工作流：启动 (start)、测试 (test)、停止 (stop)。

# 1. 启动 — 打开浏览器，开始录制，捕获服务器日志
proofshot start --run "npm run dev" --port 3000 --description "登录表单验证"

# 2. 测试 — AI Agent 驱动浏览器
agent-browser snapshot -i                                    # 查看交互元素
agent-browser open http://localhost:3000/login               # 导航
agent-browser fill @e2 "test@example.com"                    # 填写表单
agent-browser click @e5                                      # 点击提交
agent-browser screenshot ./proofshot-artifacts/step-login.png # 捕获证明

# 3. 停止 — 将视频、截图和错误打包成证明制品
proofshot stop

技能文件（skill file）会自动教会 Agent 这个工作流。用户只需说一句 "verify this with proofshot"，剩下的工作就交给 Agent 处理。

输出制品

每次会话都会在 ./proofshot-artifacts/ 目录下生成一个带时间戳的文件夹：

文件	描述
session.webm	整个会话的视频录制
viewer.html	独立的互动查看器，包含进度条、时间轴以及控制台/服务器日志标签页
SUMMARY.md	包含错误、截图和视频的 Markdown 报告
step-*.png	在关键时刻捕获的截图
session-log.json	带有时间戳和元素数据的动作时间轴
server.log	开发服务器的 stdout/stderr（使用 --run 时）
console-output.log	浏览器控制台输出

查看器还包含用于浏览控制台和服务器日志的标签页，并带有错误高亮显示，且时间戳与视频同步。

命令

proofshot install

检测机器上的 AI 编程工具并安装 ProofShot 技能。每台机器只需运行一次。

proofshot install               # 交互式工具选择
proofshot install --only claude  # 仅为特定工具安装
proofshot install --skip cursor  # 跳过特定工具
proofshot install --force        # 覆盖现有安装

proofshot start

启动验证会话：浏览器、录制、错误捕获。

proofshot start                                        # 服务器已在运行
proofshot start --run "npm run dev" --port 3000         # 启动并捕获服务器输出
proofshot start --description "验证结账流程"    # 向报告添加描述
proofshot start --url http://localhost:3000/login       # 打开特定 URL
proofshot start --headed                                # 显示浏览器（用于调试）
proofshot start --force                                 # 覆盖之前崩溃遗留的旧会话

proofshot stop

停止录制，收集错误，生成证明制品。

proofshot stop              # 停止会话并关闭浏览器
proofshot stop --no-close   # 停止但保持浏览器打开

proofshot exec

透传给 agent-browser 并进行自动会话记录。捕获时间戳、元素数据并解析截图路径。

proofshot exec click @e3
proofshot exec screenshot step-checkout.png

proofshot diff

将当前截图与基准进行比较，以进行视觉回归测试。

proofshot diff --baseline ./previous-artifacts

proofshot pr

将会话制品上传到 GitHub 并向 PR 发布验证评论。它会自动查找当前分支上记录的所有会话，并上传截图和视频。