Agent Countercheck — 让 AI 的「已完成」有据可查

技能简介

Agent Countercheck 是一款专门用来核实 AI 编码 Agent 是否真的把活干完的验证工具。AI 经常声称「改好了，测试全过」，实际却跳过了失败的测试、改掉测试让它通过，甚至根本没运行。Countercheck 不参与写代码，它只做裁判：从改动之前的基线版本读取你写好的检查项，把 Agent 改过的受保护文件（例如测试）还原，再在干净副本里重新跑一遍检查，最后生成一份带 SHA-256 封印的回执，写明声明内容、实际跑了什么、输出是什么、Agent 动了哪些不该动的文件，以及最终判定。它本身不含任何 AI 模型，就是一个像 git、pytest 一样的普通程序。

核心能力

1. 基线锁定检查项：检查清单从改动前的版本读取，Agent 无法在执行过程中弱化或删除判定标准。
2. 受保护文件还原：把 Agent 修改过的测试等受保护文件从基线恢复，再放进干净副本中执行。
3. 沙箱执行：在 macOS 上使用系统沙箱运行检查，默认禁止联网、只允许写入检查目录，检查项可显式申请放开。
4. 三态判定：只输出「已验证」「未通过」「无法判定（附原因）」，绝不含糊；失败提示不会因为一句解释就变成通过。
5. 封印回执：每次运行生成 JSON 回执并以 SHA-256 封印，任何人可以复核，回执被改动会被识别出来。
6. 钩子接入：为 Claude Code / Cortex Code 提供停止钩子，为 Hermes Agent 提供验证前钩子；其他 Agent 与 CI 直接调用命令行即可。
7. 可视化与报告：ui 打开本地运行看板，report 生成可附到 PR 的离线 HTML 报告。

安装配置

1. 任选其一安装：pip install agent-countercheck、uv tool install agent-countercheck，或使用官方 Homebrew tap、安装脚本、直接下载二进制。
2. 安装后执行 countercheck --version 确认命令可用；Windows 需要额外安装 Git for Windows，因为检查依赖 git 与 sh。
3. 在项目内执行 countercheck init 生成 .countercheck/checks.toml 模板，按需填写检查项并提交到仓库。
4. 接入 Agent：Claude Code 在设置中加入 countercheck hook claude-stop，Hermes 使用 countercheck hook hermes-pre-verify。

使用步骤

1. 进入项目：切换到 Agent 实际修改的那个 git 仓库目录，不要在家目录或工具安装目录里执行。
2. 写检查：编辑 checks.toml 定义检查项与命令，提交到仓库，让它成为基线的一部分。
3. 让 Agent 干活：正常让 Claude Code、Codex、Cursor 等 Agent 完成任务。
4. 执行核实：运行 countercheck verify --claim "已修复折扣 bug，测试全过" --agent claude-code，工具会在干净副本里重跑检查。
5. 看判定与回执：返回「已验证」即放行；「未通过」会把失败检查回推给 Agent 继续修（默认最多三轮）；同时可用 show 复核回执封印，用 report 附到 PR。

适用场景

1. 让 AI 自动修 bug、跑测试，但需要确认测试没有被偷偷改掉。
2. 在 CI 中用 verify --base origin/main 卡住「假完成」的提交。
3. 多 Agent 协作或长任务链中，需要独立第三方判定每一段产出。
4. 对外交付项目，需要可审计、可复核的验证证据。
5. 评估不同模型的可靠性，统计虚假「已完成」声明的比例。

适用人群

适合把编码 Agent 纳入正式交付流程的工程团队、需要审计证据的技术负责人、以及做 Agent 可靠性研究的开发者；对只在本地随手写脚本的用户偏重。

工作原理

Countercheck 把「谁执行」和「谁判定」彻底分开：判定标准来自基线版本，执行发生在隔离的干净目录与沙箱中，Agent 的日志和自述从不作为证据。运行结束后它把声明、检查项、输出、被改动文件与判定结果写成回执并计算哈希封印，通过退出码（0 通过、2 未通过、3 无法判定）把结论交给钩子或 CI。官方基准测试中，GPT 6.1 在 87 次运行里的虚假完成声明从 7 次降到 3 次，不可能通过的题目从 6 次降到 0 次，单次运行中位数只增加约 1 秒。

官方链接

• PyPI 页面：https://pypi.org/project/agent-countercheck/
• 开源仓库：https://github.com/datacrate360/agent-countercheck
• 项目站点：https://countercheck.datacrate360.ai
• 许可证：MIT
• 当前版本：0.5.3（Rust 实现，支持 macOS / Linux / Windows）