开源 · MIT 协议 · GO 语言

运行,且带凭据。

给 AI 编程 Agent 用的本地验证凭据。ProofRun 不去主观评判你的代码写得对不对——它只用密码学指纹证明,哪些检查真的在你现在这份确切的代码上跑过。

go 1.22+linux · macos · windows零网络请求自带 github action

问题在哪

AI 编程 Agent 说 “所有测试都通过了”。这句话是真的吗?

也许是。它上一次真的跑测试的时候,这句话确实是真的。但那可能是三次修改之前的事了。Agent 甚至未必记得自己有没有真的跑过——它可能只是在推断“这个改动看起来没问题,测试应该还能过”。光看这句话本身,你没法分辨 “我跑了,而且真的过了” 和 “我觉得应该会过” 之间的区别。

ProofRun 补的就是这个缺口。 不是靠让 Agent 更诚实——而是让这句话本身变得可以被客观核查。

工作原理

每一条检查结果都绑定着你当前代码状态的指纹:git commit,加上所有未提交改动(不管有没有 stage、有没有被 git 跟踪)算出的哈希。哪怕只改了一个字节,结果都会自动变成 STALE(已失效)。不需要谁刻意记得去问“这个 PASS 现在还作数吗”。

proofrun 状态演示
$ proofrun run test -- pytest
...
test: pass (exit 0, 1841ms)

$ proofrun status
test PASS (exit 0, 1841ms)

# 这之后代码被改动了——无论是 Agent 改的还是人类改的

$ proofrun status
test STALE (last run: pass, exit 0 — code changed since)

为什么用它,而不是盲目相信 Agent

●全离线,不调任何大模型

ProofRun 不用 AI 去验证 AI。它启动真实的系统子进程并读取真实的退出状态码——这就是全部机制。

●四个状态,绝不靠猜

PASS、FAIL、STALE、NOT RUN——每一个状态都来自真实的执行观察,或明确记录的未执行。绝无第五种“大概没问题”。

●纯本地运行,隐私安全

零网络请求、零数据上报、零账号绑定。你的代码永远不离开本地机器。

●参数精确匹配,非字符串模糊匹配

声明为 pytest -k "foo bar" 的检查,绝不可能被形式相似的命令冒充——ProofRun 严格比对真实的 argv 参数数组。

快速开始

快速安装与使用
# 安装(Linux amd64;其他平台见 Release 页面)
$ curl -L https://github.com/yebiguo/proofrun/releases/latest/download/proofrun_linux_amd64.tar.gz | tar xz

# 或直接从源码构建
$ go install github.com/yebiguo/proofrun/cmd/proofrun@latest

$ proofrun init # 生成 .proofrun.yml 配置
$ proofrun run test -- pytest # 真正运行 pytest 并绑定结果指纹
$ proofrun status --strict # 若有任何未通过项则非零退出

把 status --strict 配置到 pre-commit hook 或 CI 门禁中。项目自带开箱即用的 GitHub Action——它会严格基于 PR 的目标 commit 重新执行所有检查,绝不盲信签入的凭据。

防篡改凭据 (Receipt)

每一个存储的结果都使用机器本地私钥进行 HMAC-SHA256 签名。手工修改过的 receipt.json——哪怕指纹完全对得上——也无法通过校验,绝不会显示虚假的 PASS。防篡改旨在防御恶意或失控的 Agent 伪造结果,这正是它诞生的初衷。

有意不做的功能:解析测试输出内容、评判代码质量、自动修复代码。ProofRun 只证明“跑过什么”,仅此而已。