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 支持的语义层，但核心引擎始终保持确定性和离线状态。