ProofRun：为 AI 编程代理提供可验证的本地检查凭证

ProofRun 是一款本地命令行工具，专门解决 AI 编程代理在汇报测试结果时「真假难辨」的问题。当代理说「所有测试通过」时，用户往往无从判断这是真实执行后得出的结论，还是代理在改动代码后凭印象推断的乐观估计。ProofRun 不试图让代理「更诚实」，而是让代理的声明本身可被独立核查。

核心机制：用 git 指纹绑定检查结果

ProofRun 的做法是：每当一次检查（如 pytest、npm run build）真实执行后，工具会把退出码、执行耗时与「当前代码状态指纹」绑定并保存。这里的指纹由 git HEAD 提交哈希，加上未提交改动（已暂存、未暂存、未跟踪但非 .gitignore 排除的文件）的 SHA-256 哈希共同组成。任何一行代码、一个字节被修改，指纹就会变化，对应的历史结果自动翻转为 STALE 状态。

命令示例：

proofrun run test -- pytest：真实执行 pytest，并把结果绑定到当前代码状态；
proofrun status：输出每个检查的 PASS / FAIL / STALE / NOT RUN；
proofrun status --strict：若有必需检查不是 PASS，则以非零退出码中断；
proofrun report --json：输出机器可读的完整报告。

设计取舍：不做的事同样重要

工具刻意划清了边界，以避免「用 AI 验证 AI」的循环：

不调用任何 LLM，不解析测试输出，不评判代码质量，不自动修复；
全程离线，零网络请求、零遥测、零账号；
command 字段是 argv 列表而非 shell 字符串，工具直接启动子进程读取真实退出码，不走 shell 层；
状态只有四种——PASS、FAIL、STALE、NOT RUN，没有「应该没问题」这种含糊值。

配置文件 .proofrun.yml 用 YAML 列出每个检查的名称、命令数组与是否必需，可直接接入 pre-commit 或 CI 门禁。

自审与已知局限

ProofRun 自身由 Claude Code 在人工指导下编写，发布前经历了多轮只读对抗审查。审查发现其命令比较曾被一个未正确转义的 shell 参数绕过：检查看似通过，实际零测试运行。完整复现与修复过程记录在仓库的 docs/case-study.md，每处修复都在真实复现上验证后才合并。

项目同时内置 GitHub Action，可在 PR 上独立 checkout、清理 PR 自带的 receipt.json、下载校验和后的二进制并重新执行所有检查，再以 status --strict 作为门禁。Action 不会信任 PR 分支里 check-in 的任何旧凭证。

不过官方也明确披露一个已知限制：.proofrun.yml 本身在同一 PR 内可能被削弱——同一个 PR 既改代码又放宽检查命令时，Action 只会忠实地重新跑宽松后的版本，并通过 build annotation 提醒，不会因此拦截。这部分需要依赖人工 review 配置变更来兜底。

当前阶段与路线图

当前版本为 v0.2.0，提供 Linux amd64 预编译二进制，也可用 go install 从源码构建。后续 v0.3 计划加入对 pytest、Jest、JUnit 等常见测试运行器的结构化输出支持；签名化、防篡改的凭证也在规划中，尚未进入设计阶段。