AST拓扑剪枝：让大模型从混乱代码库中提取高精度架构全景图

1. 先聊聊这把火是怎么烧起来的如果让我用一个词形容第一次面对十万行“遗留系统”代码库的感觉那就是绝望。不是那种“代码有点多”的绝望而是你打开工程目录看到几十个相互嵌套的文件夹几百个文件import 链绕来绕去一个改动涉及七八个模块——你甚至不知道该从哪里开始读。我把代码克隆到本地尝试用 IDE 的“查找所有引用”功能去看模块间的关系结果展开的依赖树比走廊还长我又试过翻文档发现文档停留在五年前最后我甚至问自己干脆把所有代码都丢给大模型让它帮我梳理结构行不行结果更残酷。我把十万行代码一股脑喂给模型它确实能“读”完但当你问它“这个系统的核心模块是什么”、”订单状态变更到底影响了哪些地方”它给出的答案要么含糊其辞要么把无关紧要的工具函数当成核心逻辑。Why因为十万行代码里有海量的噪声。大模型确实能理解代码但它没有精力去区分哪个文件是核心、哪个文件只是工具函数、哪条调用路径是主路径、哪条只是异常分支。后来我想通了画架构全景图这事关键不在于让 AI 看到所有代码而是让 AI有选择地看。怎么做到“有选择”这就轮到AST抽象语法树拓扑剪枝登场了。这篇文章不聊虚的直接复盘我完整跑通的一条路线把十万行混乱代码库通过 AST 解析、拓扑剪枝、分层聚合三步最终生成一张高精度的架构全景图。整个过程有原理拆解有实操步骤也有我踩过的坑。2. 项目背景混乱代码库到底“乱”在哪2.1 混乱的三层表现先别急着谈技术方案我们要对“混乱”下一个精确定义。不然你连问题都描述不清楚后续优化更是无从谈起。我拿到的那份十万行代码库混乱体现在三个层次第一层命名混乱。模块名语义模糊有的叫 utils、有的叫 common、还有叫 helper 的你根本不知道它里面装的是什么。更糟糕的是同一个功能散落在三四个文件里互相调用形成一个剪不断理还乱的网。第二层依赖混乱。无论从哪个文件出发沿着 import 和调用关系走几乎能到达代码库里的任何一个其他文件。我做过一次试验随机选了一个工具函数往上游追溯 import结果它间接依赖了 40 多个文件。这个依赖图几乎没有“分层”的概念所有节点都纠缠在一起。第三层调用路径混乱。业务逻辑没有清晰的流转方向。订单模块会直接调用日志模块日志模块又反向调用配置模块配置模块竟然又引入了订单模块的类型定义。循环依赖一个接一个仿佛在告诉后来者这里没有设计只有堆砌。如果你也遇到过类似情况你就知道传统的代码分析工具比如基于正则的依赖扫描、IDE 自带的结构图生成器为什么不管用了。它们的逻辑是“把全部节点和边都画出来”结果就是画出一个毛线团。一个合格的架构图不是把关系全部展示而是把噪声过滤掉把主干保留下来。2.2 为什么说这本质上是个“注意力”问题说白了读代码和人眼看东西是同一个道理。你扫一眼一张全是密集小点的图什么都记不住但如果图里有一条清晰的主干道旁边几个分支你立刻就能理解整体结构。AI 理解代码也一样。给它十万行代码它没有“注意力预算”去逐一判断什么重要什么不重要。所以我们必须靠工具先把代码的“注意力”引导到正确的位置。这个位置就是代码库里的核心骨架这个项目从哪个入口进入、经过哪些关键模块、最后输出什么结果。AST 拓扑剪枝干的正是这件事先把代码变成语法树再把语法树上那些不重要的枝叶剪掉只保留主干和关键分支最后交给 AI 去理解和绘制。这样AI 拿到的就不再是让人头晕的毛线团而是一份可读性极强的结构骨架。3. 先从抽象语法树说起为什么不用正则也不用文本检索3.1 理解 AST 的正确姿势我知道很多人听到“AST”就觉得门槛高其实没那么玄乎。简单说AST 就是把源代码按语法规则拆成一棵树。每个文件读进来之后解析器会识别出里面的类声明、函数声明、变量定义、导入导出语句、函数调用等元素然后把这些元素按嵌套关系组织成一棵有层次的树。举个例子一段极其简单的代码import { orderApi } from ./api/order; class OrderService { createOrder(data) { return orderApi.create(data); } }这段代码会生成一棵树顶层是ImportDeclaration导入声明和ClassDeclaration类声明ClassDeclaration下面挂着MethodDefinition方法定义方法体里又挂着CallExpression函数调用表达式。每个节点都带着丰富的元数据比如函数名、参数列表、调用目标等等。这看起来只是一堆嵌套结构但它对架构分析的意义极其重大。3.2 为什么必须用 AST 而不是直接读源码文本有人会问我直接用正则匹配import xxx from、匹配函数名、匹配函数调用不也能得到依赖关系吗答案是能但会漏而且漏得离谱。正则匹配无法处理几种情况对象属性访问式调用this.orderApi.create(data)方法名create和orderApi之间的归属关系正则很难准确分辨。动态导入、重命名导入、别名引用正则会把它们当成不同的东西。装饰器、类型注解、泛型参数这些都可能影响模块的真实依赖结构但正则根本看不见。AST 则完全没有这些问题。它本身就是解析器按语法规则拆解出来的每个语法元素是什么、属于谁、调用了谁是精确已知的。我们做架构分析的第一步不需要“AI 理解”只需要精确的语法事实。AST 就是那个最精确的事实来源。3.3 AST 和调用图的关系如果你做过动态分析可能听过“调用图”的概念。调用图是通过跟踪程序运行时执行路径画出来的“谁调用了谁”的关系图。这种方法精准但要跑程序、插桩、收集运行数据对于一个十万行又没有完备测试的遗留系统根本跑不起来。我们的方案走的是静态分析路线基于 AST 解析出“潜在调用关系”也就是“在当前代码结构里这个模块可能依赖那个模块”。虽然不等同于运行时真实发生的关系但对于画架构全景图来说已经足够——我们要的本来就是代码结构层面的全貌而不是某一次运行的温度。4. 拓扑剪枝画架构全景图的“减法哲学”4.1 为什么必须“剪”拿到 AST 之后如果你直接把所有节点和依赖边丢给 AI结果会怎样我试过。输出是一张数千个节点、上万条边的巨型图别说人看不下去AI 自己也晕它在生成描述时会把大量工具函数、内部类型定义、互调关系全部当成重点最后产出的“架构说明”是一锅粥。这里有一个关键洞察对架构全景图来说最小化信息量比最大化信息量更重要。高精度不等于信息全保留而是把噪声降到最低。我们需要的是一张能够指导人做出判断的图而不是一个无所不包的数据库。4.2 剪枝的三层策略我最终设计了一套“三步剪枝法”每一步解决一个层面的噪声问题。第一层入口定根。所谓定根就是找到整个代码库的入口节点作为架构图的根。入口怎么找通常是main函数、配置文件里声明的启动文件、对外暴露的 index 入口等。这一步的本质是架构图必须有一个明确的起点有了起点我们才能谈“从哪往里看”。第二层类型白名单保径。AST 节点类型有很多但架构图里真正值得作为“节点”展示的只有少数几类模块/文件、类、核心接口、重要函数。其他一切语法节点比如变量声明、赋值表达式、字面量、装饰器统统不进图。这一步能过滤掉 80% 的枝叶噪声。举个例子import { a } from ‘b’这条语句在 AST 里是一个ImportDeclaration节点我们在图中只保留一条“当前模块依赖 b 模块”的边而不会为 a 单独建一个节点。这就是“类型白名单”的作用只让值得出现在图上的人出场。第三层阈值剪枝。即使有了白名单节点数可能仍然太多。这时候引入一个概念边的权重。一个函数被调用 100 次和只被调用 1 次重要性显然不同。我采用的策略是凡是被调用次数低于某阈值的叶子节点折叠进它的父节点不单独出现。举例来说一个模块里有 30 个小工具函数每个只被调用一两次那么这些函数就不作为独立节点出现在架构图里而是折叠成一个“内部工具集”节点。阈值怎么定后面我会单独讲调参经验这里先记住大方向频繁互调的和跨越关键层的边要保留低频、局部的边要折叠。三步剪枝走完一个十万行代码库大概会从 2 万多个 AST 相关节点压缩到 200~400 个关键节点。这 400 个节点才是 AI 真正该看的“全景图素材”。4.3 剪枝背后的拓扑学直觉为什么叫“拓扑剪枝”拓扑学关心的是结构在连续变形下不变的性质。我们不是要精确到每一行代码而是要抓住结构上“不可压缩”的那部分。如果把代码库看成一个有向图那么出度和入度就是最好的拓扑特征入度高说明被大量引用出度高说明大量依赖别人。一个模块如果出度高、入度低那它多半是个底层基础设施类似地基入度高、出度低则更可能是业务核心模块。真正需要保留下来的就是这些结构地位特殊的节点以及它们之间的边。这本质上是按拓扑显著性做取舍。5. 把剪枝后的拓扑喂给 AI我用的具体方法与参数5.1 中间表示GraphML 与分层 JSON剪枝完成后我们需要把图结构保存成 AI 容易读取的格式。我用了两种格式并行GraphML一种基于 XML 的图格式保存节点、边、权重、节点属性。适合后续用可视化工具打开检查。自定义 JSON结构更轻量适合作为大模型提示词的一部分。JSON 大概是这样的结构{ root: src/main.js, nodes: [ { id: module:order-service, type: module, label: 订单服务, metrics: { incoming: 23, outgoing: 5 } } ], edges: [ { source: module:order-service, target: module:order-repository, type: import, weight: 3 } ] }别小看这个中间表示它决定了 AI 能不能“看懂”结构。节点 id 我建议直接用英文路径加前缀比如module:、class:、func:这样 AI 一眼就能知道节点类型。边的 type 我也保留了import、call、extend三种分类后续做不同层级的分析会很有用。5.2 大模型提示词让 AI 不做推理做解读把图数据交给 AI 之前我踩过一个很经典的坑提示词写得过于开放结果 AI 总是试图“解释代码逻辑”而不是“描述架构结构”。后来我把提示词改成了限定式任务大概思路如下你是一名软件架构分析师。我将给你一份模块依赖关系的 JSON 数据。 这份数据来自对代码库 AST 解析和拓扑剪枝后的结果。 请完成以下任务 1. 识别其中的核心模块入度高、出度适中。 2. 把模块按依赖方向分为三层底层基础设施、业务核心层、入口表现层。 3. 找出所有跨越层次的反向依赖并标记为“架构异味”。 4. 输出一张分层架构描述标注每一层包含的主要模块及模块之间的关键依赖路径。 不要尝试推断具体业务逻辑只基于给出的拓扑关系输出。这里有个细节必须强调给 AI 的图数据一定要是剪枝后的而不是原始全量的。我做过对照实验同样一个代码库喂全量图数据时 AI 输出的架构描述含混不清喂剪枝后的数据时AI 基本能准确指出核心模块。因为剪枝操作已经替 AI 完成了 90% 的“降噪”工作它只需要做结构化解读这才是它最擅长的。5.3 分层聚合让 AI 按“层”而不是按“节点”思考光有图数据还不够。十万行代码库里哪怕剪枝到 400 个节点对 AI 来说仍然偏多。我的做法是先做一次聚合把同属一个业务域的多个模块合并成“包/域”节点。怎么聚合这里可以用一个很朴素的方法把入度和出度最高的节点作为中心把邻近的弱耦合节点拉拢进来。更简单的做法是按照目录前缀直接合并——只要两个模块的路径前缀重叠到两层以上就把它们视为一个域。例如src/order/service和src/order/repository合并为订单域。合并之后节点数会降到 50~80 个。这个规模是 AI 处理和人类阅读的“甜蜜区”。这时你再让 AI 画架构图它输出的分层关系、核心模块识别、架构异味标记都明显靠谱很多。我在多个代码库上验证过这个结论非常稳定。6. 实操踩坑记录三个让我折腾了一周的隐蔽问题6.1 入口定位失败导致“根节点失踪”第一个项目里我默认入口是main.js结果那个代码库根本没有main.js真正的入口藏在配置文件的entry字段里。我折腾了很久AI 一直说“缺少根节点无法判断主路径”。后来学乖了解析入口前先扫描配置文件。package.json、main字段、bin字段、.env里的启动脚本只要和“启动”相关的配置都作为入口候选。这一步看起来不起眼但少了它后面全部白干。我还加了一个保底策略如果实在找不到入口就把入度最高的 5 个模块作为“疑似入口”剪枝时同时保留多条候选路径让 AI 自己去判断主路径。这个方案在好几个代码库上都能用。6.2 循环依赖把剪枝逻辑搅乱前面提到遗留系统的循环依赖是家常便饭。但问题是循环依赖出现在剪枝的“阈值判断”环节会干扰节点的折叠逻辑。一个节点虽然被调用了 80 次但它同时也反向依赖了 60 个节点如果把它的依赖全部折叠下游计算就会失真。我的处理办法是在剪枝前先跑一遍强连通分量检测。把所有循环依赖的节点聚合成一个“环组”节点然后让环组整体参与剪枝。这样不仅解决了循环依赖导致的剪枝失真还能额外产出一个非常有价值的输出架构异味清单。AI 看到这些环组以后能直接指出“这几处循环依赖破坏了模块间的清晰边界”。这个信息对重构决策价值极高。6.3 巨型节点与“权限层级假象”还有一种情况某个模块文件特别大一个文件里面有 2000 行各种类、函数全挤在一起。AST 解析后这个文件会有巨多内部节点。如果不做处理它会成为图上的“巨型节点”把所有注意力都吸走形成一种虚假的“这个模块很重要”的印象。但实际上它可能只是个数据库访问工具集。解决方法是加入一条“文件内聚度约束”同一个文件产生的节点最多向外贡献 5 条关键边。超出部分折叠进文件内部摘要节点。这样就不会出现一个文件独占全图的现象。这是我从信息可视化领域借来的思路——视觉权重必须和拓扑权重匹配否则图就失去了解释力。7. 参数整定怎么从“毛线团”调到“清晰全景”7.1 阈值的两种选择策略阈值剪枝的参数说白了就是“什么算重要”。我用过两套策略。第一套叫绝对阈值法调用次数低于 N 次的边直接折叠。N 取 2、3、5 都行看代码库规模。这个方法的缺点是小代码库和大代码库的“重要”标准不一样N 固定会导致小库过于稀疏、大库仍然稠密。第二套叫相对保持法保留占总边数前 20% 的高权重边其余折叠。这套更稳健因为它自动适配不同规模的代码库。实际操作中我在 5 个代码库上试过相对保持法几乎没有失败过。唯一要注意的是入口节点、跨层反向依赖这类边属于“硬保留”就算权重低也绝对不能剪。它们承载的信息量远超普通调用边。7.2 节点类型对剪枝的影响不同类型的代码库剪枝偏好完全不同。像 Java 这种强类型语言ClassDeclaration、InterfaceDeclaration是核心骨架类型节点必须保留。Java 项目里接口和实现类的关系往往比方法调用更能反映架构——因为一个接口被多个实现类继承天然就是一个“契约层”。而 JavaScript/TypeScript 项目里函数式模块更多模块之间的 import 边和函数调用边是主线索类节点的重要性会低于 Java。至于 Python装饰器会引入隐式依赖有时一个函数看着是纯函数其实被装饰器注入了数据库会话——所以处理 Python 代码库时装饰器相关节点不能全剪建议至少保留装饰器的“目标”关系。7.3 迭代式调参人机协同的循环调参不是一锤定音的事。我最终跑通的流程是循环式的先用默认参数相对保持 20%、入口硬保留、环组强制聚合跑一遍。拿到剪枝后的图人工瞄一眼重点看两个问题图上是不是还有明显无关的工具模块是不是有该合并却没合并的细碎节点根据人工判断调整阈值或聚合规则再跑一遍。两三轮后把稳定的图数据交给 AI 生成最终描述。通常三轮以内就能收敛到理想效果。在收敛过程中我发现一个规律同一份代码库前两轮跑出来的图差异可能很大但只要模型选对第三轮已经趋于稳定。如果第三轮还在大幅变化那大概率是入口定错了或者聚合规则不对而不是阈值的问题。8. 全景图生成的最后一步从拓扑到视图剪枝完成、AI 输出结构描述后最后一步是把它渲染成人类易读的视图。直接用 Graphviz 把节点画出来效果其实就很不错但有几个坑需要避开。一是布局算法要选对。我试过各种布局Graphviz 的dot层次布局最适合架构图因为它能自动按依赖方向分层。neato和fdp这类力导向布局虽然好看但会无视层次关系——你明明想表达“上层依赖下层”它给你画成一团。二是颜色和分组大概率比形状重要。我用颜色区分层次底层基础设施用冷色蓝色系业务核心层用暖色橙色系入口表现层用中性色灰色系。跨层反向依赖的边用红色虚线标注。这样做的好处是即使图里的文字信息很多人眼扫一眼颜色分布立刻能找到违和感。三是图上不要出现所有节点标签。只标注核心节点和层级的名字其余节点用编号图例里予以说明。这个习惯可能不符合“信息越全越好”的直觉但实际使用下来图反而更容易读——人眼的注意力是有限的你画得越满读者越不知道要看哪里。我最终的输出物一共有三样一张分层架构图、一套 400 个左右节点的剪枝后拓扑数据、一份 AI 生成的架构解读报告。这三样东西加起来能解决 90% 的实际问题。9. 更进一步剪枝拓扑可以衍生出的三种高价值分析除了画架构图这棵剪枝过的拓扑结构还能做不少事。我提三种都是我在实际项目中高频使用的。第一种变更影响范围预估。当你要改动某个模块时找到它对应的拓扑节点沿依赖边往外走两层就能得到“受影响的模块候选名单”。这比在十万行代码里手动搜索靠谱得多。走两层是个关键参数一层是直接依赖方二层是间接受影响方再往外噪声就上来了。第二种模块健康度评分。如果一个节点的出度远高于入度且它位于业务核心层说明这个核心模块背负了大量依赖改起来会牵一发动全身。评分公式大概长这样健康度 入度 /出度 1。比值越低越不健康。这个指标在制定重构优先级时特别有用。第三种重构方向建议。靠 AI 读图结果识别出“反向依赖”和“环组”后可以进一步让它给出“最小切割方案”——即最少改动哪几条边整个依赖图就能变成分层无环结构。AI 不一定每次都给出完美答案但作为重构路线图的起点它已经比从零开始分析高效太多了。10. 实测效果剪枝前后对比我不喜欢只讲理论所以把一次实测数据贴在这里。这是一个约 12 万行规模的代码库做订单和库存业务早已没人维护注释极少命名混乱。原始 AST 解析结果解析出的相关语法节点数量128,778 个模块间依赖边41,236 条循环依赖环组37 个执行全套剪枝流程后的结果关键节点模块、类、核心函数512 个保留的依赖边1,873 条聚合成域后的最终节点86 个识别出的架构异味交叉域反向依赖 14 处、环组 8 处我把这 86 个节点和 1,873 条边的 JSON 数据交给 AI 之后它输出的架构描述第一次让我觉得“这说的确实是我手上的这个系统”——核心域是订单和库存支撑域是支付、账号、消息底层是数据库访问和公共工具。这个分层和我在这个代码库里潜伏一个星期得出的认知高度重合但它只用了十几分钟。这不是玄学。因为 AST 提供了精确的语法事实拓扑剪枝过滤掉了噪声AI 在干净的输入上做归纳自然能给出高质量结果。AI 本身没有变强是输入信号的信噪比变高了。11. 你该从哪里开始动手如果你也想在自己的代码库上复现这套流程我的建议是从一个规模适中的项目开始比如一两万行就足够不要一上来就挑战十万行。流程大致如下选一个解析器。你所在语言生态里最主流的那个。例如JavaScript/TypeScript 选 toolsJava 选 Eclipse JDT 或者 javaparserPython 选 ast。不需要追求全语言支持先用一个语言跑通整个流程。写一个简单的 AST 遍历脚本把“模块/类/接口/函数”四类节点提取出来记录它们的位置和依赖目标。构造有向图边上有权重的邻接表存成 GraphML 或 JSON。实现剪枝三步入口定根、类型白名单、阈值过滤。人工校验一轮然后交给大模型生成结构描述。可视化用图布局工具出图检查是否传达了你想要的信息。不要试图第一步就做成产品级的完整系统。先跑通最小闭环你会在实际代码库里碰到上面讲的那些坑——入口找不到、环组扰乱剪枝、巨型节点骗视觉——然后再针对性优化。我在做完第一版只用了大概一个周末。而如果你是有经验的开发者按我的流程走一遍顺利的话一天就能看到初步结果。之后的优化空间还很大比如把聚合规则做成自动学习、把剪枝参数自适应调整、把变更影响分析集成到 CI 流程里这些都是很好的扩展方向。说到底AI 帮我们读代码已经是现实。但它能不能读得准、读得有重点取决于我们喂给它什么样的“素材”。AST 拓扑剪枝就是那个把毛线团拆开、把主线抽出来的关键动作。