你是不是也遇到过这种情况AI 编程助手帮你写好了整整一个模块代码结构完整、注释规范、命名讲究你几乎准备直接提交了。结果仔细一查发现它调用了一个你从没听过的 API再顺着文档去找这个 API 三年前就被移除了。或者更隐蔽一点它在 requirements 里“认真”地加了一个依赖PyPI 上确实能看到这个名字但包作者是一周前注册的用户。AI Agent 编程工具比如 Claude Code、Cursor已经进入日常开发流程。于是AI 在代码里的“编造”也从聊天机器人的无害胡说升级成一种直接影响代码库质量、依赖安全甚至线上稳定性的工程风险。Ledgerful 正是冲着这个问题来的一个运行在本地、专门捕捉“AI 在代码里发明东西”的工具。这篇文章要做三件事第一拆解 AI 代码幻觉到底长什么样为什么常规的语法检查、code review 和单元测试都很难拦住它第二讲解 Ledgerful 这类工具的核心设计——为什么它把“生成”和“证明”分开以及账本机制在验证流程中的作用第三给出一个可以独立跑起来的最小本地检测器实现包括依赖核验、API 存在性检查和语法检查并把它接进 pre-commit 和 CI。如果你正在用 AI 编程助手或者正准备在团队里引入 AI Agent 开发流程这篇文章值得读完。读完之后你会对“AI 生成的代码能否被信任”有一个更实际的判断标准也能在自己项目里快速搭出一个初级版本的“幻觉拦截器”。1. AI 代码幻觉为什么这么快就变成了工程问题1.1 从“内容胡说”到“代码事故”前两年我们谈 AI 幻觉主要谈的是文本生成——AI 写一篇技术文章可能把不存在的论文引用编得煞有介事。那最多算“内容风险”你只要不拿去投稿损失有限。但代码生成把这个问题完全放大了。代码幻觉一旦进入仓库它会变成真实的进程、真实的网络请求、真实的依赖树和真实的线上事故。AI Agent 编程的典型流程是你给它一个需求它生成一段或多段代码然后你 review、测试、合入。问题在于Agent 生成代码的“置信度”很高它不会在代码旁边标注“这段我不确定”。一个没见过AutoTuner类的模型依然会把它写得像真的一样参数合理、调用链完整、返回类型对得上。从文本上看它和正确的代码几乎无法区分。这里的核心矛盾是AI 生成的代码外在形态越来越像人写的代码但它的“事实依据”并没有被任何东西保证。人类程序员写错代码通常是因为疏忽或理解偏差AI 幻觉则是一种“自信的编造”——它不是在犯错而是在生成一个语法正确、结构完整、但外部事实可能完全不存在的东西。这个区别非常重要因为它决定了我们不能沿用传统的方式去审查 AI 代码。1.2 为什么常规检查兜不住有人会说项目里有 linter、有编译、有单元测试、有 code review这些机制加起来难道还拦不住幻觉先说编译和语法检查。语法检查只能保证代码“能被解释器读出来”但幻觉代码往往是语法完全正确的。你调用一个不存在的 APIPython 解释器只有在那行代码执行到的时候才会抛AttributeError如果这个分支在测试里没覆盖到它就会安静地在生产环境里炸开。再说 code review。它的核心弱点是“自动化偏见”当一段代码结构完整、命名规范、注释说明清晰时reviewer 的警惕性会明显下降。更麻烦的是很多幻觉代码表面上的正确性本来就比人类错误更难识别——至少人类同事写错时会犹犹豫豫AI 生成时却永远理直气壮。你很难对一个“看起来合理的东西”保持足够的怀疑。最后是单元测试。测试能验证“这个函数对给定输入是否返回预期输出”但很难验证“这个函数所依赖的外部世界是否真实存在”。import some_made_up_package之后如果代码路径根本没执行到测试全部绿了也不会发现依赖是假的等到部署时包管理器才报错才是最典型的“幻觉漏网现场”。所以我们需要一个独立于现有检查体系的验证层机制上不假设 AI 生成的内容是真的而是用账本、证据链和自动核验去确认它的真实性。这正是 Ledgerful 想做的事。2. 先弄清楚AI 在代码里的“编造”到底长什么样2.1 五种常见幻觉类型要把幻觉检测做好先得知道幻觉有哪些形态。结合我在项目里见过的案例AI 代码幻觉大致可以分成五类幻觉类型典型表现为什么难以发现检测思路虚构 API调用不存在的函数、类、方法语法正确运行到对应代码行才报错文档索引、类型系统、运行时反射核验虚假依赖添加不存在的包或真实但可疑的包代码不执行到对应 import 就不会暴露查询 PyPI 或内部包源核对包名与版本过期用法使用已删除或废弃的接口旧文档在网上大量存在模型容易“学习”到对照版本化文档和发布说明虚假配置写入不存在的配置项或权限策略很多服务会静默忽略未知配置不报错用配置 schema 做白名单校验自洽但错误的业务逻辑逻辑完整、方向错误测试按错误的业务规则写结果全部通过领域规则校验人工复核五类幻觉有一个共同特征它们都不是“明显的语法错误”而是“语法正确但事实不成立”。这也解释了为什么传统工具链对它们基本失灵。2.2 一个看起来非常真实的错误示例我们用一个假想的例子来感受一下。假设 AI 生成了一段“自动调参”代码from future_ml import AutoTuner tuner AutoTuner(modebayesian) result tuner.optimize( datasetiris, target_metricaccuracy, max_trials50, ) print(result.best_params)这段代码的问题在于future_ml这个包不一定存在AutoTuner类也不一定存在于任何真实包里optimize方法的签名、best_params属性都可能是模型“顺理成章”编出来的。但从阅读体验看它变量命名合理、参数结构完整、函数调用链自洽——如果 AI 把它作为“参考实现”给你你可能只会疑惑“我怎么没用过这个库”。这才是 AI 代码幻觉最麻烦的地方它编造的不是一个明显错误的fake_function()而是一整套相互自洽的假象。检测工具要做的是去验证这些“合理”背后的“事实”是否真实存在。3. Ledgerful 的核心设计把“生成”和“证明”分开3.1 账本到底记什么Ledgerful 这个名字很有意思。Ledger 是“账本”的意思。它把 AI 生成代码的过程看成一笔一笔“待记账的交易”模型生成了什么、来自哪个会话、做了哪些检查、检查结果如何、有没有人复核过——这些信息按条目记录形成一条可追踪的验证链。这与传统 linter 有本质区别。linter 是“发现问题就报错”Ledgerful 是“把问题留在证据链里”。它不追求一次检查就把所有问题改正而是追求每一段 AI 生成代码都有据可查后续任何人都能回溯这段代码为什么被信任、依据是什么。一个账本条目至少应该包含这些字段来源信息哪个 AI 工具、哪次会话、哪个 prompt 生成。验证项语法、依赖、API、配置、运行行为。验证证据检查器返回的原始输出比如 PyPI 的 404、AST 解析失败的行号。状态通过、警告、失败、待人工复核。人工复核记录谁看过、结果如何、是否合入。3.2 分层验证策略从工程实践的角度看幻觉验证可以分成四个层次L1 静态检查语法解析、格式检查、AST 结构分析。最快、最便宜但只能抓最表面问题。L2 事实核验去包索引确认依赖是否存在、去文档或运行时确认 API 是否存在、用 schema 校验配置项。这是幻觉检测的关键层。L3 行为验证在隔离环境里运行代码或测试观察是否有异常网络请求、异常文件写入等行为。L4 人工复核模型无法自己证明的领域规则标记后交给人类工程师确认。Ledgerful 这类本地工具的重点一般放在 L1 和 L2因为它们在本地就能完成大部分自动化不需要频繁触发昂贵的外部模型评测也不需要把代码交给第三方服务。3.3 本地优先原则“本地工具”是这个项目定位的关键词。代码审查本来就应当发生在本地仓库和 CI 环境里而不是把整个代码库发给第三方服务去“审查”。本地优先意味着三件事代码不出仓库在线核验只发送必要信息比如包名所有结论沉淀为本地可审计的记录。对于看重代码安全和企业合规的团队这一点尤其重要。4. 构建最小可用版本环境准备与模块拆解4.1 环境准备本文的示例使用 Python 3.10 以上版本因为要用标准库的ast解析和importlib.metadata。你需要准备一个 git 仓库最好已经初始化。Python 3.10 环境。pre-commit可选用于本地 Git 钩子集成。能够访问 PyPI 的网络环境用于包核验或者配置内部代理源。为了最大程度降低复现成本最小版本不引入任何第三方依赖全部使用 Python 标准库。这也符合工具定位它只是一个本地校验器不承担重型分析任务。4.2 项目结构一个最小可用版本可以这样组织ledgerful-demo/ ├── ledgerful/ │ ├── __init__.py │ ├── cli.py # 命令行入口接收文件并调用验证器 │ ├── collector.py # 获取 git 暂存区或指定目录的 Python 文件 │ ├── verifiers/ │ │ ├── __init__.py │ │ ├── syntax_check.py # L1 静态检查AST 语法解析 │ │ ├── deps_check.py # L2 事实核验依赖包与 import 核验 │ │ └── api_check.py # L2 事实核验API 存在性检查 │ ├── ledger.py # 生成/更新账本记录 │ └── reporters.py # 汇总输出格式化打印 ├── .pre-commit-hooks.yaml └── pyproject.tomlcollector.py负责收集“要检查的文件”verifiers目录放各层检查器ledger.py负责把结果写入账本reporters.py负责任务结束后的汇总打印。这个结构的好处是每个验证器都可以独立添加和测试后续要支持 JS、Go 或者其他语言时只需要新增对应验证器。5. 核心代码实现一个本地“代码幻觉检测器”5.1 命令行入口与 Git 暂存区采集先写命令行入口。为了让它能在 pre-commit 里工作我们支持两种模式指定文件路径或者使用--staged参数读取 git 暂存区中的 Python 文件。# ledgerful/cli.py import argparse import pathlib import subprocess import sys from ledgerful.verifiers.syntax_check import syntax_check from ledgerful.verifiers.deps_check import deps_check from ledgerful.verifiers.api_check import api_check from ledgerful.ledger import append_entry from ledgerful.reporters import print_report def get_staged_python_files() - list[str]: 获取 git 暂存区中新增、修改、复制、重命名的 Python 文件。 result subprocess.run( [git, diff, --cached, --name-only, --diff-filterACM], capture_outputTrue, textTrue, checkTrue, ) files [] for line in result.stdout.splitlines(): if line.endswith(.py) and pathlib.Path(line).exists(): files.append(line) return files def run_checks(file_path: str) - dict: 依次运行所有验证器返回该文件的检查结果。 results { file: file_path, checks: [], status: pass, } syntax_result syntax_check(file_path) deps_result deps_check(file_path) api_result api_check(file_path) results[checks] [ {name: syntax, **syntax_result}, {name: deps, **deps_result}, {name: api, **api_result}, ] if any(item[status] fail for item in results[checks]): results[status] fail elif any(item[status] warn for item in results[checks]): results[status] warn return results def main() - int: parser argparse.ArgumentParser( descriptionLedgerful - local AI hallucination checker ) parser.add_argument(targets, nargs*, help要检查的文件或目录) parser.add_argument(--staged, actionstore_true, help只检查 git 暂存区) args parser.parse_args() targets args.targets if args.staged: targets get_staged_python_files() if not targets: print(No Python files to check.) return 0 all_results [] exit_code 0 for file_path in targets: result run_checks(file_path) all_results.append(result) append_entry(result) if result[status] fail: exit_code 1 print_report(all_results) return exit_code if __name__ __main__: sys.exit(main())这段代码的逻辑很直接get_staged_python_files调用 git 命令拿到暂存区文件run_checks依次执行三个验证器append_entry把结果写入账本最后统一打印。真正容易踩坑的地方是如果你的 repo 里有很多 Python 文件都在暂存区每个文件都去跑一遍 PyPI 网络查询会非常慢。实际使用中建议把“在线核验”放到 CI 阶段本地只跑语法和静态检查或者为常见的包名做一层缓存。5.2 语法检查器用 AST 抓最表层的错误接下来是语法检查器。使用ast.parse而非compile是因为ast.parse可以直接定位出错的行号和列号便于在账本里保存结构化证据。# ledgerful/verifiers/syntax_check.py import ast from pathlib import Path def syntax_check(path: str) - dict: 检查 Python 文件语法是否合法。 try: source Path(path).read_text(encodingutf-8) ast.parse(source, filenamestr(path)) return {status: pass, detail: syntax ok} except SyntaxError as e: return { status: fail, detail: fSyntaxError at line {e.lineno}: {