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 許可證釋出。