如何贡献ProofShot开源项目:TypeScript构建、vitest测试与示例应用实战

原创2026-10-24 21:46:401,959 阅读

如何贡献ProofShot开源项目:TypeScript构建、vitest测试与示例应用实战

ProofShot 是一个为 AI coding agent 提供视觉验证的开源 CLI 工具:它录制浏览器会话、截取关键截图、收集控制台与服务端错误,并把视频、截图和报告打包成可审查的证明工件(proof artifacts)。想给 ProofShot 贡献代码?本文带你从零走通 TypeScript 构建、vitest 测试与示例应用端到端验证的完整本地开发流程,快速上手你的第一次贡献。 🚀

先跑起来:ProofShot 项目概览与仓库结构

ProofShot 的核心工作流只有三步:start(启动浏览器并开始录制)、exec(代理驱动浏览器交互)、stop(停止录制、裁剪视频、生成报告)。每次会话最终会产出一个包含 session.webm 视频、step-*.png 截图、SUMMARY.md 报告和交互式 viewer.html 的工件目录。

ProofShot AI视觉验证工具:带视频播放与交互式时间线的viewer界面

ProofShot 交互式 viewer:视频回放、时间线步骤与动作标记

理解代码前,先掌握这份目录地图(完整说明见 CLAUDE.md):

目录 职责
src/cli.ts Commander.js 命令注册入口
src/commands/ 每个 CLI 命令一个文件(install、start、stop、diff、pr…)
src/browser/ agent-browser CLI 封装(session、capture、interact、navigate)
src/session/ .session.json 会话生命周期管理
src/utils/ 配置加载、进程执行、错误模式、端口与 GitHub API 工具
test/fixtures/ 三套示例应用,用于端到端测试

架构细节可以深入阅读 docs/architecture.md,它解释了会话生命周期、视频裁剪与 viewer 的内部实现。

一键搭建本地开发环境:clone 与依赖安装步骤

环境要求很简单:Node.js ≥ 18,其余交给 npm。

git clone https://gitcode.com/gh_mirrors/pr/proofshot
cd proofshot
npm install
npm run build

npm install 之后,package.json 的 postinstall 钩子会尝试自动执行 agent-browser install 下载无头 Chromium,这是浏览器操作层的基础。

三条最常用的脚本命令(定义在 package.json 中):

npm run build   # 用 tsup 构建,代码改动后必须执行
npm test        # vitest 单次运行全部测试
npm run dev     # watch 模式,边改边构建

⚠️ 记住一条铁律:先 build 再 test。CLI 运行时读取的是 dist/ 产物,而不是源码。

读懂 TypeScript 构建:tsup 双入口配置解析

ProofShot 采用 ESM-only + tsup 的构建方案,配置集中在 tsup.config.ts,它定义了两个构建目标:

  1. CLI 可执行文件:入口 bin/proofshot.ts,输出为带 #!/usr/bin/env node shebang 的 ESM 脚本(tsup.config.ts),这就是 npm link 后全局 proofshot 命令的来源;
  2. 库入口:入口 src/index.ts,开启 splitting 与 dts,额外生成类型声明供下游项目引用。

两个目标都以 node18 为目标,并通过 define 把 __PROOFSHOT_VERSION__ 注入为 package.json 中的版本号——这也是为什么贡献时永远不要手动改 version 字段。

TypeScript 侧则开启了 strict 模式(见 tsconfig.json),写代码时类型错误会在构建阶段直接暴露。

vitest 测试实战:从 describe/it 到 vi.mock

测试文件与源码同目录存放(如 src/utils/config.test.ts),风格统一、易读易仿照。

真实 IO 类测试用临时目录隔离,例如 config.test.ts 中:

describe('loadConfig', () => {
  it('merges nested browser config with defaults', () => {
    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'proofshot-config-test-'));
    fs.writeFileSync(path.join(tempDir, 'proofshot.config.json'), JSON.stringify({ ... }));
    expect(loadConfig(tempDir).browser).toEqual({ ... });
  });
});

依赖外部命令的测试则用 vi.hoisted + vi.mock 打桩,避免真的去执行 agent-browser、ffmpeg。典型模式见 src/commands/doctor.test.ts:

const { loadConfigMock, findExecutablePathMock } = vi.hoisted(() => ({
  loadConfigMock: vi.fn(),
  findExecutablePathMock: vi.fn(),
}));
vi.mock('../utils/config.js', () => ({
  findConfigPath: findConfigPathMock,
  loadConfig: loadConfigMock,
}));

注意 ESM 约定:所有 import 必须带 .js 后缀,mock 路径同样如此。

提交前只需两条命令自测:

npm run build && npm test

示例应用端到端实战:3 套 fixtures 覆盖不同 UI

仓库内置三套示例应用(docs/test-apps.md 有现成的测试提示词),分别覆盖 SaaS 仪表盘、看板拖拽、聊天界面三类 UI 模式:

应用 端口 UI 模式
sample-app 5173 SaaS 落地页 + 仪表盘 + 设置表单
todo-app 5174 看板拖拽、右键菜单、键盘快捷键
chat-app 5175 频道切换、表情、消息回应、文件拖拽

以 sample-app 为例,无需 AI agent 也能完整跑通 start → 浏览器交互 → stop → pr → clean 全生命周期:

cd test/fixtures/sample-app
npm install
npm run build   # 回到仓库根目录先构建 CLI
bash test-proofshot.sh

test-proofshot.sh 脚本会启动 5173 端口的 dev server、驱动浏览器访问三个页面并截图,最后生成工件。运行后在 proofshot-artifacts/ 中即可看到一次完整验证会话的产物:

ProofShot验证工件文件夹:截图、视频与会话报告文件一览

单次验证会话生成的工件文件夹

如果你改动的是 viewer 或日志收集逻辑,可以打开生成的 viewer.html,在 Console 标签页核对错误高亮与视频时间戳同步是否正常:

ProofShot控制台日志面板:错误高亮与视频同步时间戳展示

viewer 的 Console 标签页:错误高亮 + 与视频同步的时间戳

新手友好切入点:添加错误模式与新命令

第一次贡献不必动核心链路,两个官方推荐的低门槛切入点(说明见 CLAUDE.md):

  • 为新语言添加错误检测模式:编辑 src/utils/error-patterns.ts,向 PATTERNS 数组追加 { name, patterns } 条目即可让 ProofShot 识别新语言的服务端错误(目前已覆盖 10+ 语言);
  • 新增 CLI 命令:三步走——在 src/commands/ 下新建 mycommand.ts 导出 mycommandCommand,在 src/cli.ts 中注册 program.command('mycommand'),需要公开为 API 时再从 src/index.ts 导出。

改动涉及多智能体协作行为时,别忘了同步更新 skills/ 下各 agent 的技能说明(Claude、Codex、Cursor、OpenCode 各有一份),以及 content/docs/ 下的 Nextra 文档站。

提交规范与自动发布:Conventional Commits 指南

ProofShot 合并到 main 后由 semantic-release 自动发版,因此提交信息直接决定版本号:

提交类型 版本影响
feat: minor(1.6.0 → 1.7.0)
fix: / perf: / refactor: patch(1.6.0 → 1.6.1)
feat!: 或 BREAKING CHANGE: major
docs: / test: / chore: 不触发发版

格式为 type(scope): description,例如 feat(cli): add diff command。分支命名建议采用 <用户名>/<描述性名称> 的风格,便于追溯。

常见问题速查清单

  • 测试报 CLI 行为异常? 先 npm run build,CLI 只认 dist/ 产物。
  • import 找不到模块? ESM-only 项目,import 路径必须带 .js 后缀。
  • 会话状态混乱? 用 proofshot doctor 打印当前环境、活动会话与二进制诊断(实现见 src/commands/doctor.ts)。
  • 端口被占用? proofshot start 会快速失败(fail fast);用 --force 可覆盖上次崩溃遗留的会话。
  • 本地调试浏览器行为? proofshot start --headed 让浏览器窗口可见,配合 --run 参数可同时抓取 dev server 日志。

至此你已经掌握 ProofShot 贡献的完整链路:环境搭建 → tsup 构建 → vitest 测试 → 示例应用端到端验证 → 规范化提交。挑一个错误模式或新命令开工吧,欢迎在 issue 中聊聊你的想法! 🎯

登录后查看全文
proofshot