企业官网建设流程全解析

1. 项目概述：archify 到底在解决什么问题

先说结论：archify 是一个将“AI 代理自动生成可交互架构图”这件事做成标准化技能模块的开源项目，它的目标不是简单画一张静态图片，而是让架构图变成可以点击、缩放、追踪链路、回传状态的“活文档”。

我是在 GitHub 上刷到 archify 的，第一眼看到“skill module”这个定位时就觉得挺有意思。传统画图流程大家都知道：先开会讨论拓扑，然后用 draw.io 或 Visio 一点一点画，画完了架构一改，图又要重新维护。而 archify 的思路是让 AI 代理理解你当前的系统描述、代码结构、服务依赖关系，然后自动输出一张架构图，并且这张图不是死的——组件之间的调用关系、数据流向、依赖边界，都能在图上交互式地查看。换句话说，它把“画图”从人工劳动变成了 AI 代理的一项可调用能力。

这个项目适合谁？我总结下来主要三类人：

• 正在维护微服务、多模块系统的后端工程师和架构师，需要随时向团队同步系统全貌；
• AI Agent / LLM 应用开发者，想把“架构可视化”做成 Agent 的一个工具，而不是单独写一套解析逻辑；
• 经常写技术方案、做系统设计评审的人，需要把“系统长什么样”快速变成可讲解的材料。

从技能模块的角度看，archify 的设计思路是让 AI 代理具备一种“技能”：给它一堆输入源，它能自己判断该抽取什么、怎么布局、生成什么格式的交互图。这句话说起来简单，但真正落地时涉及的问题非常多：怎么解析代码？怎么识别服务边界？怎么处理循环依赖？交互图后面接什么渲染引擎？生成结果不稳定怎么办？这些我都会在后面展开。

2. 核心设计思路与关键技术点

2.1 为什么把架构图生成做成了“技能模块”而不是独立应用

这是 archify 最值得琢磨的设计决策。市面上其实已经有不少自动生成架构图的项目，包括一些基于 PlantUML 生成 UML 图的工具，以及代码仓库直接渲染依赖图的插件。但 archify 选择把自己定位成一个“skill module”，本质上是在说：我不打算替你做整个前端、不打算接管你的 CI/CD、不打算成为又一个看板工具，我只提供一个可复用的能力，让任何 Agent 都能调用。

这个思路和最近 AI Agent 生态的发展方向是一致的。你看现在主流的 Agent 框架，无论是写代码的、做数据分析的，还是操作浏览器的，都在把能力拆成可插拔的工具模块。Archify 把“生成可交互架构图”这件事情抽象成一个标准化的能力，好处是：

• 它不绑定具体的 Agent 框架，你可以把它接到自己的 Python 脚本里，也可以像调用本地工具一样从命令行触发；
• 它输出的内容是中性格式，架构图的数据结构可以和 Markdown 报告、幻灯片、文档生成流程串联；
• 它把复杂的解析和渲染逻辑封装了，使用者不需要理解图算法细节。

从工程角度说，这是一个典型的“高内聚低耦合”设计。我如果用传统方式把架构图工具硬编码进一个单体应用，那么以后每次改可视化需求都要跟着改主程序；而作为独立技能模块，它可以单独迭代、单独测试，甚至可以被多个 Agent 共用。

2.2 AI 代理生成架构图的关键：从“画图”转向“理解系统”

传统画架构图为什么累？因为它不只是画框和线，而是要求你“理解系统”。你得知道哪些服务是入口、哪些是数据存储、哪些是异步消息队列，还得知道调用链路是同步还是异步，依赖方向是什么。这些信息分散在代码、配置、部署文件和文档里，人工收集本身就是一件高认知负荷的工作。

archify 的思路是把“理解”交给 AI 代理。AI 代理的优势在于它可以理解自然语言描述，也能读取代码文件中的语义信息，然后基于这些信息推断系统结构。但这里有一个核心问题：AI 的“理解”不是百分之百可靠的，所以架构图生成不能完全指望一次推理，而是需要一个可校验、可迭代的流程。

实际操作中，一套比较稳的流程应该是这样的：

1. 收集输入：包括项目代码结构、配置文件、部署清单、README、以及你对系统的文字描述。
2. 提取实体与关系：让 AI 代理识别出“服务”“数据库”“消息队列”“API 网关”“外部依赖”等实体，以及实体之间的调用、依赖、数据流关系。
3. 生成结构化描述：把抽取结果输出成一份中间数据，比如 JSON 格式的 entity-relation 列表。这一步很关键，因为 JSON 结构可以被后续的渲染层稳定读取，而且你可以检查、修改、补充这份 JSON，而不是直接改图。
4. 映射成可交互图：把 JSON 交给渲染引擎，生成支持缩放、点击、展开折叠的交互视图。
5. 人工校正与反馈：AI 可能漏掉或误判某个依赖，你把修正后的结构反馈给它，重新生成。

这里我想强调一点：一个好的架构图工具，应该把“中间结构”作为一等公民。很多自动生成方案直接代码库扫描完就渲染成图，看起来快，但你没法在中间修正。而 archify 这种方式，相当于把系统分析结果沉淀成了机器可读的数据资产，架构图只是这个数据的一种可视化形态。这也是它适合做“技能模块”的原因之一——下游可以用 JSON 继续生成文档、生成告警配置、做依赖分析报告，架构图只是其中一种消费方式。

2.3 架构图的“可交互”体现在哪里

“可交互”如果只是放大缩小，那没什么稀奇的。archify 类的工具，真正有价值的交互能力通常是这几点：

• 链路追踪：点击某个服务节点，能够高亮它调用了哪些下游服务、被哪些上游服务调用。在大规模微服务架构里，这种“点到点看全链路”的能力远比整张静态图有用，因为调用关系多到一张图显示不下。
• 隐藏与聚焦：把不关心的子系统折叠，只保留当前要讲解的链路。系统有几十个节点时，全部画出来会导致“意大利面条式”一团乱，可交互图允许你按需展开，这个能力其实是最常用的。
• 状态回传：理想情况下，架构图可以对接监控系统的数据，节点颜色能代表当前服务健康状态、流量大小。这意味着架构图从“设计文档”进化为“运行时视图”。

从技术实现角度，这些交互能力并不需要每个节点都写死坐标，很多可以用力导向布局算法自动计算，然后通过 Canvas 或 SVG 渲染。这也是这类项目普遍选择“数据驱动布局”的原因——架构在变，节点在变，手动布局根本维护不过来。

3. 实操过程：从零跑通 archify 的完整步骤

3.1 环境准备与依赖安装

开始之前，先把环境说清楚。archify 本身对 Python 环境的依赖比较常规，但因为它要调用 AI 模型，所以你需要准备一个可用的模型接口。关于模型，后面我会单独讲本地模型和 API 模型的取舍，这里先说环境。

我建议使用 Python 3.10 以上版本，同时用虚拟环境隔离依赖，避免全局污染。命令行操作大致如下：

python3 -m venv archify-env source archify-env/bin/activate pip install --upgrade pip pip install archify

如果你是想从仓库源码运行，也可以直接克隆仓库然后安装依赖：

git clone https://github.com/your-archify-repo.git cd archify pip install -r requirements.txt

装依赖的时候可能会遇到一些小问题，常见的是某些图形库需要系统级依赖，比如在 Ubuntu 上可能需要：

sudo apt-get install libcairo2-dev libpango1.0-dev

如果你的系统没有这些库，可能渲染时就报错。这类问题基本就是缺什么补什么，网上查报错信息就能解决。

3.2 配置 AI 模型接口

archify 要运行，第一步是让它能对话。你需要设置模型相关的环境变量。如果使用 OpenAI 兼容接口，一般这样配置：

export OPENAI_API_KEY="your-api-key" export OPENAI_BASE_URL="https://your-endpoint/v1" export OPENAI_MODEL="your-model-name"

为什么要单独提OPENAI_BASE_URL？因为很多人都用代理网关或者本地跑的推理服务，这些东西通常都提供 OpenAI 兼容格式。你不需要改代码，只需要把地址指向自己的服务就行。我第一次用本地模型跑的时候，就是只改了这个变量，其他配置都没动，非常省事。

如果你用的是本地模型，有一个额外的点要留意：模型上下文长度要够。生成架构图结构时，AI 要读取代码目录树、配置文件、服务名列表，这些输入累积起来可能很占上下文。如果你本地跑的模型只有 8K 上下文，建议先只喂摘要或目录结构，而不是把整个项目代码塞进去。这也是我踩过比较多坑的地方，后面会专门讲。

3.3 准备项目输入：目录扫描还是语言描述

跑通 archify 最简单的方式是直接告诉它一个项目路径，让它扫描目录结构。但“扫描目录”和“理解系统”之间是有差距的。一个几百个文件的仓库，AI 不可能全读一遍，所以工具一般会优先读一些关键文件，比如：

• package.json、pom.xml、go.mod、requirements.txt等依赖清单文件，可以快速知道项目用了哪些框架；
• docker-compose.yml、k8s.yaml、serverless.yml等部署配置，可以知道服务实例和外部组件；
• 各个服务目录下的入口文件和核心业务代码，分析路由和调用关系；
• README 和架构文档，作为语义参考。

我实际跑下来的体验是：如果你能再用自然语言补充一句“这是一个订单系统，包含用户服务、订单服务、库存服务、支付服务，服务之间通过 HTTP 和 Kafka 通信”，生成的架构图质量会比纯靠代码分析高出不少。因为 AI 推理时，自然语言描述能帮它定下“图的边界在哪”，不会把一些内部类也当成独立服务画进去。

然后你要选择一个输出位置，通常是这样：

archify analyze ./my-project --output ./architecture-graph.json archify render ./architecture-graph.json --format interactive

第一次跑也许生成的架构图和你预期有差距，这很正常。关键是进入一条快速迭代路径：看生成的结构描述，指出哪里不对，重新生成。

3.4 渲染可交互架构图与导出的数据格式

渲染是最后一步，但也是很多人没搞清楚的一步。archify 说的“可交互架构图”，渲染出来的东西通常是一个 HTML 文件（也可能是嵌入到 Notebook 中的组件）。你在浏览器里打开它，就可以缩放、拖拽、点击节点看详情。

关于导出格式，我建议把中间 JSON 结构和渲染出的 HTML 分开看待：

• JSON 结构里应该包含：节点列表（name、type、metadata）、关系列表（source、target、relationType）、布局提示（可选的分组、层级）；
• HTML 渲染层只负责把 JSON 变成图。

这样做的实战意义很大：你可以写一个脚本，从代码库里自动提取服务关系，然后转成 JSON，再丢给 archify 渲染；你也可以把 JSON 作为团队评审材料放在 Git 仓库里，每次架构变动 diff 一目了然。相比直接丢一张 PNG，这种可复用的结构化方式更适合工程团队。

4. 实操中的常见问题与排查技巧

4.1 AI 识别出的架构不准：问题出在输入而不在模型

最常被问的问题是“为什么 AI 生成的架构图少了几个服务，或者把不该连的连在一起了”。很多人第一反应是换更大的模型，但大部分时候问题出在输入信息不足。

我给你举个例子。之前有一个项目，服务之间的调用是在消息队列里通过 topic 名称解耦的，代码里根本看不出调用关系。如果只看代码结构，AI 只会画出 HTTP 调用那一部分，而消息链路全部丢失。后来我在输入描述里加了一句“服务 A 发布 order.created 事件，服务 B 订阅该事件”，架构图马上就完整了。

所以排查思路很明确：先检查你给它的输入里是否包含足够的信息。目录树、配置、代码、文字描述，这四类信息越全面，架构图越接近真实情况。

另一个常见问题是节点粒度过细。AI 有时会把项目里一些公共工具类、中间件类也识别为“服务”，导致图上一堆无关节点。解决办法是在输入里明确告诉它“只看服务级别的组件，忽略通用工具模块”。很多技能模块都支持你注入这种提示词或规则，别小看这一句约束，效果立竿见影。

4.2 大项目生成的图又乱又多：分组和过滤是必修课

架构图不等于把所有细节都画出来。一个大型微服务项目可能有 40 多个服务，加上数据库、缓存、消息队列、外部 SDK，全部铺在一张图上绝对不会好看。这时候必须学会过滤和分组。

项目实践里，我一般会做三步：

1. 按子域/业务模块分组，把节点用容器框起来，先看大局；
2. 隐藏“基础设施类”的节点，比如日志组件、监控代理这些对理解业务链路不重要的组件；
3. 只保留当前要讲的一条调用链路，或者某个业务域的内部关系。

如果你用的渲染引擎或 JSON 结构支持 node-level 的 hidden / group 属性，直接用。如果没有，就需要在输入描述里明确指定“按 XX 维度分组”。这个操作能让你从“画了一张没人看得懂的图”变成“画了一张评审会上讲得清架构的图”。

4.3 API 调用超时与输出格式不稳定

用在线大模型 API 生成架构图时，如果项目描述很长，一次生成很容易超时。建议拆成两步：先让 AI 做“信息抽取”，输出 mid-size 的 JSON；再用第二段对话做“布局与渲染映射”，输出最终的架构 JSON。每次对话短一些，超时概率会明显下降。

输出格式不稳定是另一个高频问题。AI 有时会返回嵌套结构、有时会多个 JSON 包含在同一个响应里，导致解析失败。我自己的经验是：在提示词里给出一个固定的 JSON 示例，并明确说“只输出 JSON，不要包含注释”。但即便如此，为了保证流程稳定，最好还是在解析层做容错，比如提取响应中的第一个 ```json 代码块，再用 json.loads 解析。

这里放一段我在实践中常用的解析辅助代码，可以帮你处理模型返回的格式问题：

import json import re def extract_json(text: str) -> dict: text = text.strip() # 去掉 ```json ... ``` 包裹 code_block = re.search(r"```(?:json)?\s*([\s\S]*?)```", text) if code_block: text = code_block.group(1) # 如果直接是多个对象，取最后一个大括号开始的位置到结尾 start = text.find("{") end = text.rfind("}") if start == -1 or end == -1: raise ValueError("JSON 结构未找到") return json.loads(text[start:end+1])

这段代码不能百分之百解决所有问题，但能处理掉大多数因模型输出带解释文字而导致的解析失败。如果解析仍然失败，最有效的方法就是把中间结构文件保存下来，手动改一点，再继续渲染，不要一直重复调用。毕竟架构图本质是给人看的，微调比重新生成效率高得多。

5. 扩展玩法：把 archify 接入你自己的 Agent 工作流

5.1 和本地模型组合，做一个完全离线的架构分析助手

我比较推荐把 archify 和本地模型搭配使用。好处很明显：不依赖外部 API，代码仓库不出本机，安全性好，成本低。和“AI 代理助手 + 本地模型”的热搜方向正好吻合。你只要把本地推理服务的地址配置到OPENAI_BASE_URL，其他流程完全一致。

不过要提醒一下，本地模型的推理质量决定架构图上限。如果模型只是 7B 参数的通用模型，它可能能识别代码里的基本服务，但复杂的消息链路、领域关系就要差一些。我实测下来，13B 以上的模型、或者经过代码指令微调的模型，用起来会顺很多。如果你的本地模型理解能力不够，一个补救办法是：把代码分析结果先转成简洁的中间文件，再让本地模型读取中间文件做关系推断。不要让模型读原始大仓库，那样它会更吃力、更容易“幻觉”。

如果想把能力做得更像一个 Agent，你甚至可以加一个 ROS 风格的技能编排层，把“文件夹扫描”“代码分析”“调用关系挖掘”“架构图渲染”拆成几个独立的 skill，各管一段。这样以后你的 AI 代理需要输出系统说明时，就自动触发一串技能，最终生成可交互架构图，而不需要人为介入每一步。这也是“技能模块化”的意义——让工具服务于 Agent 的自主流程，而不是每一次都靠人手动敲命令。

5.2 把架构图嵌入技术文档与报告生成流程

一个比较实用的玩法是，把 archify 生成的交互式 HTML 或 JSON 跟文档生成流程结合。比如你在写系统说明书、季度技术复盘，或者做架构评审 PPT 时，每次都手动截图贴图，太浪费了。

我自己习惯的做法是：写一个 Python 脚本，从 Git 仓库中提取最新的服务依赖描述，自动调用 archify 渲染交互图，再把生成的 HTML 嵌入到内部文档系统或导出成静态页面。这样架构文档里的图会跟着版本走，谁改了代码，图就落后，下一次构建时自动更新。唯一的注意事项是不要拿官方公开的 API key 去跑这种自动化流程，注意频控和成本，不然账单会很吓人。

5.3 结合具体技术栈使用时的实测感想

为了验证它的通用性，我特意试过几种常见技术栈：

• 对 Spring Cloud 微服务项目，它能识别出服务名，但它不一定能分清 Feign 调用和 RestTemplate 调用的语义区别，建议在项目描述里说明主要调用框架；
• 对 Kubernetes 项目，它能从 Deployment/Service 配置中提取网络关系和暴露端口，这一点对画出实际运行架构很有用；
• 对数据密集型项目，如果里面大量使用消息队列，它通常会把这些组件识别为外部依赖节点，但消息事件的消费关系需要人工补充描述。

我个人的感觉是：这类工具最适合“不追求像素级完美，但追求快速、及时、可沟通”的场景。它不能替代架构评审会议上你对着白板讲半小时，但能在评审前帮你把一张大家都认可的系统全貌图快速铺出来，保证讨论基于同一个认知层。这价值已经很大了。

6. 经验总结而非总结

最后再多说几句我心里话。自动生成可交互架构图这件事，技术难点不在渲染，而在理解和控制。渲染引擎哪家都能做，SVG、Canvas 都不是问题，最难的是让 AI 代理稳定地理解系统边界，并且按人的意图输出。所以，如果你打算在团队里推广类似 archify 的工具，我建议你第一件事不是折腾部署，而是先想清楚：你们团队的架构信息最准确的来源是什么？是代码？是配置文件？还是某位老同事的脑袋？不管你用什么工具，信息源头不解决，AI 再怎么生成都只是把错误重复得更有条理而已。

一个非常实用的小技巧，也是我在实践里反复用的：让 archify 生成架构图之后，顺手让它把“生成依据”也一并列出来。也就是说，每一条关系都要有出处，比如来自哪个配置文件、哪段代码的哪个路由，或者文档里的哪句话。这样团队里有人对图提出质疑时，可以追溯到依据，不会陷入“AI 这么画的”这种玄学局面。能够追溯的架构图，才真正有资格成为团队的基础设施。