1. 项目概述Archify 到底在解决什么问题先说结论Archify 是一个利用 AI 生成交互式架构图的工具核心玩法是“用一个高质量的提示词让大模型输出可交互的 HTML 架构图”。这个项目在 GitHub 上拿到了 30k Stars而且是国产独立开发者作品放在整个开源生态里都算现象级。架构图这个东西软件行业的人都不陌生。画架构图本身不难难的是把架构图画得清晰、准确还能跟上迭代速度。用 PPT、Visio、draw.io 画图画完基本就过时了用 Mermaid 写文本之后让工具渲染可交互能力又很弱点击节点想看个详情都做不到。Archify 的思路是把这件事交给 AI你描述系统、技术栈、模块关系AI 直接生成一份带交互能力的 HTML 页面节点可以悬停、点击、拖拽链路和依赖关系一目了然可以在浏览器里直接运行。适合谁用三类人最需要。第一类是架构师和研发负责人。日常要画系统架构图、梳理微服务调用链路、做技术方案评审这些工作本质上是在“把复杂关系表达清楚”Archify 能把从想到画的过程压缩到几分钟。第二类是写技术文档的开发者。好的技术文档离不开架构图但很多开发者画图能力有限用 Archify 生成 HTML 后可以直接嵌入文档、PPT 甚至部署成静态页面比截图好维护。第三类是正在学习 AI Agent 和提示词工程的人Archify 是一个非常好的实战案例一个项目证明了只要提示词设计足够好AI 能完成非常复杂的生成任务。这篇博文我会从提示词设计、工具原理、实操流程、问题排错四个角度把这个项目彻底拆开保证你看完能直接上手并把关键技巧迁移到自己的项目里。2. 从 Mermaid 到交互式架构图为什么这个方向能火2.1 传统架构图工具的痛点先说一个很多团队的真实尴尬架构图是用公司标配的绘图工具画的画完导出一张 PNG贴在文档里。过了两个迭代系统加了服务、改了调用关系文档里的图片就成了“历史文物”。想更新得打开绘图工具找到原来的文件在一堆框和线里改稍不小心就把布局弄乱了。文本化方案解决了一部分问题Mermaid 是典型代表。它用代码描述图改了文本图就变配合 Git 还能有版本记录。但 Mermaid 的问题也很明显表达能力上限低。它擅长流程图、时序图、状态机这类结构相对固定的图形一旦架构复杂起来——高维度的微服务调用、分层依赖、异步消息流转——Mermaid 写出来就是一坨难以阅读的文本。而且 Mermaid 的交互能力几乎为零。Mermaid 官方支持点击节点跳转、tooltip 提示但体验非常原始想实现“点击服务节点弹出该服务的 API 列表、依赖数据库、环境配置信息”这种需求基本做不到。2.2 “交互式”在架构图场景里的真实价值很多人看到“交互式”这三个字第一反应是“花架子”。但如果你真的在一套上千个服务的分布式系统里做过排障就会明白把架构交互起来有多重要。静态图只能回答“这个系统大概长什么样”交互式架构图回答的是“这个服务到底依赖了谁、谁在调用它、它挂了会影响谁”。后者的价值在故障排查时会被无限放大。用 Archify 的思路生成架构图后你可以点击一个服务节点直接看到它的上游调用方、下游依赖方、使用的中间件、环境部署信息这张图就从一个“摆设”变成了“可查询的系统地图”。再比如做容量规划和技术改造你必须在几十个服务里理清链路关系。静态图上一根线压着另一根线看十分钟眼睛就花了交互式图表允许你聚焦某一层、过滤无关节点、高亮关键链路分析效率完全是两个量级。2.3 30k Stars 背后的设计决策拆解前面说了这个项目 30k Stars涨星是有原因的不是说“蹭了 AI 风口”就完事。我拆解了一下Archify 能在同类工具里跑出来至少做对了三件事。第一抓住了“AI 生成 HTML”这个稳定可靠的技术路线。大模型生成图片不稳定生成 JSON 又不够直观但生成 HTML 是它的强项——HTML 本身是文本模型训练语料里又有海量前端代码输出质量高而且浏览器是所有系统都自带的环境无需额外安装任何东西。第二选择了“单文件交付”的隐性工程标准。好的客户端架构图工具往往生成一大堆依赖文件很难迁移。Archify 生成的 HTML 是独立单页双击就能看嵌入 iframe 就能复用部署到静态托管平台就能分享。这种轻量交付方式非常符合开发者的使用习惯。第三项目本身是“提示词即产品”的范例。它把复杂的架构图生成流程浓缩成了一条高质量的提示词和一套引导对话的方法论。使用门槛非常低不需要写代码不会前端也不影响只要你描述得清楚AI 就能画出像样的图。这个设计思路对任何 AI 应用开发者都有启发一个工具能火不是因为用了多先进的模型而是因为把用户完成一件事的成本降到了足够低。3. 提示词工程Archify 的灵魂在这场对话里3.1 生成交互式架构图的提示词结构拆解Archify 最核心的东西不是代码是提示词。我研究了这个项目的思路结合自己的使用经验把有效提示词拆成五个模块缺一个效果都会打折扣。角色设定。要让大模型知道自己是“资深系统架构师 前端可视化工程师”并且明确告诉它既要懂系统设计又要会写前端代码。角色设定这一步很多人忽略但实测下来做了角色设定之后输出质量明显提升大模型在指定专家身份下会更收敛、更专业。输入结构约定。告诉 AI 你期望收到的信息组织方式系统名称、核心模块、调用关系、技术组件、部署环境、关键链路。这一步的本质是给 AI 建立信息框架让它后续的输出有据可依。输出格式约束。明确提出“输出一个完整可运行的 HTML 文件包含样式和 JavaScript不要输出解释性文字”。这一步极其关键否则 AI 很容易输出半截代码加一堆说明根本没法直接用。交互功能清单。把你要的交互能力逐条说出来节点悬停高亮、点击展开服务详情、拖拽移动节点、搜索定位、链路高亮、分层折叠。大模型是概率模型你不说它就默认不需要说了它才会努力满足。视觉与信息设计要求。告诉它用什么样的配色表达环境区分、用多大的节点承载信息量、什么情况下加图标。架构图不是只要有框和线就行视觉信息层级直接决定读者能否快速提取重点。把这五块拼到一起我实际在用的一个基础模板大致长这样你是一名资深系统架构师同时是前端可视化专家。我会给你描述一个系统的模块构成和调用关系你需要帮我生成一个交互式架构图。 系统信息我将用如下结构提供 【系统名称】 【核心模块】模块名 一句话职能 【模块间依赖】 【技术组件】数据库、缓存、消息队列等 【部署环境】测试、预发、生产 你的输出要求 1. 只输出一个完整可运行的 HTML 文件内部包含 CSS 和 JavaScript不要输出任何解释文字 2. 采用 SVG 或 Canvas 自绘方式不要用 Mermaid因为无法满足交互需求 3. 节点需要有拖拽能力连线需要能跟随节点移动 4. 点击节点弹出详情抽屉展示该模块的职能、依赖方、下游、技术栈 5. 支持输入框搜索搜索到节点时自动高亮并居中 6. 使用颜色区分模块类型业务服务、基础组件、外部依赖 7. 页面整体深色或浅色风格统一布局要清晰避免节点重叠你看这已经是把“需求文档”直接变成提示词了。实际使用时再把自己的系统信息填进去就是 Archify 的完整输入。3.2 一次生成还是分步迭代经验与原因不少第一次用 Archify 的人会犯一个错误把整个系统的所有模块一口气全部塞给 AI让它一步到位生成成品。实测下来效果通常不太好。原因有三。上下文太长导致关键信息被稀释。大模型的能力强但注意力是有限度的几十个模块塞进去AI 很容易漏掉某个依赖关系画出来之后你检查到凌晨。一次生成的纠错成本很高。架构图这东西错一个依赖关系就必须重新生成重新生成又可能破坏之前正确的部分陷入反复横跳。缺少人在中间的架构决策参与。AI 不是你的业务方它不理解为什么 A 模块依赖 B 模块是合理的、为什么 C 模块不能直接连数据库。完全让它自由发挥生成的图只能算“形似”。所以我推荐的流程是“先骨架后血肉”的分步迭代法。第一步先让 AI 生成一个“框架级”架构图。只需要把系统和顶层模块列出来让 AI 画出整体结构。拿生成结果检查和你的理解是否一致框架对了再继续。第二步针对每个模块做深度解析。例如告诉 AI“用户服务模块下包含登录、注册、鉴权三个子模块登录依赖用户中心和短信平台”让 AI 在已有图上做局部展开。第三步检查交互细节并做视觉调整。比如“生产环境的节点用红色调标识核心链路加粗”这一步像是打磨让架构图从“能看”变成“好用”。每一步只给 AI 明确且范围收敛的任务效果远远好于一次性大而全的提示词这是我的核心经验。3.3 提示词里必须写清楚的“隐性约束”有些约束如果你不写AI 大概率会踩坑我列几个最容易忽略的。必须写明“不要在页面顶部输出大段说明文字”。大模型生成 HTML 页面时特别喜欢加一段“这是一个架构图展示的是……”的引导语占空间且没用。你要直接告诉它“不要额外的文字直接是可视化页面”。必须写明“节点文字可读不允许溢出”。AI 自动布局时经常把长服务名塞进小框里文字挤成一团。要在提示词里约定“节点尺寸根据文字长度自适应文字超过 X 字自动换行”。必须写明“单文件不依赖 CDN”。很多 AI 会生成一个引用 CDN 的 HTML 页面如果你在离线环境打开整个图表白屏。要在提示词里明确“不允许外链 CDN所有依赖内联”。这些约束普通用户根本想不到要写但写不写生成结果的可用性差一大截。这也是提示词工程的核心把人类默认的常识显式化变成 AI 可执行的指令。4. 实操指南从零到一做出你自己的交互式架构图4.1 生成前准备选对 AI 工具并明确预期Archify 项目的实现思路是通用的你可以用任何支持代码输出的大模型来驱动不必限定某个产品。我自己测过几类模型体验有差异但核心流程一致。如果你用的是通用对话大模型比如 ChatGPT、Claude 或国产的 kimi、智谱等等直接复制我上面给的基础提示词模板然后把系统信息替换成自己的即可。如果你的工具支持“项目”或“知识库”功能可以把系统的 API 文档、服务清单、部署拓扑文件提前导入模型会基于这些信息生成更准确的图。这里有一个预期管理的问题AI 生成的架构图精确度有限它不是你系统的真身而是你描述的理想模型。你要把它当成“逻辑表达工具”而不是“监控面板”。如果某个依赖关系生成错了大概率是你的描述有歧义或者 AI 的猜测偏差修正描述再重新生成就好不要指望 AI 读心。4.2 案例实操用 Archify 画一个电商系统微服务架构为了让你看完能直接复现我走一遍完整案例。假设我现在要给一个电商平台画架构图系统大概有用户服务、商品服务、订单服务、支付服务、库存服务、网关、消息队列、数据库、Redis以及第三方物流接口。这些信息怎么组织我会写成这样发给 AI请帮我生成一个电商平台的微服务架构交互式图。系统包含这些模块 1. 网关API Gateway负责统一流量入口和鉴权转发 2. 用户服务负责注册、登录、用户信息管理依赖用户库 MySQL、缓存用户会话 Redis 3. 商品服务负责商品查询与库存联动依赖商品库 MySQL、缓存热销商品 Redis 4. 订单服务负责下单流程通过消息队列 RocketMQ 发送订单事件依赖订单库 MySQL 5. 支付服务负责支付回调、对账依赖支付库 MySQL回调后通知订单服务 6. 库存服务负责扣减库存接收订单服务的 MQ 消息依赖库存库 MySQL 7. 第三方物流接口外部依赖订单发货后调用 模块间核心调用关系 - 客户端 - 网关 - 用户服务 / 商品服务 / 订单服务 - 订单服务 - 支付服务发起支付 - 支付服务 - 订单服务异步回调 - 订单服务 - MQ - 库存服务 请提供完整可运行的 HTML单文件、无 CDN底部设计一个图例节点点击弹出详情支持搜索定位。 AI 最好是输出一个完整 HTML 代码块直接在浏览器运行。这一步的关键是“关系描述要具体到位”。不要只说“订单服务依赖支付服务”要说明是同步发起支付还是异步回调AI 才能画出正确的箭头方向和数据流语义。不少人画出来的架构图依赖方向是反的问题就出在描述里没说清楚方向。生成之后我一般会在浏览器里打开检查这几个点整体布局是否清晰节点间连线方向是否符合真实调用关系点击每个节点是否都能弹出对应详情搜索框定位是否准确。如果发现布局不好看我会追加一句“把商品服务和订单服务放在画布中央相关依赖围绕布置”让 AI 重新调整布局。这个流程不用重来效率很高。4.3 生成后的输出与复用不只是看一眼就完拿到一个可交互的 HTML 架构图之后怎么把它纳入日常工作流我有三个惯用做法。嵌入技术文档。大部分技术文档平台支持 HTML 嵌入或 iframe直接把生成的 HTML 文件传上去文档里就能演示完整交互。比静态截图强在读者可以自己点自己查。部署成静态页面。放到 GitHub Pages、对象存储之类的静态托管上链接发到群里所有人打开就能看到最新的架构全貌。做组内分享和评审时非常方便。如果你有内部部署环境建议在 CI 流程里加一个“架构图生成”的任务代码变化触发重新生成技术文档永远是最新的。导出成图或 PDF 作为离线备份。如果你要放进 PPT 或邮件可以直接用浏览器打印功能把 HTML 转成 PDF或者截图关键区域作为静态图使用。这不影响 HTML 版本作为主文件存在属于备用渠道。4.4 用 Archify 辅助架构评审的方法架构评审场景可能是 Archify 这类工具最被低估的价值。我参与过不少评审会大部分时间耗在“讲清楚系统是什么样的”真正用来讨论“为什么这么设计”的时间反而很少。有了交互式架构图情况会好很多。评审前把生成的架构图发给参会者大家提前浏览有疑问在图上标注。评审会开始直接过疑问点而不是像以前一样从画图开始讲起。会议中如果讨论到某个服务的依赖问题直接点开交互面板看全局比投影一张静态图要灵活得多。还有一个技巧让 AI 基于架构图生成“分析报告”。把架构图的 HTML 先让 AI 自己解读一遍总结出单点风险、异常链路、资源瓶颈候选贴在评审文档附注里。这个环节相当于做了一次初步治理检查很多明显的问题在评审前就被过滤掉了。5. 常见问题与排查技巧实录5.1 AI 生成的 HTML 直接白屏怎么办这是最高频的问题。先说原因你用的模型支持 Markdown 预览AI 输出的可能是 Markdown 包裹的 HTML 代码块你直接复制粘贴到 .html 文件里页面渲染不出来或者代码里引用了本地文件、CDN 资源离线打开白屏甚至有些工具会把 HTML 内容截断只生成了半截代码。排查思路按这个顺序走先把 AI 输出的所有内容复制到纯文本编辑器检查有没有 Markdown 代码块的包裹符号有就手动去掉然后搜索有没有 http 开头的资源引用有的话要么联网加载要么让 AI 改成内联最后检查代码结尾看 HTML、script 标签是否闭合如果截断了就让 AI 补全剩余部分不要自己拼。5.2 交互功能不好用点击节点没有反应节点点击没反应九成是 AI 生成的 JavaScript 事件绑定有问题。常见原因是给多个节点绑定时用了重复的 id事件冲突或者弹窗的层级被 CSS 遮挡看着像是没反应。遇到这种问题在提示词里追加一句“确保每个节点绑定各自的点击事件使用 data 属性标识弹窗层级要高于所有画布元素”重新生成。如果模型反复出错就切换到更强代码能力的模型再生成一次。多数情况下这类问题重生成一次就能解决。5.3 AI 画出的依赖关系方向不对这个问题比较隐蔽。AI 默认用户描述里的“A 依赖 B”可能理解成 A 指向 B也可能理解成 B 指向 A不同模型、不同上下文结果不一样。我在提示词里会明确“连线方向从调用方指向被调用方”这样就不会有歧义。如果已经画错了不必重新生成直接对 AI 说“图中所有依赖方向的语义应该是调用方指向被调用方请检查并修正”。大模型能理解你是在修正方向语义一般会自动调整连线不需要你重头开始。5.4 常见错误速查对照表问题表现大概率原因解决办法白屏Markdown 代码块或外链 CDN去掉包裹符让 AI 所有资源内联点击无反应JS 事件绑定冲突追加明确的事件绑定约束后重新生成依赖方向错描述存在歧义明确“调用方指向被调用方”节点重叠布局算法未约束追加“自动避让节点间最小间距”指令页面有文字说明提示词未约束明示“只输出可视化页面不要说明文字”数据不准确描述信息遗漏补全模块、关系、技术栈信息后重新生成5.5 一个独家技巧用“架构数据层”提升生成稳定性这个技巧是 Archify 的进阶玩法也是我自己反复试出来的。与其让 AI 直接生成最终 HTML不如先让 AI 生成一份架构的 JSON 数据格式再基于这份 JSON 生成可视化页面。两步走的好处很明显先保证数据准确再保证渲染漂亮避免数据和渲染互相干扰。实际操作中提示词里加一句“第一步请先输出组件化 JSON包含 nodes 和 edges 两大部分每个 node 有 id、label、type、detail每条 edge 有 source、target、relation确认数据完整后再基于 JSON 生成 HTML 页面”。这样做的好处是迭代时只改 JSON页面渲染逻辑不用动加减服务只需改一个文件。如果你的系统经常变化这个技巧能极大降低维护成本。这个方案还有一个附带优势JSON 本身可以继续喂给 AI 做别的分析比如让 AI 找出“哪些服务是关键的中间节点”“如果某个数据存储挂掉哪些链路会中断”这些都是架构治理的起点从一张图延伸出很多价值。6. 我的使用心得与选择建议用了 Archify 一段时间后我最大的感受是架构图终于从“一次性的输出物”变成了“可持续演进的工具”。以前画架构图画完就完了现在生成的 HTML 可以反复迭代、实时查询甚至作为团队交流的公共语言。如果你只在出文档前临时抱佛脚画一张图那这个工具的收益可能不明显但如果你持续在做系统治理、技术方案评审或者需要经常向新人解释系统架构那 Archify 的思路绝对值得引入工作流。30k Stars 的数据说明这个方向是行业真需求不是凑热点。最后说个小经验提示词不是玄学它是把需求说清楚的学问。Archify 教会我的不是“怎么让 AI 画图”而是“怎么把脑子里的复杂系统讲成一个 AI 能听懂、能执行的明确任务”。这个能力在以后的 AI 开发、AI 辅助编程里会越来越值钱。值得花一个下午研究透。