1. 项目概述archify到底是什么1.1 先解决一个真实痛点AI生成的代码越来越复杂架构图却没人画我用AI辅助写代码也有两年多了工具从最早的Copilot一路换到Trae、Cursor、Claude Code这类Agent型IDE。写得越多越发现一个问题代码量增长的速度和架构文档的更新速度完全不成正比。改一个核心模块牵一发动全身脑子里的记忆撑不过两周回头再看这段代码连自己都看不懂当初的设计意图。这时候最需要的就是一张清晰的架构图。但人画图有多痛苦做过的人都知道拖框、拉线、对齐、调色一张稍微像样的架构图少说半小时复杂系统画一天也不夸张。更麻烦的是画完就过时——下次改了代码又得重新画根本维护不起来。所以当我看到archify这个概念——一个专门用于生成AI架构图的Agent技能——第一反应是这就是给“画架构图”这件事加了一个标准化工序。它不是一个普通的画图插件不是一个只能渲染固定模板的小工具而是把它做成了一个Agent可以反复调用、按需执行、能理解上下文并输出结构化结果的能力模块。换句话说Archify让AI不再只会写代码还会“看懂”代码结构并用图表达出来。1.2 “Agent技能”和普通插件的本质区别这里要先厘清“技能”这个词。最近Agent相关的东西确实火网上到处是“技能树”“技能包”的说法。但抛开各种包装Agent技能的本质其实很朴素它是把一个固定场景下的工作流程、输入输出约定、处理逻辑打包成一个可复用的模块交给Agent按需调用。用生活化的类比来说普通插件像是一个买回来就能用的家电功能固定、操作面板已经定死而Agent技能更像是一本菜谱——它告诉Agent“这道菜该用什么食材、什么顺序下锅、什么火候收尾”但具体的用料和手法可以由Agent根据实际情况微调。这点放到archify上就很有意思。传统的UML工具、架构图编辑器核心是给你一个画布和一堆控件让你自己动手画。而archify这种技能式工具核心是让Agent代替你做“从理解到表达”的全过程你给它一段需求描述、一份代码目录结构、甚至是一次会话上下文它先理解系统包含哪些部分再判断这些部分之间的依赖关系最后生成一份标准化结构描述交给渲染端出图。2. 核心逻辑拆解archify怎么从文本变成图2.1 整个链路拆开看需求文本 → 组件抽取 → 关系推断 → 结构化输出我研究过的架构图生成工具其实不少但大多数都停留在“把JSON/YAML格式的数据转换成图”这一步这并不稀奇Graphviz、PlantUML、Mermaid这些老牌工具几十年前就能做到了。真正难的部分也是archify这类Agent技能的核心价值在于最前面这一段如何从非结构化描述中抽取组件和依赖关系。整个链路大致是这样走的第一层是输入理解。你给Agent的资料可能是多种形态一句话需求“我想做一个带用户登录和订单管理的电商后台”、一份目录树src/main/java下面几十个包、一段需求文档甚至只是一次对话里逐渐聊出来的约束条件。Agent技能需要把这些异构输入统一转换为一张内部清单写清楚系统里有哪些模块、每个模块大概承担什么职责。第二层是关系推断。模块之间的依赖关系往往不是显式写出来的Agent需要根据语境去猜。比如看到“订单模块调用了库存模块的服务接口”就要在订单和库存之间画一条调用方向的边。这个环节最容易出错也比较考验所调用的模型本身的推理能力。第三层是结构化输出。识别完组件和关系之后archify内部会维护一个结构化的图模型然后再映射为具体的图渲染语言——可以是Mermaid的flowchart语法也可以是PlantUML的component图语法。这一步很关键因为不同渲染语言表达同一种关系时语法差异很大而且很多建模工具对中文字符、特殊符号的处理都不够友好。我实际测试下来archify在判断“哪些模块需要出现在图中”这件事上比通用对话模型做得更克制。什么叫克制就是它不会把工具类、配置类、测试类这些跟主干架构无关的东西全都塞进图里。普通模型你让它生成架构图它往往会一股脑把所有类都画出来结果一张图几百个节点根本没法看。archify这种技能式设计在指令里就内置了“按架构层级过滤细节”的规则天然会先画高层视图再按需下钻。2.2 为什么“技能化”比“独立工具”更符合现在的使用习惯这两年我观察到一个趋势像Trae、Cursor这些AI IDE越来越强调“上下文”这个概念。Agent在帮你看代码、改代码的时候已经对项目结构有了相当深的理解。如果这个时候你要画架构图还需要把代码目录树重新复制粘贴到一个独立工具里那就太割裂了。把archify做成Agent技能好处就在这里它可以被内联在日常开发会话中。你在Trae里选中几个核心模块直接说“给这几个模块画个架构图标注它们之间的调用关系”archify技能自动触发不需要切换窗口、不需要重新描述上下文。这就是技能化相较独立工具最核心的体验优势——它不是把一个新工具塞进你的工作流而是融入了你已有的工作流。另外从开发者和团队角度来说技能化还有一个隐性好处便于维护和定制。一个技能的本质就是一个带固定指令模板和工具接口的配置包。如果你们团队有自己的架构规范比如必须标注数据流向、必须区分内部服务与外部依赖你只需要修改技能配置里的指令模板Agent之后生成的所有架构图都会自动遵循这个规范。这比在工具里手动配置或者在每次提问时重复描述规则要高效得多。3. 实操过程把archify跑起来3.1 在Trae、VS Code、Cursor中安装和加载技能先说明一点archify对不同平台的接入方式略有不同但核心都不复杂本质上就是“加载技能包 调用渲染命令”两步。以Trae为例Trae本身支持技能Skill机制加载方式是在技能市场或者本地技能目录中引入archify技能包。装好之后你在对话窗口里的提问方式跟平时差不多只是在描述需求时Agent会自动识别到“画架构图”这个意图并调用archify技能来处理。实际的触发词不用死记我一般会说“帮我梳理一下当前项目的架构”“给XX模块画一张依赖图”“把这段需求转成架构图”甚至更口语化的“这项目结构太乱了帮我理清楚各个服务之间的关系”都能正确触发。在VS Code或Cursor里如果你用的是支持MCP模型上下文协议的方式则需要先确保MCP服务端配置好然后在模型配置中启用archify对应的工具入口。有的版本支持直接在配置文件里声明技能路径有的需要你在对话中指定“使用archify技能”。我建议先把默认的Skill目录搞清楚比如Trae是在用户目录下的skills文件夹VS Code系则可能是插件的数据目录路径不对会导致加载失败但又不报错这一点容易让人摸不着头脑。# 示例在Trae中声明一个自定义技能简化版 name: archify description: 生成系统架构图支持从代码目录或自然语言描述中提取组件依赖关系 version: 1.0.0 triggers: - 画架构图 - 生成架构图 - 梳理架构 - 依赖关系图 input: mode: 自动识别 sources: - 对话上下文 - 目录结构 - 粘贴的代码片段 output: format: mermaid detail: - 高层架构视图 - 模块依赖视图3.2 实操案例一从一个产品需求描述生成系统架构图我先用一个比较常见的场景演示只有一段需求描述没有现成代码。这适合项目启动初期、技术方案设计阶段。我测试时用的提示词大概是这样的“帮我生成一个在线教育平台的系统架构图包含用户端APP、管理后台、课程服务、支付服务、消息通知、数据库和对象存储这几个部分调用关系要标清楚。”archify的处理过程很典型。它先拆解实体用户端APP是入口管理后台是运营人员使用的前台系统课程服务是核心业务模块支付服务和消息通知是支撑模块数据库和对象存储属于基础设施。然后判断关系APP会调用课程服务、支付服务管理后台也会调用课程服务课程服务读写数据库、把课件和视频存到对象存储支付回调之后要触发消息通知。最后输出一张Mermaid的flowchart图。生成的图默认是LR方向从左往右每个模块用圆角矩形表示基础设施类的模块在颜色上做了区分调用方向线上标注了简单说明。整体出来的效果比我们自己手画要专业得多而且清晰度足够直接贴进方案文档。这里有个重要的细节如果需求描述中某些模块之间的关系不明确archify会主动询问而不是乱猜。在我测试这个案例时需求里没有说明课程服务和用户服务之间是否需要单独的认证服务Agent就停下来问我“是否需要加入统一认证模块”。这个“停一下”的行为在技能设计里其实是一个可控项你在配置里可以设置模式为“保守模式”还是“快速模式”。保守模式遇到不明确就提问快速模式就按最合理假设直接出图。3.3 实操案例二扫描已有代码库目录自动生成模块依赖图第二个场景是存量项目——代码已经写了一年多架构图一直没补。我拿一个后端Java项目试了一次项目有四十多个Maven模块目录层级比较深很多开发者也说不清模块间的依赖关系。操作其实很简单直接在Trae中让它“扫描当前项目画一张模块依赖架构图”。archify做的事情是先递归读取目录结构识别模块边界pom.xml所在层级然后逐个模块分析import语句和Service调用抽取模块间依赖最后生成图。整个过程大概一两分钟最后那张图直接暴露了一个问题工具链模块被几乎所有业务模块依赖这其实是一个典型的架构坏味道但平时代码里根本看不出来。对比人工画图这类存量项目的架构梳理通常是花上一天时间、翻无数代码文件才能做到而且因为有清理和统计的成本团队往往不愿意投入。archify把这件事压缩到了分钟级单凭这一点就值得所有写代码超过半年的团队在本地配一套。3.4 实操案例三将“绘制架构图”沉淀为团队自定义技能前面讲的都是直接使用现成的archify技能但更进阶的玩法是把archify当作模板改造出团队专属的架构图技能。我自己踩过这个坑之后强烈建议每个团队都要有一份符合自己规范的技能配置。我们团队的情况是公司有技术规范要求架构图必须画清楚数据流方向和部署边界比如哪些服务部署在同一台机器、哪些必须隔离在图上还要标注相应的技术栈标签。用通用技能生成的图风格上跟公司规范对不上改起来又费时。于是我把规范写进了技能配置里在指令模板中追加了下面的约束# 团队自定义版 archify 技能配置节选 rules: - 必须区分部署边界使用subgraph标识不同部署单元 - 数据流方向一律从左到右禁止逆向连线 - 每个模块必须标注技术栈如Java 17 / MySQL 8 / Redis 7 - 外部系统如支付通道、短信服务商单独用菱形节点标识 - 分析完成后先用一句话输出整体架构评价再输出代码块图这样改完之后团队任何成员在IDE里问架构相关的问题Agent都会自动按这套规范生成图不再需要每个人手动记忆规范。再看“把重复工作流程保存为自定义技能”这句话其实就是这个意思——做一次技能配置之后几乎所有画架构图的会话都会被格式化地处理不会走样。4. 核心原理与参数详解如何调出理想架构图4.1 理解技能内部的指令模板和变量传递机制很多人把Agent技能想得很玄其实拆开看核心就两块一段长时间的提示词指令以及一组可以被调用工具替换的变量。在archify这类技能中输入变量通常是待分析的文本、目录结构、需求描述输出变量则是生成的图语法文本。以“生成Mermaid图”为例技能指令模板中会包含这样一段逻辑第一步分析输入内容识别主要组件。组件类型包括用户端、服务端外部依赖、内部模块、基础设施。第二步分析组件之间关系。关系类型包括调用、依赖、数据读写、消息订阅、部署包含。第三步输出Mermaid语法配置flowchart方向、节点形状、连线标签。节点ID使用英文驼峰命名但在node label中展示中文。第四步按需附加简要说明说明图中主要调用链。这个模板只会在技能被触发时加载所以它不会占用日常开发对话的上下文空间只有在真正需要画架构图的时候整套指令体系才会被注入。这也是技能化能保持多请求准确性的原因之一——它把不常变化的规则部分和每天变化的对话内容分离开了。4.2 参数调节方向、层级、粒度、模式用了archify一段时间后我总结出几个直接影响出图质量的调节项搞懂这些才能真正用好而不是碰运气出图。第一个是图方向direction。架构图分两种典型布局从上往下适合表现层级结构比如网关→服务→数据库从左往右适合表现调用链和数据流向。构建系统架构建议用LR左到右组织架构或分层架构用TB上到下。在技能配置里可以设默认值也可以每次提问时后补说明。第二个是粒度detail level。我实测下来给Agent约束“分三层画”比不约束默认输出的效果要好很多。所谓三层就是入口层网关/APP/前端、业务层服务模块、基础设施层数据库/缓存/消息队列。当粒度设为“高层”时archify会自动忽略一些DTO类、工具类等低层次细节当设为“详细”时才会把所有依赖都展示出来。第三个是推断置信度inference threshold。这个参数决定Agent在关系不明朗时是倾向于猜测还是倾向于不画。置信度设高图会更精简但可能遗漏关系置信度设低图会更全但会很乱。我的建议是先设为默认值跑一次如果发现漏了关键连线再降低阈值重新生成不要一开始就追求全。第四个是模式mode。快速模式生成一张基础图大概十几秒适合探索详细模式会多一步“使用代码检索工具验证依赖确认后再出图”耗时翻倍但准确性更好。如果是画核心交易链路的架构图建议用详细模式稳一点如果是画个大概方案草图用快速模式够了。下面是我整理的参数对照表收藏备用参数可选值默认值影响建议图方向LR / TB / RL / BTLR布局与阅读顺序调用链用LR分层结构用TB粒度高层 / 标准 / 详细标准节点数量与图中细节多少高层用于汇报详细用于排查代码置信度1~53关系推断主动性对复杂系统调低到2避免漏连线模式快速 / 详细快速是否用检索工具验证后再出图核心环节建议详细模式输出格式Mermaid / PlantUML / JSONMermaid后续是否需要导入其他工具PlantUML适合生成图片文档4.3 上下文限制与长代码库的优化策略在实际使用中代码库过大是很容易遇到的问题。一个大型项目可能有上千个模块API和依赖关系数以万计而模型的上下文窗口是有限的你要是把整个目录树硬塞进去要么被截断要么生成质量严重下降。这里有几个实用策略第一限定分析范围。不要一上来就说“分析整个项目”尽量在提问时加入路径范围比如“只看order-service模块内部以及它依赖的其他模块”。这样既减少了上下文消耗也让archify的注意力更集中出图质量明显更高。第二利用架构层级递归。如果系统确实很大先画一张高层图只包含大的模块边界再针对其中某个模块单独画一张子图。比一次性试图画一张包含所有细节的大图要靠谱得多。实际上很多架构设计标准也支持这种分层视图算是歪打正着地符合了规范。第三精简输入材料。清晰粘贴服务接口定义比粘贴大段业务实现代码更有效。只需要把服务名、方法签名、依赖关系表达清楚这样Agent的处理效率会更快输出也更准确。粘贴几百行业务代码反而会增加噪音让它把核心调用关系淹没在细节里。5. 常见问题与排查技巧实录5.1 问题速查表从我身边朋友和社区反馈的情况来看下面这些问题出现频率最高提前了解能省不少折腾时间现象可能原因解决方法技能未被触发回答变成了普通对话没有技能包没加载成功或触发词没写对确认技能目录路径正确重启IDE重新描述“生成架构图”意图生成的Mermaid代码在预览中渲染报错节点ID包含中文或特殊字符导致语法解析失败在技能配置中增加规则节点ID使用驼峰英文命名中文只放label中图特别乱交叉连线满天飞粒度设置太细把不重要的细节也画进去了把粒度调为“高层”或手动指定“只要模块级依赖不要类级依赖”漏掉了关键模块或依赖关系置信度阈值太高Agent不敢推断下调置信度参数或者对关系描述补充更明确的话语分析大项目时卡死或超时上下文过长超出模型承受范围限定范围、分层生成避免一次分析整个代码库问了架构图但输出的却是别的格式技能输出类型没有限定清楚在提问中明确“用Mermaid flowchart格式输出”5.2 排查思路与实际踩坑记录第一个坑技能包路径不对导致静默失败。我之前在Trae里导入archify技能包倒了半天以为成功了但实际上技能目录层级不应该有多余的嵌套。比如正确的路径应该是一种结构但如果你把它放到另一个嵌套层级系统就识别不到而且不报任何错误。排查方法就是在对话里故意问一句“你会哪些技能”如果答案里没有archify大概率就是没加载成功。第二个坑Mermaid中文节点ID渲染兼容性。这是个非常典型的坑因为默认情况下Agent很自然地会用中文去给节点命名。Mermaid语法本身支持中文ID但在某些预览插件和导出工具里兼容性很差会报Unexpected token。我的解决方案是在archify技能模板中固定规则节点ID统一用英文比如userService节点展示名用中文label部分显示“用户服务”。这样中文只是显示内容不影响底层语法解析兼容性会好很多。第三个坑依赖方向搞反。这个问题的教训是不要轻信第一次生成的调用方向尤其是复杂链路。我遇到过系统把“订单服务读数据库”画成了“数据库调用订单服务”这是从描述中将数据流和依赖关系在主被动方向上搞反了。如果觉得图有违和感建议在生成后人工扫一遍关键依赖方向尤其是那些数据流比较明显的环节。5.3 用好archify的几条避坑建议根据我实际操作的经验给你几条实在的建议不一定写在官方文档里但很实用生成Mermaid代码后一定要在IDE里先预览再使用。预览插件可以及时暴露语法问题不要等到粘贴到文档里才发现渲染失败。画图前先明确图的受众。给领导汇报用高层简洁图给开发评审用详细依赖图受众不同参数设置完全不同。没必要一张图走天下。把archify技能和团队的目录结构约定联动起来会更好用。如果你的代码工程有统一的模块命名规范Agent识别组件会更准。一个技能不够就组合多个技能。我在实际工作中会把archify和另一个文档总结技能配合使用先让文档技能把需求文档压缩成摘要再用摘要生成架构图整体效率和准确率都提升了不少。出图后如果需要二次修改不要直接改图代码而是用自然语言描述修改需求让Agent去改。比如“把支付服务放到数据库旁边因为它们部署在同一台机器”Agent会理解语义并调整布局比你手动改代码要高效。6. 写在后面几次实操之后的一些体会我在本地把这套流程跑了大半个月最大的感受是架构图的价值不只是“有张图可以贴文档”而是生成架构图的过程本身会逼着Agent把系统结构重新梳理一遍很多平时被忽略的模块关系和潜在的问题都在这个过程中暴露出来了。这有点像你写代码时候经历代码审查——没有人喜欢做但做完之后系统真的变得更清晰了。另外一点体会是archify这类技能的能力上限很大程度上取决于使用者的表达质量。你给它的信息越结构化它生成的图就越准确。如果你只是丢一句“画个架构图”那它只能给你一张泛泛而谈的图但如果你能说清楚“包括哪几个模块、模块之间什么关系、需要什么粒度的视图”得到的图基本就是可以直接交付的成果。这一点和我这些年用各种AI工具的经验是一致的——高质量的输入才有高质量的输出。最后如果你所在的团队经常要画架构图或者你们的项目已经复杂到没人能说清全貌建议别只把archify当成一个尝鲜的小玩艺用起来就完事而是认真把它嵌入到研发流程里。每次新增模块、每次架构调整顺手让Agent帮大家更新一次架构图积累一段时间后你会发现自己终于有了一份跟代码同步演进的架构文档光这一件事就值回所有折腾时间了。 Agent技能实战：用archify让AI自动生成系统架构图
1. 项目概述archify到底是什么1.1 先解决一个真实痛点AI生成的代码越来越复杂架构图却没人画我用AI辅助写代码也有两年多了工具从最早的Copilot一路换到Trae、Cursor、Claude Code这类Agent型IDE。写得越多越发现一个问题代码量增长的速度和架构文档的更新速度完全不成正比。改一个核心模块牵一发动全身脑子里的记忆撑不过两周回头再看这段代码连自己都看不懂当初的设计意图。这时候最需要的就是一张清晰的架构图。但人画图有多痛苦做过的人都知道拖框、拉线、对齐、调色一张稍微像样的架构图少说半小时复杂系统画一天也不夸张。更麻烦的是画完就过时——下次改了代码又得重新画根本维护不起来。所以当我看到archify这个概念——一个专门用于生成AI架构图的Agent技能——第一反应是这就是给“画架构图”这件事加了一个标准化工序。它不是一个普通的画图插件不是一个只能渲染固定模板的小工具而是把它做成了一个Agent可以反复调用、按需执行、能理解上下文并输出结构化结果的能力模块。换句话说Archify让AI不再只会写代码还会“看懂”代码结构并用图表达出来。1.2 “Agent技能”和普通插件的本质区别这里要先厘清“技能”这个词。最近Agent相关的东西确实火网上到处是“技能树”“技能包”的说法。但抛开各种包装Agent技能的本质其实很朴素它是把一个固定场景下的工作流程、输入输出约定、处理逻辑打包成一个可复用的模块交给Agent按需调用。用生活化的类比来说普通插件像是一个买回来就能用的家电功能固定、操作面板已经定死而Agent技能更像是一本菜谱——它告诉Agent“这道菜该用什么食材、什么顺序下锅、什么火候收尾”但具体的用料和手法可以由Agent根据实际情况微调。这点放到archify上就很有意思。传统的UML工具、架构图编辑器核心是给你一个画布和一堆控件让你自己动手画。而archify这种技能式工具核心是让Agent代替你做“从理解到表达”的全过程你给它一段需求描述、一份代码目录结构、甚至是一次会话上下文它先理解系统包含哪些部分再判断这些部分之间的依赖关系最后生成一份标准化结构描述交给渲染端出图。2. 核心逻辑拆解archify怎么从文本变成图2.1 整个链路拆开看需求文本 → 组件抽取 → 关系推断 → 结构化输出我研究过的架构图生成工具其实不少但大多数都停留在“把JSON/YAML格式的数据转换成图”这一步这并不稀奇Graphviz、PlantUML、Mermaid这些老牌工具几十年前就能做到了。真正难的部分也是archify这类Agent技能的核心价值在于最前面这一段如何从非结构化描述中抽取组件和依赖关系。整个链路大致是这样走的第一层是输入理解。你给Agent的资料可能是多种形态一句话需求“我想做一个带用户登录和订单管理的电商后台”、一份目录树src/main/java下面几十个包、一段需求文档甚至只是一次对话里逐渐聊出来的约束条件。Agent技能需要把这些异构输入统一转换为一张内部清单写清楚系统里有哪些模块、每个模块大概承担什么职责。第二层是关系推断。模块之间的依赖关系往往不是显式写出来的Agent需要根据语境去猜。比如看到“订单模块调用了库存模块的服务接口”就要在订单和库存之间画一条调用方向的边。这个环节最容易出错也比较考验所调用的模型本身的推理能力。第三层是结构化输出。识别完组件和关系之后archify内部会维护一个结构化的图模型然后再映射为具体的图渲染语言——可以是Mermaid的flowchart语法也可以是PlantUML的component图语法。这一步很关键因为不同渲染语言表达同一种关系时语法差异很大而且很多建模工具对中文字符、特殊符号的处理都不够友好。我实际测试下来archify在判断“哪些模块需要出现在图中”这件事上比通用对话模型做得更克制。什么叫克制就是它不会把工具类、配置类、测试类这些跟主干架构无关的东西全都塞进图里。普通模型你让它生成架构图它往往会一股脑把所有类都画出来结果一张图几百个节点根本没法看。archify这种技能式设计在指令里就内置了“按架构层级过滤细节”的规则天然会先画高层视图再按需下钻。2.2 为什么“技能化”比“独立工具”更符合现在的使用习惯这两年我观察到一个趋势像Trae、Cursor这些AI IDE越来越强调“上下文”这个概念。Agent在帮你看代码、改代码的时候已经对项目结构有了相当深的理解。如果这个时候你要画架构图还需要把代码目录树重新复制粘贴到一个独立工具里那就太割裂了。把archify做成Agent技能好处就在这里它可以被内联在日常开发会话中。你在Trae里选中几个核心模块直接说“给这几个模块画个架构图标注它们之间的调用关系”archify技能自动触发不需要切换窗口、不需要重新描述上下文。这就是技能化相较独立工具最核心的体验优势——它不是把一个新工具塞进你的工作流而是融入了你已有的工作流。另外从开发者和团队角度来说技能化还有一个隐性好处便于维护和定制。一个技能的本质就是一个带固定指令模板和工具接口的配置包。如果你们团队有自己的架构规范比如必须标注数据流向、必须区分内部服务与外部依赖你只需要修改技能配置里的指令模板Agent之后生成的所有架构图都会自动遵循这个规范。这比在工具里手动配置或者在每次提问时重复描述规则要高效得多。3. 实操过程把archify跑起来3.1 在Trae、VS Code、Cursor中安装和加载技能先说明一点archify对不同平台的接入方式略有不同但核心都不复杂本质上就是“加载技能包 调用渲染命令”两步。以Trae为例Trae本身支持技能Skill机制加载方式是在技能市场或者本地技能目录中引入archify技能包。装好之后你在对话窗口里的提问方式跟平时差不多只是在描述需求时Agent会自动识别到“画架构图”这个意图并调用archify技能来处理。实际的触发词不用死记我一般会说“帮我梳理一下当前项目的架构”“给XX模块画一张依赖图”“把这段需求转成架构图”甚至更口语化的“这项目结构太乱了帮我理清楚各个服务之间的关系”都能正确触发。在VS Code或Cursor里如果你用的是支持MCP模型上下文协议的方式则需要先确保MCP服务端配置好然后在模型配置中启用archify对应的工具入口。有的版本支持直接在配置文件里声明技能路径有的需要你在对话中指定“使用archify技能”。我建议先把默认的Skill目录搞清楚比如Trae是在用户目录下的skills文件夹VS Code系则可能是插件的数据目录路径不对会导致加载失败但又不报错这一点容易让人摸不着头脑。# 示例在Trae中声明一个自定义技能简化版 name: archify description: 生成系统架构图支持从代码目录或自然语言描述中提取组件依赖关系 version: 1.0.0 triggers: - 画架构图 - 生成架构图 - 梳理架构 - 依赖关系图 input: mode: 自动识别 sources: - 对话上下文 - 目录结构 - 粘贴的代码片段 output: format: mermaid detail: - 高层架构视图 - 模块依赖视图3.2 实操案例一从一个产品需求描述生成系统架构图我先用一个比较常见的场景演示只有一段需求描述没有现成代码。这适合项目启动初期、技术方案设计阶段。我测试时用的提示词大概是这样的“帮我生成一个在线教育平台的系统架构图包含用户端APP、管理后台、课程服务、支付服务、消息通知、数据库和对象存储这几个部分调用关系要标清楚。”archify的处理过程很典型。它先拆解实体用户端APP是入口管理后台是运营人员使用的前台系统课程服务是核心业务模块支付服务和消息通知是支撑模块数据库和对象存储属于基础设施。然后判断关系APP会调用课程服务、支付服务管理后台也会调用课程服务课程服务读写数据库、把课件和视频存到对象存储支付回调之后要触发消息通知。最后输出一张Mermaid的flowchart图。生成的图默认是LR方向从左往右每个模块用圆角矩形表示基础设施类的模块在颜色上做了区分调用方向线上标注了简单说明。整体出来的效果比我们自己手画要专业得多而且清晰度足够直接贴进方案文档。这里有个重要的细节如果需求描述中某些模块之间的关系不明确archify会主动询问而不是乱猜。在我测试这个案例时需求里没有说明课程服务和用户服务之间是否需要单独的认证服务Agent就停下来问我“是否需要加入统一认证模块”。这个“停一下”的行为在技能设计里其实是一个可控项你在配置里可以设置模式为“保守模式”还是“快速模式”。保守模式遇到不明确就提问快速模式就按最合理假设直接出图。3.3 实操案例二扫描已有代码库目录自动生成模块依赖图第二个场景是存量项目——代码已经写了一年多架构图一直没补。我拿一个后端Java项目试了一次项目有四十多个Maven模块目录层级比较深很多开发者也说不清模块间的依赖关系。操作其实很简单直接在Trae中让它“扫描当前项目画一张模块依赖架构图”。archify做的事情是先递归读取目录结构识别模块边界pom.xml所在层级然后逐个模块分析import语句和Service调用抽取模块间依赖最后生成图。整个过程大概一两分钟最后那张图直接暴露了一个问题工具链模块被几乎所有业务模块依赖这其实是一个典型的架构坏味道但平时代码里根本看不出来。对比人工画图这类存量项目的架构梳理通常是花上一天时间、翻无数代码文件才能做到而且因为有清理和统计的成本团队往往不愿意投入。archify把这件事压缩到了分钟级单凭这一点就值得所有写代码超过半年的团队在本地配一套。3.4 实操案例三将“绘制架构图”沉淀为团队自定义技能前面讲的都是直接使用现成的archify技能但更进阶的玩法是把archify当作模板改造出团队专属的架构图技能。我自己踩过这个坑之后强烈建议每个团队都要有一份符合自己规范的技能配置。我们团队的情况是公司有技术规范要求架构图必须画清楚数据流方向和部署边界比如哪些服务部署在同一台机器、哪些必须隔离在图上还要标注相应的技术栈标签。用通用技能生成的图风格上跟公司规范对不上改起来又费时。于是我把规范写进了技能配置里在指令模板中追加了下面的约束# 团队自定义版 archify 技能配置节选 rules: - 必须区分部署边界使用subgraph标识不同部署单元 - 数据流方向一律从左到右禁止逆向连线 - 每个模块必须标注技术栈如Java 17 / MySQL 8 / Redis 7 - 外部系统如支付通道、短信服务商单独用菱形节点标识 - 分析完成后先用一句话输出整体架构评价再输出代码块图这样改完之后团队任何成员在IDE里问架构相关的问题Agent都会自动按这套规范生成图不再需要每个人手动记忆规范。再看“把重复工作流程保存为自定义技能”这句话其实就是这个意思——做一次技能配置之后几乎所有画架构图的会话都会被格式化地处理不会走样。4. 核心原理与参数详解如何调出理想架构图4.1 理解技能内部的指令模板和变量传递机制很多人把Agent技能想得很玄其实拆开看核心就两块一段长时间的提示词指令以及一组可以被调用工具替换的变量。在archify这类技能中输入变量通常是待分析的文本、目录结构、需求描述输出变量则是生成的图语法文本。以“生成Mermaid图”为例技能指令模板中会包含这样一段逻辑第一步分析输入内容识别主要组件。组件类型包括用户端、服务端外部依赖、内部模块、基础设施。第二步分析组件之间关系。关系类型包括调用、依赖、数据读写、消息订阅、部署包含。第三步输出Mermaid语法配置flowchart方向、节点形状、连线标签。节点ID使用英文驼峰命名但在node label中展示中文。第四步按需附加简要说明说明图中主要调用链。这个模板只会在技能被触发时加载所以它不会占用日常开发对话的上下文空间只有在真正需要画架构图的时候整套指令体系才会被注入。这也是技能化能保持多请求准确性的原因之一——它把不常变化的规则部分和每天变化的对话内容分离开了。4.2 参数调节方向、层级、粒度、模式用了archify一段时间后我总结出几个直接影响出图质量的调节项搞懂这些才能真正用好而不是碰运气出图。第一个是图方向direction。架构图分两种典型布局从上往下适合表现层级结构比如网关→服务→数据库从左往右适合表现调用链和数据流向。构建系统架构建议用LR左到右组织架构或分层架构用TB上到下。在技能配置里可以设默认值也可以每次提问时后补说明。第二个是粒度detail level。我实测下来给Agent约束“分三层画”比不约束默认输出的效果要好很多。所谓三层就是入口层网关/APP/前端、业务层服务模块、基础设施层数据库/缓存/消息队列。当粒度设为“高层”时archify会自动忽略一些DTO类、工具类等低层次细节当设为“详细”时才会把所有依赖都展示出来。第三个是推断置信度inference threshold。这个参数决定Agent在关系不明朗时是倾向于猜测还是倾向于不画。置信度设高图会更精简但可能遗漏关系置信度设低图会更全但会很乱。我的建议是先设为默认值跑一次如果发现漏了关键连线再降低阈值重新生成不要一开始就追求全。第四个是模式mode。快速模式生成一张基础图大概十几秒适合探索详细模式会多一步“使用代码检索工具验证依赖确认后再出图”耗时翻倍但准确性更好。如果是画核心交易链路的架构图建议用详细模式稳一点如果是画个大概方案草图用快速模式够了。下面是我整理的参数对照表收藏备用参数可选值默认值影响建议图方向LR / TB / RL / BTLR布局与阅读顺序调用链用LR分层结构用TB粒度高层 / 标准 / 详细标准节点数量与图中细节多少高层用于汇报详细用于排查代码置信度1~53关系推断主动性对复杂系统调低到2避免漏连线模式快速 / 详细快速是否用检索工具验证后再出图核心环节建议详细模式输出格式Mermaid / PlantUML / JSONMermaid后续是否需要导入其他工具PlantUML适合生成图片文档4.3 上下文限制与长代码库的优化策略在实际使用中代码库过大是很容易遇到的问题。一个大型项目可能有上千个模块API和依赖关系数以万计而模型的上下文窗口是有限的你要是把整个目录树硬塞进去要么被截断要么生成质量严重下降。这里有几个实用策略第一限定分析范围。不要一上来就说“分析整个项目”尽量在提问时加入路径范围比如“只看order-service模块内部以及它依赖的其他模块”。这样既减少了上下文消耗也让archify的注意力更集中出图质量明显更高。第二利用架构层级递归。如果系统确实很大先画一张高层图只包含大的模块边界再针对其中某个模块单独画一张子图。比一次性试图画一张包含所有细节的大图要靠谱得多。实际上很多架构设计标准也支持这种分层视图算是歪打正着地符合了规范。第三精简输入材料。清晰粘贴服务接口定义比粘贴大段业务实现代码更有效。只需要把服务名、方法签名、依赖关系表达清楚这样Agent的处理效率会更快输出也更准确。粘贴几百行业务代码反而会增加噪音让它把核心调用关系淹没在细节里。5. 常见问题与排查技巧实录5.1 问题速查表从我身边朋友和社区反馈的情况来看下面这些问题出现频率最高提前了解能省不少折腾时间现象可能原因解决方法技能未被触发回答变成了普通对话没有技能包没加载成功或触发词没写对确认技能目录路径正确重启IDE重新描述“生成架构图”意图生成的Mermaid代码在预览中渲染报错节点ID包含中文或特殊字符导致语法解析失败在技能配置中增加规则节点ID使用驼峰英文命名中文只放label中图特别乱交叉连线满天飞粒度设置太细把不重要的细节也画进去了把粒度调为“高层”或手动指定“只要模块级依赖不要类级依赖”漏掉了关键模块或依赖关系置信度阈值太高Agent不敢推断下调置信度参数或者对关系描述补充更明确的话语分析大项目时卡死或超时上下文过长超出模型承受范围限定范围、分层生成避免一次分析整个代码库问了架构图但输出的却是别的格式技能输出类型没有限定清楚在提问中明确“用Mermaid flowchart格式输出”5.2 排查思路与实际踩坑记录第一个坑技能包路径不对导致静默失败。我之前在Trae里导入archify技能包倒了半天以为成功了但实际上技能目录层级不应该有多余的嵌套。比如正确的路径应该是一种结构但如果你把它放到另一个嵌套层级系统就识别不到而且不报任何错误。排查方法就是在对话里故意问一句“你会哪些技能”如果答案里没有archify大概率就是没加载成功。第二个坑Mermaid中文节点ID渲染兼容性。这是个非常典型的坑因为默认情况下Agent很自然地会用中文去给节点命名。Mermaid语法本身支持中文ID但在某些预览插件和导出工具里兼容性很差会报Unexpected token。我的解决方案是在archify技能模板中固定规则节点ID统一用英文比如userService节点展示名用中文label部分显示“用户服务”。这样中文只是显示内容不影响底层语法解析兼容性会好很多。第三个坑依赖方向搞反。这个问题的教训是不要轻信第一次生成的调用方向尤其是复杂链路。我遇到过系统把“订单服务读数据库”画成了“数据库调用订单服务”这是从描述中将数据流和依赖关系在主被动方向上搞反了。如果觉得图有违和感建议在生成后人工扫一遍关键依赖方向尤其是那些数据流比较明显的环节。5.3 用好archify的几条避坑建议根据我实际操作的经验给你几条实在的建议不一定写在官方文档里但很实用生成Mermaid代码后一定要在IDE里先预览再使用。预览插件可以及时暴露语法问题不要等到粘贴到文档里才发现渲染失败。画图前先明确图的受众。给领导汇报用高层简洁图给开发评审用详细依赖图受众不同参数设置完全不同。没必要一张图走天下。把archify技能和团队的目录结构约定联动起来会更好用。如果你的代码工程有统一的模块命名规范Agent识别组件会更准。一个技能不够就组合多个技能。我在实际工作中会把archify和另一个文档总结技能配合使用先让文档技能把需求文档压缩成摘要再用摘要生成架构图整体效率和准确率都提升了不少。出图后如果需要二次修改不要直接改图代码而是用自然语言描述修改需求让Agent去改。比如“把支付服务放到数据库旁边因为它们部署在同一台机器”Agent会理解语义并调整布局比你手动改代码要高效。6. 写在后面几次实操之后的一些体会我在本地把这套流程跑了大半个月最大的感受是架构图的价值不只是“有张图可以贴文档”而是生成架构图的过程本身会逼着Agent把系统结构重新梳理一遍很多平时被忽略的模块关系和潜在的问题都在这个过程中暴露出来了。这有点像你写代码时候经历代码审查——没有人喜欢做但做完之后系统真的变得更清晰了。另外一点体会是archify这类技能的能力上限很大程度上取决于使用者的表达质量。你给它的信息越结构化它生成的图就越准确。如果你只是丢一句“画个架构图”那它只能给你一张泛泛而谈的图但如果你能说清楚“包括哪几个模块、模块之间什么关系、需要什么粒度的视图”得到的图基本就是可以直接交付的成果。这一点和我这些年用各种AI工具的经验是一致的——高质量的输入才有高质量的输出。最后如果你所在的团队经常要画架构图或者你们的项目已经复杂到没人能说清全貌建议别只把archify当成一个尝鲜的小玩艺用起来就完事而是认真把它嵌入到研发流程里。每次新增模块、每次架构调整顺手让Agent帮大家更新一次架构图积累一段时间后你会发现自己终于有了一份跟代码同步演进的架构文档光这一件事就值回所有折腾时间了。