绘图这件事一直是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.mdLLM就会在合适的时机自己去加载这份文件并使用。如果你在使用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画图的质量发愁不妨试试把这套思路搬过去先花半小时把规则文件和示例库搭起来后面的收益会超出预期。