ProofRun——AI 编码代理的本地验证凭证

ProofRun 是一个开源的命令行工具，定位是“AI 编码代理的本地验证凭证”。它并不判断代码是否正确，而是用密码学方式证明：在当前这份确切代码上，哪些检查真的运行过。用户不再需要从“我跑过而且通过了”和“我觉得它应该会过”两句话里靠文本猜真假——每一次声明的背后都对应一次真实观察到的执行。

问题背景很直接：AI 编码代理说“所有测试都通过”时，它可能真的刚跑过，也可能是在三次修改之前跑过，甚至只是根据“改动看起来没问题”推断测试应该会过。ProofRun 不试图让代理更诚实，而是让声明本身可核查。运行 proofrun run test -- pytest 会真正启动一个子进程执行 pytest，并记录退出码和耗时；之后再运行 proofrun status，每个检查只会显示四种状态之一：PASS、FAIL、STALE 或 NOT RUN。不存在“大概没问题”的第五种状态。

为了把结果绑定到代码状态，ProofRun 会计算当前 git HEAD、未提交改动（无论是否暂存、是否被跟踪）的 SHA-256 哈希，以及所有未跟踪且未被忽略文件的内容。只要代码改变一个字节，之前的结果就会自动变成 STALE，无需任何人记得去问“这次 PASS 还算不算数”。

设计原则明确：全程不调用任何 LLM，不使用 AI 来验证 AI，真正的机制是启动真实子进程并读取真实退出码；完全离线，零网络请求、零遥测、零账户；命令比对是参数级精确的 argv 数组，而不是展平后的字符串，因此声明为 pytest -k "foo bar" 的检查不会被看起来相似的命令冒充。

ProofRun 也划清了不做什么的边界：不解析测试输出、不评判代码质量、不自动修复问题。项目本身由 Claude Code 在人类指导下编写，并在首次发布前接受了多轮独立的只读对抗性审查。审查发现了一个真实漏洞：错误的 shell 引号可以让检查静默运行零个测试却仍然报告 PASS。团队用真实复现验证了修复，而不是仅凭“看起来合理”就接受修补。

使用上，proofrun init 生成 .proofrun.yml；proofrun run-all 依次运行所有声明的检查；proofrun status --strict 在必需检查不是 PASS 时以非零退出码阻断；proofrun report --json 输出完整报告。配置中每个检查用 argv 数组声明，例如 [pytest] 或 [npm, run, build]，并可用 required: true 标记为强制门禁。

GitHub Action 会自己检出 PR 的 head 提交，而不是信任调用工作流已检出的内容，避免拿到 GitHub 合成的 merge-preview 提交；它还会清除 PR 分支上可能带来的 receipt.json，下载经校验和验证的二进制，真实运行全部检查后再用 status --strict 把关。已知局限是它无法防止同一个 PR 同时弱化 .proofrun.yml 本身，比如移除或调松某个检查；Action 只会在配置与基准分支不同时给出构建注释警告，不会阻断，需要人工审查这部分 diff。

路线图方面，v0.3 计划支持 pytest、Jest、JUnit 等测试运行器的结构化输出；签名、防篡改的收据正在规划中；保护 .proofrun.yml 不被同一 PR 弱化的能力也在考虑中。项目以 MIT 许可证发布。