Groundtruth – 檢查你的AI編碼代理的聲明與Git差異

Groundtruth 是一個專為 Claude Code 設計的插件，旨在解決 AI 編碼代理常見的“完成幻覺”問題。它不依賴另一個大語言模型（LLM）來審查代碼，而是通過確定性方式將代理的聲明與實際的 Git 差異進行比對，從而驗證其工作是否真實完成。該插件作為本地鈎子運行，無需網絡連接或 API 密鑰，且不會讀取工作代碼，因此無法被説服改變裁決。

Groundtruth 的核心功能是在每個代理回合結束時生成一張裁決卡，檢查四個方面：誠實性（如虛假的測試通過聲明、佔位符、無聲無操作）、完整性（要求中的命名交付物是否出現在差異中）、規則合規性（項目文件中的確定性規則是否被違反）以及安全性（硬編碼密鑰、不安全的數據庫表等）。這些檢查完全基於 Git 差異和對話記錄，無需模型參與。

安裝過程極其簡單：在 Claude Code 中執行 /plugin marketplace add akahkhanna/groundtruth 和 /plugin install groundtruth@groundtruth，然後重啓即可。插件會註冊一個停止鈎子，在每個回合結束時自動運行。用户可以通過命令 /groundtruth 查看最新裁決，通過 /groundtruth-block on 啓用阻塞模式（默認僅警告）。阻塞模式下，若發現嚴重問題，插件會拒絕回合結束並返回糾正負載，最多允許兩次修復嘗試，否則升級至人工處理。

Groundtruth 提供三層執行等級：每回合警告、預提交鈎子（捕獲粘貼代碼）和 CI 門禁（基於分支差異，無法繞過）。其信任模型基於代理無法篡改的兩種輸入：對話記錄和 Git 計算的工作樹差異。對於更高安全性，建議將鈎子放置在獨立的信任域（如預合併 CI 門禁）中。

項目已進行嚴格測試，包括 440 個單元測試和紅隊演練，所有修復記錄在 FIXES.md 中。插件還包含 groundtruth-audit 命令用於掃描整個倉庫的代理債務，以及 groundtruth-rules 命令用於審查和批准從文檔編譯的規則。未來路線圖包括 LLM 支持的語義層，但核心引擎始終保持確定性和離線狀態。