从扫描到渲染：用Agent搭建代码仓库架构图生成器

接手一个陌生代码仓库时，最耗时间的往往不是让程序跑起来，而是弄清楚这个项目的模块边界、依赖方向和数据入口。人工读代码画架构图，仓库小的时候还能维护，文件超过几十个后，图很快过时，团队每个人手里的版本都不一样。Agent 开发正在改变这件事：用 Agent 自动解析代码仓库，抽取文件与模块之间的依赖，再输出可视化架构图。下面从零搭建一个最小可用的仓库解析 Agent，把仓库扫描、依赖提取、模型理解、Graphviz 渲染串成一条流水线，并给出可复现的命令、常见报错和排查路径。

1. 先拆开“仓库解析 Agent”这条链路

1.1 为什么人工画架构图跟不上仓库变化

代码仓库是持续变化的事实集合。每次重构、新增模块、调整目录，架构图都要跟着改，而人工维护的图往往落后于代码。更麻烦的是，人看代码时会漏掉边界情况：一个看似不重要的工具模块被几十个模块引用，一个 service 层文件偷偷 import 了仓储层实现。这些信息靠肉眼很难在大仓库里快速汇总。

自动化解析能解决“事实”部分，也就是模块有哪些、依赖谁、谁被谁依赖。但自动化工具很难回答“这个模块在业务上承担什么角色”“层间调用是否符合规范”。这正是 Agent 能补上的部分：把代码片段和依赖上下文交给大模型，让它输出分层、职责和风险描述。

1.2 一条完整流水线：扫描、解析、建模、理解、渲染

这个工具可以拆成五段，每一段解决一个问题：

1. 扫描：遍历仓库目录，按语言后缀收集源码文件。
2. 解析：用语法分析器抽取每个文件里的 import、引用和调用关系。
3. 建模：把文件和依赖关系建成有向图，节点是文件或目录，边是依赖方向。
4. 理解：调用 Agent 对关键文件做语义分析，补充分层、职责和风险。
5. 渲染：把图数据输出成 Graphviz 的 DOT 文件，再渲染成 PNG、SVG。

流水线的关键点在于顺序。静态解析必须走在 Agent 之前，因为依赖关系是确定事实，不能交给可能产生幻觉的模型去编。Agent 只处理“这张图里每个节点该怎么解释”的问题。

1.3 静态分析与 Agent 的分工边界

用表格来说明分工：

结论是：静态分析负责喂事实，Agent 负责解释语义，两者各管一段。这个边界一旦反过来，架构图就会变成“看起来漂亮但不可信”。

2. 环境准备：把最小链路先跑起来

2.1 Python 依赖与 Graphviz 安装

示例代码用 Python 实现，依赖只有两个：networkx 负责建图，requests 负责调用 Agent 接口。先创建虚拟环境并安装：

python -m venv venv source venv/bin/activate pip install networkx requests

架构图渲染依赖 Graphviz 的外部命令dot，安装方式按系统区分：

# Ubuntu / Debian sudo apt-get install graphviz # macOS brew install graphviz # Windows（管理员 shell） choco install graphviz

安装后确认两个命令都能执行：

dot -V python -c "import networkx, requests; print('networkx', networkx.__version__); print('requests', requests.__version__)"

环境要求如下：

这里要先确认自己的版本。Python 3.8 也能运行，但代码里用了Path.read_text、集合语法和类型标注，老版本需要微调。

2.2 项目目录结构

按职责拆四个模块，后续扩展只需要替换其中一段：

repo-arch-agent/ ├── main.py # 入口，组装流水线 ├── scan.py # 仓库扫描 ├── graph_builder.py # 依赖提取和建图 ├── agent_client.py # Agent 调用和输出解析 ├── render.py # DOT 生成与目录聚合 ├── requirements.txt └── output/ # 生成结果目录

main.py 只负责调度，scan.py 不知道 Agent 的存在，agent_client.py 不知道 Graphviz 的存在。这样测试时可以用--skip-agent只验证静态链路。

2.3 准备一个待分析的示例仓库

用于验证的数据不要太小，也不要太大。20 到 50 个 Python 文件的仓库最合适，既有足够的依赖关系，又能在几分钟内看出结果。

可以直接拿本地 Python 项目做实验，也可以从 GitHub、Gitee、GitLab 克隆一个中小型 Flask 或 FastAPI 项目。下面的命令统一把仓库放在sample_repo目录：

git clone <你的仓库地址> sample_repo

注意：仓库里的代码会以文本片段方式发送给 Agent 接口。涉及密钥、内部域名、客户数据时，先做脱敏或改用私有化部署模型，否则不要把整段代码直接外发。

3. 仓库扫描与依赖提取：先拿到确定的事实

3.1 递归收集源码文件，过滤无关目录

第一步是遍历目录，收集指定后缀的源码文件。真正要处理的文件往往只占仓库的一部分，.git、node_modules、venv、__pycache__这些目录必须跳过。

# scan.py import os from pathlib import Path SKIP_DIRS = {".git", "node_modules", "venv", ".venv", "__pycache__", "dist", "build", ".idea", ".vscode"} def collect_source_files(repo_path: Path, extensions: set[str]) -> list[Path]: files = [] for root, dirs, filenames in os.walk(repo_path): dirs[:] = [d for d in dirs if d not in SKIP_DIRS] for name in filenames: if Path(name).suffix in extensions: files.append(Path(root) / name) return sorted(files)

dirs[:] = [...]这一行是关键，它直接修改os.walk下一次遍历的目录列表。如果写成普通赋值，os.walk仍然会进入被跳过的目录，过滤就不生效。

3.2 用标准库 ast 提取 import 关系

Python 项目可以直接用标准库ast做语法解析，不需要安装 C 扩展。脚本文件、动态导入可以靠正则粗筛，但正则很难处理重名变量和复杂的 import 写法，ast是更可靠的起点。

# graph_builder.py import ast from pathlib import Path def extract_python_imports(file_path: Path) -> set[str]: imports = set() try: source = file_path.read_text(encoding="utf-8") tree = ast.parse(source) except (SyntaxError, UnicodeDecodeError) as exc: print(f"[warn] 解析失败: {file_path} ({exc})") return imports for node in ast.walk(tree): if isinstance(node, ast.Import): for alias in node.names: imports.add(alias.name) elif isinstance(node, ast.ImportFrom): if node.module: imports.add(node.module) return imports

返回结果同时包含项目内部模块和第三方包。内部模块能匹配到仓库里的文件，第三方包匹配不到，自然会被过滤，这也符合画架构图的诉求：只展示仓库内部结构，不展示外部依赖细节。

如果要支持 Java、Go、JavaScript、TypeScript 仓库，把ast换成 tree-sitter 对应的 grammar 即可，每个语言对应一个解析器包，接法完全相同。

3.3 把模块依赖建成有向图

用 networkx 的DiGraph保存文件级依赖。节点是相对路径，边从“当前文件”指向“被依赖文件”。

# graph_builder.py import networkx as nx def build_dependency_graph(repo_path: Path, files: list[Path]) -> nx.DiGraph: G = nx.DiGraph() module_to_file = {} for f in files: rel = f.relative_to(repo_path) module = str(rel.parent / rel.stem) # services/order_service module_to_file[module] = rel.as_posix() G.add_node(rel.as_posix()) for f in files: rel = f.relative_to(repo_path) source = rel.as_posix() for mod in extract_python_imports(f): target = module_to_file.get(mod.replace(".", "/")) if target and target != source: G.add_edge(source, target) return G

这里mod.replace(".", "/")是为了把services.order_service这种模块名还原成相对路径形式，才能和module_to_file的键对齐。若仓库里存在跨目录的相对导入，还需要按当前文件所在目录做一次展开，这个可以作为后续优化点。

依赖图建好后，可以立刻检查一些全局指标：

import networkx as nx print("节点数:", G.number_of_nodes(), "边数:", G.number_of_edges()) print("前 5 个高入度节点（被依赖最多）:") for node, degree in sorted(G.in_degree(), key=lambda x: -x[1])[:5]: print(" ", node, degree)

这里显示的“高被依赖节点”往往就是核心模块，也是下面应该优先交给 Agent 分析的对象。

4. 让 Agent 负责语义理解，而不是负责编造事实

4.1 给 Agent 划定职责边界

Agent 在这条流水线里只做三件事：

1. 判断文件属于哪一层。
2. 用一句话概括文件职责。
3. 标记最明显的架构风险。

它不需要生成依赖列表。依赖列表由静态解析产出，Agent 一旦参与生成，就可能出现它没见过某个 import、却凭训练记忆补充出“可疑依赖”的情况。这种幻觉在单文件上不明显，叠加到整张图上就会误导排查。

实际项目里如果用的是 LangGraph、AutoGen 这类 Agent 框架，可以把“扫描”“解析”“渲染”封装成工具节点，把“语义理解”封装成 LLM 节点。本文保持纯 Python 函数实现，便于看清每一步发生了什么。

4.2 用结构化 Prompt 约束输出

Agent 的输出必须是机器可解析的 JSON。除了在 prompt 里说明字段，还要在请求里带上response_format，并要求低温度，减少随机波动。

# agent_client.py import json import os import re import requests SYSTEM_PROMPT = """你是资深架构师，正在审查 Python 代码仓库。 请分析指定文件在系统架构中的角色，严格输出 JSON，不要输出其他内容。 字段如下： - layer: web|service|data|utils|other - responsibility: 不超过 40 字的一句话职责 - risk: 没有风险写 null，有风险写一句话描述 """ def call_agent(path: str, code: str, model: str = None) -> str: api_base = os.getenv("LLM_API_BASE", "https://api.example.com/v1") api_key = os.getenv("LLM_API_KEY", "") model = model or os.getenv("LLM_MODEL", "gpt-4o-mini") resp = requests.post( f"{api_base}/chat/completions", headers={"Authorization": f"Bearer {api_key}"}, json={ "model": model, "messages": [ {"role": "system", "content": SYSTEM_PROMPT}, {"role": "user", "content": f"文件: {path}\n代码预览:\n{code[:4000]}"}, ], "temperature": 0.2, "response_format": {"type": "json_object"}, }, timeout=60, ) resp.raise_for_status() return resp.json()["choices"][0]["message"]["content"]

代码里调用的是 OpenAI 兼容的/chat/completions接口，因此 OpenAI、Azure，以及大量提供兼容网关的开源模型服务都可以直接替换 base URL 和模型名。四个参数决定了 Agent 效果：

很多模型虽然声明支持 JSON 模式，实际输出仍可能混入解释文字。做一个解析兜底，从响应里直接抽取最外层大括号：

def parse_json_safe(content: str) -> dict: try: return json.loads(content) except json.JSONDecodeError: match = re.search(r"\{.*\}", content, re.S) if match: return json.loads(match.group(0)) raise ValueError("无法从 Agent 输出中解析 JSON")

4.3 把 Agent 结果合并到依赖图

对每个文件调用call_agent，把返回的 layer 和 responsibility 记录下来，供渲染阶段给节点上色和加标签。

# main.py 中的语义分析函数 def analyze_with_agent(files, repo_path, max_files=80): layers, responsibilities = {}, {} for f in files[:max_files]: rel = f.relative_to(repo_path).as_posix() code = f.read_text(encoding="utf-8") for attempt in range(2): try: result = parse_json_safe(call_agent(rel, code)) layers[rel] = result.get("layer", "other") responsibilities[rel] = result.get("responsibility", "") print(f"[agent] {rel} -> layer={layers[rel]}") break except Exception as exc: print(f"[agent] 第 {attempt + 1} 次失败 {rel}: {exc}") return layers, responsibilities

这里做了最多 2 次重试。Agent 请求可能因为超时、限流或返回格式异常而失败，重试是最基本的韧性手段。生产环境还应该加指数退避，避免多文件同时失败把接口打爆。

注意：max_files=80是学习环境的阈值，跑通即可。真实仓库上千个文件时不要全量分析，优先分析高入度、高出度的核心文件，或者按目录抽样。

5. 渲染架构图：从依赖图到可视化

5.1 生成 DOT 描述文件

Graphviz 使用 DOT 语言描述图结构。渲染时用不同填充色区分层级，用节点标签同时显示文件路径和职责。

# render.py from pathlib import Path import networkx as nx LAYER_COLORS = { "web": "#dbeafe", "service": "#dcfce7", "data": "#fef3c7", "utils": "#f3e8ff", "other": "#f8fafc", } def write_dot(G, layers, responsibilities, output_path: Path): lines = [ "digraph architecture {", " rankdir=LR;", ' node [shape=box, style="rounded,filled", fontname="Microsoft YaHei"];', ] for node in G.nodes: color = LAYER_COLORS.get(layers.get(node, "other"), "#f8fafc") label = node desc = responsibilities.get(node, "") if desc: label = f"{node}\n{desc}" label = label.replace("\\", "\\\\").replace('"', '\\"') lines.append(f' "{node}" [label="{label}", fillcolor="{color}"];') for src, dst in G.edges: lines.append(f' "{src}" -> "{dst}";') lines.append("}") output_path.write_text("\n".join(lines), encoding="utf-8")

DOT 文件里节点名和 label 都在双引号内，文件名本身就带"或\时，必须先转义，否则 Graphviz 会报语法错误。中文字体名按操作系统调整：Windows 用 Microsoft YaHei，macOS 用 PingFang SC，Linux 需要先安装中文字体再用 fontconfig 查询名称。

5.2 用 Graphviz 渲染 PNG/SVG

DOT 文件生成后，用dot命令渲染：

dot -Tpng output/arch.dot -o output/arch.png dot -Tsvg output/arch.dot -o output/arch.svg

SVG 适合放进文档和 Web 页面，可以缩放不模糊；PNG 适合直接发给同事或贴到设计文档里。渲染失败时先检查 DOT 文件本身：

dot -v output/arch.dot -o /dev/null

-v会输出详细的布局过程，语法错误会在最开始报出来。

5.3 目录级聚合，解决节点爆炸

文件级图在 20 到 50 个文件时很清晰，到 500 个文件就会变成一团线球。目录级聚合是解决节点爆炸最简单的手段：把同一目录下的文件合并成一个包节点，边在目录之间连接。

def aggregate_by_directory(G: nx.DiGraph, level: int = 1) -> nx.DiGraph: A = nx.DiGraph() for node in G.nodes: parts = Path(node).parts group = "/".join(parts[:level]) or node A.add_node(group) for src, dst in G.edges: s = "/".join(Path(src).parts[:level]) d = "/".join(Path(dst).parts[:level]) if s != d: A.add_edge(s, d) return A

命令行参数化后，可以通过--dir-level控制粒度。一级目录适合看整体分层，三级目录适合看具体业务模块，文件级只适合小仓库。

6. 运行与验证：架构图到底可不可信

6.1 完整命令与预期输出

把主流程组装到 main.py 中：

# main.py import argparse from pathlib import Path from scan import collect_source_files from graph_builder import build_dependency_graph from agent_client import call_agent, parse_json_safe from render import write_dot, aggregate_by_directory def analyze_with_agent(files, repo_path, max_files=80): # 完整版带重试，见 4.3；这里为了可读性省略重试逻辑 layers, responsibilities = {}, {} for f in files[:max_files]: rel = f.relative_to(repo_path).as_posix() code = f.read_text(encoding="utf-8") try: result = parse_json_safe(call_agent(rel, code)) layers[rel] = result.get("layer", "other") responsibilities[rel] = result.get("responsibility", "") except Exception as exc: print(f"[agent] 失败 {rel}: {exc}") return layers, responsibilities def main(): parser = argparse.ArgumentParser(description="代码仓库架构图生成 Agent") parser.add_argument("--repo", type=Path, default=Path("sample_repo")) parser.add_argument("--max-files", type=int, default=80) parser.add_argument("--dir-level", type=int, default=0) parser.add_argument("--skip-agent", action="store_true") parser.add_argument("--output", type=Path, default=Path("output/arch.dot")) args = parser.parse_args() files = collect_source_files(args.repo, {".py"}) print(f"[scan] 发现 {len(files)} 个 Python 文件") G = build_dependency_graph(args.repo, files) print(f"[graph] 节点 {G.number_of_nodes()}, 边 {G.number_of_edges()}") layers, responsibilities = {}, {} if not args.skip_agent: layers, responsibilities = analyze_with_agent(files, args.repo, args.max_files) if args.dir_level > 0: G = aggregate_by_directory(G, args.dir_level) print(f"[graph] 聚合后节点 {G.number_of_nodes()}") write_dot(G, layers, responsibilities, args.output) print(f"[render] DOT 已写入 {args.output}") if __name__ == "__main__": main()

先配好 Agent 环境变量，再执行：

export LLM_API_BASE="https://你的模型网关地址/v1" export LLM_API_KEY="你的密钥" export LLM_MODEL="gpt-4o-mini" python main.py --repo ./sample_repo --output output/arch.dot dot -Tpng output/arch.dot -o output/arch.png

正常输出大致如下：

[scan] 发现 36 个 Python 文件 [graph] 节点 36, 边 47 [agent] app.py -> layer=web [agent] services/order_service.py -> layer=service [agent] repositories/order_repo.py -> layer=data ... [render] DOT 已写入 output/arch.dot

到这里就拿到了第一版架构图。但“能生成图”和“图是可信的”是两回事，必须验证。

6.2 人工抽检 Agent 判别结果

抽检建议按固定比例执行：从所有被 Agent 分析的文件里随机挑 10 个，人工判断 layer 和 responsibility 是否正确，统计一致率。

• 一致率在 80% 以上，说明 prompt 和上下文足够，可以继续扩展。
• 一致率在 60% 到 80%，优先检查代码预览是否截断了关键逻辑，或文件职责本身不清晰。
• 一致率低于 60%，不要硬调 prompt，先看静态依赖图是否正确，因为 Agent 拿到的上下文来自这张图，图错则语义必错。

如果目标是做成可回归的东西，就把抽检文件做成 golden 集合：固定 10 个文件的期望输出，每次修改 prompt 后跑一遍对比，防止优化一个模块同时破坏另一个模块。

6.3 从架构图上发现真实问题

架构图的价值不只是把依赖画出来，而是让问题浮出来：

• 高被依赖节点。入度最大的几个节点往往是核心服务，也可能是被过度复用的“上帝模块”。
• 层间逆向调用。web 层越过 service 层直接依赖 data 层，说明接口未收敛。
• 循环依赖。networkx 可以直接找环：

cycles = list(nx.simple_cycles(G)) if cycles: print("发现循环依赖:", cycles[:5]) else: print("无循环依赖")

这些检查点应该固化成脚本，交给 CI 在每次合并请求时自动跑，而不是等人工看图。

7. 常见问题与排查链路

7.1 排错顺序：从输入到输出逐层检查

遇到问题不要先怀疑模型。按依赖顺序排查：

1. 仓库目录是否扫描到文件，[scan]行数字是否合理。
2. import 匹配逻辑是否正确，[graph]的边数是否少得异常。
3. Agent 接口是否可用，返回是否 JSON，是否超时。
4. DOT 文件是否合法，用dot -v校验。
5. 渲染结果是否有乱码，是否缺字体。
6. 架构图本身是否可信，回到 6.2 做抽检。

前两层是静态逻辑，出错误差是确定的；后四层是外部依赖和语义判断，需要观察日志。

7.2 常见现象、原因和处理方案速查表

7.3 两个高频报错的现场还原

第一个高频报错是agent execution terminated due to error.这种提示，通常出现在 Agent 执行中途被框架终止时。常见于把整个文件甚至整个仓库一次性塞进上下文，导致请求超时或 token 超限。处理方式是代码预览固定截断，例如只保留前 4000 字符和所有 import 行；同时把单文件分析封装成可重试的独立任务，失败不拖垮整批。

第二个高频报错是 Graphviz 的Error: syntax error in line X near '<'。DOT 里 label 使用 HTML 风格标签时，<和>有特殊含义。如果文件路径里出现泛型写法或尖括号，必须先替换或转义。更稳妥的做法是始终保持label="..."字符串格式，并把文件名里的引号、反斜杠一并处理。

8. 落地最佳实践与扩展方向

8.1 学习环境和生产环境的差异

这个工具在个人电脑上跑通，和在公司内部稳定运行，差别很大。

生产环境下最容易被忽视的是代码安全。仓库中的代码可能包含密钥、内部域名、客户信息和未公开逻辑，调用外部 Agent 前必须确认脱敏策略和审批流程。私有化部署模型可以显著降低外发风险，但如果企业内部有大量仓库，还要做好预算控制和批次限流。

8.2 落地前检查清单

发布到团队内部前，逐项确认：

• [ ] 目标仓库的语言是否在解析器支持范围内。
• [ ] 已配置模型网关、密钥和模型名，且密钥不写入代码仓库。
• [ ] 已对长文件做截断，并对 Agent 调用加重试和超时。
• [ ] 已随机抽检至少 10 个文件的判别结果，一致率达标。
• [ ] 渲染端已安装 Graphviz，中文字体可正常显示。
• [ ] 大仓库已配置目录级聚合阈值和最大分析文件数。
• [ ] 输出目录和运行日志有固定位置，失败可重跑。
• [ ] 涉及敏感代码的仓库不会把原始代码外发到外部模型。

8.3 可以继续做的五个方向

1. 多语言支持。Python 示例只覆盖ast，接入 tree-sitter 后可以解析 Java、Go、JavaScript、TypeScript，图结构和渲染部分不需要改。
2. 增量分析。在 CI 里只对git diff涉及的文件重算依赖和 Agent 标注，避免每次全量跑。
3. Agent 记忆。对已分析过的文件保存结果，文件内容未变化时直接复用，降低 token 成本，也提高结果稳定性。
4. 架构规则检查。把“web 不能直连 data 层”“不允许循环依赖”等规则写到引擎里，图中每出现一次违规就产生一条 issue，而不是只画出来让人肉眼看。
5. 文档联动。把架构图、模块职责和风险描述一起交给 Agent，生成 README 的架构章节，让文档和代码保持同步。

最后说一句实践判断：这类工具最容易犯的错误，是让 Agent 在缺少静态事实的情况下“自由发挥”。先把扫描、解析、建图这三段做扎实，再把 Agent 的语义分析加进来，每一步都可抽检、可回滚、可离线运行，这样的架构图工具才有长期使用价值。