接手一个没有架构文档的代码仓库多数人都会经历类似的痛苦先在目录树里凭命名猜测模块再打开 IDE 逐个类跳转最后在 wiki 里手工维护一张架构图。整个过程不仅耗时长而且图与代码的偏差会随着迭代越来越大。如果能把“读代码、理解结构、生成图、维护图”这条链路交给一个 Agent 自动完成团队就能把精力放在更有价值的事情上判断这个架构是否合理、模块边界是否需要调整。这类“自动解析代码仓库并输出可视化架构图”的工具正在从玩具变成工程效率基建的一部分。这篇文章不打算只介绍某个现成工具而是从原理出发演示一个可运行的最小“仓库架构解析 Agent”再讲清楚它在真实工程中的边界、常见坑和实践建议。读完你可以照着实现一个轻量版本也可以据此评估现有 Agent 框架或商业方案是否适合你的团队。1. 这篇文章真正要解决的问题1.1 看懂一个项目为什么这么贵软件开发者的大部分工作不是从零写新代码而是阅读和修改已有代码。尤其当你刚进入一个团队、接手一个中大型项目时第一周往往不是在写需求而是在“考古”。一个典型的中型项目可能包含几十个模块、几百个文件、上千个函数与类。人脑理解代码的方式是分层抽象的先看系统有哪些模块再进入具体模块看类与接口最后才深入到函数实现。但代码仓库的物理组织方式并不总是等于逻辑架构目录名可能过时README 可能只有几句话注释可能比代码更误导人。于是开发者只能靠大量跳转和搜索在脑中慢慢拼接出系统全貌。这个过程被称为“建立心智模型”。心智模型建立得越快后续开发效率越高。然而传统工具在“快速建立系统级心智模型”这件事上做得并不好。1.2 传统工具差在哪里很多人第一时间会想到 IDE 的类图功能。以主流的 Java IDE 和 Python 静态分析工具为例它们能生成类图、包图、调用关系图准确性很高。但这些图通常存在两个问题。第一粒度太细。IDE 围绕类与方法生成依赖图节点数量动辄上百读图成本比读代码还高。第二缺少语义。工具能告诉你 A 类依赖 B 类但不会告诉你 A 类负责订单校验、B 类负责库存扣减更不会把这些类归纳成一个“订单服务”。架构图需要表达的是“为什么这么分”和“模块间如何协作”而不是逐条罗列引用关系。手工画架构图则走向另一个极端信息高度浓缩但维护成本极高。代码只要发生一次模块合并或拆分图就失效了。许多团队的架构文档半年不更新不是团队懒而是“手工更新”与“代码变更”之间没有建立自动化通路。下面用一张表格对比三种方案的差异。方案准确度理解粒度语义归纳能力维护成本典型用途IDE/静态分析工具高类和方法级弱手动触发代码调试、重构手工架构图取决于作者模块/服务级强很高架构评审、新人培训仓库解析 Agent较高可控模块/包/类中到强可自动化文档同步、快速入门、治理“仓库解析 Agent”的核心价值不是替代 IDE 的分析能力而是把“结构解析的准确性”和“语义归纳的智能性”组合起来并让整条管线自动运行。1.3 谁最需要这类 Agent从实际场景看有三类人收益最明显。第一类是刚接手项目的开发者。他们需要在一两天内回答“系统有哪些模块”“模块之间怎么调用”“核心链路是什么”。一份自动生成的架构图能大幅压缩建立心智模型的时间。第二类是负责架构治理的技术负责人。他们最关心模块边界是否清晰、是否存在循环依赖、哪些模块正在变得臃肿。架构图作为“架构现状”的输入比人工评审更客观。第三类是自己正在做 Agent 开发的工程师。代码仓库分析是一个非常典型的 Agent 落地场景它需要调用工具文件系统、AST 解析器、API、处理长上下文代码量通常超过模型窗口、并对外输出结构化结果。做一遍这个场景远比做一个“聊天式 Demo”更能理解 Agent 工程的边界。需要说明的是这类 Agent 不适合用来做精确到行级的性能分析也无法代替代码评审中对具体实现细节的讨论。它的目标是“先让整体结构变得可讨论”而不是“把所有细节都画出来”。2. Agent 如何自动解析代码仓库核心原理与边界2.1 把仓库理解成四层结构一个代码仓库可以从下往上拆成四层文件层仓库里有哪些文件、目录哪些文件属于同一业务模块。语法层每个文件里有哪些类、函数、接口、导入语句。依赖层模块之间存在哪些调用、引用依赖哪些是内部依赖哪些引用了第三方库。语义层每个模块在业务上承担什么职责例如“订单处理”“用户认证”“数据持久化”。传统的静态分析工具擅长处理前两层并且可以在一定程度上处理依赖层。但语义层需要人来总结或者需要大模型通过阅读代码片段进行归纳。仓库解析 Agent 的典型实现思路就是用传统解析器解决精确性问题用大模型解决模糊的语义归纳问题。两者结合才能输出一张“既能看懂、又相对准确”的架构图。2.2 核心工作链路一个最小可用的仓库架构解析 Agent通常包含六个环节。代码采集递归扫描仓库文件过滤掉构建产物、依赖目录和版本控制目录。结构解析对代码文件做 AST 解析提取导入关系、类、函数等结构信息。依赖归约将文件级依赖收敛到模块级依赖去掉噪音边。语义归纳可选步骤调用大模型为关键模块生成职责描述。图形生成根据依赖关系生成可视化文本常见格式包括 Mermaid、Graphviz DOT、D2。人工校验架构图生成后需要人工审校确认模块划分是否符合团队认知。这个链路和“Agent 开发”中常见的“感知—规划—工具调用—输出”有相通之处。差异在于这里的“工具调用”非常具体文件系统扫描、AST 解析器、JSON 序列化、渲染器。模型不需要做太多自由规划反而是确定性的管线更可靠。2.3 为什么不能直接让大模型读全部代码一个很自然的想法是把整个仓库塞给大模型让它直接画出架构图。在演示场景下可行但在真实仓库中会遇到三个问题。第一上下文窗口放不下。一个几万文件的企业项目源码体积往往超出上下文限制即使强行截断也会丢失关键模块。第二幻觉风险高。模型如果只看到零散文件很容易基于文件名猜测模块职责生成看似合理但实际错误的架构图。第三成本不可控。大量代码反复送入模型接口费用和耗时都会快速上升。所以更稳的做法是先用 AST 或 tree-sitter 做确定性压缩把仓库从“源码全文”压缩为“结构化符号表”让大模型只处理相对精简的模块摘要。这样既降低幻觉风险也减少 token 消耗。这个思路与 RAG 类工具异曲同工先建立索引再做检索增强生成。2.4 这类 Agent 的边界在哪里再强的仓库解析 Agent 也有边界。最明显的是它只能分析静态结构无法覆盖运行时行为。动态导入、反射、依赖注入、外部服务调用、消息队列订阅关系这些只有在程序运行期才会显现的信息静态扫描无法直接获得。对分布式系统来说微服务之间的实际调用链可能由配置中心和注册中心决定仅靠读代码生成架构图会漏掉大量关键信息。因此合理的预期是把自动生成的架构图当作“初稿”或“代码现状快照”由领域专家确认后再进入正式文档。它替代的是重复劳动而不是架构师的判断力。3. 环境准备与前置条件在开始动手之前先准备运行环境。本文的示例是一个基于 Python 的最小 Agent因此需要一台能运行 Python 的机器并安装 Git如果仓库未克隆到本地。3.1 软件依赖Python建议使用 Python 3.10 或更高版本版本以实际环境为准。Git用于克隆远程仓库如果直接分析本地目录也可以不安装。pip用于安装 requests、pyyaml 等小工具。本文示例的主体逻辑只用 Python 标准库即可运行调用大模型的部分才需要 requests。如果你不想调用大模型完全可以只跑 AST 分析部分。3.2 可选的大模型服务为了让 Agent 具备“语义归纳”能力可以接入一个 OpenAI 兼容的聊天模型接口。它的范围很广既可以是云端模型服务也可以是团队内部以本地方式部署的模型服务。需要说明的是私有代码属于高敏感信息。如果代码涉及商业机密更稳妥的做法是把模型部署在内网或者先对代码做脱敏处理再调用外部模型。这个问题在“安全边界”部分会重点展开。3.3 环境搭建命令创建虚拟环境并安装依赖python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install requests pyyaml如果你预计会使用远程模型接口还需要准备好环境变量避免在代码中硬编码密钥export LLM_API_KEY你的密钥 export LLM_BASE_URLhttps://api.openai.com/v1 export LLM_MODELgpt-3.5-turbo在 Windows 的命令行中可以把export换成set。这里的关键原则是密钥只从环境变量读取不写入代码也不进入 Git 历史。4. 核心流程拆解从仓库到架构图的四个步骤下面把仓库解析链路拆成四步每一步对应一个相对独立的工作模块。理解这四步能帮助你在遇到问题时快速定位是“扫描漏了文件”还是“依赖关系归约错误”还是“图形渲染异常”。4.1 仓库扫描与噪声过滤第一步是确定“到底应该扫描哪些文件”。一个仓库里真正需要分析的源码通常只占一小部分。.git目录、虚拟环境、依赖包、构建产物都不应进入分析范围否则不仅拖慢速度还会让依赖图充满无意义节点。因此扫描模块需要维护一个忽略目录集合常见包括.git__pycache__venv、.venvnode_modulesbuild、dist、target.idea、.vscode对于 Python 项目还可以按文件后缀过滤只保留.py文件。对其他语言项目递归遍历逻辑相同替换文件后缀和 AST 解析器即可。4.2 语法结构提取第二步是把源码文件变成结构化的语法数据。Python 提供了内置的ast模块可以把源码解析为抽象语法树。有了语法树我们能准确提取三类信息导入了哪些模块import和from ... import ...定义了哪些类ClassDef定义了哪些函数FunctionDef、AsyncFunctionDef为什么要用 AST 而不是用正则表达式匹配因为正则无法处理换行、注释、字符串干扰等复杂情况而 AST 是编译器级的结果准确率更高。这也是“仓库架构解析 Agent”与简单脚本搜索的一个关键区别。对其他语言可以替换为 tree-sitter 或对应语言的解析库。核心目标不变把“文本文件”转成“结构化符号表”。4.3 依赖归约与分类第三步是把“文件级依赖”收敛成“模块级依赖”。先解释一个概念文件级依赖是指 A 文件 import 了 B 文件。真项目里文件数量多如果每条 import 都画一条边架构图会变成一张无法阅读的蜘蛛网。更实用的做法是先按顶层包名把文件分组再把文件之间的 import 关系归约到顶层模块之间。比如order.api.controller依赖order.service.order_service归约后就是order.api依赖order.service。这样架构图的节点数量大幅缩减阅读性显著提升。同时还需要区分内部依赖和外部依赖内部依赖import 的目标属于本项目包通常是top_packages集合中的模块。外部依赖import 的目标是第三方库如requests、numpy等。对外部依赖架构图里通常不会画成普通节点更合理的做法是单独生成“技术栈清单”或者在图中用特殊样式统一标注。4.4 语义归纳与图形生成第四步是让结果从“依赖关系”升级为“架构视图”。仅看依赖图你可能知道order.api依赖order.service但不知道order.api是做什么的。这时可以把每个模块的 AST 符号表、源文件片段交给大模型请它生成一句话职责描述。这样架构图边上就能标注出“用户接口层”“业务逻辑层”“数据访问层”这类人类友好信息。图形生成通常使用文本描述语言。常见选择有三种Mermaid写起来最简单GitHub、各种 Markdown 编辑器都支持最推荐作为默认输出。Graphviz DOT表达能力更强适合复杂有向图但语法更繁琐。D2新一代文本图形语言输出更现代生态仍在发展中。对大多数团队来说Mermaid 是最平衡的选择学习成本低渲染方便可以直接嵌入 Markdown 文档。5. 完整示例一个最小的“仓库架构解析 Agent”现在进入本文的实操部分。下面的脚本会扫描一个 Python 仓库解析依赖关系并生成 Mermaid 格式的可视化架构图。5.1 主脚本将以下内容保存为repo_architect_agent.py。#!/usr/bin/env python3 repo_architect_agent.py 一个最小可运行的仓库架构解析 Agent 示例。 流程扫描仓库 - AST 解析 - 依赖归约 - 生成 Mermaid 架构图。 import ast import argparse import json import sys from pathlib import Path # 扫描时需要忽略的目录 IGNORE_DIRS { .git, __pycache__, node_modules, venv, .venv, build, dist, target, .idea, .vscode, } def scan_py_files(repo: Path): 扫描仓库下所有 Python 文件过滤掉忽略目录。 return [ p for p in repo.rglob(*.py) if not any(part in IGNORE_DIRS for part in p.parts) ] def module_name(path: Path, repo: Path) - str: 把文件路径转换为模块名例如 src/core/__init__.py - src.core。 rel path.relative_to(repo) if rel.name __init__.py: parts rel.parts[:-1] else: parts rel.with_suffix().parts return ..join(parts) if parts else rel.parent.name def parse_python_file(path: Path): 用 AST 解析 Python 文件返回导入列表与顶层符号。 imports, symbols, error [], [], None try: tree ast.parse(path.read_text(encodingutf-8)) except SyntaxError as exc: return imports, symbols, f{exc} for node in ast.walk(tree): if isinstance(node, ast.Import): for alias in node.names: imports.append(alias.name) elif isinstance(node, ast.ImportFrom): if node.module: imports.append(node.module) elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)): symbols.append(node.name) return imports, symbols, error def build_dep_map(py_files, repo: Path): 建立 模块 - 依赖信息 的映射。 local_modules {module_name(f, repo) for f in py_files} top_packages {m.split(.)[0] for m in local_modules} dep_map {} for f in py_files: imports, symbols, error parse_python_file(f) internal, external [], [] for imp in imports: first imp.split(.)[0] if first in top_packages: internal.append(imp) else: external.append(imp) dep_map[module_name(f, repo)] { file: str(f.relative_to(repo)), symbols: symbols, internal: sorted(set(internal)), external: sorted(set(external)), error: error, } return dep_map def build_edges(dep_map): 将文件级依赖收敛为顶层模块之间的边。 edges set() for module, info in dep_map.items(): src module.split(.)[0] for imp in info[internal]: dst imp.split(.)[0] if src ! dst: edges.add((src, dst)) return sorted(edges) def render_mermaid(edges): 将模块依赖边渲染为 Mermaid 文本。 lines [graph TD] for src, dst in edges: lines.append(f {src} -- {dst}) return \n.join(lines) def main(): parser argparse.ArgumentParser(description仓库架构解析 Agent 最小示例) parser.add_argument(--repo, requiredTrue, help代码仓库根目录) parser.add_argument(--output, defaultarch.json, helpJSON 数据文件) parser.add_argument(--mermaid, defaultarch.mmd, helpMermaid 图形文件) args parser.parse_args() repo Path(args.repo).resolve() if not repo.exists(): print(f仓库目录不存在: {repo}, filesys.stderr) sys.exit(1) print(f[1/4] 扫描仓库: {repo}) py_files scan_py_files(repo) print(f 找到 {len(py_files)} 个 Python 文件) print([2/4] 解析 AST 与依赖...) dep_map build_dep_map(py_files, repo) edges build_edges(dep_map) print([3/4] 生成架构图...) mermaid_text render_mermaid(edges) Path(args.mermaid).write_text(mermaid_text, encodingutf-8) payload { repo: str(repo), file_count: len(py_files), edges: edges, modules: dep_map, } Path(args.output).write_text( json.dumps(payload, ensure_asciiFalse, indent2), encodingutf-8, ) print([4/4] 完成) print(f 结构化数据: {args.output}) print(f Mermaid 图: {args.mermaid}) print(\n模块级依赖图:) print(mermaid_text) if __name__ __main__: main()这段脚本不依赖任何第三方库运行成本极低。它展示了仓库解析 Agent 的骨架扫描、解析、归约、渲染。5.2 关键逻辑说明脚本的核心在build_dep_map和build_edges两个函数。build_dep_map做了三件事第一通过module_name把文件路径转换为模块名第二用 AST 解析导入关系和顶层符号第三把导入模块分为内部依赖和外部依赖。判断标准是“导入模块的顶层包名是否存在于本项目模块集合中”。build_edges的作用是降噪。它不关心order.api.controller具体依赖了哪个文件而只关心order.api这个顶层模块最终依赖了哪些顶层模块。这一步会把几百条文件级依赖压缩成几十条模块级依赖可读性大大提升。如果分析结果中出现了“孤立模块”即一个模块没有任何依赖边可以先怀疑是解析遗漏也可能是这个模块确实没有被其他代码引用比如工具函数模块或入口脚本。5.3 可选接入大模型生成语义架构描述上面的脚本只能输出依赖关系不能输出“模块做什么”。如果需要语义描述可以增加一个调用大模型的模块。下面是一个简洁示例支持所有 OpenAI 兼容接口。# 文件路径llm_summary.py 可选模块调用大模型生成架构语义描述。 import os import requests BASE_URL os.getenv(LLM_BASE_URL, https://api.openai.com/v1) API_KEY os.getenv(LLM_API_KEY, ) MODEL os.getenv(LLM_MODEL, gpt-3.5-turbo) def summarize(mermaid_text: str, module_info: str) - str: if not API_KEY: return [跳过] 未配置 LLM_API_KEY无法调用大模型。 prompt ( 你是一名资深软件架构师。 以下是某个 Python 项目的模块级依赖图和模块清单。\n f依赖图:\n{mermaid_text}\n f模块信息:\n{module_info}\n 请用不超过 8 句话总结该项目的整体架构 包括核心模块职责和依赖关系。 ) resp requests.post( f{BASE_URL}/chat/completions, headers{Authorization: fBearer {API_KEY}}, json{ model: MODEL, messages: [{role: user, content: prompt}], temperature: 0.2, }, timeout60, ) resp.raise_for_status() return resp.json()[choices][0][message][content]调用这个模块时可以先把arch.json中的模块清单和arch.mmd的内容读入再拼接成 prompt。这样大模型看到的是经过结构化压缩的信息而不是动辄几十万字的原始代码。这段代码特意遵循了一个安全实践API Key 全部来自环境变量代码仓库里不会出现明文密钥。BASE_URL也留成了可配置项方便接入本地模型服务。5.4 运行时需要的文件结构如果要在真实项目中使用建议保持以下结构agent-demo/ ├── repo_architect_agent.py ├── llm_summary.py ├── arch.json └── arch.mmdarch.json是中间产物方便后续扩展比如接入 CI 或 RAG 索引arch.mmd是可视化产物用于人工阅读和文档展示。6. 运行结果与效果验证6.1 运行命令在仓库目录的上一级执行python repo_architect_agent.py --repo ./my_project --output arch.json --mermaid arch.mmd其中./my_project换成你实际的项目目录。如果一切正常会看到类似下面的输出[1/4] 扫描仓库: /Users/dev/my_project 找到 18 个 Python 文件 [2/4] 解析 AST 与依赖... [3/4] 生成架构图... [4/4] 完成 结构化数据: arch.json Mermaid 图: arch.mmd 模块级依赖图: graph TD api -- common api -- service service -- common service -- repository6.2 预期产物arch.mmd的内容示例graph TD api -- common api -- service service -- common service -- repository这段文本是 Mermaid 格式。复制到支持 Mermaid 的在线编辑器、GitHub Markdown 页面或本地文档工具中即可渲染出节点和箭头构成的可视化架构图。arch.json则会保存更详细的结构化数据。每条模块信息包含文件名、符号列表、内部依赖、外部依赖和解析错误。这些数据可以成为后续“代码知识问答”Agent 的输入。6.3 如何判断成果是否可用判断生成结果是否有价值可以从三个角度检查。第一节点是否完整。仓库中的主要业务模块是否都出现在图里如果某个核心模块缺失说明扫描或模块名归约出了问题。第二依赖方向是否合理。业务上应该是上层模块依赖下层模块比如接口层依赖业务层、业务层依赖数据访问层。如果出现大量反向依赖要么是代码真存在循环依赖要么是归约规则过于简单导致的错误。第三是否能直接讲给新人听。把生成的架构图交给一个不了解项目的人看他能不能根据图复述出系统主干。如果能说明抽象层级是合适的如果他说“看不懂”多半是图中节点还是太细需要进一步收敛。6.4 可选的大模型结果验证如果启用了llm_summary.py输出会是一段自然语言架构总结。同样需要人工校验不能因为模型说得流畅就认为它是正确的。建议把“架构总结”和“依赖图”放在一起评审图形提供结构证据文本补充语义解释两者互相对照。7. 常见问题与排查思路从实际经验看仓库解析 Agent 遇到的问题大多不在模型能力而在工程细节。下面整理了一份高频问题清单。问题现象可能原因排查方式解决方案扫描结果为 0 个文件仓库路径错误或忽略目录规则过宽检查--repo路径确认仓库里是否有目标后缀文件缩小 IGNORE_DIRS确认文件后缀正确生成的架构图节点太多直接使用文件级依赖没有归约到模块级查看arch.json中的 edges 数量在 build_edges 中提升抽象层级外部依赖被误标为内部依赖项目中存在与第三方库同名的顶层目录检查top_packages是否混入外部包增加第三方包白名单过滤解析时报语法错误模块信息不完整个别文件使用了未安装的语法特性或被加密混淆查看模块的 error 字段单独处理报错文件或跳过它LLM 调用超时模型服务不稳定或 prompt 内容过长先单独测试一次接口调用增加重试机制精简 prompt架构总结与代码明显不符喂给模型的上下文信息不足查看 prompt 是否包含模块符号和职责线索在 prompt 中加入更多文件摘要私有代码安全疑虑直接发送源码到云端模型服务检查上报内容是否包含敏感字段使用本地模型或先做敏感信息脱敏这些排查思路背后有一条主线先确认数据流走到哪一步断了。是扫描阶段没拿到文件还是解析阶段产生了错误或者归约阶段丢掉了关键边只要定位到具体环节修复成本通常不高。8. 最佳实践与工程建议8.1 先确定你希望架构图回答什么问题动手开发仓库解析 Agent 之前先明确“给谁看”和“回答什么问题”。如果是给新成员做快速入门抽象层级应该在模块或服务级别图中只保留核心依赖如果是做代码治理可能需要额外展示循环依赖和模块体积如果是做微服务梳理则需要结合注册中心、配置中心等运行时信息。不要试图做一张“什么都有”的全能架构图。信息密度一旦过高图的可读性会急剧下降最终没人愿意看。好的架构图都是“有选择地简化”的产物。8.2 把架构图当成“代码资产”来维护架构图不应该是一次性产物而应该与代码库同步演进。实践中可以这样做仓库中维护arch.mmd文件CI 流程中定时运行仓库解析 Agent当生成结果与提交版本不一致时在合并请求中提示“架构图有更新请确认”。这会把架构文档从“事后补”变成“变更触发自动更新”减少手工维护的成本。团队甚至可以约定以arch.mmd为评审材料在 Code Review 时同步审视架构变化。8.3 用结构化信息降低大模型幻觉调用大模型补全语义时尽量让它基于结构化信息做推断而不是直接阅读整段源码。AST 符号、字符串常量、文件名、模块依赖列表这些都是低噪声的输入。模型拿到这些信息后职责归纳的准确性会明显高于“读一个文件猜它的用途”。可以在 prompt 中要求模型“只根据给定信息回答不要臆测”控制 temperature 在 0.2 左右。如果模型输出“我猜”“可能”之类的不确定表达说明输入信息不足而不是模型能力有问题。8.4 权限与安全边界仓库解析 Agent 会读取大量源码Security 是必须提前考虑的问题。如果仓库是闭源或敏感项目默认选择是本地部署模型服务所有分析过程不离开内网。如果需要调用云端模型能力必须经过脱敏和许可检查。建议的脱敏方式包括删除注释中的敏感信息、替换字符串常量为占位符、禁止上传密钥文件、排除包含测试数据的目录。Agent 开发中常讨论的“Agent 安全”同样适用于这个场景。不要给 Agent 过大的自主权限生成式分析结果不能直接写入文档或推送变更先让人工确认。8.5 性能优化先缓存再增量后并发大型仓库的完整扫描和解析可能耗时较长。从工程角度优化顺序是缓存对未变更文件的 AST 解析结果做本地缓存复用上一次的产物。增量每次只分析 Git diff 影响的文件生成增量依赖边。并发多文件并行解析Python 可用concurrent.futures或进程池。架构图生成对实时性要求不高没有必要每次都全量重跑。将运行时开销与业务开发解耦是工程化落地的关键。8.6 从“模块图”走向“多视图架构图”真实系统往往需要多张视图部署视图、服务调用视图、数据流向视图、组件依赖视图。仓库解析 Agent 按代码静态结构生成的是“组件依赖视图”它可以作为基础但不能替代所有视图。后续可以继续扩展结合数据流分析生成调用链路结合端口信息生成部署拓扑结合文档注释生成职责说明。每新增一个视图Agent 的价值就增加一层。9. 总结与后续学习方向回到最初的问题自动解析代码仓库并输出可视化架构图到底是一个“画图工具”还是一个“知识工程工具”从本文的实现可以看出画图只是最后一步。真正有价值的是前面几条链路把文件扫描成结构化符号把符号归约为模块依赖再让大模型补全语义。这本质上是在做“代码知识压缩”。最小示例中AST 解析是确定性的依赖归约是可解释的Mermaid 渲染是完全可控的。这三者构成了仓库解析 Agent 的稳定底座。大模型只负责语义描述拿到的是压缩过的结构化信息因此幻觉空间被限制在合理范围内。如果你接下来想深入建议按三个方向推进。第一个方向是多语言支持。用 tree-sitter 统一解析 Python、Java、TypeScript、Go 等语言让 Agent 不再局限于单一代码库。第二个方向是知识检索增强。把arch.json导入向量数据库构建“仓库级 RAG”让团队可以用自然语言提问“订单模块的核心入口在哪”“哪些模块依赖了过时的 SDK”。第三个方向是架构变更检测。让 Agent 定时扫描仓库比较两次生成的依赖图自动提示新增依赖、循环依赖、模块拆分等变化。这个能力在微服务治理和代码评审中尤其有用。最后提醒一点不要第一次就追求大型仓库的完美架构图。先拿一个中型 Python 项目跑通流程再逐步增加语义总结、并发解析、CI 集成。从小处开始工程复杂度会自然告诉你下一次该优化哪里。