企业官网建设流程全解析

把代码交给 AI 自动生成架构图，这个想法在 GitHub Trending 上被反复验证过：某段时间内，相关项目会突然冲到全球趋势榜前列，随后大量开发者涌入试用。对长期维护“文档过时、架构图缺失、新人上手靠口口相传”的仓库而言，这类工具确实解决了真实痛点。架构图不是画出来就完事，而是要回答一个问题：这个系统为什么分成这些模块，模块之间怎样依赖，数据如何流动，部署边界在哪里。本文围绕这类 AI 架构图生成工具，从原理、环境准备、实际操作、结果校验到生产落地顺序，写一篇能直接照着用的实践笔记。

文章会以一个典型的 Web 后端仓库为示例，说明工具如何分析代码结构、AI 如何参与架构识别、生成结果如何校验，以及遇到“生成图太粗、依赖错乱、仓库拉不下来”之类问题时怎么排查。适合正在做系统重构、接手老项目或要准备架构评审材料的开发者阅读。

1. 先理解 AI 生成架构图为什么能成立，以及它不等于“自动画图”

1.1 架构图难以维护的根源在于代码库本身在变化

传统绘制架构图的方式是架构师阅读代码、归纳模块边界、手工绘制。这种方式有三个明显问题。一是滞后，架构图往往只在项目立项或大版本评审时更新一次，日常提交不会有人同步修改文档。二是失真，阅读代码的人看到的依赖关系是局部的，A 服务调用了 B 服务的接口，但 B 服务是否被 C 服务反向依赖，靠人肉扫一遍调用链很难保证全面。三是表达歧义，同样一张分层图，有人理解是逻辑分层，有人理解是部署结构，争论半天没有结论。

AI 生成架构图的思路不是替代架构师，而是把“读代码、提取结构、形成图形描述”这一步自动化。它的输入是代码仓库，中间产物是模块列表、依赖关系和关键节点，输出是可以在文档工具中渲染的图形描述，比如 Mermaid、PlantUML、D2 或 JSON 图数据。整个过程尽量回避“人读完全部代码”的环节，而是让构建系统、AST 分析、依赖扫描和 LLM 推理协作完成结构还原。

1.2 三种常见技术路线，决定了生成结果的精确度

当前常见的方式可以分为三类，理解它们的区别对选择工具有帮助。

第一种是静态依赖分析路线。解析项目中的 import、require、module declaration、依赖描述文件，生成模块间的调用关系。精确度高，但只能反映“代码里已经存在的依赖”，无法理解业务边界和架构意图，容易画出“所有模块互相引用”的蜘蛛网。

第二种是 LLM 推理路线。把整个仓库或关键文件的摘要交给大模型，让模型推断系统有哪些核心模块、模块间是什么关系。优点是能给出接近人工分析的模块命名和职责描述，缺点是代码量一大，模型上下文不够，很容易忽略部分模块，导致生成的架构图与真实代码有偏差。

第三种是混合路线。先用静态分析把代码依赖和文件结构提取出来，再交给 LLM 生成模块解释和图表描述。它兼顾精确性和可读性，是目前大多数 GitHub 热门项目采用的方案。实际使用时，可能还要加入构建系统信息，比如 Maven 多模块、Gradle 子工程、npm workspace，才能让模块划分更接近真实部署边界。

1.3 选型前先想清楚这张图给谁看

不同使用场景对架构图的要求完全不同。给新人看系统概览，需要高层次的模块划分和职责说明；给架构评审用，要展示依赖关系和分层合理性；给运维同学看，要标出部署节点、端口和调用链。AI 生成的结果往往偏向“模块依赖关系”，很难直接满足所有场景。

所以在实际操作之前，先把目标定下来。如果只是给新人做快速上手说明，让 AI 生成一张模块概览图就够；如果是代码评审，需要先跑静态依赖分析再让 AI 生成分层说明。这里有一个很容易踩的坑：拿到一张 AI 生成的架构图，不加校验直接贴进项目文档，结果图上标的模块名和实际代码目录对不上，反而误导读图人。后续会专门讲结果校验。

2. 本地环境准备：先把仓库结构和依赖入口摸清楚

在调用任何 AI 工具之前，先确认环境是否满足条件。很多失败不是 AI 能力不行，而是代码仓库本身没有正确拉取、依赖没有解析成功、目录被构建产物污染。

2.1 环境检查清单

推荐按下面的清单逐项检查：

2.2 通过 git clone 获取仓库，并按需浅克隆

用浅克隆减少仓库体积是一种很实用的做法。对一个只做分析、不参与开发提交的临时目录来说，不需要完整历史。

git clone --depth 1 https://github.com/example/example-repo.git cd example-repo

浅克隆虽然速度快，但后面如果要用git log分析模块演进或定位某次重构，历史不全会有限制。建议保留一个完整 clone 作为分析主目录，浅克隆只用于快速试用。

2.3 用文件结构和依赖描述文件理解仓库入口

拿到仓库后不要急着运行 AI 工具，先用常规命令看一眼结构。推荐命令：

find . -maxdepth 2 -type d -not -path '*/\.*' | sort

这个命令可以快速看到顶层模块。接下来看依赖描述文件，判断技术栈：

ls -la pom.xml build.gradle package.json requirements.txt go.mod Cargo.toml 2>/dev/null

看到pom.xml和src/main/java目录，基本可以确定是 Java Maven 工程；看到package.json加src，可能是前端或 Node 服务；既有pom.xml又有package.json，则是前后端混合仓库。AI 工具在分析时如果缺少这一步，很容易把前端目录和后端目录混在一个模块里，生成的图层次混乱。

2.4 排除干扰目录，确定分析范围

一个典型仓库中，真正反映架构的代码通常只占一部分。node_modules、target、dist、__pycache__这些目录应该从分析范围中排除。有些工具支持.gitignore自动读取，有些需要手动配置排除规则。手动执行时可以用下面的命令确认哪些目录占空间最大，判断是否应该排除：

du -sh */ | sort -h | tail -20

这一步非常关键。AI 工具如果误把node_modules里的第三方包当作项目模块，生成的架构图会包含大量无关节点，根本没有可读性。后面看到“架构图里有 200 个模块”的异常情况，大多数是范围没有限定好。

3. 用 AI 生成架构图的完整操作步骤

这一节用一个典型场景说明完整流程：一个后端仓库，使用 Java + Spring Boot，包含多个 Maven 子模块。目的是生成一份“模块划分 + 层间依赖”的架构图。

3.1 方式一：使用 AI Agent 自动分析代码库

如果选择的工具是 AI Agent 类型，通常会提供命令行入口或阶段式任务。启动后 Agent 会执行代码扫描、读取关键文件、生成分析结果。这类工具的特点是“自主性强”，但用户需要给它足够清晰的目标。

一个典型命令可能是：

ai-arch-agent analyze --repo . --output docs/architecture.md --format mermaid

这里--repo .表示分析当前目录；--output指定生成文件位置；--format指明输出图形格式。命令的具体参数以项目 README 为准，但流程是通用的：扫描代码、生成描述、输出图形文件。

使用 Agent 方式时，建议先做一次 dry-run 或小范围测试。如果工具支持--scope或--exclude，直接指定要分析的目录，否则等工具扫描完整个仓库，再剔除无关模块会非常吃力。

3.2 方式二：用结构化提示词驱动 LLM 生成 Mermaid 图

在没有现成 Agent 工具的情况下，可以借助通用大模型接口完成分析。做法分三步：先提取必要的代码结构信息，再构造结构化提示词，最后把模型输出转成图形。

提取结构信息可以用一条命令完成：

find src -name "*.java" | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -30

这个命令统计哪些包目录文件最多，哪些包是主要业务模块。文件数量多的包通常是核心模块，数量少但被许多包依赖的可能是公共基础模块。

把结果整理成如下提示词：

你是一个代码架构分析助手。下面是一个 Spring Boot 项目的包结构信息： controller: 12 个文件 service: 18 个文件 repository: 14 个文件 common: 20 个文件 config: 5 个文件 请根据这些包名，推断模块间的依赖关系，并生成一张 Mermaid 架构图。 要求： 1. 说明这些包在分层架构中的位置 2. 标出典型调用方向 3. 使用 graph TD 格式

这样的提示词相对可控，但要注意一个局限：包结构信息只在宏观层面有效，具体类之间的关联仍然缺失。如果某个 service 类直接依赖另一个 controller，模型不会知道。要提升准确度，需要把关键类的依赖关系也提取出来，例如用jdeps检查 Java 类依赖：

jdeps --multi-release 17 -s target/classes

jdeps输出的是包级别的依赖摘要，可以直接给到提示词里，让模型知道“包 A 依赖包 B”。

生成后的 Mermaid 图示例：

graph TD Controller[Controller Layer] --> Service[Service Layer] Service --> Repository[Repository Layer] Service --> Common[Common Module] Repository --> DB[(Database)]

注意：这里的 Mermaid 代码块是展示给读者的示例，文章本身不会使用 Mermaid 渲染。把它当作提示词期望输出的格式就好。

3.3 方式三：静态分析工具辅助，再让 AI 补可读性

如果仓库复杂度高，直接用代码结构让 AI 猜依赖关系会失真。更稳妥的路是先用静态依赖分析工具生成结构化描述，比如 JSON 或 DOT 文件，再交给 AI 转换成架构图。

以 Java 项目为例，用 Maven 插件生成依赖树：

mvn dependency:tree -Dscope=runtime -DoutputFile=dependency-tree.txt

dependency-tree.txt记录了 Maven 模块之间的依赖关系。AI 读取这份文件后，能更准确地区分“本地模块”和“第三方依赖”。一般需要告诉模型：只关注本地模块，第三方库统一归为 External Dependencies 节点。

这种方式比直接让 LLM 猜代码结构要强得多，因为它把最耗 token 的“代码阅读”环节替换成了结构化数据，模型只需要做一次归纳。成本更低，准确率也更高。

3.4 通用流程总结

无论采用哪种方式，核心流程都可以收敛为四个阶段：

很多项目只做了前两个阶段，结果生成一张“文件依赖图”，不是“架构图”。两者的区别在于：文件依赖图是事实，架构图是解释。AI 的作用恰恰是把事实整理成有层次的解释。

4. 生成结果校验：不校验的架构图是新的文档负债

AI 生成的架构图有一个天然缺陷：它可能“读起来合理，但某处细节是错的”。尤其当仓库结构复杂、模型上下文不足时，容易遗漏模块或把第三方依赖误判为业务模块。所以校验环节不能省略。

4.1 对照模块清单逐项查

先把生成结果中的模块列表和实际目录结构对照一遍。列出仓库一级目录的模块名称：

find src -maxdepth 1 -type d -printf '%f\n' | sort

再把这个结果与架构图中的模块节点比较。缺失的模块要补，多余的节点要删。这里最容易出现的问题是“公共模块被忽略”：很多静态分析工具会把被大量模块依赖的工具类目录省略，因为它在文件数量上不突出，但架构图上少了它，模块间的依赖关系就说不通。

4.2 校验依赖方向

依赖方向是架构图最核心的信息。如果架构图显示 Controller 依赖 Repository，而代码里 repository 包被 service 包依赖，那这张图就是错的。手动校验时，建议抽查 3 到 5 条真实调用链。

用grep查找一个接口的实现：

grep -r "class UserServiceImpl" src/main/java --include="*.java"

查看该实现类里是否调用了 Repository 接口。然后到架构图上确认箭头方向是否从 Service 指向 Repository。不要全量校验，优先校验“分层边界处”的调用链，因为跨层调用往往是架构违规的高发区。

4.3 统一架构图的抽象层次

AI 生成容易犯的一个错误是层次混乱。比如控制器、服务、仓库被画成并列节点，而实际上它们属于同一个服务的不同层。修正时可以在 Mermaid 中加入 subgraph 表达分组：

graph TD subgraph Backend Service Controller --> Service Service --> Repository end Repository --> ExternalDB[(Database)]

用 subgraph 把同一部署单元内部分层放到一个组里，跨部署单元的依赖关系再单独连接。这样图的结构更贴近现实，也更容易让看的人理解系统边界。

4.4 将校验结果纳入文档管理

架构图只有持续更新才有价值。建议把生成架构图的命令和提示词模板放到文档目录中，例如docs/architecture/README.md中写明：

重新生成架构图： 1. 清理本地构建产物 2. 执行静态依赖分析 3. 按 docs/ai-arch-prompt.md 里的提示词生成 4. 按 docs/architecture/checklist.md 校验

这样每次架构调整后，团队可以重新生成并快速核对差异，而不是让架构图再次变成无人维护的旧文档。

5. 常见问题排查：从现象定位到处理方案

5.1 GitHub 仓库拉不下来或下载慢

现象：git clone长时间卡住或报Failed to connect，下载 zip 包也很慢。

可能原因：网络到 GitHub 域名的连通性不稳定；仓库历史过大或包含大文件；本机 DNS 解析异常。

检查顺序：

1. 先确认当前网络能否正常访问 GitHub 官网页面。这里说的“正常访问”指不依赖任何第三方劫持页面或改写页面，直接请求官方域名是否返回结果。
2. 用git clone --depth 1做浅克隆，排除历史包袱造成的问题。
3. 检查仓库是否有大文件子模块，例如通过du -sh查看下载后的体积。
4. 如果网络确实不稳定，可以改从代码托管平台直接下载归档包，或使用企业内部代码库同步后的地址。

不建议做的事：不要在任何生产环境或正式开发流程中依赖来源不明的第三方“加速”域名。文件来源不可控，存在代码安全和供应链风险，宁可把 clone 任务放到网络可达的工作环境执行，也不要引入无法审计的中间源。

5.2 生成的架构图过于笼统，看不出模块职责

现象：AI 输出只有三个节点，“前端”“后端”“数据库”，没有任何分层和模块边界。

可能原因：提示词没有要求模块级分析；提取的代码结构信息太少；仓库中文件组织确实扁平。

处理方式：回到结构提取阶段，用find和jdeps补充包级别依赖数据，再重新生成。如果仓库本身就没有清晰模块化，AI 只能按文件目录硬猜，这种情况下先做代码结构调整比生成架构图更有意义。

5.3 依赖关系错乱，箭头方向和代码实现不一致

现象：架构图显示 A 依赖 B，代码中 B 却反向依赖 A。

可能原因：分析工具把 import 方向和运行时调用方向混淆；Maven 多模块与包名不一致导致模块归并不对；AI 在生成时做了错误推断。

处理方式：先用静态依赖工具确认实际依赖方向，再修正提示词，明确要求“只基于依赖分析结果，不要推测”。人工抽查核心调用链，至少保证纵向上“Controller -> Service -> Repository”的关键链路是正确的。

5.4 AI 生成的模块名与代码目录名不一致

现象：代码中有payment目录，AI 却写出billing模块名。

可能原因：模型根据上下文语义自行归纳了名称；提示词没有约束使用目录名作为节点名。

处理方式：在提示词中写死规则：模块名必须与包路径或目录名保持一致。这样虽然少了一点抽象，但保证了图和代码的可映射性。业务含义可以由节点的说明文字补充，不要用臆造名替换真实模块名。

5.5 常见问题速查表

6. 在真实项目中落地的顺序和建议

6.1 先跑通最小案例，再投入整个仓库

第一次使用 AI 架构图工具时，不要直接拿全公司最大的单体仓库测试。选一个小型后端服务或一个独立子模块，跑通流程，确认输出格式和校验方式，再扩大到主仓库。这样做的好处是能快速建立对工具行为的预期，知道哪些内容要人工修正，哪些输出可信。

对于有遗留代码的系统，建议分模块生成，再手工拼接总图。一次让 AI 分析 50 个模块和文件之间的依赖，效果通常不会好；但每次分析 5 到 10 个模块，再在总图上合并，准确率会明显提升。

6.2 建立架构图更新机制，而不是一次性生成

架构图生成不是架构治理的终点。比较实用的做法是把“生成架构图”做成 CI 的可选任务：每次主分支合并后，触发一次依赖分析和架构描述更新，生成的图作为 PR 附件或文档自动更新。这样至少能保证代码合并后，架构描述不会立刻失真。

如果没有 CI 条件，也可以在项目文档中写明更新周期，比如“每次大版本评审前必须重新生成并对照模块清单”。实际开发中，很多团队不是不想更新，而是不知道需要更新。把生成命令写进 README 之后，更新成本降低，遵守率也会提高。

6.3 推荐给团队使用的检查清单

以下清单可以在发布架构文档或评审前逐项确认：

• 代码仓库是否已清理构建产物，分析范围是否限定在业务代码目录。
• 依赖分析结果是否排除了第三方包，仅保留本地模块之间的依赖。
• 生成的模块名是否与代码目录/包路径一致。
• 分层依赖方向是否抽查验证，至少验证 Controller 到 Service 到 Repository 的主链路。
• 架构图中是否区分了逻辑分层和部署边界。
• 生成命令、提示词模板和校验清单是否已提交到文档目录。
• 文档中是否注明重新生成的时间和对应代码版本。

6.4 可以继续扩展的方向

如果已经能稳定生成模块级架构图，下一步可以尝试几个方向：把架构图与接口文档关联，从调用链中识别热点路径；用同样的分析流程生成系统演进记录，对比两个版本间的依赖变化；把架构图接入技术债分析，找出跨层调用和循环依赖的模块。这些方向核心依赖的数据依然是“准确的代码结构与依赖关系”，所以先把生成和校验基础打牢，再向更多场景扩展。

对新手来说，最有价值的练习不是换用更多 AI 工具，而是拿自己最近维护的小项目跑一遍，先自己画一版架构图，再让 AI 生成一版，最后对比差异。差异出现的地方，就是你对这个系统理解还不够或者当前代码边界不清晰的地方。用这种方式，架构图生成工具就成了检查架构认知是否准确的镜子。