大概在三个月前我让 AI 代理帮忙梳理一个老项目的服务依赖关系它很干脆地甩给我一段 Mermaid 代码。我复制到在线渲染器里导出 PNG再发到项目群。群里同事追问订单服务到底连了哪几张表我只能重新打开那张静态图拿放大镜慢慢找。这事儿让我意识到一个关键问题让 AI 生成架构图根本不稀奇稀奇的是让它生成一张能回答追问的图。后来我就在 GitHub 上翻到 archify 这个项目它的定位非常明确——给 AI 代理装一个技能模块让代理把系统描述或代码仓库直接转成一份可交互的架构图网页节点可以拖动、点击能展开依赖细节、还能按链路过滤。这篇我就围绕 archify 展开聊聊它到底解决了什么问题、内部管线怎么运转、怎么接入你自己的代理以及我实测过程中踩过的几个印象深刻的坑。1. 为什么画架构图这件事值得做成一个技能模块1.1 让 AI 直接画图问题从来不在会不会画直接说结论当前的 AI 模型基本都会画架构图它们缺的不是能力而是稳定的输出形式和可控的工作流程。最常见的输出形式是 Mermaid 或 PlantUML 代码这本身没什么问题但使用链条是断裂的——你得自己找工具渲染、手动调整样式、再导出图片。更别扭的地方在于静态图在图和信息之间砌了一堵墙评审的时候别人问支付服务挂了会影响哪些下游你没法在图上点一下让这条影响链自己高亮出来。交互这件事在一些人看来是锦上添花但在架构评审、系统交接、故障影响面分析这些场景里它是刚需。第二个问题是输出不稳定。同一个代理上午你问它要架构图它给你 Mermaid下午加了一句画详细一点它直接给你 PlantUML如果你没指定格式它甚至可能甩给你一张 ASCII 文本图。我不是说这些格式不好而是它们之间不能无缝互转你每次都要重新适配一遍自己的工具链。技能模块的核心价值就在这里把画图这件事固化成一套有输入、有处理、有输出的标准流程让结果格式稳定、行为可预期。1.2 技能模块和写得更好的提示词的本质区别很多人会想那我写一段足够详细的提示词不就行了我的真实体会是提示词能约束 AI 的回答但约束不了它的过程。你可以告诉它用 Mermaid 画、用颜色区分层次但它内部怎么抽取实体、怎么决定层级、画完怎么交付本质上还是它自己说了算每次的临场发挥都会有偏差。技能模块不一样。它不是一句指令而是一组文件通常包含说明文档和可执行脚本。AI 代理读到技能说明后会按照说明引导的步骤走先理解输入再抽取实体再组织数据最后调用渲染模板产出结果。每一步都有明确的中间产物不再是碰运气。打个比方提示词是口头交代一句你顺便把数据整理一下技能模块是交给你一份包含表格模板、填写规范、检查清单的工具包。后者做出来的东西当然稳定得多。这也是 archify 这类项目让我眼前一亮的原因它把AI 生成架构图从一个随机行为变成了一件接近工业级标准的事。只要你的代理支持技能机制把它放进技能目录注册好代理就知道在合适的时机调用它。1.3 archify 在整个 AI 代理工作流中的位置如果从信息流的角度看archify 夹在代理的理解层和用户的表达层之间上游是用户的需求描述或者代码仓库路径下游是浏览器里那份可交互架构图。它不需要自己做代理那套记忆、规划、工具调用的事情它只负责把架构信息转换成专业的可视化表达。这个定位很讨巧。因为架构图的难点从来不在画而在信息组织和呈现方式。你真正需要一个专业模块的原因是你能稳定拿到可以交互、信息完整的结果而不是每次靠运气得到一个半成品。2. archify 的工作管线从一句需求到一份可交互架构图2.1 输入理解与实体抽取假设你在对话框里输入这样一句话画一个在线商城的架构图包含前端应用、API 网关、订单、用户、商品、库存、支付、消息队列和数据库。这句话里其实藏着三类信息系统边界在线商城组件清单前端、网关、订单、用户……隐含关系调用关系、依赖关系比如消息队列和数据库通常是被依赖方archify 要做的第一件事就是把这段描述变成强结构化的实体列表。过程中最常出问题的地方有三个实体重叠例如订单服务和订单系统被当成两个节点、依赖方向搞反谁调用谁反了、环境要素缺失数据库、缓存、消息队列这类被依赖组件容易被漏掉。为了规避这类问题好的技能模块会在说明文档里内置检查项比如每个实体必须有明确的类型标签服务/网关/存储/中间件每条边必须标注方向和数据性质同步/异步。AI 不是临场发挥而是照着清单干活质量下限就兜住了。2.2 图数据模型中间 JSON 才是灵魂抽取完实体后下一步不是直接画图而是先转成一份统一的图数据模型。这类模型几乎都是由两样东西组成的节点和边。一个典型的结构长这样{ title: 在线商城架构, nodes: [ { id: frontend, label: 前端应用, group: client, meta: {} }, { id: gateway, label: API 网关, group: gateway, meta: {} }, { id: order, label: 订单服务, group: service, meta: { port: 8081 } } ], edges: [ { source: frontend, target: gateway, type: http }, { source: gateway, target: order, type: http }, { source: order, target: db-order, type: storage, label: 读写订单表 } ] }为什么必须经过中间 JSON 这一步两个原因。第一AI 直接生成前端代码非常容易出错。让它写一百个 SVG 节点的绝对坐标十个里面有一个错位整张图就散架了但让它输出 JSON 里的对象列表结构稳定得多渲染由程序完成出错概率大幅下降。第二可交互的底层其实是数据。你在页面上点一个节点、过滤一条链路页面底层操作的正是这份 JSON。数据模型清晰了交互才有依托。这也是静态图和可交互图的分水岭静态图的产物是像素可交互图的产物是数据 视图的双层结构。2.3 渲染与交付为什么最终产物通常是单个 HTML我自己实际打开 archify 生成的产物时最常见的形态是一个自包含的单个 HTML 文件——脚本、样式、数据全部内嵌在里面。这个形态对架构图场景非常合适不依赖网络不需要开着在线服务才能看交付简单一个文件发给同事双击就打开可归档跟着项目文档走链接不会失效渲染管线大致是读 JSON → 布局计算 → 生成 SVG 节点与连线 → 绑定交互事件点击、拖动、缩放、搜索、过滤。单文件 HTML 是消费端中间 JSON 是数据端AI 代理负责把数据端的东西灌进模板。理解这层关系后你想自己改样式、改布局都有明确的侵入点。3. 动手接入环境准备、技能注册与第一次实测3.1 环境准备先把这个技能装进代理前提是你已经在用某个支持 Agent Skills 机制的代理客户端这类机制现在很常见主流的 CLI 代理基本都支持。准备事项其实不多在 GitHub 上找到 archify 的仓库主页把仓库克隆到本地找到它的技能目录将技能目录放到你的代理能识别的位置。通常有两个位置可选全局技能目录比如用户目录下的~/.claude/skills/文件夹项目级技能目录比如当前项目的.claude/skills/文件夹。全局生效是任何项目都能用项目级生效是只在这个项目里用按需选择确认运行依赖。如果技能模块内部用 Python 脚本做数据处理一般要求 Python 3.10 以上具体版本以仓库 README 为准我不建议你把整个仓库直接塞进技能目录。技能目录只需要放能完成生成架构图功能的核心部分——说明文件、脚本、模板。仓库里的示例、测试、文档留在外面就好这样代理加载技能时开销小也不容易发生文件冲突。3.2 注册时最容易忽略的细节description 怎么写技能能不能被 AI 代理正确调用很大程度取决于技能说明文件里的描述信息。这里的坑是描述写得太窄代理不知道什么时候该用它写得太宽代理又会在不该用的场景乱用。我个人的习惯写法是明确场景 输入 输出三段式场景当用户要求生成系统架构图、梳理组件依赖、展示调用链路、分析代码仓库结构时使用输入用户描述或代码路径输出可交互 HTML 架构图包含节点、边、分组、元信息这样代理检索技能时能把用户请求非常自然地映射到 archify。描述信息是代理判断要不要调用这个技能的依据值得花几分钟认真写别抄 README 里那种八股式描述。3.3 第一次实测在线商城系统接入后的第一个测试输入我用了典型场景生成一个在线商城的架构图包含前端、网关、订单、用户、商品、库存、支付、数据库、消息队列。第一轮输出约 11 个节点、14 条边整体骨架能看但有个明显问题所有数据库被画成了一个叫数据库的大节点。点击它之后你根本不知道订单服务用的是哪张库、商品服务用的是哪张库。我补了一句话请按领域边界拆分数据库实例第二轮的输出质量明显提升——变成 20 多个节点订单库、商品库、用户库各自独立每条服务到库的边都带上了用途标签。这个例子想说明一件事archify 不是输入一句话就自动完美。它提供的是一套可控的生成框架你需要把领域知识比如库表拆分规则通过对话或配置注入进去。第一次用不要期待一步到位先用小图试跑再逐步增加细节是最稳妥的方式。生成 HTML 后建议在浏览器里验证三个交互动作拖动节点看布局是否稳定点击服务节点看有没有弹出元信息尝试过滤只看某条调用链。这些动作都正常说明技能已经跑通了。3.4 进阶玩法让代理直接分析代码仓库除了对话描述archify 的一个我很看重的用法是分析现成代码库。比如在项目根目录输入扫描这个仓库的架构生成依赖关系图技能流程会引导代理去读取关键信息源服务注册配置、路由定义、数据库连接配置、docker-compose 里的服务清单、消息队列的 topic 定义等。这类分析特别适合老系统交接和重构前的摸底。好处是图上的每个节点都对应真实代码不是 AI 凭空编的。需要提醒一点采集代码信息的动作通常还是由代理自己的文件读取工具完成的技能模块提供的是分析框架和渲染框架不是一个万能扫描器。扫描质量取决于代码可读性和代理的上下文长度这个提前有预期就好。4. 可交互架构图的底层支撑布局、状态与渲染方案4.1 布局算法决定第一印象一份架构图好不好看七成靠布局。我拿常见的三种布局方式做个对比布局方式适合场景主要问题分层布局前端 → 网关 → 服务 → 存储这类有清晰流向的图跨层依赖一多连线容易绕力导向布局服务间网状依赖复杂、无明确层级节点多时容易变成毛线球树形布局按系统/子系统/模块逐层拆解公共依赖需要复制节点不够灵活架构图最常见的需求是分层 局部网状的混合体所以很多实现会在分层布局的基础上对跨层依赖做额外处理。一个常见做法是把公共依赖聚合成一个节点比如把十个缓存实例聚合成一个缓存集群节点图面立刻清爽很多。4.2 交互不是炫技是为了回答三类问题为什么要做可交互而不是老老实实给一张大图因为架构图的读者通常需要追问三类问题全局问题整套系统由哪些部分构成边界在哪里局部问题这个服务依赖哪些下游它挂了会连累谁路径问题一次下单请求完整经过哪些组件静态图只能一次性回答全局局部和路径问题只能靠人眼在图上追踪。交互图把后两类问题变成了点击和过滤操作点一个节点看上下游输入关键字只看相关链路。我在评审会上最喜欢这个用法——别人问影响面我直接现场操作给他看说服力比拿一张静态图指来指去强得多。4.3 渲染方案的取舍做一个可交互架构图渲染器可选方案不少。我列几个常见方向原生 SVG 少量 JS无依赖单文件好生成适合 AI 直接产出ECharts图例丰富、交互内置但体积偏大Cytoscape.js专攻图数据可视化布局算法多React Flow适合做可编辑的流程图但一般要引入前端构建链archify 这类需要AI 自动生成产物的技能一般倾向选单文件可交付的方案。原因前面说过不需要构建、不需要联网、双击即用。如果你打开生成的文件看源码大概率是内联 SVG 加少量原生事件绑定或者内联了一个轻量图库。理解这层之后你可以在上面加导出 PNG一键切换布局这类功能侵入点非常清楚。5. 实测中踩过的高频坑和我的处理办法5.1 粒度失控AI 什么都想画第一次跑稍大的系统时我让代理画一个含 12 个微服务的架构图结果它顺手把每个服务里的 Controller、Service、Mapper 全列了出来输出两百多个节点。打开图的那一刻密密麻麻完全没法看。根源其实不在 archify而在输入约束不明确。处理办法是在需求里直接定好层级公约例如只画到服务级每个服务的内部细节作为节点的元信息点击节点可查看详情不要直接铺在图上。技能模块本身也最好在说明文档里写清楚默认的展开深度。我的经验是先约定层级再约定范围最后才让代理动手顺序错了就很容易出现两百个节点的灾难现场。5.2 连线交叉与节点重叠第二类高频问题来自拓扑布局。当系统存在大量跨层依赖比如网关直接调用数据库、订单服务又调用用户服务时分层布局画出来会有大量竖线相互穿插。图看着乱评审时也容易被质疑这条线到底连的是哪边。我的处理思路是把要展示的关系分成主次。主关系核心调用链用正常连线展示次关系数据依赖、偶发调用放进元信息里只在点击节点时才显示。这样既保留了信息又避免了图面污染。如果生成结果实在太乱另一个办法是先砍节点——先聚合再按需展开这比让 AI 一次画全所有关系要清晰得多。5.3 中文显示与字体问题因为我主要画的是内部系统架构节点名基本都是中文。生成的 HTML 在干净环境比如没装中文字体的服务器上用浏览器打开时中文可能显示成方框非常尴尬。这其实是单文件 HTML方案的一个共性坑如果不做字体处理它就完全依赖系统字体。我目前的习惯是在技能模板里加一层字体回退链优先使用系统常见中文字体比如微软雅黑、苹方、思源黑体同时明确禁止使用需要联网加载的字体源避免打开文件时字体从外网拉取导致显示延迟。如果你在浏览器里发现中文字体不对优先检查这一步。5.4 大图性能和内存占用节点超过 500 个的时候纯 SVG 的交互性能会明显下降。我遇到过拖动卡顿、点击响应延迟的情况。这不算 archify 的 bug任何纯 SVG 图库到这个量级都会有类似表现。应对思路有两个方向一是限制单图规模默认控制在 50 到 150 个节点之间这也是大多数人能理解的复杂度区间二是需求确实是大规模拓扑时考虑让渲染器切换 Canvas 模式牺牲一部分每个节点都是 DOM 元素的灵活性换来流畅度。对我的日常场景来说控制规模远比提升上限实用——一张图如果大到一屏放不下它作为沟通工具的效果就已经打折了。把 archify 加进日常工作流之后我最大的感受是它没有让画架构图这件事变成魔法而是让它变得稳定可控。输入同样的描述输出的结构和交互行为是基本一致的配合代理的代码阅读能力还能把真实代码变成评审材料。如果你也在做系统梳理、方案汇报这类事建议直接把仓库克隆下来花十几分钟注册一个技能然后拿一个小项目试跑一次。第一次生成的图大概率不完美把粒度约定和领域规则说清楚之后第二次、第三次就会明显顺手。