ProofShot设计决策清单:ESM、最小依赖与优雅降级的7个工程实践
ProofShot设计决策清单:ESM、最小依赖与优雅降级的7个工程实践
ProofShot 是一个为 AI 编码 Agent 提供视觉验证的开源 CLI 工具:它录制浏览器操作视频、采集控制台错误、打包"证据产物"(proof artifacts),让人类能快速验证 Agent 构建的功能是否真的可用。这篇文章把 ProofShot 源码中的设计决策逐一拆解——ESM 模块化、最小依赖、双入口构建与优雅的降级策略,是一份可直接复用的 Node.js 工程实践清单。
一、先看成品:一次验证会话的证据产物
理解设计决策前,先看输出。每个会话会在 ./proofshot-artifacts/ 下生成一个时间戳文件夹:session.webm 视频、step-*.png 关键截图、SUMMARY.md 报告,以及视频同步的日志查看器。
架构上,ProofShot 是一个薄编排层:AI Agent 通过 shell 调用 proofshot start / exec / stop,ProofShot 管理会话状态与产物生成,所有浏览器操作委托给可选的 agent-browser。全部决策都围绕一个目标:让这套流程在任何 Agent、任何机器上都尽量跑起来。
架构全景见 docs/architecture.md。
二、决策 1:ESM-only,导入显式使用 .js 扩展名
在 package.json 中,一行 "type": "module" 声明了整个项目只用 ESM;而 src/cli.ts 里所有导入都写成显式扩展名:
import { installCommand } from './commands/install.js';
import { PROOFSHOT_VERSION } from './version.js';
这是官方架构文档中明确记录的设计决策:源码里导入 .ts 文件时写 .js,保证 TypeScript 编译后文件在 Node 原生 ESM 下无需任何模块解析启发式就能正确定位,避免"构建能过、运行时报 Cannot find module"这类隐蔽问题。配套配置在 tsconfig.json:module: ESNext + moduleResolution: bundler,开发期由打包器解析,产物期由 Node 解析,两边都成立。
💡 新手要点:如果你从零写 Node CLI,
ESM + 显式扩展名是当前成本最低、兼容性最好的选择。
三、决策 2:最小依赖,供应链只有 3 个生产依赖
打开 package.json 会看到一个极干净的依赖区:
| 依赖 | 作用 |
|---|---|
commander |
CLI 命令框架 |
chalk |
终端彩色输出 |
detect-port |
端口占用检测 |
而真正干重活(驱动浏览器、录屏)的 agent-browser 被声明为可选 peerDependency("optional": true)。这意味着:
- 安装 ProofShot 本身就极快,供应链攻击面小到可以逐个审查;
- 缺少
agent-browser时不会导致npm install失败,而是运行期给出明确指引(见下文降级策略); - 配合
"engines": { "node": ">=18" },明确告诉用户最低运行环境。
克制是设计的一部分:能用 Node 标准库解决的(fs、path、child_process、net),一律不引第三方包,例如端口探测就在 src/utils/port.ts 里用原生 net.Socket 实现。
四、决策 3:tsup 双入口构建,一个包支持两种用法
tsup.config.ts 定义了同一个 package.json 里的两条构建链路:
- CLI 入口
bin/proofshot:单文件打包,注入#!/usr/bin/env nodeshebang,npm install -g后直接得到可执行命令; - 库入口
src/index:启用 code splitting 和.d.ts生成,供其他工具以编程方式 import。
两个入口都是 format: <a href="https://link.gitcode.com/i/a94adead83a27cd895f453675dfa8f89" target="_blank">'esm']、target: 'node18',并通过 define 把版本号 __PROOFSHOT_VERSION__ 在构建期注入 [src/version.ts,运行时 --version 无需再读 package.json。CLI 与库共享同一套 ESM 产物,避免 CJS/ESM 双构建带来的维护成本。
五、决策 4:优雅降级——非关键失败绝不中断会话
这是 ProofShot 最值得学习的一组实践。官方架构文档的原话是 "Graceful degradation everywhere"(处处优雅降级)。看几个真实场景:
- 缺少 ffmpeg:视频"死时间"自动裁剪只是锦上添花。src/commands/stop.ts 先探测
ffmpeg -version,不存在就打印一条安装提示并返回偏移量 0,会话照常完成;上传 PR 时则直接传.webm原片(src/commands/pr.ts)。 - 浏览器已关闭:src/browser/session.ts 的
closeBrowser用空catch静默处理——"浏览器可能早就关了,这没问题"。 - 无法采集控制台错误:
getConsoleErrors返回空串,最终报告里显示 "0 errors",而不是抛异常。 - 元素定位失败:exec 阶段的元素数据采集采用多策略回退(先按
id查,再按文本查),全失败就跳过 overlay 渲染——这是非关键路径。
所有外部命令都收口到 src/utils/exec.ts 的统一封装 ab(),带 30 秒默认超时和结构化错误类 ProofShotError,降级决策才有统一的"抓手"。
⚠️ 但降级有边界——关键路径必须硬性失败:录屏开始后若失败,src/commands/start.ts 会重试 3 次,仍失败就退出并给出 3 条排障指引。因为"视频证据"是这个工具的存在意义,此处绝不能"优雅"。
降级原则总结:可选项缺失 → 提示 + 跳过;非关键数据失败 → 空值兜底;关键能力失败 → 快速失败 + 明确指引。
六、决策 5:配置与状态的三个小心思
- 配置向上查找:
proofshot.config.json从当前目录逐级向上直到文件系统根(src/utils/config.ts),天然支持 monorepo 根目录放一份配置; - 缺省合并:文件不存在或 JSON 解析失败都回落到内置
DEFAULT_CONFIG(src/utils/config.ts),子项逐层合并,用户只需写想改的字段; - 会话状态跟着产物走:
.session.json不放在全局位置,而是存在各项目的产物目录里——不同项目可并行开多个会话,且proofshot clean一删了之,无残留。
配合 proofshot doctor 自检命令(src/commands/doctor.ts),用户可随时查看 agent-browser、ffmpeg 的路径与版本,把"环境缺什么"从猜谜变成一条命令。
七、彩蛋式扩展性:多语言错误识别只需加一行
src/utils/error-patterns.ts 用一张正则表覆盖 JavaScript、Python、Ruby、Go、Java、Rust 等 10+ 语言的错误日志特征,文件头注释直接写明扩展方式:往 PATTERNS 数组追加一个条目即可支持新语言。数据驱动 + 单点注册,是"最小依赖"思想在功能层的延续。
八、决策清单速查表
| 决策 | 做法 | 收益 |
|---|---|---|
| 模块化 | ESM-only + 显式 .js 导入 |
编译产物零歧义,无 CJS 兼容负担 |
| 依赖 | 仅 3 个生产依赖,重活走可选 peer dep | 安装快、供应链可审查 |
| 构建 | tsup 双入口(单文件 CLI + 切分库) | 命令行与编程集成一套产物 |
| 降级 | 缺失即提示、失败即跳过、关键路径快速失败 | 任何机器上都能"跑完" |
| 状态 | 会话状态存产物目录 + 配置向上查找 | 并行会话、monorepo 友好、干净删除 |
这套清单的底层逻辑只有一句话:把"能跑"放在第一位,把"完美"留给可选增强。对照自己的 CLI 项目逐条检查,你会发现大多数"环境跑不起来"的抱怨,都能在这份清单里找到对应的解法。


