ProofShot开源CLI工具：为AI编程助手添加视觉验证与测试能力

你的 AI 助手刚刚写完一个登录页面，但它真的知道这个页面长什么样吗？

从“盲人摸象”到“眼见为实”

想象这样一个场景：深夜加班，你的 AI 编程助手，比如 Claude，刚刚生成了一个完整的用户注册流程代码。逻辑看起来完美，测试用例也全部通过。但当你满怀期待地打开浏览器时，看到的却是错位的布局、无法点击的按钮，以及控制台里一串刺眼的红色错误。

这让人不禁疑惑：“明明测试都通过了，为什么实际运行却不行？”

这正是当前许多 AI编程助手 面临的核心挑战：它们擅长生成代码逻辑，却看不见代码运行时的实际效果，如同一位盲人厨师，难以评估最终菜肴的“色香味”。为了解决这一痛点，一个名为 ProofShot 的开源工具应运而生。

ProofShot 是什么？AI 的“行车记录仪”

如果要用一个比喻来形容 ProofShot，那么它就像是AI编程助手的“行车记录仪”。

当你的 AI 助手（无论是 Claude Code、Cursor 还是 GitHub Copilot）执行构建任务时，ProofShot 会在后台自动记录整个过程：启动浏览器、导航页面、填写表单、点击交互元素……它不仅录制操作视频，还会同步捕获屏幕截图、收集控制台错误以及服务器日志。

最终，它会将所有“证据”整理成一份清晰的报告，让你能够直观地验证 AI 的产出是否真的“能用”，而不仅仅是“能跑”。

# 简单三步，让AI自证清白
proofshot start --run "npm run dev" --port 3000  # 第一步：启动记录
# AI在这里操作浏览器...
proofshot stop  # 第三步：生成证据包

ProofShot 的设计理念是 “代理人无关（agent-agnostic）” 的。这意味着无论你使用何种 AI 助手，只要它能执行 shell 命令，ProofShot 就能为它装上这双“眼睛”。

为什么需要 ProofShot？直面三大开发痛点

痛点一：AI 的“盲盒编程”

你是否遇到过这种情况？AI 自信地完成了某个组件的重构，声称性能提升了30%，所有单元测试也都通过。但上线后却发现，某个关键按钮在移动端消失了。

问题在于，传统的单元测试只验证代码逻辑的正确性，无法评估视觉表现和交互细节。ProofShot 的解决方式直截了当：把运行过程录下来，让你亲眼看到。

痛点二：调试的“时间黑洞”

当AI生成的复杂交互代码出错时，定位问题往往像大海捞针。你可能需要花费大量时间手动添加 console.log、反复刷新页面调试。

ProofShot 可以自动收集所有运行时错误，包括 JavaScript 异常、网络请求失败、控制台警告等，并按时间戳与视频操作精准对齐，极大缩短了问题排查路径。

痛点三：协作的“信任危机”

在团队代码评审中，我们常听到这样的对话：“这个 PR 改动太大，我不敢合并。”“但我测试过了，没问题！”此时，如何提供令人信服的证据？

传统方式需要手动录屏、截图、整理日志，费时费力。ProofShot 可以将这个过程自动化，运行一条命令即可将完整的验证证据包上传到 GitHub PR 中，生成包含视频、截图和日志的内联评论，有效建立基于事实的协作信任。

ProofShot 工作原理详解：三步曲

第一步：搭建舞台 (Start)

运行 proofshot start 命令后，ProofShot 会执行以下操作：

1. 启动浏览器实例：默认使用无头模式的 Chrome，也支持有头模式便于调试。
2. 开始录制：启动屏幕录制进程。
3. 捕获日志：如果指定了 --run 参数，它会启动开发服务器并捕获其输出。
4. 准备就绪：等待 AI 助手开始执行测试操作。

proofshot start \
  --run "npm run dev" \
  --port 3000 \
  --description "验证用户登录流程" \
  --url "http://localhost:3000/login"

这个命令的含义是：“启动开发服务器，监控本地 3000 端口的登录页面，并准备记录名为‘验证用户登录流程’的测试会话。”

第二步：AI 表演 (Test)

这是 AI 助手的舞台。ProofShot 通过技能文件（skill file）教导 AI 如何使用 agent-browser 等命令来操作浏览器，完成测试步骤。

# AI助手会自动执行这些命令
agent-browser open http://localhost:3000/login
agent-browser fill @email-input "user@example.com"
agent-browser fill @password-input "secret123"
agent-browser click @submit-button
agent-browser screenshot ./proofshot-artifacts/step-login-success.png

注意 @email-input 这样的语法，这是 agent-browser 使用的元素选择器。AI 无需记忆复杂的 CSS 路径，只需为元素赋予有意义的别名，ProofShot 会自动记录何时操作了哪个元素。

第三步：打包证据 (Stop)

测试完成后，执行 proofshot stop，ProofShot 会：

1. 停止录制。
2. 关闭浏览器。
3. 分析所有收集到的数据。
4. 生成一个结构化的证据包。

证据包通常位于 ./proofshot-artifacts/ 目录下，包含以下文件：

2024-03-30_14-30-25_验证用户登录流程/
├── session.webm                   # 完整录制视频
├── viewer.html                    # 交互式查看器
├── SUMMARY.md                     # Markdown总结报告
├── step-login-form.png            # 关键步骤截图
├── step-login-success.png
├── session-log.json               # 带时间戳的操作日志
├── server.log                     # 服务器日志
└── console-output.log             # 浏览器控制台输出

核心亮点：交互式查看器

ProofShot 生成的 交互式查看器 (viewer.html) 是其精髓所在。它不仅仅是一个视频播放器：

• 左侧是视频播放器，带精确进度控制。
• 右侧是时间线，清晰展示每个关键操作的发生时刻。
• 下方是标签页，可切换查看控制台日志、服务器日志和详细操作记录。

最具价值的是时间同步功能：点击时间线上的任何事件（如“填写密码”），视频会自动跳转到对应时刻；在日志中点击一个错误记录，视频也会定位到错误发生的时间点。这使得回溯和调试变得异常高效。

安装与快速开始

安装过程非常简单：

npm install -g proofshot
proofshot install

第一条命令安装 ProofShot CLI 和 agent-browser。第二条命令 proofshot install 会自动检测你系统上已安装的 AI 编程工具（如 Claude Code、Cursor、GitHub Copilot 等），并为它们配置 ProofShot 技能文件，实现开箱即用。

高级功能与应用场景

1. 视觉回归测试

ProofShot 的 diff 命令可用于对比视觉变化，非常适合UI组件库的维护。

proofshot diff --baseline ./previous-artifacts

2. 自动化 PR 评审

在团队协作中，一条命令即可将验证证据与代码变更关联。

proofshot pr

该命令会自动识别当前 Git 分支关联的 Pull Request，上传证据文件，并发布格式化的内嵌评论。

3. 实战示例：验证登录表单

假设需要验证一个 AI 生成的登录页面，流程如下：

人类开发者发起验证：

proofshot start --run "npm run dev" --port 3000 --description "登录表单验证"

AI 助手执行测试步骤：

# 1. 查看页面可交互元素
agent-browser snapshot -i

# 2. 导航到登录页面
agent-browser open http://localhost:3000/login

# 3. 截图记录初始状态
proofshot exec screenshot step-1-initial.png

# 4. 填写表单
agent-browser fill @email-input "test@example.com"
agent-browser fill @password-input "password123"

# 5. 截图记录填写后状态
proofshot exec screenshot step-2-filled.png

# 6. 点击提交
agent-browser click @submit-button

# 7. 等待并验证结果
agent-browser wait 2000  # 等待2秒
proofshot exec screenshot step-3-after-submit.png

# 8. 检查控制台错误
agent-browser check-console

生成并查看报告：

proofshot stop

生成的 SUMMARY.md 报告会清晰呈现测试概述、关键截图、控制台输出和最终结论。

技术背后：如何实现可靠录制与追踪

• 录制技术：基于 Puppeteer 的 page.screenshot 进行定时截图，再合成视频。这种方式兼容无头模式，内存占用低。
• 错误收集：通过监听 page.on(‘pageerror’), page.on(‘console’), page.on(‘requestfailed’) 等多重事件源，捕获全方位的运行时异常。
• 元素追踪：当 AI 使用 @alias 操作元素时，ProofShot 会记录该元素的多重选择器信息，确保即使页面结构变化，也能追溯原始操作对象。

最佳实践建议

1. 给 AI 明确指令：不要只说“测试一下”，应明确列出验证要点，如“确保表单可输入、提交后正确跳转、无控制台错误”。
2. 设计有意义的检查点：每个 screenshot 应对应一个明确的验证状态（如 step-1-loaded.png, step-2-submitted.png）。
3. 作为现有测试的补充：ProofShot 并非取代单元测试或 E2E 测试，而是作为视觉与集成验证层，与它们协同工作。

   # 在CI/CD流水线中的可能组合
   npm test          # 单元测试
   npm run e2e       # E2E测试
   proofshot start --run "npm run dev" --port 3000 # AI执行关键用户流验证
   proofshot stop
   proofshot pr      # 上传证据

总结：建立基于证据的 AI 开发协作

ProofShot 代表了 AI 开发可观察性 的重要一步。它通过提供可视化的运行时证据，将 AI 的编程过程从“黑盒”变为“透明盒”，有效解决了信任与验证问题。

在 AI编程 和 软件测试 日益融合的今天，这类工具对于提升开发效率与协作质量至关重要。下次当你的 AI 助手声称完成任务时，不妨尝试说：“证明给我看。”

ProofShot 项目信息：

• GitHub 仓库：https://github.com/AmElmo/proofshot
• 安装：npm install -g proofshot
• 主要语言：TypeScript
• 许可证：MIT

对于热衷探索 前端 与 AI 结合实践的开发者而言，ProofShot 提供了一个非常实用的切入点，值得在具体的开发场景中尝试和应用，更多技术工具的实践与讨论也欢迎在云栈社区进行交流。