LLM生成Python代码库的分层审计：从AST扫描到CI集成

大约从去年开始我观察到越来越多团队的代码库里开始出现一批风格高度统一的 Python 文件函数命名规范、注释完整、 docstring 齐全但整体结构透着一股生成感。这些代码不是某位高级工程师手写的而是由 Cursor、Copilot、Codex、Claude 等工具批量产出的。代码能跑测试也能过但问题往往藏在后面依赖版本为什么这样锁这个异常为什么被吞掉了这条 import 链为什么会循环当你在 code review 里连问三个为什么却没人能回答的时候LLM 生成代码带来的工程债就已经开始积累了。这篇文章要讨论的是专门用来快速步进式审查 LLM 生成 Python 代码库的工具思路。它解决的不是有没有 bug这种初级问题而是这个代码库是怎么被构建出来的、哪些地方不值得信任、哪些地方必须人工复核这层更深的问题。读完你会理解这类审计工具的设计逻辑也能亲手搭起一套最小可用的审计脚本把它接入自己的项目流程。1. 为什么 LLM 生成的代码库需要专门的审计工具如果只是审查几段 AI 生成的函数用肉眼加 IDE 的警告就足够了。但当一个完整的代码库——几十个文件、几千行代码——都是由 LLM 生成并逐步拼接而成时问题性质就变了。第一个变化是代码量增长速率远超人类阅读速度。传统 code review 可以逐行审因为一个 PR 通常只有几百行改动。但 LLM 生成代码库时一次可能产生几十个文件人类 Reviewer 根本看不过来。第二个变化是LLM 对项目上下文的语义理解是概率性的它可能在一个模块里认为某个函数返回 Optional在另一个模块里却当成非空直接用可能为了避免报错而用except Exception: pass掩盖掉真实异常可能为了满足静态检查而写冗余的防御代码。这些都不是语法错误而是语义裂缝。第三点更关键审计的目的不是找错而是建立信任边界。当你接手一个 LLM 生成的代码库你需要快速知道哪些部分可以放心修改哪些部分一碰就碎哪些部分应该在合适时机重写。人工逐行看当然可以但效率太低。专门针对 LLM 生成代码的审计工具核心能力不是替代人工审查而是缩小需要人工审查的范围。它通过静态分析、依赖追踪、模式识别、结构度量等手段把几千行代码归类为高置信度区域和低置信度区域让审查者把精力集中在真正有风险的地方。这类工具之所以单独成为一类是因为传统静态分析工具如 pylint、bandit是规则驱动的它们检查的是代码是否违反了既定规范而 LLM 代码审计需要的是生成过程感知——它要回答的是这段代码可能是怎么来的、为什么会被写成这样而不只是这段代码是否符合规范。2. 审计什么LLM 代码库的六大高风险点要设计或使用这类工具首先得知道该把放大镜放在哪里。从实际项目经验看LLM 生成的 Python 代码库里有六个最值得重点关注的方向。2.1 表面正常但语义错误的 importLLM 在生成代码时import 部分经常出问题。常见形态包括导入了一个未安装的第三方库导入了项目里根本不存在的模块为了满足命名习惯而重复导入更隐蔽的是导入路径写错导致运行时才报错。从代码审查角度import 区域应该最先看因为它决定了模块之间的依赖关系也最容易暴露这个项目是不是由多个互不知晓上下文的片段拼接而成。2.2 被静默吞掉的异常这几乎成了 LLM 生成代码的标志性特征。生成模型在训练语料里见过大量try...except结构但未必理解异常处理的业务语义。结果就是try: result api_client.fetch_data() except Exception: pass # 什么都不做假装成功代码能跑但出现问题时什么都查不到。审计工具应该能统计异常捕获语句中pass、return None、仅打印日志等掩盖型处理并按数量排序输出。2.3 类型标注与真实逻辑不一致LLM 经常会生成看起来很规范的类型注解但函数体内的实际返回路径并不完全符合注解。比如注解写了- list[str]但在某个分支里返回了None。这类问题在小型脚本里不会暴露一旦代码库变大调用方就会因为这种不一致而出现运行时错误。2.4 过度防御或永远触发的条件分支一些生成代码会写出大量防御性判断检查一个必然存在的 key、处理一个永远抛不出的异常。这类代码表面上看更稳健实际上是增加了阅读负担和测试成本。异常分支覆盖率极低一旦真触发逻辑往往是错的。2.5 隐藏的动态执行eval()、exec()、__import__()、os.system()、subprocess等动态执行接口在 LLM 生成的代码中并不少见。这类代码既可能是功能需要也可能是安全风险来源。审计工具必须把它们全部标记出来人工确认。2.6 依赖与实际调用不匹配LLM 生成的代码库通常伴随自动生成的requirements.txt但里边的依赖可能比实际需要的多——模型会把训练时见过的常见依赖也写进去。多出来的包不仅增加安装时间和安全攻击面还可能带来版本冲突。反过来也可能漏掉隐式依赖。3. 这类工具的核心设计思路分层审计一个合格的 LLM 代码审计工具不应该是一次性扫描后输出一个风险分而应该是多层级、可交互、支持逐步深入的。我比较推荐把审计拆成四个层次。3.1 第一层结构快照先不判断对错只做事实提取。包括文件清单、文件大小、函数数量、类数量、import 关系图、函数调用图、嵌套深度、圈复杂度等。这一层的目的是让审查者在几分钟内知道这个代码库长什么样哪里有异常大的文件、哪里有循环依赖。3.2 第二层模式匹配利用正则、AST 模板、语义规则去匹配高风险模式。这一层可以复用不少传统静态分析工具的思想但侧重点要针对 LLM 生成代码的特点异常掩盖、类型不一致、影子变量、重复代码、无意义的条件判断、硬编码的超时和密钥等。3.3 第三层语义推断这是最难也最有价值的一层。工具尝试理解代码的意图与实现是否匹配。常见做法包括对函数进行摘要生成然后对比函数命名与摘要语义分析异常处理路径是否覆盖了调用方的真实需求检查状态变更是否缺乏持久化或事务保护。这一层通常需要用 LLM 做辅助分析但因为这里是用 LLM 审 LLM 的代码所以必须允许人工介入不能全自动下结论。3.4 第四层人工复核工作台好的审计工具最后必须输出一个复核队列把人需要看的内容、建议看的理由和建议的修改方向都列出来。它不代替人类做决策而是让人类决策更高效。4. 环境准备与前置条件如果你想把这类审计能力接入自己的项目不需要一上来就找什么重型平台很多能力可以用几个开源库组合出来。下面是一个建议的最小技术栈。Python 3.10 或更高版本AST 相关能力和类型注解支持更完整ast模块Python 标准库用于解析代码结构pathlib标准库用于路径遍历networkx非标准库用于依赖图分析可选但推荐pytest如果要做审计规则自测会非常方便一个能输出 JSON 的 CLI 框架方便后续 CI 集成版本方面没有必须锁死的限制以你自己的项目为准。下面演示的是实现思路不是某个特定工具的 API 说明。如果你要审 Large 项目建议把代码托管仓库 clone 到本地一个专门目录不要在线上直接跑审计脚本避免把生产密钥扫进报告。5. 核心实现一个最小可用的 LLM 代码库审计脚本我们直接写一个可运行的审计脚本。这个脚本的设计目标有三个扫描一个 Python 项目目录提取基础结构信息。识别 LLM 生成代码中常见的高风险模式。输出分层的审计报告供人工继续检查。5.1 项目结构建议先建立一个小项目结构如下llm_code_auditor/ ├── auditor/ │ ├── __init__.py │ ├── scanner.py │ ├── patterns.py │ └── report.py ├── tests/ │ └── test_auditor.py └── main.py5.2 scanner.py核心扫描器这个文件负责遍历目录把每个 Python 文件解析成 AST 树并保存文件级信息。# auditor/scanner.py import ast import os from pathlib import Path from typing import Dict, List, Optional class FileScanResult: 单个 Python 文件的扫描结果 def __init__(self, file_path: Path): self.file_path file_path self.lines 0 self.function_count 0 self.class_count 0 self.exception_handlers: List[dict] [] self.dynamic_exec: List[dict] [] self.imports: List[str] [] self.type_hint_issues: List[dict] [] def to_dict(self) - dict: return { file_path: str(self.file_path), lines: self.lines, function_count: self.function_count, class_count: self.class_count, exception_handlers: self.exception_handlers, dynamic_exec: self.dynamic_exec, imports: self.imports, type_hint_issues: self.type_hint_issues, } def parse_python_file(file_path: Path) - Optional[ast.AST]: 解析一个 Python 文件返回 AST 树。语法错误时返回 None。 try: code file_path.read_text(encodingutf-8) return ast.parse(code) except SyntaxError as e: print(f[解析失败] {file_path}: {e}) return None def scan_file(file_path: Path) - Optional[FileScanResult]: 扫描单个文件提取基础结构和风险模式。 tree parse_python_file(file_path) if tree is None: return None result FileScanResult(file_path) result.lines len(file_path.read_text(encodingutf-8).splitlines()) for node in ast.walk(tree): if isinstance(node, ast.FunctionDef): result.function_count 1 elif isinstance(node, ast.ClassDef): result.class_count 1 elif isinstance(node, ast.ExceptHandler): result.exception_handlers.append( { lineno: node.lineno, name: node.name, body_length: len(node.body), } ) elif isinstance(node, ast.Call): # 检测动态执行相关调用 if isinstance(node.func, ast.Name) and node.func.id in { eval, exec, __import__, compile, }: result.dynamic_exec.append( { lineno: node.lineno, func: node.func.id, } ) elif ( isinstance(node.func, ast.Attribute) and node.func.attr system and isinstance(node.func.value, ast.Name) and node.func.value.id os ): result.dynamic_exec.append( { lineno: node.lineno, func: os.system, } ) elif isinstance(node, ast.Import): for alias in node.names: result.imports.append(alias.name) elif isinstance(node, ast.ImportFrom): if node.module: result.imports.append(node.module) return result def scan_directory(root_dir: Path) - List[FileScanResult]: 递归扫描目录下所有 .py 文件。 results: List[FileScanResult] [] for file_path in sorted(root_dir.rglob(*.py)): # 跳过常见虚拟环境和构建目录避免把依赖包也扫进来 skip_dirs {.venv, venv, node_modules, __pycache__, .git, build, dist} if any(part in skip_dirs for part in file_path.parts): continue result scan_file(file_path) if result is not None: results.append(result) return results5.3 patterns.py风险模式检测规则这里实现几个典型的LLM 痕迹检测规则。# auditor/patterns.py import ast from typing import List from .scanner import FileScanResult def detect_silent_exception(scan: FileScanResult) - List[dict]: 检测异常处理中 body 为空、只有 pass、或只打印日志后继续 执行的模式。这类代码会吞掉真实异常导致线上问题难排查。 issues [] for handler in scan.exception_handlers: lineno handler[lineno] body_length handler[body_length] if body_length 2: issues.append( { type: silent_exception, lineno: lineno, file: str(scan.file_path), why: 异常处理体过短可能有吞异常风险, } ) return issues def detect_dynamic_execution(scan: FileScanResult) - List[dict]: 检测 eval / exec / os.system 等动态执行调用。 这类代码在 LLM 生成的代码库中尤其需要警惕 因为它可能来自任意来源的字符串输入。 issues [] for item in scan.dynamic_exec: issues.append( { type: dynamic_execution, lineno: item[lineno], func: item[func], file: str(scan.file_path), why: f动态执行接口 {item[func]} 被调用请确认输入来源可信, } ) return issues def collect_all_issues(scans: List[FileScanResult]) - List[dict]: 汇总所有风险问题。 all_issues [] for scan in scans: all_issues.extend(detect_silent_exception(scan)) all_issues.extend(detect_dynamic_execution(scan)) return all_issues5.4 main.pyCLI 入口做一个简单的命令行入口支持指定目录、输出 JSON 报告。# main.py import argparse import json from pathlib import Path from auditor.scanner import scan_directory from auditor.patterns import collect_all_issues def main(): parser argparse.ArgumentParser( descriptionLLM 生成 Python 代码库的快速审计工具 ) parser.add_argument( target, help要审计的项目目录路径, ) parser.add_argument( --output, -o, help报告输出路径如果不指定则打印到标准输出, ) args parser.parse_args() root_dir Path(args.target) if not root_dir.is_dir(): print(f[错误] {root_dir} 不是有效目录) return 1 scans scan_directory(root_dir) issues collect_all_issues(scans) report { summary: { scanned_files: len(scans), total_lines: sum(s.lines for s in scans), total_issues: len(issues), }, issues: issues, files: [s.to_dict() for s in scans], } if args.output: output_path Path(args.output) output_path.write_text( json.dumps(report, ensure_asciiFalse, indent2), encodingutf-8, ) print(f[完成] 报告已写入 {output_path}) else: print(json.dumps(report, ensure_asciiFalse, indent2)) return 0 if __name__ __main__: raise SystemExit(main())5.5 如何运行和验证假设你要审计的代码库位于~/projects/llm_generated_app在项目根目录执行python main.py ~/projects/llm_generated_app如果只想看汇总信息可以加--output report.json输出到文件。你可以先拿一个小型模拟 LLM 生成代码的目录做验证比如# demo_app/main.py import os import subprocess def fetch_data(): try: result os.popen(echo hello) return result.read() except Exception: pass def run_task(cmd): return subprocess.run(cmd, shellTrue) def safe_divide(a: int, b: int) - float: try: return a / b except ZeroDivisionError: pass运行审计脚本后你会在报告里看到silent_exception和dynamic_execution两类问题被标记出来。这三处代码分别对应异常被吞、动态 shell 执行、异常被吞后再返回 None。6. 从脚本到工程化把审计接入 CI 流程单机审计脚本只是第一步。真正有价值的用法是把它接入团队的 CI 流程让每一个新提交的代码库变更都自动跑一遍审计。这样在 PR 阶段就能看到风险提示。下面是接入 GitHub Actions 的示例配置你也可以按自己团队使用的 CI 平台做等价配置。# .github/workflows/llm-code-audit.yml name: LLM Code Audit on: pull_request: paths: - **.py workflow_dispatch: jobs: audit: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 - name: Set up Python uses: actions/setup-pythonv5 with: python-version: 3.11 - name: Install dependencies run: | pip install networkx pytest - name: Run audit script run: | python main.py . --output audit-report.json - name: Upload audit report uses: actions/upload-artifactv4 with: name: llm-audit-report path: audit-report.json - name: Check issue threshold run: | python - EOF import json with open(audit-report.json, r, encodingutf-8) as f: report json.load(f) total report[summary][total_issues] print(fTotal issues: {total}) if total 100: print(Issues exceed threshold, please review generated code.) exit(1) EOF这段配置会在每次 PR 修改 Python 文件时触发审计并把报告作为构建产物上传。你可以根据自己的容忍度调整阈值比如把超过 100 个问题设为失败门禁。注意这里的阈值只是示例实际项目应该根据代码库大小、团队人力、发布风险综合设定。7. 运行效果与结果验证把审计脚本接入 CI 后你会在 PR 页面看到一个LLM Code Audit的检查项。点开报告可以重点看三块内容。第一块是summary它告诉你这个代码库有多大、扫出多少问题。如果代码量很小但问题数量很多说明这块代码的生成痕迹很重需要优先人工处理。如果代码量很大但问题数量不多也不代表完全安全只说明最容易出问题的地方没有踩雷仍然需要抽查。第二块是issues列表。每条问题都包含文件路径、行号、问题类型、审计理由。这个列表应该按建议处理优先级排序。比如dynamic_execution比silent_exception优先级高因为它们可能带来安全风险。第三块是files列表。这里的数据可以辅助你识别异常文件——几千行的单文件、没有任何函数定义的脚本、import 了 30 个库的文件。这些特征往往对应着某次大段生成没有经过第二次重构。验证成功的判断标准有两个审计脚本能稳定输出 JSON 报告CI 流程能正常获取并展示。你能根据报告的指引快速定位到真正需要看的位置而不是把报告扔到一边。如果报告生成了但没有人看过那这个工具就没有接入流程只是多了一个无人问津的 artifact。8. 常见问题与排查思路问题现象可能原因排查方式解决方案脚本运行时报SyntaxError被扫描目录里存在非 UTF-8 编码文件或语法损坏的 Python 碎片查看报错路径手动打开文件确认修改编码读取逻辑或跳过无法解析的文件并记录到报告中扫描到了虚拟环境中的大量第三方包忽略目录列表没有覆盖.venv、venv等目录检查scan_directory中的skip_dirs是否包含相关目录扩充忽略列表或在调用时传入排除参数报告里没有检测到类型不一致问题当前脚本只做了结构检测没有实现语义推断检查patterns.py中是否有类型分析逻辑增加针对 typing 和函数返回体的语义检测规则CI 中审计脚本超时代码库过大逐文件 AST 解析太慢在本地执行time python main.py .观察耗时启用增量扫描只扫描本次变更涉及的 Python 文件报告里的 JSON 过大CI 界面打不开文件列表和 issues 列表全部输出数据量过大查看报告体积用du -h检查精简报告字段或把 files 明细输出到单独文件误报率太高团队成员不再信任审计结果规则过于宽泛比如把所有except都标记问题随机抽 10 条报告中的问题人工核对准确率提高检测置信度对低置信度问题降级为信息提示而非警告审计了别人手写的老代码问题数量爆炸老代码本来就是历史产物审计规则对新代码更严格对比两份不同代码库的问题密度分模块设置审计阈值优先审计新增/重写代码9. 最佳实践与工程建议9.1 不要让审计工具替代 Code Review这一点要反复强调。审计工具的价值在于缩小需要人工关注的范围而不是给出通过/不通过的结论。建议的协作姿势是工具负责把所有可疑点列出来人类负责对这些可疑点做最终裁决。工具只是提高了审查者的起点。9.2 把 LLM 生成的代码与手写代码分开审计如果项目里同时存在 LLM 生成代码和手写代码建议把审计结果按来源分组。可以在项目里约定LLM 生成的文件放在scripts/generated/或者文件头部有明确的生成标记。这样审计工具可以优先检查生成代码而手写代码采用传统 review 流程。9.3 审计要分层不要只输出一个综合风险分综合风险分看似方便但对定位问题没有帮助。更好的输出方式是按风险和问题类型分类P0动态执行、明文密钥、越权接口P1异常吞没、类型不一致、依赖冲突P2过度防御、死代码、无意义注释按这个优先级排序人工审查者能更快决定先看哪里。9.4 引入审计工具要渐进不要一次性扫描全部存量代码如果你把整个历史代码库一次性跑一遍大概率会得到一份几千条问题的报告然后这个问题追踪单就永远没有人去关闭。更务实的做法是新代码强制审计存量代码仅做基线统计不阻塞发布。等团队习惯了审计报告的格式再逐步清理高优先级存量问题。9.5 审计规则的维护是一个持续动作审计工具写完后不是一劳永逸的。LLM 能力在变生成代码的模式也在变。今天常见的问题类型半年后可能就不再常见而新的问题模式会出现。建议每个季度复盘一次审计规则把实际 code review 中发现的、规则还没覆盖到的问题补进规则库。同时给规则写单测防止规则更新时误伤正常代码。9.6 注意审计范围与权限控制审计脚本可能会读取到代码库里的环境变量、配置文件、密钥占位符。在编写审计报告时要有意识地避免把敏感值直接写入报告。更稳妥的做法是只报告这里存在硬编码密钥不要把密钥内容本身打印出来。生产环境接入审计时建议用最小权限的服务账号运行定期轮换访问凭据。10. 总结与下一步围绕快速 step through 并审计 LLM 生成的 Python 代码库这个话题这篇文章讲清楚了三点第一传统静态分析解决的是代码是否符合规范的问题而 LLM 代码审计解决的是这个代码库是否值得信任的问题。两者目标不同手段也不同。第二一个最小可用的 LLM 代码审计工具核心能力在于分层先做结构快照再做模式匹配再辅助语义推断最后输出人工复核队列。这个分层思路可以逐步完善不用一开始就做得很重。第三工具工程化的关键在于 CI 集成和阈值管理。没有人工复核的审计只是徒增噪音没有阈值控制的审计只会积累大量无人处理的低优先级问题。如果你手头正好有 LLM 生成的 Python 项目建议按文章里的脚本思路先搭一个最小版本跑一遍看看报告长什么样。不要急着加更多规则——先把哪些文件最可疑这个结论拿到手你自然会知道接下来的审计规则该往哪个方向写。往下走可以考虑在这些方向深入对 import 环路做图分析、对函数的 docstring 与实现做语义一致性检查、把审计结果与项目里的 issue 系统打通。每个方向都够写一系列文章但起点都是你现在跑通的这个最小脚本。