Archify实战：用AI提示词生成可交互HTML架构图-平芜编程栈

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 找出“哪些服务是关键的中间节点”“如果某个数据存储挂掉，哪些链路会中断”，这些都是架构治理的起点，从一张图延伸出很多价值。