如何贡献ProofShot开源项目:TypeScript构建、vitest测试与示例应用实战
如何贡献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 交互式 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,它定义了两个构建目标:
- CLI 可执行文件:入口
bin/proofshot.ts,输出为带#!/usr/bin/env nodeshebang 的 ESM 脚本(tsup.config.ts),这就是npm link后全局proofshot命令的来源; - 库入口:入口 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/ 中即可看到一次完整验证会话的产物:
单次验证会话生成的工件文件夹
如果你改动的是 viewer 或日志收集逻辑,可以打开生成的 viewer.html,在 Console 标签页核对错误高亮与视频时间戳同步是否正常:
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 中聊聊你的想法! 🎯


