前两天在整理一个跨团队技术方案光是架构图就改到第七版。改到后面真正让我上火的不是方案本身而是每次评审后都要手动挪方框、改连线、调层级——图形渲染出来很漂亮维护成本一点也不漂亮。也就是在这个节骨眼上我又把 Archify 捡了回来。Archify 是一个专门面向 AI Agent 的架构图生成技能核心用途很纯粹把一段业务描述、代码阅读结果或会议纪要自动转换为可渲染的架构图定义并输出到文档系统里。它解决的不是“AI能不能画图”这种体验问题而是“架构图能不能稳定、规范、可维护地批量生产”的效率问题。适合 AI Agent 开发者、架构师、DevOps、技术文档负责人参考尤其是那些每天要跟微服务、系统拓扑、软件架构图打交道的人。1. 先想清楚 Archify 到底有什么用AI画图技能、Agent 和工具不要混为一谈1.1 会描述架构不等于会画架构很多人第一次让大模型“帮我画个架构图”时得到的往往是一堆文字描述或者一段语法错误百出的图形代码。原因并不复杂大模型擅长生成自然语言但架构图本质上是一种“半结构化表达”它要求模型同时处理节点、关系、方向、分组、样式和语义一致性这比写一段说明文字要严格得多。我见过最典型的一次对话是用户让 AI 画一个“订单中台架构图”模型给了一段流程描述然后在文字最后补了一句“请将以上内容放到画图工具中”。用户拿着这段话去画发现根本画不出来因为里面没有明确的边界、没有节点类型、没有连接方向。Archify 这类技能存在的意义就是把“画架构图的专业规则”封装进 Agent 的执行上下文里让模型不是靠临场发挥去猜而是按一套预设标准去输出。从这点看Archify 解决的其实是两个问题一是降低画图门槛二是统一画图质量。前者让不会画图的人也能快速得到初稿后者让团队里不同人产出的架构图不会风格迥异、规范混乱。这两件事手动画图很难同时做到。1.2 Skill、Agent 和 Tool职责边界要分清围绕这类型项目始终绕不开一个经典问题Skill 和 Agent 到底有什么区别很多人在做 AI 应用开发时会把这三样东西混在一起。我这里给个简单类比。Agent 像一个项目经理它负责拆解目标、制定计划、调用资源Tool 是一个具体干活的底层员工比如“搜索文件”“执行 Shell 命令”“请求 HTTP 接口”而 Skill 更像是一本项目经理随身携带的行业标准手册里面写着遇到某类需求时应该按什么步骤、什么规范去做。Archify 属于后者它不是一个独立运行的循环而是被 Agent 在合适时机加载的能力包。为了更直观我把三者放一起比较。类型核心作用是否自主运行举例Agent感知需求、拆解任务、编排调用是有自主决策循环帮我写方案并画架构图的智能助手Skill给 Agent 注入特定领域的规范与操作流程否被 Agent 按需加载Archify 架构图生成技能Tool提供具体的外部功能操作否被 Agent 调用文件读写工具、代码搜索工具如果你在做一个 Agent 项目发现 Agent “什么都能聊但一涉及专业产出就泛泛而谈”大概率不是模型不够聪明而是没有给它配好 Skill。Archify 这类技能本质上就是把“你是一名资深架构师”这种空泛设定变成可检查、可复现、可执行的具体动作。1.3 Archify 适合画什么图不适合画什么图我在实际使用中发现Archify 最适合处理的场景是系统架构图、微服务调用关系图、部署视图、数据流图、时序图。这些都是强逻辑、弱表象的图形节点和关系清晰不太依赖美术设计非常适合文本化生成。它对“网络拓扑类架构图”也有不错的表现只要你把设备类型、链路方向、协议说清楚它就能把层次梳理出来。但注意这类信息往往涉及实际网络环境生成后一定需要人工核对不能直接照搬。它不适合画什么不适合画需要精确像素级布局的原型图也不适合画那种为了美观要反复调色、调间距的品牌宣传图。我不止一次让 Agent 生成这种图结果它要么输出一堆样式代码要么生成一种“看起来很像但无法直接落地”的东西。这不是 Agent 能力不够而是工具选型不对。你让一个写文档的岗位去画海报画出来当然不专业。2. Archify 这类架构生成技能是如何把“画得对”变成默认动作的2.1 为什么首选文本化图定义而不是直接生成图片大部分架构图工具是绘图软件你拖拽一个框、拉一条线AI 在旁边看着。但 Archify 这类技能走的是另一条路线让 AI 生成一份结构化的图定义文本再由渲染器解析成图。你可以理解成它不是在“画画”而是在“写代码”只不过这段代码最终能变成画面。这条路线的优势非常明显。首先是可控性高文本定义可以逐行 review哪里关系画错了改一行文本就行不用在画布里重新拖动其次是版本管理方便架构图可以作为普通文本提交到 Git 仓库每次变更都能 diff谁改了、为什么改清清楚楚最后是渲染解耦同一个文本定义可以用不同工具渲染也可以嵌入到 Markdown 文档、Confluence、内部文档站中。我团队里曾经用 PPT 维护系统架构图每次架构调整都要重新画整页经常出现文档里贴的图和线上真实架构不一致的情况。后来全部切换成文本化架构定义才发现原来架构图也可以像代码一样做代码评审。Archify 能发挥价值依赖的正是“文本作为中间产物”这个大前提。2.2 技能内部藏着的三层规则真正让 Archify 区别于普通“画图提示词”的是它内部封装了规则。把这些规则拆开看大致是三层。第一层是证据优先。技能会要求 Agent 不能凭空捏造不存在的组件只能使用需求描述、代码分析、已有文档中出现的模块。如果信息不够必须显式列出假设项而不是默默补一个“订单缓存”节点上去。这一条能避免架构图做得非常精美、但和真实系统完全对不上。第二层是层次与粒度控制。一个复杂系统如果不分层节点会全部平铺在一张图里密密麻麻根本没法看。Archify 通常会让 Agent 先判断该用哪个层级比如系统上下文、容器、组件还是代码级同一张图中不允许跨层连线外部依赖统一收敛到边界节点。这么做的目的是保证可读性。第三层是出口格式规范。包括节点命名是否统一、标签是否使用约定语言、关系方向是否标注清楚、是否需要按图标分组。不要小看这些细节一份架构图如果一半节点叫“用户服务”另一半叫“user-service”那维护时就会非常痛苦。2.3 “先有矩阵再有图”的思考方式操作中让我最受益的一个设计是要求 Agent 在真正输出图形之前先产出一份“关系矩阵”或者“依赖清单”。说白了就是先让 AI 想清楚这张图里到底有哪些元素、每两个元素之间是什么关系。我以前直接让 AI “画一张微服务架构图”它输出的连线经常是乱的比如服务 A 调服务 B箭头却从 B 指向 A。后来我改成让它先输出类似下面的结构节点列表客户端、网关、订单服务、库存服务、支付服务、消息队列、数据库依赖关系客户端 - 网关网关 - 订单服务订单服务 - 库存服务……有了这个清单再让 AI 把清单渲染成图形准确率会高很多。为什么因为“关系判断”和“图形渲染”是两个任务混在一起做容易出错。先解决语义问题再解决展示问题这正是 Archify 这类技能高效的关键。3. 实操记录怎么落地 Archify 技能以及一份真实的架构图生成过程3.1 自定义技能的基本目录结构Archify 的安装并不复杂核心任务是让 Agent 在合适时机读到一个叫 SKILL.md 的文件。以我常用的项目目录为例结构大致如下skills/ archify/ SKILL.md references/ architecture-standard.md其中 SKILL.md 是技能入口里面定义了技能的名称、用途描述以及核心指令references 目录存放更详细的规范文档当 SKILL.md 提示“需要参考架构规范”时Agent 再去加载其中的内容。这套机制的巧妙之处在于技能可以先给出一个精简的启动说明避免每次把所有规范都塞进上下文等到真正需要时再加载详细信息。如果你的 Agent 客户端支持自定义技能目录通常只需要在配置中指定 skills 目录位置或者在项目根目录下按照约定创建即可。不同客户端路径可能不同但逻辑基本一致agent-skills/skills/archify/SKILL.md 这种结构基本通用。3.2 核心指令到底长什么样SKILL.md 的开头通常是一段元信息用来让 Agent 判断“什么情况下该启动这个技能”。下面是简化后的示例--- name: archify description: Use when the user wants to generate system architecture diagrams, software architecture diagrams, microservice call relationships, deployment views, sequence diagrams, or data flow diagrams. --- When asked to draw an architecture diagram, follow this workflow: 1. Collect all necessary information. If context is incomplete, list assumptions explicitly. 2. Decide the target diagram type and hierarchy level. 3. Build a node list and relationship matrix before rendering. 4. Output a valid text-based diagram definition. 5. Ensure labels use logical names instead of sensitive internal addresses. 6. If there are more than 20 nodes, group them by domain or subsystem.这份指令不长但每一条都在约束模型行为。你会发现它不是在告诉模型“架构图有多重要”而是在告诉它“第一步做什么、第二步做什么、遇到问题怎么办”。第一次写 Skill 的人容易犯的错是把描述写得很抽象比如“Generate high-quality architecture diagrams”模型读完根本不知道高质量怎么落地。换成流程化描述后即使不额外调试输出稳定性也会有明显提升。3.3 完整实操案例微服务交易系统架构图为了让你看得更明白我模拟一次真实使用过程。假设我正在写一份技术方案需要一张交易微服务相关的架构图于是给 Agent 的指令大致是“用 archify 技能生成交易域的容器架构图。系统包含小程序客户端、API 网关、用户服务、订单服务、库存服务、支付服务、消息队列和数据库。外部依赖有一个短信服务。”Agent 会先进行信息整理然后输出类似下面的文本定义不同工具渲染标签可能不同这里用通用文本表达graph TD Client[小程序客户端] --|HTTPS| Gateway[API网关] Gateway -- UserSvc[用户服务] Gateway -- OrderSvc[订单服务] Gateway -- StockSvc[库存服务] OrderSvc -- PaySvc[支付服务] OrderSvc -- MQ[(消息队列)] OrderSvc -- OrderDB[(订单数据库)] StockSvc -- StockDB[(库存数据库)] PaySvc --|回调| Gateway OrderSvc -.-|触发通知| SMSService[外部短信服务] subgraph Infra[基础设施] MQ OrderDB StockDB end我在意的不只是它画出了图而是它做对了三件事第一把基础设施和业务服务分成了组第二支付回调方向画对了是支付服务回网关而不是反了第三外部短信服务被特殊标注为“外部依赖”和内部服务做了区分。这些细节如果只靠一句“帮我画一下”很难得到也正是规则约束起到的效果。拿到这段输出后我可以直接把它嵌入到 Markdown 文档中替换掉原本手画的图片。以后架构如果有调整只需要修改文本再生成一次就好。3.4 怎么控制架构图粒度和风格Archify 并不是只能画一种固定样式的图。日常使用中我通常会在需求里点名期望的“视角”比如“从系统级别画”“聚焦订单流程”“把中间件隐藏掉”等。它背后对应的是技能内部关于粒度、范围、节点数量上限的控制逻辑。可控的维度包括图形类型容器图、部署图、时序图、数据流图系统边界只画核心链路还是全量系统都画层级深度系统级、应用级、模块级节点数量超过一定数量时自动分组命名风格统一用中文业务名还是英文技术名举个例子如果你只想看核心链路可以在输入里追加一句“只展示下单过程中的关键服务忽略用户中心内部实现”。Agent 会按技能规则把次要节点折叠掉把焦点收敛在下单主链路。这套机制很适合在做技术汇报前快速出一版精简版架构图而不是每次都把几十个服务堆在一起。4. 运行阶段最常见的坑架构图生成失败的原因与排查顺序4.1 常见失败排查速查表任何 Agent 技能在实际运行中都会出幺蛾子Archify 也不例外。我整理过一份经常遇到的故障清单先放在表格里后面逐条展开说明。现象可能原因处理办法输出内容无法被渲染器解析语法标签缺失或转义错误让 Agent 先输出纯文本定义再放到支持对应语法的环境中渲染节点太多图被挤成一团没有约束粒度补充说明“按子系统聚合节点”或调低节点数量上限箭头方向反复画反关系判断和图形渲染混在一起强制先输出依赖清单再生成图图里出现不存在的组件模型基于经验脑补启动“只使用上下文证据”的规则并要求列出假设项画出的类型不对比如要部署图却画了流程图技能描述太泛或触发不精准优化 SKILL.md 的 description增加更明确的触发词中文标签渲染异常字体或字符转义问题使用节点 ID 映射中文标签或更换渲染环境这六类问题里第一类最容易在初次使用时就遇到。很多人拿到一份看起来是图的东西直接放到渲染工具里发现报错就以为 Agent 能力不行。实际上大多数时候是格式不匹配的问题。我的建议是先要求 Agent 输出不包含语言标记的纯文本定义确认内容本身可读再放到渲染器里测试。4.2 跑偏的核心原因唤醒不精准与约束缺失很多技能跑偏不是执行环节出了问题而是“该生效的时候没生效”。我见过一份自定义技能描述只写了“用于生成架构图”结果用户在对话里连续说了三次“画一张调用图”Agent 都没有加载技能而是直接用通用能力硬画。原因不在模型而在技能的 description 写得不够具体。有效的描述应该类似“Use when user requests architecture diagram, system topology, service relationship, deployment architecture, or component diagram. Also use when asking to visualize module dependency or data flow.” 说白了要让 Agent 在模糊需求下也能判断出该调用哪个技能而不是等用户说出精确技能名才触发。至于约束缺失的问题更多体现在 Agent 输出自由度太高。没有节点数量上限时它可以把几十个节点全部平铺没有强调层级时它会随意把应用层组件和基础设施混在一起。Archify 这类技能真正值钱的部分就是这些看不见的约束规则。如果你正在自己写类似的 Agent 技能一定要把“允许什么、禁止什么”写清楚不要让模型全靠推理。4.3 拿不到真实架构时别让 AI 替你脑补架构图生成最危险的瞬间是用户说“你按常识帮我画一个典型电商架构”的时候。模型基于公开经验确实可以迅速生成一张看起来很专业的图。但问题是这张图画的是“一个典型的电商系统”而不是“你团队正在做的系统”。如果拿去做了汇报后续被追问细节会很尴尬。更尴尬的情况是模型顺手画出了一些团队根本不用的中间件比如用户没提到 Kafaka模型却画了一个消息队列节点还标注“采用异步削峰”。现场看到这种图基本等于告诉别人这是 AI 生成的没有人做过校对。所以我在使用 Archify 时有一条铁律前期信息不足宁可让它输出“假设清单”也不要让它强行给结论。例如在生成图末尾追加一段“Assumptions: 默认外部依赖是 XXX默认存在统一认证中心”等。这样哪怕图不够完整至少每个决策点都有据可查。后续再拿着这张图找研发确认沟通效率会高很多。4.4 信息安全边界需要提前约法三章使用 AI 生成架构图容易忽略的一点是敏感信息暴露。架构图本身包含服务名、域名、网络区域、数据库类型、通信协议等这些信息对内部文档来说很正常但如果生成过程发生在不受控的平台上或者生成结果被随意分享就存在信息扩散风险。我团队落地这类技能时会约束几点第一图上尽量使用逻辑命名比如“用户中心”“支付中心”不要直接贴内部 IP第二所有输出默认需要经过人工评审不直接进正式文档第三如果使用了外部 AI 服务提交内容要做脱敏处理去掉真正的域名、账号、密钥等。这些不是某个平台的特殊限制而是任何企业用 AI 处理架构信息时都应该有的意识。另外不要让 Agent 自己去读取带有敏感配置的文件后再画图。有些内部配置文件名看上去很诱人读进来之后图是更好画了但你的上下文里多了一大堆不应该提交给第三方服务的内容。信息最小化在架构生成场景里同样适用。5. 影响边界它能改变“画图协作”而不是“架构决策”5.1 架构图进入版本库是工作流的质变用了 Archify 一段时间后我最大的感受不是“AI 帮我省了画图时间”而是“架构图的维护方式彻底变了”。以前架构图是文档里的静态图片改一次系统就要重画一次画完还要手动同步到各处。现在架构图以文本形式存在版本库里每一次修改都和代码提交关联评审时能清晰看到图和代码是否同步变更。这种质变带来的影响远不止效率提升。它让架构图拥有了和代码一样的“可审查性”。以前架构评审会上一张图错了需要靠人眼发现现在图是文本生成的每次改动可以 diff可以在 CI 阶段校验语法是否合法甚至可以扫描是否出现了不该出现的节点。在合规要求比较严格的环境里这一点尤其有用。它能确保你对外展示的系统结构图确实是从受控的代码状态生成的而不是某个人拍的脑袋。很多人问我既然 AI 能生成架构图那是不是可以不用养专门画图的文档工程师了。我的看法是文档工程师的职责会从“手工绘制”转向“流程定义与内容质检”。他们不再负责拖动方框而是负责沉淀规范、设计模板、检查语义。这个岗位的价值没有消失而是升级了。5.2 Agent 按场景自动选择视图团队协作进入新阶段再往后走一步当 Archify 这样的技能接入一个完整的 Agent 工作流时团队协作方式会发生变化。例如开发人员提交一段代码变更说明之后Agent 可以根据变更内容自动判断这次改动影响哪些服务需不需要更新原有架构图如果需要它会自动生成新一版方案图并提交给相关人员确认。这种能力在大型系统里价值巨大。曾经有一个案例一个团队在深夜上线了一个小功能因为涉及的只是单个服务内部逻辑所以没有问题。但运营文档里引用的架构图还是旧版其他团队照着旧图排查问题白白浪费了半小时。如果架构图生成和 Agent 流程绑定每次变更后自动检测影响面并触发文档更新这类“文档与实现脱节”的问题就能大大减少。当然要做到这一步不能只依赖 Archify 一个技能还需要有代码搜索工具、文档更新工具、通知工具协同。但 Archify 在其中扮演了“专业内容生成者”的角色。它是一个可以被复用的原子能力而不是孤立的玩具。5.3 什么情况下不要过度依赖 Archify任何工具都有边界Archify 也一样。它擅长把已经梳理清楚的架构信息转换成图但这不意味着它能帮你发明架构。你在草稿纸上都还没想清楚“这个系统到底要分几个域”的时候让 AI 画出来的图表大概率是别人家的系统套路对你的决策没有帮助。我的经验是最合适的使用时机有两个一个是“思路已经八九不离十只是想快速看到可视化效果”另一个是“需要把已有代码或文档中的结构关系整理成图”。如果连需求边界都不确定我更建议先开白板会议或者在文档里把系统边界、模块职责写清楚然后再让 Archify 帮你正式成图。同时也注意AI 生成的架构图不一定代表系统现状尤其当技能没有连接实时代码数据的时候。所以把 AI 生成的架构图当作“架构愿景图”可以当作“现状审计结论”就要小心。真正想获得系统真实依赖关系应该去读代码、看链路追踪、查看配置中心而不是凭模型经验猜。最后分享一个我自己的实操体会。最理想的使用方式是把 Archify 当成一个“随时可用的画图助手”而不是“一次性的画图工具”。每次开新项目的时候我都习惯在第一周让它基于已有的代码结构生成一张总体架构草图把基础服务、业务模块、外部依赖标记清楚之后每次代码评审发现架构有调整顺手就更新对应的文本图。时间长了你会发现团队里永远有一份和代码保持同步的架构视图这对新人上手、跨团队沟通、季度汇报都是很大的加分项。别再让架构图成为上线前临时补的文档了把这个工作交给还不错的技能把省下来的精力用在真正需要你判断的结构决策上。