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 許可證發佈。