不知道你有没有经历过这种场景让大模型画一张系统架构图它回复得倒是很干脆唰唰输出一大段代码结果你粘到渲染工具里出来的图要么节点叠成一坨要么箭头方向莫名其妙要么核心模块被挤到角落怎么看怎么别扭。我前前后后试过不少提示词模板效果都不稳定直到我接触到 Archify 这个项目思路才一下打开了。Archify 本质上是一份写给大模型看的“绘制架构图操作手册”。它不依赖某个具体的画图软件也不是一个新的渲染引擎而是把“如何画一张合格的架构图”这件事拆成了从需求理解、图类型选择、节点梳理、连线定义到最终生成可渲染代码的完整规则集。你把它塞进大模型的上下文里它画出来的图质量能明显上一个台阶。这篇文章我就把自己拆解 Archify、接入不同工具、实际跑通全流程的经验全部写出来包括遇到的报错和排查过程给你一条可以照着做的路。1. 项目整体设计与拆解思路1.1 为什么大模型画架构图总是翻车先说结论不是大模型不够聪明是我们从来没有给它一本“画图手册”。大模型本质上是一个文本生成模型它对视觉空间没有真实的感知能力。我们人类画架构图时能感知到“这个模块应该在左上角”“这两个服务之间关系紧密所以离得近”“消息队列放在中间会比较合理”但大模型面对这些需求时只能依赖它在训练数据里见过的图例和文本描述来推测结构。它没有“眼睛”去预览自己的输出所以经常出现下面这些问题。第一是层次混乱。画系统架构图时最基础的要求是分层从上到下依次是接入层、应用层、服务层、数据层。但大模型如果不被明确告知“必须分层”它很容易把网关、数据库、微服务全部堆在同一层级里导致整张图平面化看不出边界。第二是关系线乱连。数据流、调用流、部署关系这三者本质上是不同的关系语义。调用流是“订单服务调用库存服务”数据流是“订单数据写入订单库”部署关系是“支付服务部署在K8s集群里”。大模型画图时如果没有明确的语义区分就会把三种线混在一起甚至出现数据线、调用线交叉的情况。第三是节点命名没有规范。同一个服务第一处叫“订单服务”第二处叫“order-service”第三处叫“订单模块”渲染出来三个节点看起来像三个不同的服务。这种问题在大模型输出里特别常见因为自然语言本来就是同义词满天飞但架构图需要的是严格的唯一标识。换句话说大模型缺少一套“操作SOP”。我们自己画架构图的时候有职业习惯比如先列节点再连线、分区域布局、用统一命名但这些潜规则都在我们脑子里没有显式地告诉模型。Archify做的最核心的一件事就是把这个隐性的职业习惯变成了显式的、可执行的手册指令。1.2 Archify 的核心思路用操作手册约束生成过程Archify 这个名字很容易让人联想到“架构”Architecture和“美化/分类”-ify它确实承担了“让LLM画图变得更结构化”的职责。但它的实现方式不是写一个更大的模型也不是做一个新的画图框架而是用“规则文本”的形式把绘制架构图的完整流程固化下来。这个思路的巧妙之处在于它把“让模型更聪明”的问题转换成了“给模型更好的工作流程”的问题。想象一下你带一个新人画架构图。你不可能指望他看一眼需求就画出完美成品你会一步步告诉他先明确用户想要什么范围的图是系统全景还是单个服务内部再选图类型系统架构图用分层布局微服务调用图用调用链布局部署图用分组布局接着列节点清单然后画连线最后自己检查一遍有没有孤立节点。这一套流程对于一个新人来说就是“操作手册”Archify 对大模型做的正是同样的事。所以 Archify 的整个内容设计是围绕流程拆解来的需求理解阶段告诉模型应该提取哪些关键信息比如系统边界、核心组件、关系类型。图类型选择阶段根据需求判断该画哪一种图选择对应的图形语言。节点建模阶段要求模型先列出所有节点并给出统一的命名规范。关系建模阶段要求模型区分调用关系、数据流动关系、部署关系。布局规范阶段明确分层的方向、分组的容器、避免连线交叉的规则。输出代码阶段要求生成可直接被渲染工具识别的代码而不是画一个示意图就算完事。自检阶段输出前检查节点重复、孤立节点、箭头方向、语法正确性。为什么这样做有效因为大模型行为高度受上下文影响你把规则写得越具体、越可操作它就越有可能遵守。你如果只跟它说“画一张架构图”它只能依赖平均水平的模糊记忆但如果你告诉它“按照这六步来每一步做什么最后用什么格式输出”它的表现会稳定非常多。我自己的测试里用 Archify 这类的规则约束后架构图的可用率从原来的五六成提升到了九成以上。1.3 Archify 的适用范围与边界Archify 好用的前提是选对场景。我实际测试下来下面这几类图它处理得非常好微服务架构图几十个服务之间的调用关系、依赖关系、数据流向它能把节点、分组、箭头捋得很清楚。系统整体架构图从用户端到网关到业务服务到基础设施的分层展示。部署架构图服务如何在服务器或容器集群上分布用分组容器展示。时序图描述一次请求经过的调用链顺序特别适合排查接口性能或梳理业务流程。ER 图实体关系图数据表之间的关系。但它也有明显的边界。比如需要精细控制视觉层次的 3D 立体架构图、需要精确像素级别布局的 UI 界面原型图、高度定制的品牌风格视觉图这些都不适合用 Archify 来做。原因很简单大模型对精细空间的控制能力有限这些场景需要的是人能实时拖拽微调的绘图软件而不是一套语言规则。认清这个边界你才不会在错误的地方花时间。2. Archify 操作手册的核心内容拆解2.1 架构图类型与选型规则Archify 手册里最重要的一个概念是“先选对图再动手画”。很多人在让大模型画图的时候不提类型需求模型只能凭感觉选这是翻车的重灾区。Archify 对常见架构图类型做了明确分类并给出了选型规则。我用一张表把手册里的核心类型整理出来图类型适合表达的内容首选图形语言布局倾向系统架构图系统各模块整体关系与分层Mermaid / D2自上而下分层微服务调用图服务之间的调用链与依赖D2 / Graphviz按调用关系排布部署架构图服务与基础设施的部署位置Mermaid graph / D2按环境分组时序图一次请求的完整调用顺序Mermaid sequenceDiagram / PlantUML时间轴纵向ER 图数据实体与关系Mermaid erDiagram / Graphviz实体围绕关系业务流程图流程分支与状态流转Mermaid flowchart / D2从左到右或从上到下选型规则也很简单你首先要判断用户描述的核心是“系统的静态组成”还是“动态的调用过程”。静态组成选架构图动态过程选时序图或流程图。如果描述里大量出现“调用”“请求”“响应”那就是调用关系图如果出现“部署在”“运行于”那就是部署架构图。Archify 会让模型先对需求做一个分类判断再基于这个判断选择对应的模板。这个环节可能看起来很简单但它直接影响后续所有步骤。图类型选错了后面的节点、连线、布局全都会跟着错。这也是为什么手册必须把这一步放在最前面而不是让模型直接开画。2.2 节点定义与关系建模的规范在 Archify 的规则框架里画图的第一步不是写代码是“列清单”。模型必须先定义清楚图中会出现哪些节点并且严格按照规范命名。命名规范上Archify 要求所有节点必须有全局唯一的 ID。推荐使用短横线命名法比如order-service、inventory-service、order-db这个 ID 会直接用在图形代码里保证同一个服务不会因为称呼不同而出现多个节点。节点的显示文本label可以写中文比如“订单服务”但 ID 必须保持稳定。这样既能保证图的可读性也能保证代码的逻辑正确性。关系建模方面Archify 会要求模型区分三种基本关系类型调用关系A 调用 B通常用实线箭头表示方向代表调用方向。数据流动关系数据从 A 流向 B通常用带箭头的虚线或其他样式表示。部署关系A 部署在 B 之上用包含关系或父子节点表示。这三种关系如果混在一起读者就无法判断图里表达的到底是“谁调用谁”还是“谁依赖谁”。Archify 的处理方式很朴素在生成代码之前先要求模型把所有的关系列成“A → B调用订单服务接口”这样的清单。所有关系梳理清楚了再去写代码。这就像你写作文之前先列提纲虽然多了一步但能避免后面返工。2.3 布局与视觉规则的约定这是很多人忽略但实际体验差异最大的部分。同样一组节点和连线布局合理与否直接决定这张图能不能看得下去。Archify 手册里对布局有几条非常实用的约束。第一条是分层方向。系统架构图默认按“自上而下”分层最上面是客户端/用户入口往下是网关层再往下是业务服务层最下面是数据层和基础设施。部署架构图反而是按“自下而上”的包含关系处理底层是物理机/集群上面是服务实例。这些方向约定必须在手册里写清楚否则 Mermaid 默认会按照代码顺序横着排出来的图很容易变成一条长蛇。第二条是分组容器的使用。对于微服务架构Archify 要求模型使用分组来体现模块边界比如某个业务域下的多个服务放进一个组里基础设施单独一个组。在 D2 里就是containers在 Mermaid 里就是subgraph。分组用好之后图的可读性会极大提升一眼就能看出系统分了哪几个区域。第三条是连线交叉最小化。这其实是布局算法的地盘模型很难直接控制但 Archify 会引导模型在生成代码时注意节点顺序和分组位置通过调整节点的代码放置顺序来减少交叉线。比如把经常互相关联的节点放在相邻位置让调用线尽量短视觉效果就会好很多。2.4 输出格式与自检机制Archify 整个手册的最终目的是生成“能直接渲染”的架构图代码而不是把逻辑说清楚就行。所以它会明确指出推荐的图形语言最常用的是 Mermaid 和 D2。我对这两个的选择经验是如果只是放在 Markdown 文档、Obsidian、GitHub README 里展示优先 Mermaid它生态普及度高、零依赖如果是大型复杂微服务架构涉及几十上百个节点优先 D2它的布局算法更智能交叉线更少。除了指定格式Archify 手册还会要求模型在输出前进行一轮自检。我见过比较典型的一条自检规则是检查是否有节点只被声明了但没有出现在任何关系中。这种“孤立节点”在架构图里是很常见的低级错误模型只要多一个确认步骤就能避免。另外还要检查箭头的方向是否与语义一致比如“用户发起请求”的方向是用户→网关如果画反了整张图的意思就变了。这一套下来“给模型一个规则”这件事才真正闭环先分类选型再列节点梳理关系按布局规则生成代码最后自检修正。3. 实操过程把 Archify 跑起来3.1 将手册配置为 LLM 可调用的技能Archify 要生效得想办法让大模型在执行画图任务时读到这份手册。最简单的方式是把它配置成一个“技能文件”或“规则文件”在对话时自动被加载。我自己用的目录结构大致像下面这样project/ ├── .trae/ │ └── rules/ │ └── archify.md ├── skills/ │ └── archify/ │ ├── SKILL.md │ └── templates/ │ ├── microservice.d2 │ └── system.mermaid └── docs/ └── architecture/如果你是使用 Claude 系工具或者 Codex CLI 这类支持技能的开发工具通常可以直接在~/.claude/skills或者项目的.trae/rules下创建一个 Markdown 文件文件名就叫archify.md文件内容就是这套操作手册。之后对话时输入“使用 Archify 画一张某某架构图”模型就会被触发读取这份手册并按照其中的步骤来执行。触发词的设计也很讲究。不要只用“画架构图”这种泛泛的表达最好绑定技能名比如“archify”“archify skill”“用 Archify 画图”模型能更准确地匹配到对应的手册。在我测试的多个工具里只要触发词设置得足够显眼命中率都非常高。3.2 在 Trae 等 AI IDE 里的接入方式很多人问 Archify 怎么用在 Trae 里因为这个工具现在已经是不少开发者的主力 AI IDE 了。Trae 支持通过项目规则文件来约束 AI 助手所以接入 Archify 其实并不复杂。我的做法是在项目根目录下创建.trae/rules/archify.md把手册内容放进去。然后在 Trae 的对话窗口里输入“使用 archify 规则绘制订单系统的微服务架构图”Trae 助手就会读取规则文件并且按照 Archify 手册里的步骤来生成。这里有一个小坑Trae 在读取规则文件时如果你同时开了多个规则AI 可能只加载部分规则。所以建议在触发时明确点出“使用 archify 规则”而不是让 AI 自动决定用哪个。如果你用的是 Cursor、Windsurf 或者直接写.cursorrules原理也是一样的把 Archify 手册作为项目规则文件或者直接写进全局的CLAUDE.md/AGENTS.md里。这样你的每一个项目在画架构图的时候都能自动带上这套规范。3.3 与 Obsidian 和 LLM Wiki 的搭配玩法搜索热词里很多人同时搜过 Archify 和 llm wiki、Obsidian 教程它们之间确实可以形成一套很有意思的组合。llm wiki 的核心思想是给大模型维护一份“项目百科”或者“个人知识库”让它在回答问题时基于知识库而不是凭空发挥。Archify 本质上就是一份“关于如何画架构图的迷你知识库”所以它完全可以作为 llm wiki 里的一个条目或者是项目知识库中的一个配置文档。在 Obsidian 里如果你搭配了 Copilot 插件或者其他本地 LLM 插件可以在系统提示词里加入一段引用[[Archify操作手册]]的说明。这样当你在 Obsidian 中写笔记、提到某个系统时AI 可以自动按照 Archify 的规则生成架构图并直接嵌入笔记里。Obsidian 原生支持 Mermaid所以 Archify 如果输出的是 Mermaid 代码可以直接渲染不需要额外装插件。我个人比较推荐的工作流是在 Obsidian 的某个专门文件夹里维护一份 archify.md作为知识库条目然后在其他笔记里用双链引用它。这样需要画图时LLM 能顺着双链找到规范再结合当前笔记的内容生成架构图。这套组合用起来之后画架构图从“专门开一次对话反复调试提示词”变成了“写笔记时让 AI 顺手插图”效率提升非常明显。3.4 一场完整的实战生成电商系统的微服务架构图我不喜欢讲空理论所以用一个完整的案例来串一遍流程。假设用户的需求是“帮我画一下电商系统的微服务架构图包含用户、商品、订单、库存、支付、物流几个核心服务还有消息队列和数据库。”如果直接把这句话扔给没有手册的大模型它大概率会输出一段 Mermaid 代码把所有服务平铺在同一个层级然后用一堆箭头连接。能用但谈不上专业。但用 Archify 跑一遍流程就完全不一样了。第一步识别范围与类型。大模型先判断出这是一个系统级的微服务架构图适合用 D2 或 Mermaid 的分层布局。于是它决定按“客户端入口 → 网关层 → 业务服务层 → 数据层”来组织。第二步列节点清单。它会把所有节点列出来客户端Web / AppAPI 网关用户服务、商品服务、订单服务、库存服务、支付服务、物流服务消息队列Kafka / RabbitMQ用户库、商品库、订单库、库存库、支付库第三步梳理关系。这一步是重点。它会把关系一条条列出来客户端 → API 网关发起 HTTP 请求API 网关 → 各个微服务路由请求订单服务 → 库存服务调用库存扣减接口订单服务 → 支付服务发起支付请求订单服务 → 消息队列发送订单事件物流服务 → 消息队列订阅订单事件微服务 → 各自的数据库数据读写第四步生成代码。我实测用 D2 生成的效果最好布局清晰自动避免交叉线。核心代码如下简化版direction: down 客户端: { Web App } 网关层: { API网关 } 业务服务层: { 用户服务 商品服务 订单服务 库存服务 支付服务 物流服务 } 数据层: { 消息队列 用户库 商品库 订单库 库存库 支付库 } 客户端.Web - API网关 客户端.App - API网关 API网关 - 用户服务 API网关 - 商品服务 API网关 - 订单服务 API网关 - 库存服务 API网关 - 支付服务 API网关 - 物流服务 订单服务 - 库存服务: 扣减库存 订单服务 - 支付服务: 发起支付 订单服务 - 消息队列: 发送订单事件 物流服务 - 消息队列: 订阅订单事件 订单服务 - 订单库 用户服务 - 用户库 库存服务 - 库存库 支付服务 - 支付库第五步自检。大模型最后会检查一遍每个节点都有连线吗有没有重复节点箭头方向对吗确认无误后才输出结果。整个输出过程比直接画图多了几个步骤但最终图的质量完全不是一个级别。3.5 渲染与后续微调Archify 输出的是代码渲染还需要一个工具。Mermaid 代码可以直接在支持它的 Markdown 编辑器里渲染D2 则需要安装 D2 CLI 来导出为 SVG 或 PNG。我个人的渲染流程是在本地用 D2 CLI 跑一遍生成 SVG再放进文档里。如果发现某个连线交叉严重我会让大模型针对性地调整那个区域的布局而不是整个人工改代码。因为 Archify 已经帮模型建立了一个结构化的上下文你追加一句“把订单服务和库存服务的连线经过的中间节点减少一些”它通常能听懂并且给出更合理的布局。4. 常见问题与排查技巧实录我用 Archify 的这段时间踩过不少坑也遇到了不少社区里同样会碰到的报错。这里挑几个典型问题把排查过程和解决方法写出来。4.1 Mermaid 渲染失败报语法错误Mermaid 是容错率最低的图形语言之一。它要求节点 ID 不能包含特殊字符箭头两侧要留空格subgraph 要正确缩进。这些都是“大模型容易犯的错误”。我之前遇到过一个问题节点 ID 里写了个冒号order:service导致整张图渲染失败。排查思路很简单拿到代码后先用 Mermaid 在线编辑器或者 Mermaid CLI 做语法校验报错信息会直接指出哪一行有问题。当然更好的方式是在 Archify 手册的自检步骤里明确要求“所有节点 ID 只允许使用字母、数字、短横线”。这样大模型在生成的时候就不容易踩坑了。4.2 provider rejected the request schema or tool payload这个报错我印象很深提起来就头大。它通常出现在大模型通过工具调用去请求一个渲染服务或代码执行服务的场景。意思是当前调用工具时提交的参数结构不符合服务端要求最常见的几种原因某个字段拼写错了比如node_id写成了nodeId。参数类型不对比如 schema 要求一个字符串数组模型提交了一个用换行符拼起来的字符串。JSON payload 里出现了多余逗号或者非法转义字符。我当时的处理办法是先看一下具体的报错信息里指出的字段名再去检查 Archify 输出代码时是否包含了不该有的 Markdown 包围符。因为 Archify 默认是输出代码块的但工具调用场景中模型可能会错误地把代码块标记也塞进 JSON 的参数里比如{code: mermaid ... }。带有反引号的字符串会让很多渲染服务的 parser 直接崩溃。解决办法是在 Archify 的规则里加一条当作为工具参数输出时去除所有 Markdown 代码块标记只保留纯代码内容。4.3 LLM request timed out: 模型没有在超时前返回这个报错也很常见。画一张大规模架构图需要模型生成很长的代码如果再加上工具调用模型生成时间很容易超过接口的超时阈值。尤其是用了本地小模型或者远程推理较慢的模型时超时概率直线上升。我的排查思路是拆图。一张 50 个节点的架构图让模型一次性生成不仅容易超时还容易逻辑混乱。Archify 的步骤化设计其实正好能缓解这个问题可以让模型先生成节点清单和关系清单确认无误后再分区域生成代码比如先画网关和服务层再画数据层最后合并。这样每一步的 token 量都小很多模型不会半路“想太久”超时的概率会降低很多。如果用的是支持 tool 调用的远程模型还可以把超时时间调长一些比如从 30 秒调到 60 秒给模型更充足的输出窗口。4.4 常见问题速查表这张表是我在实际使用中总结的覆盖了从接入到渲染的主要坑点可以直接抄走症状常见原因解决方案渲染出来一堆叠加的节点布局未分层节点平铺让 LLM 按 Archify 规则重新组织使用 subgraph 分组同一个服务出现多个节点节点命名不统一修改手册强制要求全局唯一 ID统一使用短横线命名箭头方向与预期相反关系语义未明确定义输出前要求列出关系清单“A → B”必须表达清楚Mermaid 渲染语法报错节点 ID 含有特殊字符自检规则里明确 ID 只允许字母、数字、短横线provider rejected the request schema工具调用参数格式非法关闭 Markdown 代码块标记确保 JSON 字段名与 schema 一致LLM request timed out单次生成内容过长拆分成节点清单和代码生成两步或调大超时阈值D2 生成的图交叉线多节点顺序不合理调整节点顺序让关系紧密的节点在代码里相邻排列模型不读取手册触发词不明确在提示中显式使用“archify”并确认手册文件路径正确5. 进阶把 Archify 变成自己的制图规范5.1 按团队风格定制手册Archify 最大的好处是它本身就是一个文本文件你想怎么改就怎么改。不需要去改源代码不需要构建新工具只需要修改规则描述。比如你的团队习惯用某种特定的颜色体系或者要求所有架构图必须标注环境边界直接在手册里加一条规则就好。我自己的做法是在 Archify 手册的模板部分放好团队的标准颜色变量和常用图标。比如 Mermaid 中通过style设置每个分组的颜色D2 中通过style.fill指定底色。模型读取手册后会自动在生成代码时套用这些颜色和样式方案最终出图风格完全统一。5.2 从“画图”到“解析现有系统”其实根据已有代码生成架构图在 Archify 的框架下是顺理成章的事。规则部分不变只需要在需求理解阶段增加一个环节“读取代码库中的服务注册文件、路由定义、数据库连接配置提取出服务和依赖关系再按 Archify 规则生成架构图。”我试过用 Archify 配合 Codex CLI对一个中等规模的微服务仓库做架构还原。流程是用 Codex CLI 扫描项目让大模型分析服务之间的调用关系和依赖关系输出一份结构化的关系清单再触发 Archify 技能生成架构图。这样得到的图不是凭空画出来的实现想法而是基于实际代码的“现状图”拿来做技术文档、架构评审甚至监控服务依赖状态都有价值。5.3 融入自动化文档流水线更进一步的想法是把 Archify 的生成结果接入到持续集成的流水线里。项目构建完成后自动触发一次架构图生成任务把最新的 D2 或 Mermaid 代码渲染成 SVG提交到代码仓库再同步到内部 Wiki 或知识库。这样团队里的架构文档永远是新的不会出现文档早就过期了但没人更新的尴尬局面。实现方式也不复杂D2 和 Mermaid 都有命令行工具可以在流水线的脚本里调用。只要保证 Archify 手册是稳定的大模型每次生成的代码风格一致渲染出来的图也保持统一。写在最后用 Archify 跑了这么多轮我最大的体会是画图这件事问题常常出在“画图之外”。不是大模型不会写 Mermaid不是渲染工具不好用而是我们在让大模型执行的时候根本没有给它一套可执行的流程和标准。一份足够的操作手册比一百句“画好看一点”管用得多。一个小技巧分享给你用 Archify 画图时我会刻意让模型把中间过程输出出来而不是直接给最终代码。先让它列出节点清单我再补充遗漏再让它列出关系清单我再核对方向是否正确。确认完之后才让它生成代码。这个习惯多花一两分钟但能省下后期改图的一两个小时。实践下来真的值得。