大概在三个月前，我让 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 加进日常工作流之后，我最大的感受是：它没有让"画架构图"这件事变成魔法，而是让它变得稳定可控。输入同样的描述，输出的结构和交互行为是基本一致的；配合代理的代码阅读能力，还能把真实代码变成评审材料。如果你也在做系统梳理、方案汇报这类事，建议直接把仓库克隆下来，花十几分钟注册一个技能，然后拿一个小项目试跑一次。第一次生成的图大概率不完美，把粒度约定和领域规则说清楚之后，第二次、第三次就会明显顺手。
