企业官网建设流程全解析

1. 为什么AI画的架构图总差那么点意思

这两年AI辅助编程已经卷到飞起，写代码、补测试、做Code Review都有人用Agent在跑。但有个场景我一直觉得特别拧巴，就是让AI画架构图。你给它一段业务描述，它能给你画出一个看起来非常专业、布局规整、颜色协调的架构图，乍一看好像什么都有。可只要仔细一核对，问题就全出来了——组件关系对不上、服务之间调用方向画反、数据库和缓存混为一谈、甚至某些模块根本不存在，是从别的项目里“幻觉”过来的。这种图真拿去评审，基本被喷到怀疑人生。

我自己在项目里反复试过好几轮，包括让Cursor、Claude、GPT直接生成Mermaid、PlantUML，也试过让它们输出Draw.io的XML，结果都差不多：单看一张图，感觉能打80分；放到真实系统里一验证，很多关键细节是错的。这背后的原因其实不复杂——LLM本质是个概率模型，它对“架构图”的理解更多来自训练数据里的“共性样本”，而不是你当前系统的“真实约束”。你让它画一个微服务架构图，它大概率会画一个非常标准甚至平庸的图，所有组件都是同类项目的“平均脸”，跟你的实际系统对不上。

后来我们换了个思路，不再要求AI“一次性画对”，而是给它的产出加了一条“验收流水线”。这就是archify这个工具链在做的事情。简单说，它把AI画架构图的流程从“一句话→出图”改成了“需求描述→结构化架构描述→自动验收检查→通过才渲染出图”，不通过就打回去重画。这套流程跑通之后，AI产出的架构图从“看起来像那么回事”变成了“经得起校验的真实交付物”，我觉得这才是AI辅助架构设计真正能落地的姿势。

这篇文章就围绕这条“验收流水线”展开，适合正在折腾AI Agent辅助架构设计、或者想把AI画架构图从demo级别提升到能进评审级别的团队。文章里会讲清楚这条流水线为什么能解决AI画图不靠谱的问题，也会给出可以直接复制的实操方案和踩坑记录。

2. 先拆解问题：AI画架构图的四类典型翻车现场

在讲archify怎么解决之前，我先把AI画架构图最常见的几类问题列出来。这不是空谈，是我实际让模型画图时反复踩到的坑，理解这些问题之后，你才能明白为什么“加一条验收流水线”比“换一个更聪明的模型”更值得投入。

2.1 看起来完整，实则关系全错

这是最隐蔽也最危险的问题。AI生成的架构图从视觉上非常完整，每个服务、数据库、网关都画出来了，线条也连上了，但你深究就会发现调用方向是反的、数据流向是错的、服务和数据库之间直接连接而不是通过中间层。

比如我让AI画一个订单系统的架构，它很乖地画出了订单服务、用户服务、支付服务，然后给订单服务画了一条线直接指向用户数据库。这在图面上完全看不出来有什么问题，但真实系统里订单服务根本不应该直连用户库，它应该走用户服务的接口。这类错误靠人眼看图很难发现，因为你图都画出来了，注意力全在布局好不好看上，很难逐条核对线条语义。

2.2 幻觉式组件：图里多了几个不存在的服务

另一个高频问题是组件幻觉。AI会基于训练数据里的“典型套路”补全一些你根本没提过的模块，比如流量监控平台、日志采集Agent、配置中心。如果这些组件恰好在你系统里存在，那问题不大；但很多时候它补充的模块你压根没有，或者技术选型完全对不上。

我遇到过一个典型案例，让AI画我们一个内部工具的系统架构，它在图里放了一个Kafka消息队列。但我们那个工具的核心逻辑是同步调用，完全没有引入消息队列。图和真实系统一旦对不上，这张图就失去了架构图最核心的价值——作为团队沟通的共同语言。

2.3 格式对了，语义校验完全缺失

这个问题在Mermaid这一类基于文本的图表里尤其明显。AI生成的Mermaid语法往往完全正确，能顺利渲染，甚至节点样式都挺好看。但语法正确只代表“能画出来”，并不代表“画对了”。

打个比方，你作文每句话的语法都是通的，不代表文章内容是对的。Mermaid语法校验只能保证图能渲染，它不会检查订单服务到底该不该连用户库，也不会检查组件命名是否符合你们团队的规范。大部分AI画图流程就死在这一步——渲染能过，就觉得AI完成任务了，实际上最关键的语义正确性压根没有校验机制。

2.4 改了需求，图就全乱

最后一种情况更让人头疼：你让AI基于同一个系统改一点小需求，比如“把订单服务改成异步处理”，结果AI重新生成了一张全新的图。新图和旧图风格不一致、组件命名变了、布局全乱，甚至原来正确的部分也被改写。架构图作为长期维护的资产，这种不可控的变动非常致命，团队无法基于AI产出的图做渐进式维护。

3. archify的核心思路：给AI画图加一条“验收流水线”

我接触archify的时候，第一反应是“这不是一个画图工具，而是一个校验工具”。它的核心逻辑其实和软件开发里的CI/CD非常像——你在提交代码的时候必须有测试把关，不合格就构建失败。archify就是把这个思想搬到了架构图生成流程里，AI生成的设计稿必须通过结构化校验，才能算“验收通过”。

整条流水线分成四个环节：定义输入约束、生成结构化架构描述、执行自动校验、通过后渲染出图。下面逐个拆解。

3.1 第一步：把“画一张图”变成“生成一份带约束的结构化描述”

传统AI画图模式是“描述性输入→图像输出”，中间没有任何中间产物。archify的流水线则多了一个关键步骤——AI先生成一份结构化的架构描述文件，而不是直接输出Mermaid或图片。

这份描述文件我习惯用JSON格式，还有项目里也在用YAML。它包含四类核心信息：组件清单、组件属性、依赖关系和约束规则。

{ "version": "1.0", "components": [ { "id": "order-service", "name": "订单服务", "type": "service", "protocol": "HTTP", "belongsTo": "order-domain" }, { "id": "order-db", "name": "订单数据库", "type": "database", "engine": "PostgreSQL" } ], "dependencies": [ { "from": "order-service", "to": "user-service", "type": "HTTP", "description": "获取用户信息" } ], "constraints": { "mustNotConnect": ["service-to-service", "database-to-database"], "allowedProtocols": ["HTTP", "gRPC"] } }

你可能觉得这个步骤很多余——直接让AI画图多快，搞一个中间JSON不是很麻烦吗？但恰恰是这个中间产物，让后续的自动化验收成为可能。Mermaid只有视觉信息，计算机无法知道“订单服务”和“用户数据库”之间那条线的语义是什么；而结构化描述让每个组件、每条依赖都变成了可校验的数据。这是整条流水线的基础。

3.2 第二步：谁来判断“合格”——三层校验体系

有了结构化描述之后，就可以对它做自动校验了。archify按照我的观察是分了三层来做验收，每一层解决一类特定问题，正好对应我在前面列的几类翻车现场。

第一层是语法层校验。描述文件本身的格式是否正确、字段是否完整、组件ID是否唯一、依赖关系的两端节点是否存在。这层校验最简单，任何一个写过程序的人都能实现，但它能拦住最基础的错误，比如AI生成的组件被依赖引用但定义缺失。

第二层是逻辑层校验。这是最关键的一层，也是“验收流水线”价值最大的地方。它检查的是架构描述符不符合系统基本逻辑，比如服务不能直连数据库（如果团队规定必须走存储层）、两个服务之间的依赖不能循环、依赖类型必须匹配组件支持的协议等。这个校验规则完全是团队自定义的，你可以在配置文件里声明。

第三层是策略层校验。比如合规检查——某些组件不允许出现在边界区域；标签检查——所有组件必须带有负责人标签；安全检查——敏感数据流向是否经过脱敏节点。这一层校验本质上是把团队的技术规范和架构设计约定沉淀成机器可读的规则。

三层校验合在一起，本质上就是把原本依赖专家人肉Review的事情，变成了自动化检查。它的核心思路是：架构图不应该是一次性生成的结果，而应该像代码一样，可以通过流水线持续校验、持续演进。

3.3 第三步：校验不通过怎么办——反馈闭环

架构图校验失败之后，最关键的是如何反馈给AI进行修正。archify的处理方式是，把校验失败的具体原因和上下文信息回传给AI Agent，然后让Agent基于这些反馈进行针对性修复，而不是简单粗暴地重新生成一张图。

我在实际使用中觉得这个细节特别重要。如果只是简单返回“校验失败，请重新生成”，AI往往会陷入“改了一个错误又引入另一个错误”的循环。但如果你告诉它“订单服务不允许直连订单数据库，需要经过数据访问层”，AI就能根据这条明确反馈做精准修复。这其实跟我们人改代码的思路一样——Bug反馈信息越具体，修复效率越高。

修复过程通常是迭代式的：校验失败 → 把错误信息拼接到提示词中 → AI重新生成结构描述 → 再次校验。正常情况下，两三轮迭代基本就能通过验收。如果超过五轮还没通过，那大概率是需求描述本身有问题，需要人工介入澄清需求，而不是让AI继续烧Token瞎试。

4. 实操：从零搭一条AI架构图验收流水线

前面讲了原理，这块直接上实操。我用一套完整的流程说明怎么把archify这套思想落地到自己的项目里，包括工具安装、规则配置、Agent接入和CI集成。整个过程我不依赖任何必须付费的商业服务，核心就是一个命令行工具加一段Agent配置。

4.1 初始化项目骨架

首先你需要一个archify命令行工具。我目前用的是社区版，直接通过包管理器安装即可。

npm install -g @archify/cli archify init my-arch-project

初始化命令会生成一个标准目录结构：

my-arch-project/ ├── archify.config.js # 校验规则配置 ├── architecture/ │ └── system-description.json # 架构描述文件 ├── contexts/ │ └── system-context.md # 系统上下文提示词 └── output/ └── render/ # 渲染产物目录

这个目录结构本身就在暗示工作流程：先在contexts里定义清楚系统上下文和约束，然后让AI生成architecture里的结构化描述，接着通过archify.config.js执行校验，通过后渲染到output目录。

4.2 配置团队自定义校验规则

校验规则是整条流水线的灵魂。archify.config.js里最核心的配置就是这个rules数组，我强烈建议架构师在这里投入时间，因为规则越贴合团队实际情况，流水线的价值就越大。

module.exports = { version: "1.0", rules: [ { id: "no-service-db-direct-connection", type: "logical", severity: "error", description: "服务不允许直连数据库，必须经过数据访问层", match: { dependency: { fromType: "service", toType: "database" }, unless: { existsComponent: { type: "data-access-layer" } } } }, { id: "no-dependency-cycle", type: "logical", severity: "error", description: "服务之间不允许出现循环依赖", check: "acyclic" }, { id: "component-owner-tag-required", type: "policy", severity: "warning", description: "每个组件必须有owner标签", match: { component: { type: "*" } }, require: { tag: "owner" } } ] };

这里有几个设计和选型的原因想展开说一下。

第一个规则no-service-db-direct-connection，解决的是我认为最普遍的架构图错误——服务直连数据库。这个规则在真实的业务系统里非常重要，因为直连数据库意味着绕过了业务逻辑层，会导致数据一致性、安全审计等一系列问题。把这条规则固化成自动化校验之后，AI生成图的时候只要敢让服务直连数据库，流水线直接就亮了红灯。

第二个规则no-dependency-cycle，做的是循环依赖检测。微服务架构中服务A调服务B、服务B调服务A这种循环依赖一旦形成，调用链会变得非常不可控，而且难以排查。acyclic检查原理上就是对这个有向图做拓扑排序，如果存在环就无法形成有效的拓扑序列，检验效率也是很高的。

第三个规则是策略层的典型应用，强制每个组件带owner标签。我管它叫“可追溯性强制”，这个在团队超过十个人之后特别重要。架构图如果出现一个没人认领的服务，在系统变更的时候根本不知道该找谁确认，规范的团队管理会直接把它做成强制规则。

4.3 定义系统上下文提示词

接下来是定义一份高质量的“系统上下文”提示词。这个文件会作为AI生成架构描述时的唯一事实来源，质量直接决定AI输出的准确性。我自己总结了一个比较稳定的模板，要素包括系统边界、技术选型、组件清单和约束条件。

# 用户订单系统架构描述 ## 系统边界 这是一个电商平台的订单子系统，负责订单创建、查询、状态流转。 只与用户系统、支付系统和商品系统交互，不涉及物流系统。 ## 技术选型 - 后端服务：Java 17 + Spring Boot，同步HTTP/REST接口 - 消息队列：暂不引入，所有调用均为同步 - 数据库：PostgreSQL，每个服务独享库 - 网关：Spring Cloud Gateway ## 允许存在的组件类型 service (HTTP服务)、database (数据库)、gateway (网关)、cache (缓存) ## 明确禁止的组件 - 不存在的中间件：Kafka、RabbitMQ - 不带业务归属的通用组件：如"日志系统"、"监控平台" ## 关键约束 - 服务之间的调用必须通过HTTP接口 - 服务不允许直连其他服务的数据库 - 组件必须标注所属领域（order/user/payment/product）

这个上下文文件的重点不在于篇幅多长，而在于把边界和约束说清楚。实际使用中，AI生成架构图时的很多幻觉，都是因为上下文里缺少明确的“禁止清单”。你如果不说“不引入Kafka”，AI很可能因为训练数据里常见的电商架构而主动加上消息队列。

4.4 调用AI生成架构描述并执行验收

定义好上下文之后，就可以进入生成和验收的循环了。我通常是用它配合Cursor或Codex之类的Agent，在项目目录里执行一个命令，让Agent读取contexts/system-context.md并生成架构描述文件。

archify generate --context contexts/system-context.md \ --output architecture/system-description.json \ --prompt "订单子系统，包含用户端订单创建、订单查询、订单状态流转"

这个命令内部做的事情，是调用底层AI模型，把context文件、用户prompt和archify内置的“输出Schema约束”组装成一个完整提示词，然后将AI输出解析成结构化的JSON文件。

生成之后立刻执行验收：

archify validate architecture/system-description.json --config archify.config.js

执行结果有两种：PASS或FAIL。PASS意味着这张架构图已经通过了你团队定义的绝大部分核心校验规则，后续可以交给人工做最后确认；FAIL则会输出具体的错误清单，比如哪条规则被违反了、涉及哪些组件ID等。

我在本地跑的最常见错误截图类似这样：

[FAIL] no-service-db-direct-connection 订单服务(order-service) → 用户数据库(user-db) 服务不允许直连数据库，必须经过数据访问层 [WARN] component-owner-tag-required 组件 payment-service 缺少 owner 标签

拿到FAIL反馈之后，直接把这段错误信息回传给你用的Agent，让它基于反馈修改。大部分情况下AI都能根据“那条线不该连”、“哪个组件缺标签”这类具体反馈做出修正。

4.5 验收通过后渲染出图

校验通过之后，就可以渲染成图形了。archify本身支持Mermaid和PlantUML等主流渲染格式，我喜欢用Mermaid，因为它对GitHub和团队知识库的支持特别好。

archify render architecture/system-description.json \ --format mermaid \ --output output/arch.mmd

渲染得到的Mermaid文件就是标准的文本格式，可以直接放进Markdown里展示，也可以配合Mermaid Live Editor等工具生成PNG或SVG。关键在于，这个Mermaid文件的内容是从通过验收的结构化描述映射出来的，组件和依赖已经经过校验，所以图形的准确性和直接从AI嘴里生成的图完全是两个质量等级。

5. 进阶玩法：把验收流水线接入AI Agent工作流和CI

到了这一步，你其实已经拥有了“生成架构图→自动验收→修改→再验收”的完整闭环。但这个闭环还停留在本地手动操作阶段，真正让流水线发挥最大价值的是把它接入Agent工作流和CI管道。

5.1 和Cursor/Codex等AI编程工具集成

现在很多AI编程工具都支持自定义Skill或指令，让Agent按照特定流程工作。我在Cursor里注册了一个“架构图生成”的Skill，核心内容就是要求Agent必须遵循archify的“生成→验收→修复→再验收”循环。

你是一名架构师。当用户要求生成架构图时，必须按以下步骤执行： 1. 读取 contexts/system-context.md 中的系统约束。 2. 将用户需求映射为架构描述，写入 architecture/system-description.json。 3. 执行 archify validate，直接读取错误输出。 4. 根据错误列表逐条修复架构描述，直到全部校验通过。 5. 校验通过后，执行 archify render 输出最终图。 6. 向用户展示最终图并说明关键设计决策。

这个指令看着简单，实际效果非常显著。在没有这套工作流之前，让Agent画图基本就是猜；有了这套工作流之后，Agent的行为模式从“单次生成”变成了“面向验收标准的迭代优化”。本质上这就是把质量门禁前移，让Agent在一开始就朝着“容易通过验收”的方向生成结果，质量自然就稳定了。

5.2 在CI里增加架构图回归检查

架构图是活的资产，和代码一样需要持续维护。我们在CI管道里加了一个archify检查任务，每次有新的架构描述提交到仓库，都会自动执行校验，保证图不会“悄悄画错”。

下面是我们在GitHub Actions里的示例配置：

name: architecture-check on: pull_request: paths: - 'architecture/**' - 'archify.config.js' jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' - run: npm install -g @archify/cli - run: archify validate architecture/system-description.json

这个CI任务的效果很直接：只要有人改了架构描述文件，CI自动跑校验，没过就直接阻断合并。从源头上杜绝了“架构图在PR里看起来没问题，合并后发现连组件都没了”这种事故。

我个人的建议是，初期可以只把“error”级别的规则设为阻断项，比如循环依赖、服务直连数据库这类；把“warning”级别规则比如组件缺owner标签先留作提示，观察一段时间后再决定是否升级为阻断项。这样可以避免一上来规则太严导致团队抵触。

6. 常见问题与排查技巧实录

实际操作中总会遇到各种问题，我把这几个月折腾这套流水线遇到的典型问题集中整理一下，给后来人排雷。

6.1 组件ID频繁变化，无法做增量对比

最初我们很头疼一个问题：AI每次生成的组件ID都是随机的，比如上一次管订单服务叫order-service，下一次就变成order-svc。这导致我们没法把两张图做自动对比，无法追踪架构的变更。

后来我们在archify.config.js里配了别名映射机制，允许给组件设置alias，比如：

{ "id": "order-svc", "aliases": ["order-service", "order-center", "订单服务"] }

这样即使AI换了ID，我们也能通过别名把它归一化到统一命名空间。对于要长期维护架构图的团队，这个配置非常有必要。

6.2 逻辑校验规则写得太死，误伤正常场景

刚开始规则写得比较严格时，出现过把正常场景判错的情况——典型例子是缓存组件和服务之间的关系是双向的，服务会读取缓存、写缓存、缓存回源也会调用服务接口，这种场景如果用简单的依赖方向校验，很容易误判。

我的调整思路是，为规则增加“场景白名单”，比如某个规则只在特定上下文下生效，或者给特定组件类型放行。

{ id: "cache-access-pattern", type: "logical", severity: "error", match: { dependency: { fromType: "cache", toType: "service" } }, except: { componentTags: ["read-through-cache"] } }

写规则的时候多想想真实场景，别一刀切。架构校验的目的是帮团队减少无效沟通，不是为了造一个完美的形式系统。

6.3 Agent陷入修复循环，反复改不完

这个问题也很常见。Agent在校验失败后盲目重试，每次改一个地方又引入新问题，白白消耗Token和精力。

我的经验是设置一个“迭代上限”，一般三轮之内如果没有明显收敛，就停下来人工介入。另外在反馈信息里加上“当前是第N次修复，请优先修复error级别问题，不要修改已验证通过的组件”，这种约束能显著提高Agent的修复效率。

6.4 架构描述文件太大，超出模型上下文窗口

当系统比较复杂时，AI生成的描述文件可能非常大，再次请求时会超出上下文窗口限制。我们的解法是把大系统拆成子域处理，比如订单域、支付域、用户域各自生成描述文件，然后通过archify的merge功能合并成整体：

archify merge architecture/order-domain.json \ architecture/payment-domain.json \ architecture/user-domain.json \ --output architecture/system-description.json

这种方式既降低了单次生成的复杂度，又能通过合并步骤整体校验跨域依赖是否正确，一举两得。

6.5 Mermaid能渲染，但图里节点错位

最后这个小问题看似和校验无关，但体验上很影响观感。Mermaid渲染长名称节点时，布局经常错乱。我会在render前给所有组件统一加短ID，并使用显示名展示：

render: mermaid: idPrefix: "cmp" useDisplayName: true

这样既能保证美工上的整齐，也不影响结构的确定性。细节虽小，但评审会上架构图是否美观，确实会影响非技术人员对整体设计的认可度。

7. 使用心得与实际效果

这套验收流水线跑下来快两个月了，最直接的感受是，AI画的架构图从“能看”变成了“能用”。怎么定义这个能用？就是拿到图上线评审，团队不会因为基础结构错误吵来吵去，评审时间至少缩短了一半。

以前让AI画架构图，人肉Review至少要过好几遍：先看组件对不对，再看连线方向，再核对命名规范，最后还得检查有没有不该出现的幻觉模块。现在这些检查全部自动化了，人工只需要专注在“这样设计是否合理”这类更高层级的问题上，而不是被低级错误消耗精力。

当然这套方案也不是没有代价。前期在配置规则上需要投入一定时间，尤其是把团队的技术规范沉淀成机器可读的规则，这活儿本身就需要架构师深度参与。另外，整个流程比普通的“一句话出图”要多几个步骤，如果你只是临时画一张示意性质的图，那直接用AI生成更快，没必要上流水线。

但只要是稍微成规模、需要长期维护的系统架构，这条验收流水线的价值很快就体现出来了——它把架构图从一次性产物变成了可持续维护、可自动回归检查的工程资产。我个人觉得，这也是AI辅助架构设计的正确打开方式：不是让AI自由发挥替你决策，而是让AI作为执行者，在明确的验收标准下替你高效干活。

最后再分享一个小技巧：如果你刚开始尝试，别一上来就搞很复杂的规则体系。挑最痛的三个问题先落地，比如禁止服务直连数据库、禁止循环依赖、强制组件归属标签，跑通一两个项目之后，再根据团队反馈逐步加规则。规则不是越多越好，能让流水线挡住真实错误、帮团队省时间才是核心目标。