企业官网建设流程全解析

绘图这件事，一直是LLM应用里最让人又爱又恨的环节。爱的是，你只要把系统讲清楚，它就能给你吐出一张看起来还像样的架构图；恨的是，绝大多数时候它产出的图，要么语法跑到一半就断，要么节点乱成一团，要么把微服务画成了流程图。我自己折腾过不少方案，最后发现真正管用的不是更聪明的模型，而是一本给LLM看的"操作手册"。Archify这个项目做的就是这件事——把画架构图的经验、规则、模板固化成一份Markdown格式的手册，让LLM在动手前先读规矩，再出图。

这篇文章不聊抽象概念，直接讲Archify怎么用、手册里到底该写什么、以及当你拿到一个架构图需求时，应该怎么引导LLM产出可用的结果。适合正在做LLM Agent、Skill包、或者成天跟微服务架构图、系统架构图打交道的开发者参考。

1. 为什么需要一份给LLM看的"架构图画图手册"

1.1 LLM画架构图的常见翻车现场

先还原一个典型场景。你让LLM画一个订单系统的微服务架构图，它可能给你这样的回答：先用一段话解释什么是微服务，再列出七八个服务名称，然后掏出一段没有subgraph的Mermaid代码，所有节点平铺在一层，箭头横七竖八。图表能渲染，但完全不能看。

更麻烦的是，当你的服务数量超过十个，LLM很容易丢节点——写着写着就把支付服务忘了；当你的系统分了好几个层次，它可能把所有东西堆在一个图里，搞得像一团毛线。这些问题的根源在于：LLM没有"架构图审美"，它不知道什么该突出、什么该分组、箭头语义应该怎么统一。人画图靠经验，LLM画图只能靠规则，而规则恰恰是大部分Prompt里缺失的部分。

1.2 操作手册到底在解决什么问题

Archify这类项目的核心思路，是把画图的行业经验转译成LLM能稳定执行的约束条件。它不是让模型更聪明，而是给模型一套行为守则：先做需求拆解、再定视图类型、按规范组织节点、用统一标准表达关系、输出前自检语法。把这些流程写进一份Markdown文档，让LLM在处理图形任务前先加载这份手册，它的出图质量会有质的提升。

你可以把这份手册理解成给新员工发的《工作规范》：不靠悟性，靠流程。LLM本身知识面很广，但它的默认行为未必符合你的预期，手册的作用就是把这些预期显式化。Archify把"怎么画一张合格的架构图"这件事，变成了一套可复制、可版本管理、可跨模型迁移的文本资产，这一点对做Agent类应用的开发者来说价值很大。

2. Archify 操作手册的设计思路与核心内容拆解

2.1 为什么是"手册"，而不是更长的Prompt

很多人第一反应是：那我写个长Prompt不就行了？试过就知道不行。Prompt越长，越容易被模型在长上下文中稀释，而且企业级的画图规范动辄上千行，塞进Prompt里既浪费token又影响主任务执行。Archify选择的是"外部加载"模式——手册独立存放，在需要的时候通过文件读取或者Skill机制注入上下文。这样做有三个好处：手册可以单独维护和测试；多个LLM应用可以共享同一套规范；不会污染主对话的指令空间。

这种设计思路和现在社区流行的LLM Wiki方法论一脉相承。很多人整理知识库是给人类看的，但Archify的组织方式从一开始就考虑"机器可读性"：清晰的标题层级、明确的操作指令、大量的示例片段。人类管理员负责维护，LLM负责在需要时精准引用，双方各司其职。

2.2 手册的关键组成板块

一份合格的Archify手册，至少要有四个板块。第一是术语定义区，明确什么是架构图、什么是流程图、什么是时序图，避免LLM把类型搞混；第二是规则约束区，规定节点命名方式、分组逻辑、箭头语义、颜色使用边界；第三是示例库，给LLM几个高质量的Mermaid或D2范例，让它模仿而不是自由发挥；第四是输出协议，规定回答时的格式结构，比如先给需求理解、再给代码、最后给渲染说明。

其中规则约束区是最核心的。实际使用中我发现，LLM画图最容易跑偏的地方恰恰是最基础的规范：节点标签用中文还是英文、service和database应该用什么形状、不同层级的关系怎么表达。这些如果不写清楚，每次生成都是一次开盲盒。Archify通过把这些细节固化下来，保证LLM每次输出都在同一个风格框架内。

2.3 工具选型：Mermaid、D2与PlantUML怎么选

Archify手册通常会明确指定渲染语言，否则LLM会自由发挥。我在实际项目里对比过三种主流方案，简单说说取舍逻辑。

Mermaid的最大优势是生态成熟、文档多、LLM训练语料充足，它生成Mermaid的语法成功率最高；缺点是复杂图布局可控性较弱，节点一多就容易挤成一团。D2的语法比Mermaid更简洁，布局引擎也更现代，但LLM对它的掌握程度不如Mermaid。PlantUML在UML建模领域有独特优势，但对架构图这种偏自由布局的场景来说，语法反而显得啰嗦。

如果你刚开始接触Archify，我的建议是默认选Mermaid，把D2作为备选。理由很简单：LLM返回的Mermaid代码，绝大多数情况下不需要人工修改就能直接渲染，这在自动生成架构图的流水线里非常重要。

3. 从零搭建Archify Skill：目录、规则文件与接入方式

3.1 Skill整体目录结构

拿社区里常见的Archify Skill结构来说，通常长这样：

archify/ ├── SKILL.md ├── rules/ │ ├── general-rules.md │ ├── mermaid-style.md │ └── layout-principles.md ├── templates/ │ ├── microservice-arch.tpl.md │ ├── system-overview.tpl.md │ └── sequence-flow.tpl.md └── examples/ ├── microservice-example.md └── system-example.md

这个结构的核心思想是"入口做主控、规则做约束、模板做兜底、示例做参照"。SKILL.md是总入口，负责告诉LLM"你是一个架构图生成助手，动手前必须先读这些规则"；rules目录放具体的行为规范；templates目录定义了几种常见架构图的骨架，LLM拿到需求后先选模板再填内容；examples目录则是给LLM看的成品范文。

3.2 SKILL.md主入口怎么写

SKILL.md本质上是一份写给LLM的说明文档，格式不必复杂，但信息结构要清晰。一个我验证过比较好用的写法是这样的：

--- name: archify description: 使用标准化的规则绘制架构图，支持微服务架构、系统总览、调用时序等多种视图。 --- # Archify Skill 你是一名资深架构可视化工程师。在收到用户请求后，必须按以下步骤工作： 1. 拆解用户需求，判断需要的视图类型（微服务架构图 / 系统架构图 / 时序图 / C4分层图）。 2. 阅读 `rules/` 目录下的对应规则文件。 3. 从 `templates/` 目录选择匹配的模板结构。 4. 参考 `examples/` 目录的风格，生成最终代码。 5. 在最终回答中同时输出渲染代码和简要说明。 ## 铁律 - 禁止在未指定视图类型时直接画图。 - 禁止忽略规则文件中的任何约束。 - 输出代码必须能被目标渲染器直接执行，不允许包含占位符。

关键点在于"铁律"部分。LLM对强约束的遵循度远高于软性建议，把重要的禁忌写在这里，命中的概率会大很多。我实测下来，加了铁律之后，LLM跳过流程直接画图的概率明显下降。

3.3 规则文件的核心约束

规则文件是整个Archify手册里最有价值的部分。以mermaid-style规则为例，里面至少要覆盖几个维度。

节点命名方面，要规定所有节点必须有唯一的业务语义名称，禁止使用node1、node2这类无意义命名；节点标签应该直接体现组件职责，比如"用户服务"、"订单数据库"，不要加无意义的前缀。分组方面，要强制使用subgraph表达逻辑边界——微服务架构中，同一业务域的服务要放在同一个子图里，不同子图之间用虚线或明确的箭头表达依赖。

关系表达方面，要规定箭头的语义：实线箭头表示同步调用，虚线箭头表示异步消息，带锁标记的表示鉴权依赖，诸如此类。一套统一的语义约定，能让LLM生成的架构图具有一致的可读性，而不是每次换个风格。还有一个容易忽略的点：颜色和标签的使用边界。最好规定默认情况下不要给节点添加过多的背景色，除非用户明确要求，否则会让图变得非常花哨。

下面是一份简化的mermaid-style规则文件示例：

# Mermaid 风格约束 ## 节点命名 - 所有节点必须使用业务可读名称，禁止使用 node1 等默认名。 - 命名格式：[域]-[组件类型]-[名称]，例如 SVC-UserService、DB-OrderDB。 ## 分组要求 - 必须使用 subgraph 表达系统边界或业务域边界。 - subgraph 的标题使用系统层级的业务名称，例如 "订单中心"、"支付域"。 ## 箭头语义 - 同步调用：A --> B - 异步消息：A -.-> B - 数据流转：A -->|write| B - 禁止箭头指向不明，每条连线必须有明确语义标注或可从上下文推断。 ## 布局 - 近似功能的节点必须相邻排列。 - 不允许出现跨图层的长箭头，必须通过中间节点跳转。

3.4 接入Codex CLI、Claude等Agent环境的实操要点

手册写好之后，怎么让LLM真正读到它？目前主流的方式是通过Agent框架的Skill机制，或者直接在系统提示词里做一次引用。以Codex CLI这类工具为例，它的项目说明文档中如果写清楚了"当你需要绘制架构图时，请先阅读 archify/SKILL.md"，LLM就会在合适的时机自己去加载这份文件并使用。

如果你在使用Claude的Skill功能，那么目录结构本身就能被框架自动识别，你把archify这个目录丢进skills目录即可，无需额外注册。如果你是完全基于API自己做编排，有一个更稳妥的做法：在主系统提示词中预留一段"工具调用协议"，当检测到用户意图属于"画架构图"时，自动把SKILL.md和一两个示例文件附到当前上下文里。这样虽然消耗一点token，但能确保LLM真的读到了规则。

实际使用中，我踩过的坑是文件路径问题。LLM在读取文件时偶尔会把路径猜错，所以在SKILL.md和系统提示词里都要给出绝对路径或明确的相对路径基准，这会显著提高文件加载成功率。

4. 实操演练：三类架构图的Prompt与产出效果

4.1 微服务架构图：从一句话需求到可用图表

微服务架构图是Archify最典型的应用场景。我以一个电商订单系统为例，给一个经过实测的Prompt模板：

请为以下电商系统绘制微服务架构图： - 接入层：API网关、Web端、移动端 - 业务层：用户服务、商品服务、订单服务、支付服务、库存服务 - 数据层：用户库、商品库、订单库、支付流水库 - 服务间依赖：订单服务依赖用户服务和库存服务，支付服务依赖订单服务 - 要求：分三层展示，层内节点横向排列，服务依赖用箭头标注

搭配Archify规则，LLM应该会返回类似这样的Mermaid代码：

graph TB subgraph 接入层 GW[API网关] WEB[Web端] APP[移动端] end subgraph 业务层 US[用户服务] PS[商品服务] OS[订单服务] PAY[支付服务] IS[库存服务] end subgraph 数据层 UDB[(用户库)] PDB[(商品库)] ODB[(订单库)] PAYDB[(支付流水库)] end WEB --> GW APP --> GW GW --> US GW --> PS GW --> OS OS --> US OS --> IS OS --> PAY PAY --> PAYDB US --> UDB PS --> PDB OS --> ODB

这套输出的优点是：它先按接入、业务、数据做了三层分组，然后严格按照依赖关系拉线，没有出现跨层乱连的情况。能达到这个效果，并不完全是模型能力的功劳，更多的是手册里"分层必须用subgraph"这条规则在起作用。

4.2 系统架构图：理清外部依赖与内部组件的边界

系统架构图和微服务架构图容易混淆。我个人理解的区别是：微服务架构图更聚焦服务间的调用关系，系统架构图则更强调系统的外部边界——外部用户、第三方服务、内部模块、基础设施之间的关系。

画系统架构图时，一个常见的坑是LLM把外部依赖画成了内部组件。比如你明明只是想表达"系统接入了微信支付"，它可能画出微信支付内部的复杂结构。要避免这个问题，在Archify手册中需要加一条规则：外部系统一律以单独的"外部依赖"子图表示，不允许展开其内部结构。

实操中效果不错的Prompt结构是：

绘制系统架构图，需求如下： - 使用者：C端用户、运营后台管理员 - 系统内部：网关、核心业务服务、消息队列、任务调度、数据库集群 - 外部依赖：短信服务、对象存储、第三方支付 - 重点表达：外部依赖与系统内部的交互边界，内部消息流转方式

输出时，Archify会引导LLM在顶部画用户边界、中间画系统内部核心模块、底部画外部依赖，整体呈现清晰的上下分层结构。这种结构的可读性，明显优于LLM自由发挥时那种网状交错布局。

4.3 调用时序图：表达一次完整业务请求的处理链路

架构图不只有结构图。排查线上问题、梳理核心链路时，时序图往往比架构图更有用。Archify同样可以约束LLM生成时序图。

时序图的生成难点在于顺序的准确性和参与者的一致性。LLM经常把参与者名称改来改去，或者遗漏某个关键调用。所以手册里关于时序图的规则，我建议重点写三条：参与者必须在图例中声明且只能出现一次；消息顺序必须与业务逻辑一致，不得跳步；返回消息要用虚线明确标注，且与请求消息成对出现。

使用Archify后，你得到的时序图代码会保持一种稳定的风格：参与者定义清晰、消息编号明确、关键异常分支用alt块包裹。这种一致性，对后续把图贴进文档或做自动化校验都很有帮助。

4.4 从文本到图的完整链路：一次真实问答的记录

我把上面的思路串起来，模拟一次完整的问答过程。用户给了一段需求描述，Archify先执行了需求拆解，然后引用了规则文件，最后输出了一张图。整个过程大致分为三步：第一步分析视图类型，判断这是一个"微服务架构图"；第二步套用模板，确定分层和分组；第三步生成代码，并对每个依赖关系做了语义检查。

这个流程的意义在于，它把原本黑盒的"LLM画图"变成了可控的管线。任何一个环节出问题，你都能定位到是规则缺失、示例不足还是需求理解偏差，而不是漫无目的地重新写一遍Prompt。我在实际项目中已经把不少重复性的"需求到草图"工作交给了这套流程，效率提升非常明显。

5. 常见问题速查：LLM画图翻车与排查技巧

5.1 语法错误与格式问题

LLM输出的Mermaid代码偶尔会带一些渲染器无法解析的语法，比较常见的有：节点ID用了中文字符导致冲突、箭头方向写反、subgraph没有闭合。遇到这种问题，如果靠肉眼在一大段代码里找错误，会非常痛苦。我的经验是让LLM自己修——把渲染器的报错信息直接回传给LLM，让它对照报错逐行排查。因为在Archify手册里已经约定了语法规范，模型根据报错信息修正的准确率会比较高。

另一个更根本的预防方式是在规则文件里加上"自检清单"：输出代码前先检查subgraph是否成对出现、节点ID是否唯一、箭头是否有明确方向。实测下来，这条自检规则能让语法错误率降一半以上。

5.2 布局混乱与关系表达不清

布局混乱是LLM画架构图最突出的问题。十个以内的节点通常没有问题，节点超过十五个、层级超过三层，LLM的布局能力就会明显下降。这时候靠改Prompt往往没用，突破口是加强分组指令和层级约束。

如果LLM把一堆服务平铺在同一个层级，你可以在规则里强制规定："任何一张架构图，必须至少使用两个subgraph，除非用户明确表示只需要单层展示。"如果箭头语义混乱，比如同时存在纯依赖、数据流、调用关系且没有区分，你可以在规则里设定：这张图里最多使用两种箭头语义，多出来的一律删掉。这些约束会逼着LLM做取舍，而取舍正是清晰架构图的关键。

5.3 工具调用层面的典型报错：schema被拒与超时

跟Agent环境配合时，你可能会遇到一个很典型的错误，错误信息大致是：provider rejected the request schema or tool payload。翻译成人话就是：LLM调工具时给的参数不符合工具要求的结构，被上游直接拒绝了。这个问题的根源通常在于Skil描述与工具入参schema不一致，比如你定义了一个diagram_type参数，枚举值只有"microservice"和"system"，但LLM传了一个"architecture"进来。

排查思路很简单：先检查工具schema是否在描述里把可选项列全了；再检查Archify手册里对工具参数是否有完整说明；最后看是不是上下文太长导致LLM在生成payload时出现了截断。我自己遇到过一次，就是因为插图请求里的节点数量太多，LLM生成JSON时在中间截断，导致payload不完整。解决办法是对大图做拆分——先画主架构图，再分域画局部放大图。

还有一类很常见的报错是：llm request timed out。触发原因大多是上下文塞了太多无关内容，模型在生成时反复思考、消耗了太长响应时间。我在接入Archify时用过的一个优化是：把示例库精简到每类图一个范文，而不是塞十来个变体。示例的目的是让LLM理解风格和结构，不是让它横向对比所有可能性，数量过多反而会导致它在生成时犹豫不决。

5.4 几个需要避开的坑

最后说几个我踩过、提过多次的坑。第一个坑是过度设计规则。规则文件写得越厚，LLM越容易忽略细节，规则的权重应该优先保障"边界类"约束，比如禁止跨层连线、禁止混用箭头语义，而不是纠结每个节点的颜色值。第二个坑是忽略示例库的迭代。Archify这套方法能不能用得好，很大程度上取决于示例库的质量。每当你手工修改了一张LLM生成的图，都应该把修改后的版本沉淀回examples目录，让它成为后续生成的参照。第三个坑是"一本手册走天下"。不同渲染工具、不同业务领域，规则会有差异，最好按场景维护多份轻量手册，而不是把所有规范都堆进一个文件。

在我自己维护的项目里，Archify的手册已经成了LLM画图类技能的事实标准。它解决的核心问题不是"模型不够聪明"，而是"模型没有共同语言"。架构图的本质是沟通工具，而沟通需要共识——Archify给LLM和人类架构师之间建立了一套可共享的视觉语法。如果你也在为LLM画图的质量发愁，不妨试试把这套思路搬过去，先花半小时把规则文件和示例库搭起来，后面的收益会超出预期。