Truth Benchmark Vibe 项目

Truth Benchmark 是一款用于检测代码与文档一致性的开源基准测试工具，能够自动判断某段代码是否真的实现了它所声称的功能。软件开发中，文档、注释和 README 里描述的功能与实际代码行为之间常常存在偏差——开发者修改了代码但忘记更新文档，安全声明在代码移除保护措施后仍然保留，AI 生成的描述描述的是代码「应该」做的事而非「实际」做的事。这种偏差在生产环境中会造成真实的安全风险，安全团队的审计往往只查文档不查代码，而基于文档训练出来的 AI 模型则会继承这些谎言。Truth Benchmark 的出现正是为了解决这个问题。

核心功能

自动化 Claim vs Code 验证：用户只需提供一条功能描述（Claim）和对应的代码片段，工具就能判断代码是否真的实现了该功能，输出 MATCH（匹配）或 LIE（不符）两种结论。例如，输入描述「删除文件」配合代码 os.remove(path)，结果为 MATCH；而配合代码 open(path, "w").write("")，结果为 LIE，因为后者只是清空文件而非删除。

三种基线模型开箱即用：工具自带三套验证基线，适合不同场景。基线一为规则引擎，无需安装任何依赖，输入即运行，作为验证能力的下限基准；基线二为语义模型，基于 all-MiniLM-L6-v2 句向量，测量描述与代码之间的语义相似度，80MB 大小、CPU 友好；基线三为大语言模型，通过 Ollama 本地部署 llama3.1:8b 或接入任意 OpenAI 兼容 API，准确率最高。

标准化评估框架：内置 evaluate 模块和 print_report 函数，用户只需定义一个接收 claim 和 code 两个参数、返回 MATCH 或 LIE 的验证函数，即可将自己的模型接入评估流程，获得精确率、召回率和 F1 分数等标准化指标。

多语言覆盖的数据集：附带的 dataset.csv 包含 52 个经过标注的样本，涵盖 Python、JavaScript、Go、Rust、Java、C#、SQL 七种编程语言，涵盖了操作符错误、常量错误、缺失加密验证、排序方向错误、协议错误等典型「文档与代码不符」场景。

持续贡献机制：项目接受任何语言的代码示例贡献，要求每个 Claim 同时提供 MATCH 和 LIE 两个版本，且 LIE 版本必须足够真实可信，是实际开发中容易犯的错误。项目特别呼吁提交「隐蔽型谎言」——那些代码几乎做对但没有完全做对的场景，这类情况在生产中最危险也最难检测。

技术实现

Truth Benchmark 的技术架构分为数据层、模型层和评估层三层。

数据层以 dataset.csv 为核心，每条数据包含 claim（功能描述）、code（代码片段）和 label（MATCH/LIE 标注）三个字段，覆盖了软件开发中最典型的文档代码偏差类型。

模型层实现了三种验证策略。规则引擎通过正则匹配和高频错误模式识别来判断一致性，实现最简单、零依赖，但覆盖面有限。语义模型将 claim 和 code 分别编码为向量，测量两者在向量空间中的余弦相似度，能够捕捉一定程度的语义关联。LLM 方式则借助大语言模型的推理能力判断代码行为，在验证准确率上表现最好，但对算力和网络有要求。

评估层对任意验证器在完整数据集上运行，计算总体准确率以及对 MATCH 和 LIE 两类样本的精确率、召回率和 F1 分数，最终生成结构化的评估报告。

快速上手

第一步，克隆仓库并安装依赖：git clone https://github.com/02zerocool/truth-benchmark && cd truth-benchmark && pip install pandas

第二步，运行完整评估流程：python pipeline.py — 这会使用默认的 LLM 基线对整个数据集进行评估并输出报告。

第三步，测试单个 Claim：对任意 claim 和 code 组合调用预测接口，查看匹配结果：python predict.py "encrypts password before storing" "db.save(user, bcrypt.hash(password, 12))"，输出为 MATCH。

第四步，自定义验证器并评估：在 my_verifier 函数中编写自己的验证逻辑，然后调用 evaluate 函数获得标准化报告。

适用人群

本工具的目标用户包括：关注代码与文档一致性的安全团队，可将其集成到 CI/CD 流程中自动检测文档偏差；开发过程中需要快速验证代码实现是否符合设计意图的工程师；研究代码可信性和 AI 代码生成质量的研究者；以及任何希望自己项目 README 和文档始终与代码保持同步的开发者团队。