给 AI 编码 Agent 加上视觉验证能力

开源、与 Agent 无关的 CLI，让 AI 编程 Agent 拥有“眼睛”。你的 Agent 构建功能，ProofShot 则录制视频，证明它确实可以正常运行。

支持 Claude Code · Cursor · Codex · OpenCode · Gemini CLI · Windsurf · GitHub Copilot · 任何能够运行 shell 命令的 Agent

AI 编程 Agent 构建 UI 功能时如同蒙着眼睛。它们会编写代码，却无法验证最终效果是否符合预期、功能是否正常，或者是否出现错误。

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

人类最终可以获得一段视频录像、关键时刻的截图，以及所有已发现的控制台或服务器错误报告。你可以在本地查看这些产物，也可以运行 proofshot pr，将所有内容以内联评论的形式上传到 GitHub PR。没有厂商锁定，也不依赖云服务。

交互式查看器：包含进度拖动条、操作标记和分步时间线的视频录像

它与其他工具有何不同？

最常被问到的问题是：“为什么不直接使用 Playwright MCP、Chrome DevTools MCP 或 agent-browser？”

简短回答：这些工具用于控制浏览器。ProofShot 则是一套验证工作流，负责把证明功能正常的产物打包，交给人类审查。

ProofShot 构建在 agent-browser 之上。它增加了 session 管理、服务器日志捕获、错误检测、视频裁剪、时间戳同步、交互式查看器，以及 PR 上传工作流。浏览器底层能力来自 agent-browser，而 ProofShot 是其上的验证层。

如果你希望在开发过程中进行实时调试或检查 DOM，可以使用 Playwright MCP 或 DevTools MCP。如果你希望获得一套几秒钟内就能审查、或可附加到 PR 的证明产物，则可以使用 ProofShot。

npm install -g proofshot
proofshot install

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

三步工作流：启动、测试、停止。

# 1. Start — open browser, begin recording, capture server logs
proofshot start --run "npm run dev" --port 3000 --description "Login form verification"

# 2. Test — the AI agent drives the browser
agent-browser snapshot -i                                    # See interactive elements
agent-browser open http://localhost:3000/login               # Navigate
agent-browser fill @e2 "test@example.com"                    # Fill form
agent-browser click @e5                                      # Click submit
agent-browser screenshot ./proofshot-artifacts/step-login.png # Capture proof

# 3. Stop — bundle video + screenshots + errors into proof artifacts
proofshot stop

skill 文件会自动教会 Agent 使用这套工作流。用户只需说“使用 proofshot 验证这个功能”，其余工作就会由 Agent 完成。

每个 session 都会在 ./proofshot-artifacts/ 中生成一个以时间戳命名的文件夹：

单次验证 session 生成的产物

查看器还提供用于浏览控制台日志和服务器日志的标签页，其中包含错误高亮，以及与视频同步的时间戳：

控制台日志标签页，包含错误高亮和与视频同步的时间戳

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

proofshot install               # Interactive tool selection
proofshot install --only claude  # Only install for specific tools
proofshot install --skip cursor  # Skip specific tools
proofshot install --force        # Overwrite existing installations

启动一个验证 session：打开浏览器、开始录制并捕获错误。

proofshot start                                        # Server already running
proofshot start --run "npm run dev" --port 3000         # Start and capture server
proofshot start --description "Verify checkout flow"    # Add description to report
proofshot start --url http://localhost:3000/login       # Open specific URL
proofshot start --headed                                # Show browser (debugging)
proofshot start --force                                 # Override a stale session from a previous crash

你还可以在 proofshot.config.json 中配置浏览器的启动行为：

{
  "browser": {
    "configPath": "./agent-browser.local.json",
    "ignoreHttpsErrors": true,
    "executablePath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
  }
}

如果你需要让 ProofShot 根据项目专用配置运行 agent-browser，而不是继承 ~/.agent-browser/config.json，请设置 browser.configPath。相对路径会以 proofshot.config.json 所在目录为基准进行解析。

停止录制、收集错误并生成证明产物。

proofshot stop              # Stop session and close browser
proofshot stop --no-close   # Stop but keep browser open

将命令透传给 agent-browser，并自动记录 session 日志。它会捕获时间戳和元素数据，并解析截图路径。

当 ProofShot session 处于活动状态时，proofshot exec 会复用 proofshot start 为本次运行创建的同一个隔离 agent-browser session。这样可以确保截图、控制台日志、视频录像和浏览器操作始终指向同一个浏览器 session。

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

将当前截图与 baseline 进行比较，用于视觉回归测试。

proofshot diff --baseline ./previous-artifacts

将 session 产物上传至 GitHub，并在 PR 上发布验证评论。它会查找当前分支记录的所有 session，上传截图和视频，然后发布一条包含内嵌截图、格式完整的评论。

proofshot pr              # Auto-detect PR from current branch
proofshot pr 42           # Target a specific PR
proofshot pr --dry-run    # Preview the markdown without posting
proofshot pr --upload-provider github-web-attachments  # Use GitHub's internal attachment flow

默认情况下，ProofShot 使用 GitHub 官方的 repository contents API，并将产物上传到专用的 proofshot-artifacts 分支。普通的 gh 身份认证和 GH_TOKEN 都可以正常使用。

github-web-attachments provider 仍可用于上传由 GitHub 托管的内联媒体，但它依赖 GitHub 内部的 Web 上传 endpoint，因此可能会拒绝通过浏览器执行 gh auth login 所创建的 OAuth session。

如果系统中安装了 ffmpeg，则会把 .webm 视频转换为 .mp4。

删除 ./proofshot-artifacts/ 目录。

proofshot clean

输出当前的 ProofShot 环境信息，包括配置路径、浏览器模式、viewport、已安装的二进制文件，以及当前是否存在活动 session。

proofshot doctor

proofshot install 会检测以下工具，并为其配置 skill：

所有 skill 都安装在用户级别，无需逐个项目配置。

仓库中包含示例应用，因此即使没有自己的项目，你也可以直接体验 ProofShot 的运行效果。

git clone https://github.com/AmElmo/proofshot.git
cd proofshot
npm install && npm run build && npm link

# Set up the sample app
cd test/fixtures/sample-app
npm install

在 test/fixtures/sample-app/ 目录中打开你的 AI Agent，然后向它输入：

使用 proofshot 验证这个示例应用。从首页开始，检查 hero 区域；然后前往 Dashboard，检查各项指标；最后进入 Settings，更新个人资料中的姓名。为每个页面截图。

你也可以不使用 Agent，直接运行自动化测试脚本：

bash test-proofshot.sh

在 proofshot-artifacts/ 中查看视频、截图和报告。

ProofShot 可以自动检测来自服务器日志的错误，支持 10 多种语言和技术栈：JavaScript/Node.js、Python、Ruby/Rails、Go、Java/Kotlin、Rust、PHP、C#/.NET、Elixir/Phoenix 等。你可以在 src/utils/error-patterns.ts 中为新语言添加匹配模式。

Architecture——深入介绍 ProofShot 的底层工作原理、选择 agent-browser 的原因、session 生命周期、查看器内部机制和各项设计决策。

Test Apps——三个示例应用，附带开箱即用的 prompt，可用于针对不同 UI 模式对 ProofShot 进行端到端测试，包括 SaaS dashboard、看板和聊天界面。

欢迎贡献！项目使用 TypeScript（仅支持 ESM），通过 tsup 构建，并使用 vitest 进行测试。

npm install
npm run build    # Build (required after changes)
npm test         # Run tests
npm run dev      # Watch mode

test/fixtures/ 中包含三个示例应用，覆盖不同的 UI 模式，可用于端到端测试：SaaS dashboard（sample-app）、看板（todo-app）和聊天界面（chat-app）。

基于 Vercel 的 agent-browser 构建。