AI 编程助手写出来的代码，表面看起来非常完整，但里面很可能藏着不存在的包、不存在的 API、不存在的环境变量。社区把这种问题叫做“AI 幻觉”，落到代码上就是模型根据上下文补全了一个“听起来合理”的符号，而这类符号在本地依赖、项目文件或任何真实文档里都找不到。Ledgerful 是一个为了解决这个问题而生的小型本地工具。它不做代码生成，也不做自动修复，只负责把代码里引用的每个外部符号当成一条账目记录下来，然后和本地已知事实做核对，最后把可疑条目列出来，方便开发者逐条确认。这篇文章用一个可以本地运行的最小实现，把 Ledgerful 的检测机制讲清楚。
1. 先理解 AI 代码幻觉为什么需要“账本式核对”
1.1 幻觉在代码里的几种典型表现
AI 编程模型生成代码时，会基于训练数据中的统计模式补全内容。训练数据里经常出现requests、os、json这类常见模块，模型会倾向于把它们放在代码里，这部分通常没有问题。真正危险的是模型创建了一个“在数据分布上很像真实 API”的符号，而这个符号在任何真实环境中都不存在。
实际项目里，代码幻觉可以归成几类。
| 幻觉类型 | 典型写法 | 为什么难以发现 |
|---|---|---|
| 不存在的第三方包 | import fake_magic_lib | 本地没有这个包，但代码逻辑看起来完整 |
| 不存在的函数或类 | train_model_from_scratch(...) | 工具类、模型类数量多，人眼不会逐行核对 |
| 不存在的命令行参数 | subprocess.run(["deploy", "--force-all"]) | 命令行参数没有统一注册表 |
| 不存在的路径或配置项 | Path("/etc/myapp/secret.conf") | 路径和配置项通常只在运行时报错 |
| 不存在的环境变量 | os.getenv("CLOUD_REGION_ID") | 环境变量来源隐蔽，缺少声明文件 |
这些问题的共同点是：代码仍然能通过语法检查，甚至能通过静态阅读，只有在真正运行到对应分支时才会暴露。更麻烦的是，AI 生成的代码往往一次涉及很多文件，人工逐行 review 的成本很高，而且模型生成的内容在语言层面非常流畅，容易让人失去警惕。
1.2 人工 review 为什么不够
如果把“找幻觉”完全交给人工，就相当于让开发者对每一个 import、每一个函数调用、每一条命令都做一遍本地核实。对于小型 demo 还能接受，一旦进入真实业务仓库，代码量变大，上下文变长，人工核对很容易漏掉隐藏在某个分支里的错误符号。
另一个问题是 review 的不可重复性。上次碰巧查出了问题，不代表下次同样能发现。代码审查依赖人的经验、注意力甚至当天的状态。本地工具则可以把核对过程固化成规则：先提取引用，再和事实源比较，最后输出报告。同样的输入一定会得到同样的结果，规则更新后可以重新扫描历史代码，这种可回放能力是人工 review 不具备的。
还有一层原因：AI 编程助手往往在生成代码时给出了“看起来合理”的解释，开发者容易把这种解释当作证据。比如模型可能写一段注释“这里调用内部工具库的初始化函数”，实际上这个内部工具库根本不存在。只有把代码里的符号列出来，逐个和本地事实核对，才能发现模型描述和真实环境之间的差距。
1.3 账本视角：每条引用都是一笔待审计的条目
Ledgerful 这个名字来自 ledger，意思是账本。账本式的检查逻辑很简单：代码里出现的每一个外部引用，都是一笔需要确认的记录。
- 导入了一个模块，就要确认这个模块能在当前环境里被找到。
- 调用了一个函数，就要确认这个函数定义在当前文件里，或者从某个真实导入的模块里来。
- 写了一条命令，就要确认这个命令在 PATH 中或项目脚本里真实存在。
- 访问了一个路径或环境变量，就要确认它在项目配置、部署脚本或系统环境中被定义过。
这个思路和财务审计很像。审计不是去判断每一笔交易道德上“对不对”，而是核对凭证、流水和库存是否对得上。Ledgerful 把代码当作流水，把本地文件系统、已安装依赖、项目配置当作凭证，逐条核对，最后把对不上的记录标记出来。
注意：这里的核心目标不是证明代码一定正确，而是把“没有被证明正确”的部分暴露出来，让开发者做最后判断。
2. 设计检测模型：代码里的引用如何变成一条可验证记录
2.1 事实来源要分层级
一个本地工具能核对的“事实”来自哪里，决定了它的能力边界。Ledgerful 会优先使用成本最低、最可靠的事实源，也就是本地环境本身。
可以把事实来源分成四层：
| 层级 | 事实来源 | 例子 | 可靠性 | 获取成本 |
|---|---|---|---|---|
| 1 | Python 标准库模块清单 | sys.stdlib_module_names | 高 | 极低 |
| 2 | 当前虚拟环境已安装的包 | importlib.metadata | 高 | 低 |
| 3 | 项目内部文件和符号 | 目录结构、本文件内定义函数、内部模块 | 中高 | 低 |
| 4 | 外部文档或团队知识库 | 内部域名、内部配置项、业务白名单 | 中 | 高 |
设计原则是：本地事实优先，外部知识库可选。Level 1 和 Level 2 是绝对事实，Level 3 要根据项目根目录做路径判断，Level 4 则需要人工维护规则。
这在工程上的意义是：默认情况下工具不需要访问网络，也不需要登录远程服务，只靠本地环境就能完成大部分幻觉检测。对于包含敏感代码的仓库，这同时降低了数据和隐私风险。
2.2 Ledger 记录结构
每个被扫描出来的引用，最终都会变成一条 JSON 记录。记录里除了“符号叫什么”，还要包含“在哪一行”“为什么被提取出来”“当前状态是什么”“依据是什么”。
一个最小记录结构如下：
{ "id": "4f3a1c2b-8d2e-4f41-9c1b-123456789abc", "file": "examples/bad_entry.py", "line": 3, "column": 7, "kind": "module", "name": "fake_magic_lib", "evidence": "import fake_magic_lib", "status": "suspicious", "reason": "not_found_in_local_index", "checked_at": "2025-01-01T12:00:00+08:00" }字段含义：
kind：引用类型，比如module、function、command、path、env_var。name：被引用的具体名称。evidence：从源代码里截取的证据片段，方便后续人工复核。status：验证结果，状态机见下一节。reason：标记为什么被判定为当前状态，方便排错。
把记录写成 JSON 而不是直接打印文本，是为了后续能接入自动化流程。IDE 插件可以读取 JSON 在编辑器里标红，CI 可以解析 JSON 决定是否阻断合并，报告生成器可以把 JSON 转成 Markdown 或 HTML。
2.3 状态机：verified / suspicious / unknown
Ledgerful 的基本状态不需要设计得太复杂，三个状态就足够用。
verified：已经找到可靠的事实来源。比如模块名存在于标准库清单中，或者函数定义存在于当前文件的 AST 中。suspicious：没有找到事实来源，而且类型比较敏感。比如某个 import 找不到对应包，某个命令不在白名单里，这种状态值得人工确认。unknown：无法判断。比如字符串里的命令是动态拼接的，或者调用了getattr(obj, name)，这类引用无法靠静态扫描确定，工具选择“不做结论”更稳妥。
状态转移规则很简单：先尝试从低层事实源查证，查到就标记为verified；查不到并且不能确定动态性，标记为suspicious；明显动态或带变量拼接，标记为unknown。这个状态设计能防止扫描器因为信息不足而乱报。
2.4 一个最小规则配置
为了让使用者能控制哪些内容被忽略、哪些命令被信任，需要一个规则文件。这里使用 JSON 而不是 YAML，主要是不引入第三方库：
{ "ignore_patterns": [ "__init__", "test_", "conftest" ], "known_commands": [ "pip", "python", "ls", "cat", "grep", "git" ], "known_paths": [ "/tmp", "/usr/local/etc" ], "project_roots": [ "src", "app" ] }这个文件后续会作为扫描器的输入参数，用来控制行为。ignore_patterns跳过指定文件或目录，known_commands直接信任常用命令，known_paths避免常见路径被误报，project_roots告诉工具哪里算项目内部代码。
3. 环境准备与最小项目结构
3.1 运行环境与依赖
Ledgerful 的最小实现只依赖 Python 3.10 及以上版本的标准库。选择 3.10 是因为sys.stdlib_module_names在这个版本中稳定可用，如果没有这个属性，就需要额外维护一份标准库清单，这会让工具退化。
推荐环境：
| 环境项 | 推荐值 | 说明 |
|---|---|---|
| Python | 3.10+ | 使用sys.stdlib_module_names和ast |
| 第三方依赖 | 无 | 核心逻辑全部使用标准库 |
| 操作系统 | Linux / macOS / Windows | 路径处理使用pathlib |
| 目标项目 | 以 Python 为主的仓库 | 当前实现只扫描.py文件 |
不需要安装任何包，下载项目结构后直接用命令行运行，这是“本地工具”最重要的一点：拿到仓库就能扫，不污染目标项目的依赖环境。
3.2 初始化项目结构和文件
下面是一个最小的项目布局：
ledgerful/ ├── ledgerful/ │ ├── __init__.py │ ├── cli.py │ ├── scanner.py │ ├── models.py │ └── rules.json ├── examples/ │ └── bad_entry.py └── README.md每个文件的职责：
| 文件 | 作用 |
|---|---|
ledgerful/__init__.py | 空文件，标识包 |
ledgerful/rules.json | 忽略规则、信任命令、项目根目录配置 |
ledgerful/models.py | 定义 Ledger 记录结构 |
ledgerful/scanner.py | 核心扫描器，负责解析 AST、提取引用、核验状态 |
ledgerful/cli.py | 命令行入口，处理参数和输出 |
examples/bad_entry.py | 示例文件，故意包含幻觉代码 |
3.3 配置加载逻辑
rules.json放在包目录里，意味着使用者可以复制一份到项目根目录，再通过命令行参数指定。这样既保留了默认行为，又允许不同项目有不同的白名单。
加载配置的代码可以很简单：
import json from pathlib import Path DEFAULT_RULES = Path(__file__).parent / "rules.json" def load_rules(path: Path = DEFAULT_RULES) -> dict: if not Path(path).exists(): return {} with open(path, "r", encoding="utf-8") as f: return json.load(f)这里不需要复杂配置框架。对本地扫描工具来说，配置要解决的问题只有两件事：哪些内容不扫，哪些内容直接信任。规则太多反而会让工具难以维护和解释。
4. 用 Python AST 实现引用提取：模块、调用、命令和路径
4.1 从 import 和 from import 提取模块名
Python 的ast标准库可以把源码解析成语法树，Ledgerful 需要继承ast.NodeVisitor，在访问不同节点时提取引用。
第一步是处理import和from ... import ...：
import ast class ReferenceExtractor(ast.NodeVisitor): def __init__(self): self.references = [] def visit_Import(self, node): for alias in node.names: self.references.append({ "line": node.lineno, "column": node.col_offset, "kind": "module", "name": alias.name, "evidence": f"import {alias.name}" }) self.generic_visit(node) def visit_ImportFrom(self, node): module = node.module or "" for alias in node.names: full_name = f"{module}.{alias.name}" if module else alias.name self.references.append({ "line": node.lineno, "column": node.col_offset, "kind": "module", "name": module, "evidence": f"from {module} import {alias.name}" }) self.references.append({ "line": node.lineno, "column": node.col_offset, "kind": "function", "name": alias.name, "evidence": f"from {module} import {alias.name}" }) self.generic_visit(node)这里把from xx import yy同时拆成模块引用和函数引用：xx需要被验证为真实模块，yy需要被验证为真实导出符号。后者比前者难，因为需要解析xx模块的内部结构，初级版本可以先只验证模块名。
4.2 从函数调用和属性链提取名称
函数调用比 import 复杂。subprocess.run(...)、os.path.join(...)、torch.nn.Linear(...)都是调用，但它们指向的符号层级不同。
一个比较实用的策略是提取属性链的根模块和最终函数名：
def get_call_chain(node): parts = [] while isinstance(node, ast.Attribute): parts.append(node.attr) node = node.value if isinstance(node, ast.Name): parts.append(node.id) return ".".join(reversed(parts)) class ReferenceExtractor(ast.NodeVisitor): def visit_Call(self, node): chain = get_call_chain(node.func) if chain: self.references.append({ "line": node.lineno, "column": node.col_offset, "kind": "function", "name": chain, "evidence": f"call {chain}" }) self.generic_visit(node)比如subprocess.run(["ls"])会提取出subprocess.run，然后 Ledgerful 会先验证subprocess是标准库模块，再进一步检查run是否存在于subprocess的属性中。后一步在生产环境里需要结合真实模块检查，单独靠 AST 无法知道run是否存在，所以初始版本对属性链只验证根模块。
4.3 从字符串常量提取命令行和路径
AI 幻觉不一定只发生在代码符号上，也可能出现在字符串里。最常见的是subprocess.run("make deploy --prod")这类命令，以及Path("/opt/myapp/config.yml")这类路径。
对于字符串常量，可以用简单规则提取：
import re import ast COMMAND_PATTERN = re.compile(r"^[a-zA-Z0-9_-]+(?: [a-zA-Z0-9_=./:-]+)+$") URL_PATTERN = re.compile(r"^https?://") class ReferenceExtractor(ast.NodeVisitor): def visit_Constant(self, node): if isinstance(node.value, str): text = node.value.strip() if COMMAND_PATTERN.match(text) and not text.startswith("http"): command_name = text.split()[0] self.references.append({ "line": node.lineno, "column": node.col_offset, "kind": "command", "name": command_name, "evidence": text }) elif URL_PATTERN.match(text): self.references.append({ "line": node.lineno, "column": node.col_offset, "kind": "url", "name": text, "evidence": text }) self.generic_visit(node)这只是一个启发式实现，不可能覆盖所有字符串，但已经能抓住相当一部分由 AI 编造的命令和 URL。这些引用会被标记为suspicious或直接进入规则白名单校验。
4.4 和本地事实源交叉验证
提取到引用后，需要对每个引用做验证。验证的核心是三个本地事实源：标准库模块列表、已安装包列表、项目内部文件。
import sys import importlib.metadata from pathlib import Path class LedgerValidator: def __init__(self, project_root: Path, rules: dict): self.project_root = Path(project_root) self.rules = rules try: self.stdlib_modules = set(sys.stdlib_module_names) except AttributeError: self.stdlib_modules = set() self.installed_packages = self._load_installed_packages() def _load_installed_packages(self): result = set() for dist in importlib.metadata.distributions(): name = dist.metadata.get("Name") if name: result.add(name.lower()) return result def verify(self, ref: dict) -> dict: name = ref["name"].lower() kind = ref["kind"] if kind == "module": if name in self.stdlib_modules or name.split(".")[0] in self.stdlib_modules: ref["status"] = "verified" ref["reason"] = "found_in_stdlib" elif name.split(".")[0] in self.installed_packages: ref["status"] = "verified" ref["reason"] = "found_in_installed_packages" else: ref["status"] = "suspicious" ref["reason"] = "not_found_in_local_index" elif kind == "function": # 简单策略：根模块能验证就视为 verified，否则 suspicious root = name.split(".")[0] if root in self.stdlib_modules or root in self.installed_packages: ref["status"] = "verified" ref["reason"] = "root_module_verified" else: ref["status"] = "suspicious" ref["reason"] = "root_module_not_found" elif kind == "command": known_commands = set(self.rules.get("known_commands", [])) if name in known_commands: ref["status"] = "verified" ref["reason"] = "in_known_commands" else: ref["status"] = "suspicious" ref["reason"] = "unknown_command" else: ref["status"] = "unknown" ref["reason"] = "not_implemented" return ref需要注意，importlib.metadata.distributions()列出的是当前 Python 环境能看到的包，也就是说工具必须在目标项目的虚拟环境里运行。这一点会在后面排错部分继续展开。
5. 运行 Ledgerful 分析一个刻意写错的样例
5.1 准备样例文件
为了演示检测效果，创建一个examples/bad_entry.py，里面故意包含不存在的包和未定义函数：
import fake_magic_lib from deep_ai_toolkit import AutoDataset def run_pipeline(data_path: str) -> None: ds = AutoDataset.load(data_path) model = fake_magic_lib.QuantumModel(10) result = train_model_from_scratch(model, ds) print(result) if __name__ == "__main__": run_pipeline("./data/train.csv")这个例子里的fake_magic_lib通常不存在，deep_ai_toolkit也可能不存在，train_model_from_scratch在当前文件里没有定义。如果这段代码由 AI 编程助手生成，开发者很容易被“看起来专业”的函数名迷惑。
5.2 执行扫描命令
假设项目根目录已经包含ledgerful包，执行：
python -m ledgerful.cli scan examples/bad_entry.py --root .最终命令行入口需要简单实现，传入扫描路径和项目根目录。下面是一个可用的cli.py：
import argparse from pathlib import Path from ledgerful.scanner import scan_file from ledgerful.models import format_report def main(): parser = argparse.ArgumentParser(description="Ledgerful local hallucination scanner") parser.add_argument("path", help="file or directory to scan") parser.add_argument("--root", default=".", help="project root for path resolution") args = parser.parse_args() target = Path(args.path) root = Path(args.root) references = scan_file(target, root) print(format_report(target, references)) if __name__ == "__main__": main()这里省略了models.py中format_report的具体实现，它只需要把references列表变成下面这种可读文本。
5.3 解读报告
扫描后的输出大致如下：
FILE: examples/bad_entry.py L3 suspicious module fake_magic_lib L4 verified module deep_ai_toolkit L4 suspicious function AutoDataset L8 suspicious function train_model_from_scratch L11 unknown command/path ./data/train.csv结合程序逻辑解释输出：
fake_magic_lib不在标准库，也不在当前环境的已安装包列表里，所以是suspicious。deep_ai_toolkit如果安装过，则模块名验证为verified，但AutoDataset是否能被导出，当前实现无法直接确认，所以标记为suspicious。这是为了让开发者多留意一层。train_model_from_scratch在当前文件 AST 中没有定义出现，又不在已导入模块的已知导出里，所以是suspicious。"./data/train.csv"是一个相对路径，且不是明显的命令，当前规则没有命中，所以标记为unknown，代表需要结合项目文件判断。
5.4 把这个工具放进 AI 编程助手的工作流
Ledgerful 单独跑一次只能解决“事后检查”。更有效的方式是把扫描器接到 AI 编程助手的产出路径上：生成代码后先扫一遍，再提交。
一个简单的做法是在 git 提交前针对改动文件执行扫描：
git diff --name-only --diff-filter=ACM | grep '\.py$' | xargs python -m ledgerful.cli scan --root .如果希望把它作为 pre-commit 钩子，可以写成：
#!/usr/bin/env bash set -e files=$(git diff --cached --name-only --diff-filter=ACM | grep '\.py$' || true) if [ -n "$files" ]; then python -m ledgerful.cli scan $files --root . fi注意：在 pre-commit 钩子里阻断所有
suspicious可能过于严格，第一版建议只输出报告，让开发者在提交前人工处理。
6. 误报是本地工具最大的敌人：现象、原因和排查路径
6.1 常见误报表格
本地扫描工具最怕的不是漏报，而是误报太多。误报一多，开发者就会放弃阅读输出。下面是几个常见误报场景。
| 问题现象 | 常见原因 | 检查方式 | 处理建议 |
|---|---|---|---|
| 标准库模块被标记为 suspicious | Python 版本过低或sys.stdlib_module_names不可用 | 运行python --version，检查是否 3.10+ | 升级 Python，或维护标准库清单 fallback |
| 已安装包被标记为 suspicious | 当前 shell 的 Python 和目标项目虚拟环境不一致 | 运行which python，检查虚拟环境是否激活 | 确保在项目虚拟环境中执行扫描 |
| 项目内相对导入被误报 | 把src目录以外的项目内部模块当作第三方包 | 查看project_roots配置 | 在 rules.json 中增加项目根目录 |
| 动态生成的命令名被误报 | 命令包含变量拼接，如f"{tool} start" | 查看evidence字段，确认字符串含变量 | 增加忽略规则或人工标记为 unknown |
| 常见路径被误报 | 没有维护known_paths | 检查 rules.json 中的路径白名单 | 把固定路径加入白名单 |
| AI 生成的 pyproject 依赖名各不相同 | 同一包在不同环境 diff 后仍有差异 | 查看是否存在importlib.metadata包名规范化问题 | 对包名做 lower case 和去下划线处理 |
6.2 动态导入和魔法字符串没法被 AST 捕获怎么办
AST 只能捕获静态可读的代码结构。动态导入、eval、getattr和字符串拼接都会让名字丢失来源信息。
例如：
module_name = load_config("ai_tool") tool = __import__(module_name) method_name = config["entry"] result = getattr(tool, method_name)()这类代码里，load_config、__import__、getattr都是合法的，但是 Ledgerful 无法从 AST 知道实际的模块名和方法名。面对这种情况，正确做法是把它们标记为unknown，而不是直接当成suspicious。因为能力不足而产生的“无法确认”，不应该被当作“存在幻觉”的证据。
实际处理时可以增加启发式：扫描配置文件和模块名之间的映射，如果配置中存在某个模块名字符串，就记录unknown。这一层并不复杂，但能减少源码中的魔法字符串成为盲区。
6.3 扫描器自己报错的排查链路
Ledgerful 本身也会出错。常见的错误包括：
| 错误现象 | 检查步骤 | 解决方向 |
|---|---|---|
SyntaxError在扫描某个文件时出现 | 确认目标文件是否包含 Python 3.10 不支持的新语法 | 升级 Python，或跳过该文件 |
ModuleNotFoundError: importlib.metadata | 检查 Python 版本 | Python 3.8 需要改用importlib_metadata兼容包 |
AttributeError: module 'sys' has no attribute 'stdlib_module_names' | 检查 Python 版本 | Python 3.10 以下提供 fallback 列表 |
| 扫描结果为空 | 检查传入的路径是否为空目录，是否用了.而不是.py文件 | 确认路径是真实文件或包含 Python 文件的目录 |
排查顺序建议：
- 先确认扫描路径是否存在。
- 再确认 Python 版本和虚拟环境。
- 然后确认规则文件是否被正确加载。
- 最后查看单个文件的 AST 输出，判断是提取逻辑问题还是目标代码问题。
这样能把“用户代码有问题”和“扫描器自身有问题”区分开。
7. 从个人脚本走向团队可用：报告、增量扫描和接入检查清单
7.1 输出可读报告和 JSON 报告
个人使用可以只看文本输出，团队协作则需要机器可读的格式。可以在cli.py中增加--output参数，支持json和text两种模式。
JSON 输出的例子：
{ "summary": { "total": 12, "verified": 8, "suspicious": 3, "unknown": 1 }, "references": [ { "file": "examples/bad_entry.py", "line": 3, "kind": "module", "name": "fake_magic_lib", "status": "suspicious" } ] }团队 CI 可以解析这个 JSON，在评论机器人或代码托管平台上直接显示。需要谨慎的是：CI 通常不知道目标项目的本地虚拟环境里有哪些包，所以 CI 中的扫描应该使用项目锁文件或 CI 构建环境，而不是随便一个预装环境。
7.2 增量扫描：只在 diff 行上跑
全量扫描在早期可以用，但项目变大后会产生大量噪音。更好的策略是只扫描当前分支变更的部分。
一个可行方案：
def get_changed_python_files(base="main"): import subprocess result = subprocess.run( ["git", "diff", base, "--name-only", "--diff-filter=ACM"], capture_output=True, text=True, check=True ) return [line for line in result.stdout.splitlines() if line.endswith(".py")]拿到文件列表后，还需要把行号过滤到 diff 涉及的行。这一步可以让扫描器接收一个“只报告这些行”的参数，在scan_file中根据记录的行号做过滤。增量扫描的意义不是减少漏报，而是降低误报对开发者的打扰，让每次提交只关注本次改动引入的问题。
7.3 接入 AI 助手后的检查清单
把 Ledgerful 接入 AI 编程助手的日常使用流程后，推荐维护下面这张检查清单：
| 检查对象 | 检查内容 | 处理方式 |
|---|---|---|
| 依赖文件 | pip install命令是否来自 AI 生成的提示 | 实际执行前先查看包名和版本 |
| import 语句 | 新加入的模块是否在标准库或本地环境中 | 如果未安装，执行安装或检查拼写 |
| 函数调用 | 调用的函数是否在当前文件或导入模块中定义 | 用 IDE 跳转到定义处确认 |
| 命令行 | 新出现的命令是否真实存在于 PATH | 在终端执行which或直接运行查看 |
| 文件路径 | 路径是否存在，权限是否正确 | 用ls或test -f验证 |
| 环境变量 | 变量名是否有拼写问题，是否能从配置中找到定义 | 搜索仓库中是否有相同的字符串 |
| 配置项 | 配置键是否和实际读取代码一致 | 对比示例配置和读取逻辑 |
| 回归测试 | AI 改动是否影响原有功能 | 跑相关测试用例后再合并 |
这张清单可以打印出来，也可以沉淀为仓库里的REVIEW_CHECKLIST.md。它和扫描工具互补：工具负责快速列出可疑点，清单负责保证人工确认的完整性。
7.4 学习环境与生产环境的差异
学习环境和生产环境对工具的要求完全不同。
| 对比项 | 学习环境 | 生产环境 |
|---|---|---|
| 环境变量 | 只需要一个 Python 3.10+ 环境 | 虚拟环境必须和项目锁文件一致 |
| 规则配置 | 可以用默认 rules.json | 需要维护项目专属白名单 |
| 扫描范围 | 单文件或小目录 | 建议增量扫描或改动文件扫描 |
| 输出 | 文本报告足够 | 需要 JSON 输出、CI 集成和告警 |
| 处理策略 | 看到 suspicious 就人工看 | 需要分级：阻断合并 / 警告 / 记录 |
| 数据安全 | 本地扫描即可 | 确保不把代码上传到任何远程服务 |
生产环境里，更推荐把 Ledgerful 作为“AI 代码变更检查”的一环，而不是唯一的保障。
8. 几个值得继续扩展的方向
8.1 本地知识库：把内部包、内部域名、内部配置项纳入事实源
大型团队通常会有公司内部的 Python 包、内部域名和内部配置项。这些内容不在标准库，也不在 PyPI 的公开信息里，所以默认扫描器一定会误报。
解决方案是维护一个团队级facts.json，记录内部包、内部域名、内部路径和内部环境变量。扫描时优先加载这份文件，再执行 level 1 到 level 4 的验证。这个扩展并不复杂，但对降低误报率非常有效。
8.2 从名称相似度到语义候选
一个更高级的思路是：当某个符号找不到事实来源时，不要只报“不存在”，而是给出相似候选。比如 AI 生成transormer时，可以提示“本地存在transformers，两者名字接近”。
实现上可以用编辑距离、前缀匹配或基于 token 的相似度。需要控制候选数量，否则输出又会变成另一种噪音。建议设计为可选插件，默认关闭。
8.3 依赖图谱和真实调用链
目前的实现是逐文件独立扫描，无法回答这类问题：“这个函数确实存在，但调用链上有没有其它虚假符号？”更完善的工具应该能构建项目级依赖图，自动追踪from A import B从 A 模块导出 B 的真实定义位置。
依赖图还有助于识别循环导入和幽灵导出。所谓幽灵导出，就是一个模块在__init__.py里导出了某个名字，但这个名字在模块内部从来没有定义过。这类问题靠单文件扫描无法发现，依赖图谱扫描则可以直接定位。
8.4 最小落地建议
如果你只打算在一周内把这样的工具用上，建议按以下顺序推进：
- 先实现
import和from ... import ...的扫描，这部分最容易稳定。 - 再实现函数调用链提取，验证根模块是否可信。
- 维护一份项目专属
rules.json，把常用命令和固定路径加进去。 - 先以报告形式运行两周，观察误报率，再决定是否进入 CI。
- 进入 CI 后，先对
suspicious警告，不阻断；积累一段数据后再按严重程度分级。
Ledgerful 的核心价值不在于“证明代码没有幻觉”，而在于把需要人工确认的范围缩小到可控大小。对 AI 编程时代来说，能缩小确认范围，就已经能省下大量 review 时间。先让工具在本地跑起来，再根据项目实际情况调整规则，比一开始就追求完美模型更实际。
