企业官网建设流程全解析

1. 这个项目到底在解决什么问题：画架构图这件事，是时候换个思路了

做后端开发、系统设计、或者带团队做技术评审的朋友，应该都有过这种经历：方案文档写好了，核心模块列清楚了，结果要画一张架构图的时候，整个人就卡住了。不是不知道画什么，是画的过程太折磨人——draw.io 里拖拖拽拽大半天，框和线的对齐比写代码费劲；PlantUML 写起来快，但画完是张死图，没有交互，没有层级展开，评审会上别人问“这个服务下游挂了会影响什么”，你只能指着静态箭头干讲。

我是在翻 GitHub 今日热门仓库的时候看到 archify 的，项目标题写得很直白——AI 代理自动生成可交互架构图的技能模块。市面上 AI 画架构图的工具其实已经不少了，大部分走的是“你描述、我出图”的路线，本质是把提示词翻译成一张静态架构图。而 archify 的切入点不太一样：它是把“生成架构图的能力”做成了一个可被 AI 代理调用的技能模块，而且产出的不是 png，是带交互能力的架构图。什么意思呢？就是你不再需要自己在画布上排版布局，也不需要专门学习某一种图表 DSL 语法，你只需要向 AI 描述清楚系统长什么样，它替你完成从“文本描述”到“结构化的架构数据”，再到“可交互可视化视图”的整个过程。

这个定位让它的适用面一下子变宽了：你在设计微服务架构的时候可以用它快速出一版结构图做评审；你在带新人的时候可以让它把现有项目的依赖关系生成一张可展开的交互图；你甚至可以在技术汇报前让它把一套复杂系统浓缩成一张汇报级别的架构视图。这篇文章我就基于我实际跑的流程，把它的工作逻辑、实操过程、以及我踩过的一些坑完整拆出来,给想玩一玩这个项目的朋友一份可参考的路线。

2. 技能模块的内在逻辑：拆解一条“自然语言到可交互架构图”的流水线

先说一个很多人忽略的点——标题里的“技能模块”这三个字其实信息量很大。正常情况下你用大多数 AI 画图工具，是从外部调用一个网站的接口，把提示词发过去然后拿回一张图。但在 archify 这种设计范式下，“生成架构图”变成了 AI 代理内置的一项能力，相当于给代理装了一个工具插件。它不是一个独立的在线服务，而是注入了技能定义、结构化输出规范和渲染器之后，让 AI 在你自己的环境内完成从理解系统到产出图谱的全过程。这种设计的好处是：你不受制于某一家的模型，也不受制于固定 UI，你甚至可以把它整合进现有工作流里，比如在代码仓库里跑一个脚本，让 AI 自动读代码结构然后生成架构图。

2.1 它是怎么“听懂”架构描述的

整个流水线里最难的一步，其实是第一跳：从自然语言里提取出架构要素。假设你告诉 AI“我们有个订单服务，依赖库存服务和用户服务，消息队列在中间做解耦，数据存在 MySQL 里”，模型需要做的事情是拆出这个句子里的实体和关系。

我在实际使用中的感受是，archify 的技能模块在提示词设计上下了不少功夫。它会把架构描述拆成几类核心要素——节点（服务名、组件名）、关系（依赖方向、调用方式）、层级（分组边界）、属性信息（技术栈、协议类型），然后要求模型按一个半结构化的格式输出。所谓半结构化，就是让模型在自由文本和严格 Schema 之间取一个平衡点，它不需要像 JSON Schema 那样总是懂得语法合法性，但它要求输出的结构是稳定的、键名是一致的。

比如，同样是说“订单服务调用库存服务”，不同的输出质量差别很大。普通模型可能把它写进一大段描述里，archify 则会把模型往“源节点、目标节点、关系类型”这个三角结构上去引导。这一步做扎实了，后续所有渲染逻辑才有数据基础。

2.2 从“画框”到“生成”的关键一跳

传统画图工具里，你要自己决定一个服务放在哪个位置、箭头怎么拐弯、分组边界怎么圈。这种布局工作，对 AI 来说其实不友好。archify 的做法是把布局逻辑从 AI 的任务里剥离掉——你不再让 AI 去“画”图，而是让它去“生成图的数据结构”，渲染的活儿交给前端渲染器来处理。

这个设计的精妙之处在于：AI 擅长的是理解语义和抽取关系，而不是计算坐标。你要让模型输出一张完整画布，它大概率会在排版上翻车；但你让它输出“有哪些节点、节点之间什么关系、哪些节点属于同一个分组、关键路径是什么”，它基本不会出错。坐标和布局是确定性逻辑，交给渲染器去算，既稳定又灵活。

打个比方，这就跟前端的 MVVM 思路差不多。传统做法是“你告诉 UI 控件往哪放”，AI 画图工具的做法是“你直接用指令操作画布”，而 archify 走的是声明式路线——你只描述“有什么、什么关系”，图形怎么呈现是渲染层自动推导的。

2.3 可交互性从哪里来

这是 archify 和普通 AI 架构图工具拉开差距的核心点。传统的 AI 画图工具给你返回一张图片，意味着信息是扁平的、不可展开的。而 archify 生成的是带交互能力的视图，意味着架构数据是活的。

它能做的交互包括但不限于：缩放和平移（看大图不费眼）、节点聚焦（点一个服务，只看它连了谁）、层级折叠（收起某个分组下面的细节，保留整体结构）。这些交互能力本质上是因为渲染层读取了结构化数据，而不是读一个渲染好的像素图。数据在，交互就在。

这一点对做微服务架构的人特别有用。微服务之间依赖关系几十条甚至上百条，静态图看着像一团乱麻，但如果你能把“公共服务”折叠起来，只显示核心链路，图一下就清爽了。技术评审的时候，这种交互能力不是锦上添花，而是刚需。

3. 本地跑通 archify 的完整实操流程：从拉代码到生成第一张交互架构图

官网文档写得比较简洁，我第一次跑的时候就卡在环境依赖上，后面翻源码才搞明白。这里我把完整的踩坑过程整理出来，按步骤走，基本能一次跑通。

3.1 环境准备：几个容易忽略的依赖项

先明确一下基础环境要求。项目基于 Python 3 开发，前端渲染部分依赖 Node.js 相关的构建工具，所以这两个运行时都需要提前装好。我用的是 Python 3.10 加 Node.js 18，兼容性没问题。

依赖项里有几个比较容易忽略的点，我列一下：

• AI API 的 Key：archify 需要调用大模型接口来解析你的架构描述。它默认兼容 OpenAI 格式的 API，也就是说如果你用本地跑的模型，或者第三方兼容 OpenAI 协议的网关，也可以通过改环境变量来对接。这是它比较开放的一点，不绑定某一家。
• Graphviz：这个不是必需的，但如果你想让输出结果里有额外的布局计算能力，或者想导出部分固定格式的图，建议提前装好。apt install graphviz或者brew install graphviz都能搞定。
• 前端渲染依赖：渲染器和交互逻辑跑在 Web 环境里，需要先构建前端资源。我之前就是漏了这一步，结果后端 API 起来了，浏览器打开空白页。

我整理了一份准备清单，方便对照：

3.2 安装与构建：我踩的第一个坑

安装过程本身不复杂，clone 仓库之后装 Python 依赖就行。但这里有一个非常关键的细节：前端资源必须单独构建。

我自己第一次跑的时候只装了 Python 依赖就急着启动服务，本地倒是启动了，端口也监听了，但浏览器访问的时候页面一片空白，控制台报了一大堆静态资源 404。翻了一下项目结构才发现，它把前端构建产物放在了后端服务的静态资源目录里，而仓库里不包含预构建产物，必须手动构建一次。

操作流程是这样的：

# 1. 克隆仓库 git clone https://github.com/shihabal3amri/archify.git cd archify # 2. 创建虚拟环境并安装 Python 依赖 python -m venv .venv source .venv/bin/activate pip install -r requirements.txt # 3. 安装前端依赖并构建 cd frontend npm install npm run build cd .. # 4. 配置 API Key 环境变量 export OPENAI_API_KEY="你的API Key" # 5. 启动服务 python -m archify.server

这个顺序很重要，亲测有效。如果你构建完前端再启动服务，本地访问http://localhost:8000就能看到界面了。

3.3 用一句描述生成第一张架构图

服务跑起来之后，界面是一个输入框，你直接描述系统架构就行。我实际测的时候给了一段比较典型的微服务场景描述：

我们有一个用户服务，负责用户注册和登录。订单服务依赖用户服务来校验用户状态。商品服务和订单服务之间通过消息队列异步交互。所有的数据都存储在同一个 MySQL 实例里，分库分表。有一个 API 网关统一接收外部请求，转发到用户服务和订单服务。

提交之后，AI 会先解析这段描述，然后返回一个结构化的架构数据模型。这一步如果 API 响应正常，几秒种后画布上就会渲染出带交互的架构图：用户服务、订单服务、商品服务、API 网关、MySQL 都变成了独立的节点，消息队列作为中间节点连接了订单服务和商品服务，箭头的方向清楚地标出了依赖调用的关系。

我第一次生成完，最大的感受是：它没有把“消息队列”理解成两个服务之间的普通连线，而是作为独立节点插进了链路里。这一点对系统设计来说非常重要，因为消息中间件在架构里本身就是独立组件，而不是连线的附属品。模型对架构语义的理解明显是做过针对性优化的。

4. 生成结果的实际使用：从个人画图工具到团队协作的转变

跑通了基本流程之后，我开始把注意力放在一个更实际的问题上：这张图生成出来之后，除了好看，还能干什么？我实际用了一段时间，发现它的价值远不止“替代手动画图”这么简单。

4.1 交互操作的实际体验：折叠、聚焦与路径高亮

前面提到 archify 生成的架构图是可交互的，实际用起来确实有点东西。我最常用的两个操作是节点聚焦和子图折叠。

节点聚焦的意思是，点击某个节点之后，视图会自动把与它相关的节点突出显示，无关的节点置灰。这个功能在处理复杂系统时特别有用。比如我导入了一个包含 30 多个节点的微服务架构，直接看全貌就是一团乱麻，但点一下订单服务，视图立刻变成“订单服务以及它依赖的上下游”，整个调用链清晰得像是专门画的。

子图折叠则用于管理层次结构。比如你把某个服务内部拆成子服务，或者把一组公共组件归到一个分组里，渲染出来的图会支持在“展开完整结构”和“折叠为单个节点”之间切换。这相当于你把架构图的阅读深度控制权握在了手里——汇报时折叠成粗粒度视图讲整体，进入技术细节时逐层展开往下钻。

另外还有一个很实用的交互是路径高亮。你可以指定一个起点和一个终点，渲染器会标记出两点之间的所有调用路径。这个特性在做故障影响面分析的时候太关键了，直接回答“这个链路里还有多少个依赖是真正绕不开的”这种问题。

4.2 替代方案对比：画一张交互架构图到底需要几种工具

我把自己以前的工作流和 archify 对比了一下。以前要实现同样效果，我的工具链大致是：用 draw.io 画静态图，用 PlantUML 维护版本化文档，再用 VuePress 或者 Docusaurus 之类的静态站点做文档托管，如果需要交互还得再引入 D3.js 之类的可视化库。一套下来成本非常高，而且图越复杂维护成本越失控。

简单做了个对比：

表格里最后一行其实是我觉得最值得关注的点：archify 的中间产物是一份结构化的架构定义文件，它当然能在界面里渲染成交互图，更可以作为代码仓库里的一个版本化文档维护。架构哪里变了，diff 里看得很清楚，不用像图片时代那样“谁改了架构图也看不出来”。我在实际使用里，会把这个文件提交到仓库里，架构评审的时候直接关联 diff。

4.3 在文档中心和评审汇报中的落地用法

如果你做得稍微深入一点，archify 完全可以嵌入到现有的文档工作流里。你可以在构建文档站点时，把架构定义文件渲染成交互组件嵌入页面，读者看到的不再是“第 2 章架构总览图.jpg”，而是一张能自己探索的交互图。

我具体是这么用的：团队内部的技术文档站里，架构信息是静态的 Markdown 加图片。后来我把 archify 生成的交互架构图嵌入到核心项目文档页里，阅读者可以直接在文档里点击服务节点，查看它依赖了哪些服务、被谁依赖。这个体验的提升是很直观的——新人在第一次阅读系统文档时，普遍反馈能更快地建立大局观。

汇报场景就更自然了。技术评审会议上，你直接把交互架构图投出来，讲到订单服务就说“点开依赖链路”，讲到公共组件就“折叠子图”。整个过程不需要切换窗口，不需要切换工具，表述是完全顺着你的思维走的。

5. 用了几轮之后我踩过的坑：稳定输出的关键不在于提示词，而在于结构约束

任何和生成式 AI 打交道的工具都有一个绕不开的问题——输出质量不稳定。我在实际使用 archify 的过程中遇到了几种典型的翻车情况，每次都有可复现的原因。

5.1 模型漏节点：架构描述越长，信息丢失越严重

第一次遇到的问题是，我描述了一个十几行文字的系统，结果模型只识别出四五个核心服务，消息队列、缓存层这些组件被吞掉了，但连接关系里又出现了引用这些组件的边，导致渲染出来的图上有悬空的线。

这个问题的本质是上下文长度和信息优先级。模型在解析长文本时，会把注意力集中在语义突出的实体上（频繁出现的名词、和动词直接关联的对象），而容易被省略的是“插入语”性质的组件描述。

我采用的解决方式是：把描述拆成“节点清单 + 关系清单”两段式。第一段先说有哪些节点，每个节点一句话说明职责；第二段再说谁依赖谁。这样模型的任务从“一边找实体一边找关系”，变成了“先确认清单再连边”，信息完整度提升非常明显。如果是在 archify 界面上直接操作，我会先在文本里单独写一个小节罗列组件，再做关系描述。

5.2 依赖方向反了：箭头画反比漏画更危险

另一种翻车情况是方向错误。我描述“订单服务通过消息队列给商品服务发消息”，结果模型把箭头画成了商品服务调用订单服务。这个错误单看图不容易发现，但一旦它进入设计评审，后果就是对调用链路的误判。

这个问题的根源在于，模型对“发送方”和“接收方”的判别依赖于动词的语义解析，而中文描述里，“给……发消息”“把……返回给……”这些表达方式对模型来说并不总是能准确识别方向。我的对策是：在描述关系时强制用“A 调用 B”或“A 依赖 B”的句式，并在最后加一句强调“以上所有依赖方向均以箭头表示从调用方指向被调用方”。结构化提示确实能明显降低方向错误率，但做不到完全消除，所以生成的图我还是会快速扫一遍核心链路。

5.3 图太大之后的性能问题：交互要“够用”，而不是“炫技”

还有一个很实际的问题：当节点数量超过一定阈值时，交互式画布的实时缩放和平移会开始卡顿。如果架构图里塞了几百个节点，重新布局和碰撞检测的计算量会显著上升，浏览器端的渲染压力很大。

在这个问题上我踩过的坑是试图生成一张“全家桶”级别的大全图。后来我调整了使用方式：按边界拆分架构图。核心业务链路单独生成一张，基础设施层单独生成一张，中间件通信网络再单独一张。宁可多管理几个架构定义文件，也不硬塞一张大图。说实话，对团队协作来讲，拆开反而更好用，因为不同角色关心的边界不同——后端看业务链路，运维看基础设施，两张图硬拼在一起徒增干扰。

5.4 承诺边界与适用场景：它不是万能的

最后说一句实在的。archify 这个技能模块在“从描述生成架构示意图”这个环节上做得不错，但它不是架构设计工具，更不是审计工具。

不要指望它来验证你的架构是否合理，它不具备推理依赖合理性、找出单点故障的能力。它适合的场景是：你有一个脑内成型的架构方案，需要快速产出可视化结构，用于沟通和对齐。至于架构是否最优，那仍然是你自己的事。

另外，如果项目代码已经存在，期望它直接读代码生成真实架构，这一步超出它当前的设计边界——除非你给它喂的提示词里明确包含代码分析信息（比如让 AI 代理先扫描目录、抽取 import 关系再交给渲染器）。理论上可以做，但 archify 本身不内置代码分析器，需要你在上游自行完成。

我自己的体会是，这类工具最大的价值不在于“让画图变快”，而在于它让架构可视化的门槛降到了“会说话就能画”。以前带新人，让对方画系统架构图，对方先得学会工具操作；现在直接把文档丢给 AI，先把图生成出来，再看着图问自己“这么设计合不合理”。这个顺序的颠倒，其实比工具本身的技术含量更值得玩味。如果你平时也需要频繁输出架构图、依赖图、技术方案示意图，archify 绝对值得放进你的工具清单里跑一跑，这轮下来说不定又给你省出半天时间。