前阵子整理一个老项目的技术方案我发现自己又陷进了一件重复度极高的事里一遍一遍画架构图。改一行依赖关系整张图就得重画想加个缓存层换来的是所有箭头重新布线。更要命的是图越来越像蜘蛛网阅读成本反而比文档还高。后来我试着把一个叫 archify 的“Agent技能”装进了自己的 AI 编程助手。archify 的核心思路是让大模型不只停留在“聊天生成文字”而是有一整套可复用的“AI架构图生成”行为准则把架构描述拆成组件、关系、分层再输出干净、可维护的架构图代码。它帮我省下大量画图时间还能在方案评审前快速出一张像样的系统关系图。这篇文章就是围绕 archify 这个 Agent技能 的完整总结。我会讲清楚我为什么选这个形态、内部工作流怎么设计、技能包怎么工程化落地、以及你会踩到哪些坑。无论你是被画图逼疯的研发还是正在研究怎么把提示词封装成可复用能力的人都值得往下看。1. 为什么我会盯上“用Agent生成架构图”这个方向1.1 画架构图的真实痛点在哪里很多人觉得架构师画图无非是用 draw.io 拖几个框。但凡是画过的人都知道真正耗时间的不是“放方框”而是维护方框之间的逻辑关系。我观察到的头号痛点是图的失序系统从 5 个模块涨到 15 个模块之后手工图基本就失控了。因为你在纸上看到的是位置关系但背后是调用链、依赖、数据流、部署关系这些维度叠加在一起靠鼠标拖拽根本表达不清楚。第二个痛点是版本管理。用可视化工具画的图本质是私有文件。你说“从这张图的订单服务里加一个延迟队列”你得重新打开工具找到订单服务拖进一个队列组件再把线连好。整个过程不可脚本化也不会出现在代码 review 里。第三个痛点更像是沟通问题非技术同事要的不是完整的调用链而是“客户端请求先到网关网关调用订单订单要扣库存”这一层逻辑。你却没法为不同的听众快速生成不同粒度的图。这些痛点叠加起来让我越来越确定架构图生成这件事适合交给文档化、可重复执行的流程来做而不是每一次都从空白画布开始。于是我把注意力放到了 AI 编程助手的技能体系上。1.2 为什么首选形态是Agent技能而不是重新训练模型遇到问题先想着“训练一个新模型”是最容易踩的坑。一来成本太高二来我们其实不需要一个只会画架构图的模型我们需要的是让已经很强的通用模型具备一种专业工作习惯。Agent技能 的本质是把一套“专业人员的操作流程 判断标准 输出规范”打包成可以被大模型加载的规则集。装了 archify 之后AI 继续用它的语言理解能力去读懂你的需求描述但后续的动作不再是自由发挥而是遵守一套固定的拆解和绘制流程。这也是我理解的技能Skill和普通提示词最不一样的地方它有流程有中间产物有验证步骤像一个迷你版的工作流引擎而不只是一句写满要求的 prompt。我选这套思路还有一个私心可迭代。普通提示词效果不好你得把一大段话全部推翻技能包不一样你可以只替换掉其中的某条规则或者增加一个检查脚本改动局部就能看到差异。对我这种喜欢反复调整流程的人来说这种形态太友好了。1.3 对比几种输出方案后我为什么锁定了文本绘图格式确定了“由Agent来画图”就要回答下一个关键问题画成什么样实际选项也不少主流的有 Mermaid、PlantUML、D2、Graphviz、draw.io 的 XML 格式等。我的核心判断依据是有三个能不能进 Git、别人能不能不装软件就看到、以及机器能不能自动校验语法。在这三件事上文本型绘图语言天然有优势。Mermaid 目前是 Markdown 生态渗透率最高的GitHub、GitLab 甚至很多笔记软件都能直接渲染PlantUML 更严谨但略微重D2 很现代但生态还在增长。我最终把 Mermaid 作为 archify 的默认输出同时保留了格式扩展层。简单做了一张对比表是我在其他项目里常用的判断逻辑输出格式Git 友好度零安装渲染语法严谨度适合谁Mermaid高高中等日常文档、方案评审、README 配图PlantUML高高需插件/服务器较高需要严格时序图的团队D2高中等较高喜欢现代语法的工程师draw.io XML低低低必须交付 .drawio 文件的场合在我的实际经验里团队协同时 80% 的场景 Mermaid 就够用了。它足够轻差旅途中手机都能看也足够结构化后面扩展成 PlantUML 或 draw.io 也只是脚本层的事。2. archify怎么工作从自然语言到架构图的内部拆解2.1 第一步把“一段话”变成“可建图的要素”用户给到 archify 的输入往往是一段口语化的描述比如“用户通过小程序下单网关先鉴权然后订单服务创建订单同时调用库存服务扣减库存”。这句话在脑子里自动拆开之后其实是一条非常清晰的节点关系链。我设计 archify 的输入解析时借鉴了信息抽取的思路。它不能简单把“用户”“小程序”“网关”“订单服务”“库存服务”这些名词全抓出来然后画一堆孤立的圆圈必须同时回答三类问题谁是发起方谁是中间处理方谁是终端资源组件之间是同步调用还是异步通知哪个服务依赖哪个服务的数据。基于这个逻辑archify 的解析规则被我拆成三条主体识别找出所有承担业务动作的组件区分用户端、网关、业务服务、数据存储。动作提取标记“调用”“写入”“订阅”“返回”这样定义方向的动作词。连接关系把动作词转化为节点之间的有向边确保每一条边都“有来有回”。这里我吃过不少亏。早期版本的规则太激进会把“用户通过手机号登录”中的“手机号”拆成一个独立存储节点后来我加了一条约束先识别业务主体再判断属性词只有承担独立职责的实体才能成为节点形容词和属性一律挂在节点属性上。2.2 第二步用分层策略给架构图“减负”节点都找出来后如果直接平铺连线十有八九会变成一团乱麻。我见过同一张架构图里 30 多个方框互相连线的情况信息量是够了但人根本没法看。archify 的策略是给图加一个虚的“分层坐标系”。默认会尝试把节点映射到三个常见层次区域接入层网关、负载均衡、CDN 等边缘组件业务层账号、订单、支付、库存这类核心服务数据层数据库、缓存、消息队列这类存储和通道设施。分层的核心价值不只是视觉整齐而是帮看图的人降低理解成本。任何人扫一眼图都能先从纵向上判断流量走到了哪一层再在横向上去看那一层内部的多个服务是怎么协作的。这比统一平铺要友好得多。实际执行时archify 会先在内部生成一份“候选分层表”格式大致是“节点名 / 候选层 / 判断依据”。如果同一个组件既可能在业务层又可能在数据层技能会主动向用户确认而不是自作主张。这点很关键因为图生成后最怕的就是“AI觉得合理人类看着别扭”。2.3 第三步输出前的自检循环比画图本身更重画完初稿就交差是新手 Agent 最容易犯的错。一张图能不能用不是看它有没有把节点和箭头都画对而是看它渲染出来后有没有歧义、有没有不必要的交叉线、层次是否符合直觉。archify 在输出前强制走一轮“自检循环”我会在技能里内置几条检查规则语法层所有的括号是否闭合方向符号是否正确中英文字符有没有混入控制符号。语义层有没有“悬空节点”也就是没有任何连接关系的孤立组件有没有无法解释来源的边。阅读层如果箭头交叉超过一定数量就尝试调整节点顺序或者拆分子图来减少视觉噪音。这个阶段虽然在大模型内部完成不是真正的代码执行但它依然有效。因为请求被强制分成“先画草图再复核再修改”大模型在复核时更容易发现自己上一步的问题。就像一个工程师写完代码做 code review和写的时候盯着屏幕找 bug效果完全不一样。3. archify skill的工程结构一个可复现的技能包3.1 目录设计不是所有技能都得写代码很多朋友一听到 Agent技能第一反应是“要写程序吗”。实际上一个可用的 archify skill最小形态可以只是一个带严格命名规范的 Markdown 说明包。我把 archify 的目录设计成这样archify/ ├─ SKILL.md ├─ reference/ │ ├─ diagram-style.md │ └─ layer-naming.md └─ examples/ ├─ order-system.md ├─ message-queue.md └─ microservices.mdSKILL.md 是入口它的作用类似一个说明书告诉 AI“此刻你拥有 archify 技能你应当按照以下方式处理架构图相关请求”。reference 目录里放的是参考资料比如绘图风格规范、节点命名推荐examples 里放的是我已经人工整理好的优秀案例供模型在生成时参考“好答案长什么样”。对多数支持技能机制的 Coding Agent 来说这套目录可以被直接识别。安装方式也很简单把目录放到技能目录下或者在项目级配置里声明启用 archify skill 即可。这也是 archify怎么用这个问题最直接的答案本质就是装一套技能包然后像聊天一样描述系统。3.2 SKILL.md里面的三个关键提示词要素SKILL.md 写得好不好直接决定了 archify 的表现。我踩了很多次坑才总结出三个不能缺的要素。首先必须有“目标定义”。不能只说“帮用户画架构图”要说清最终交付物是什么比如“返回一段可渲染的 Mermaid 代码默认使用横向布局包含接入层、业务层、数据层三个分组。”其次必须有“限制清单”。大模型如果没有任何限制会倾向于生成名字很酷但意思不明的组件比如“smart-core-service”。我的 archify 会明确要求节点命名优先使用业务真实名称禁止自创缩写不确定的边必须输出到“待确认”小节。第三是“迭代路径”。理想情况下技能不该只有一轮生成能力而是要告诉 Agent先画 v1再询问用户是否需要拆分如果需要细化某个服务则继续生成对应的子图。这个要素让 archify 不再是“一次性生成工具”而更像一个陪着用户一起梳理系统的助手。我会在 SKILL.md 里写一段核心的“角色启用语”让模型进入技能状态。大致的意思是现在开始你是一名系统架构可视化专家所有输入输出请遵循技能内的架构绘制流程如果用户提供的是代码请先反向推导出组件关系再绘图如果你拿不准节点分工必须列出来让用户确认。这一段的语气与位置经过反复测试影响最大。3.3 一套可增删的验证清单完整的 archify skill应该包含一份内部验证清单。这里我给你摘录几个关键项你在自己搭技能的时候可以直接抄节点命名是否遵循“业务名词优先”原则是否存在只有一进没有一出的黑洞节点是否识别出消息队列等异步边界分层是否过度如果超过 5 层是否应该拆成多张子图是否给了明确的“未知关系”标注位置。有人可能觉得这些规则太死板但技能之所以叫技能而不是叫“脚本”正是因为它要有内化的标准。教师批改作业有标准医生开处方有标准架构图生成同样要有标准。你允许 Agent 自由发挥它反而会产出看似丰富、实则零逻辑的作品。把这些检查项放到验证清单里本质上是把专业人员的经验变成可强制执行的流程。4. 上手实操从“一句话需求”到可交付的架构图4.1 装一个archify的最小可用版本我以“支持技能机制的命令行编程助手”为例安装步骤大致是这样拿到 archify 技能包后先确认你使用的编程助手支持 Skills 能力并在配置里开启技能目录。把 archify 整个目录放到约定的 skills 目录里同时确认 SKILL.md 的路径能被正确读入。用一句简单的测试需求触发技能比如“请帮我画一个最简单的用户登录时序”。如果助手正确返回了 Mermaid 代码并主动询问是否继续拆解说明技能启用成功。这套安装流程有个额外好处不修改任何底层模型配置也不依赖网络服务换一台机器照样能复现。技能包就是一堆本地文件甚至可以直接提交到 Git 仓库里做版本管理。由于很多读者会卡在第一步搞不清 Agent 是否自动启用技能。我的建议是不要把技能当“隐形的规则”要在提示语中明确带上“archify”这个词我的命令一般是“使用 archify 画一张当前服务的部署架构图”触发成功率明显比含糊描述高得多。4.2 一个实用的实操对话样例我用一个“小型订单系统”的典型场景演示一下完整交互过程。用户输入是“想看一下我们这套系统的关系用户在小程序端下单请求先经过网关鉴权之后订单服务创建订单订单创建成功后发消息到队列由消息消费者调用库存服务扣库存同时支付服务异步处理对账单。”archify 解析后的处理过程大概如下主体识别用户端、小程序、网关、订单服务、消息队列、消息消费者、库存服务、支付服务。分层规划接入层放置小程序与网关业务层放订单服务、消费者、支付服务数据设施层放队列与库存数据。关系抽取用户端指向网关网关指向订单服务订单服务写入队列队列被消费者读取消费者调用库存服务支付服务订阅对账单结果。这个中间过程不需要向用户全部展示但我会要求技能生成一张“节点与关系确认表”从中能看出 Agent 是否真的理解了输入。这也是判断 AI 架构图生成质量的关键不是看图画得流畅而是看关系“懂没懂”。4.3 图生成之后的“精修命令”套路很多人生成一次就结束忽略了图是需要像代码一样持续重构的。archify 的进阶用法是学会给 Agent 下“精修指令”。常用的几个修图口令是横版换纵版“把布局改成从上到下的方向突出自上而下的请求链路”。分层看“把存储相关的节点统一合并到数据域我不需要看到 Redis 和 MySQL 的内部细节”。突出主线“弱化消息异步分支把订单主链路作为图的主干其他逻辑用虚线标注”。这些指令看起来简单却要求技能能产生持续的上下文它必须记住第一轮生成的节点关系在不改变语义的前提下调整样式。archify 之所以用“技能包”而不是简单提示词正是为了保证这些精修指令不会被模型的无关输出带跑偏。4.4 扩展成其他格式PlantUML与draw.ioMermaid 很好用但实际交付时总有人拿到 draw.io 文件或者团队强制用 PlantUML。我的 archify 里给这类“格式转换”留了一个扩展接口。思路并不复杂只要节点之间的逻辑关系已经确定从一个图形 DSL 换到另一个图形 DSL本质上只是语法换皮。增加一对通用的内部中间格式节点列表和边列表之后分别编写“中间格式转Mermaid”和“中间格式转PlantUML”的模板即可。遇到 draw.io 格式也是同理只不过需要额外处理画布坐标。这一步建议大家量力而行。如果团队没有硬性要求只做 Mermaid 和 PlantUML 两个输出就覆盖了 90% 的场景。尤其不要为了炫技而在技能里堆太多格式否则 SKILL.md 会变得非常臃肿反而影响大模型的命中率。5. 高频翻车与问题排查实录5.1 错误症状、根因和排查方法做 archify 的过程里我积累了不少失败经验这里按症状列一张排查表你可以直接拿来自检。典型现象可能根因排查与解决图渲染后一堆语法错误节点名包含括号或特殊字符导致方向参数读取失败将节点名统一用引号包裹对特殊字符先转义或替换全部节点变成了同一层没有层次感分层指令在 SKILL.md 里权重太低模型没按流程执行把“显式输出分层结果”作为强制步骤不出结果不给最终代码连线永远横跨半个屏幕节点顺序与主链路不一致命令 Agent 调整节点顺序为“用户到网关到核心服务”的自然阅读方向Agent 自己生成了“支付中心2.0”这种奇怪名词缺乏命名约束模型自由发挥了在 SKILL.md 明确“节点名必须来自用户原声或翻译后的标准业务名”处理大型系统时一张图内容太密集没有触发拆分子图机制强制技能在接近节点上限时自动询问“是否拆分订单域”5.2 我踩过最深的一个坑让AI过度补充“隐含组件”一次我描述“这个模块会定时扫描订单表将超时订单改为取消状态”。我原意只是让架构图包含一个定时任务结果 archify 自动补了“定时任务调度平台”“分布式锁”“订单状态机”“审计日志”四个不在当前范围内的组件。单看每个节点都没问题但整个图的主题被冲散了。后来我加了条限制archify 只能对用户描述中明确的组件建图如果推断出必要组件先放在“建议补充”清单里由用户决定加不加。这条改动让图的稳定性提升了很多也让技能看起来更像“一位严谨的同事”而不是一个“想象力过载的实习生”。5.3 排查工具链的高阶技巧如果你的 Agent 支持工具调用还有几个更进阶的保险手段。最推荐的做法是把渲染检查做成外部校验生成 Mermaid 后让 Agent 调用一个本地命令去校验语法或者用 headless 浏览器把代码渲染成 SVG 再判断是否为空图。我在 archify 的可选扩展里设计了一个 mermaid-cli 检查脚本大致会在返回给用户前先执行语法校验。若脚本反馈“语法错误”技能会被要求自动修正并重新生成。这是把人的“图生成后还得亲眼确认”的最低级劳动抽离掉的高级做法。有了这层保障你甚至可以让架构图生成完全无人值守跑在 CI 里自动更新仓库架构文档。5.4 常态化维护让archify成为团队文档的一部分最后分享一个我目前正在做的扩展方向不再把 archify 当临时画图工具而是让它定期读取项目里的服务清单和依赖配置文件自动生成“当前架构快照图”并和上一次做对比。凡是新增依赖、删除模块、网络地址变更都能在架构图上被自动标注出来。在这种用法下archify 已经不是“生成”一张图的 Agent而是变成了架构治理里的持续集成环节。这也是 Agent技能 最有想象力的地方它不是被调用一次就结束的工具而是可以常驻在开发流程里像机器人同事一样帮你维护那些看似琐碎、实则要命的 Know-how。我个人习惯是把 archify 产生的所有架构图都纳入 Git 管理并且要求最终评审前至少让技能跑两遍第一遍是“文字需求初绘图”第二遍是“代码现状反推对照图”。两轮结果不一致的地方往往就是架构文档和真实实现之间的裂缝也是下一次技术重构的最好切入口。如果你也想试试我建议从最小的 SKILL.md 起步只加三条规则先感受一周再根据翻车现场逐步补规则。