什么是ProofShot
ProofShot是一款开源、与代理无关的CLI工具，专门解决AI编程代理"盲写代码"的问题。AI编程代理会写UI功能，但无法验证结果是否正确显示、功能是否正常、有没有报错。ProofShot可以给它们装上"眼睛"，在真实浏览器中测试、录制视频证明、收集错误，把所有结果打包供人工审核。
支持所有能运行shell命令的AI编码代理：Claude Code、Cursor、Codex、Gemini CLI、Windsurf、GitHub Copilot等。
核心能力
当AI代理完成功能开发后，ProofShot可以：
- 录制整个浏览器会话的视频，证明功能正常工作
- 捕获关键节点的截图
- 收集控制台错误和服务端错误
- 生成交互式查看器，支持进度条拖动、动作标记、时间线同步
- 自动上传所有产物到GitHub PR，作为内嵌评论展示
- 无厂商锁定，无需云依赖
安装方法
npm install -g proofshot
proofshot install
第一条命令安装CLI和agent-browser（带无头Chromium），第二条命令检测你的AI编码工具，并在用户级别安装ProofShot技能，自动在所有项目中生效。
工作流程
三步即可完成验证：
# 1. 启动：打开浏览器，开始录制，捕获服务端日志
proofshot start --run "npm run dev" --port 3000 --description "登录表单验证"
# 2. 测试：AI代理驱动浏览器执行操作
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
技能文件会自动教AI代理这个工作流，用户只需要说"用proofshot验证这个"，代理就会自动处理剩下的工作。
生成的产物
每个会话会在./proofshot-artifacts/目录下生成带时间戳的文件夹，包含：
| 文件名 | 说明 |
|---|---|
| session.webm | 整个会话的视频录制 |
| viewer.html | 独立交互式查看器，支持进度条、时间线、控制台/服务端日志标签 |
| SUMMARY.md | Markdown报告，包含错误、截图、视频链接 |
| step-*.png | 关键节点的截图 |
| session-log.json | 带时间戳和元素数据的操作时间线 |
| server.log | 开发服务端的标准输出/错误（使用--run时） |
| console-output.log | 浏览器控制台输出 |
查看器还支持浏览控制台和服务端日志，错误高亮，时间戳与视频同步。
常用命令
安装相关
proofshot install # 交互式选择工具
proofshot install --only claude # 仅为特定工具安装
proofshot install --skip cursor # 跳过特定工具
proofshot install --force # 覆盖已有的安装
会话管理
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 stop # 停止会话并关闭浏览器
proofshot stop --no-close # 停止但保持浏览器打开
扩展功能
# 执行agent-browser命令，自动记录时间戳和元素数据
proofshot exec click @e3
proofshot exec screenshot step-checkout.png
# 视觉回归测试，对比当前截图与基线
proofshot diff --baseline ./previous-artifacts
# 上传产物到GitHub PR，发布验证评论
proofshot pr # 自动检测当前分支的PR
proofshot pr 42 # 指定PR编号
proofshot pr --dry-run # 预览Markdown内容不发布
# 清理产物目录
proofshot clean
支持的AI工具
proofshot install可以自动检测并配置以下工具的技能：
| 代理 | 安装位置 |
|---|---|
| Claude Code | ~/.claude/skills/proofshot/SKILL.md |
| Cursor | ~/.cursor/rules/proofshot.mdc |
| Codex（OpenAI） | ~/.codex/skills/proofshot/SKILL.md |
| Gemini CLI | 追加到~/.gemini/GEMINI.md |
| Windsurf | 追加到~/.codeium/windsurf/memories/global_rules.md |
所有技能都安装在用户级别，无需每个项目单独配置。
试用示例
仓库包含示例应用，可以快速体验效果：
git clone https://github.com/AmElmo/proofshot.git
cd proofshot
npm install && npm run build && npm link
# 设置示例应用
cd test/fixtures/sample-app
npm install
用AI代理打开test/fixtures/sample-app/目录，输入提示词：
用proofshot验证示例应用。从主页开始，检查hero部分，导航到Dashboard检查指标，然后到Settings更新个人资料名称。每个页面都截图。
或者不用AI代理，直接运行自动化测试脚本：
bash test-proofshot.sh
然后查看proofshot-artifacts/目录下的视频、截图和报告。
技术特点
- 自动检测10+语言的服务端错误：JavaScript/Node.js、Python、Ruby/Rails、Go、Java/Kotlin、Rust、PHP、C#/.NET、Elixir/Phoenix等
- 基于Vercel的agent-browser构建
- MIT开源协议
