开源仓库转交互式的系统架构图Diagram网页版GitDiagram - Visualize Any GitHub Repository开源仓库转换成一个结构化的、易于 AI 理解的文本将代码库的原始内容完整地呈现给LLMhttps://gitingest.com/开源仓库打包Repomix作用同上Repomix | Pack your codebase into AI-friendly formats项目名archify项目地址https://github.com/tt-a1i/archify从自然语言到可交互架构图一种基于原子校验的生成方案摘要本文讨论一种 Agent 生成交互式架构图的设计思路分析其校验机制、交互能力、适用场景与局限不涉及具体产品推荐。在技术方案沟通中文字描述和最终架构图之间常缺少一个中间层。Mermaid 适合文本化绘图但交互、路径追踪和分享能力有限通用画图工具灵活但维护成本较高。因此出现一类思路让 Agent 把自然语言描述转成自包含的交互式 HTML 图作为沟通交付物。一、问题背景从技术意图到沟通物通常需要经历“口头描述—白板草图—正式绘图—评审修改”的过程。这个过程存在几个痛点草图难以分享正式图修改成本高评审时无法快速追踪某条请求链路。已有的仓库转文本工具、仓库打包工具解决的是“让 AI 理解代码库”的问题但没有解决“让人快速理解系统结构”的问题。因此需要一种既能由 AI 生成、又能直接交互、还能独立分享的中间产物。二、方案思路这类方案通常以 Agent Skill 的形式存在。用户给 Agent 一段系统描述例如“Browser 调 APIAPI 查 Redis缓存未命中则查 PostgreSQL 并回填缓存”Agent 将其转成一张自包含的交互式 HTML 图。输出是一份独立 HTML 文件浏览器打开即可使用不需要额外部署。它不试图取代 Mermaid也不是通用画图编辑器而是补足“从技术意图到可分享交付物”的中间层。支持架构、工作流、时序、数据流、生命周期五类图覆盖常见的系统表达需求。三、核心机制先验证再交付这类方案值得关注的设计是原子校验机制。每次生成产物之前Schema、布局、HTML/SVG、路由以及标签避让检查必须全部通过否则不会替换上一次验证过的输出。校验失败时返回的是稳定的规则编码、精确的对象、可测量的证据以及有限的可修复项而不是一段难以理解的 Node 报错栈。它还支持可选的 preview 模式在本地端口监听一个 JSON 源文件只有通过全部校验的版本才会刷新失败时保留上一次已验证的图表。这种机制降低了 AI 生成结果不可控的问题让“生成”和“验证”绑定在一起。四、交互能力生成的 HTML 图支持多种交互节点可以悬停查看详情支持 Upstream / Downstream 路径追踪可以聚焦到具体路由切换深色/浅色主题按 S 循环切换视觉风格按 F 进入演示模式。导出菜单支持 PNG 剪贴板复制、静态图片下载以及路线的分享卡片可把某条追踪路径导出为 1200×630 的 PNG。这些能力使它适合在评审、复盘和演示场景中直接使用。五、输入方式它可以从描述开始不依赖代码仓库。用户直接对 Agent 描述请求链路然后用自然语言迭代例如“加上认证”“高亮缓存未命中路径”“切到浅色主题”。它也支持基于真实仓库生成源码背书的架构图节点会标注源码位置并链接到 Git 验证的文件和行号。这为架构图提供了可追溯性避免图与代码脱节。六、适用场景与局限适用场景包括方案评审、故障复盘、请求链路沟通、教学演示、跨团队对齐。对于复杂系统它可以快速产出第一版可交互图减少沟通成本。局限也很明显依赖 Agent 环境复杂系统可能校验失败校验规则覆盖范围有限自包含 HTML 体积较大不能替代专业建模工具。引入前应评估校验规则、维护成本和团队协作流程。此外自然语言描述的质量直接影响生成结果描述模糊时仍需要人工修正。七、总结这类方案的价值在于把“生成”和“验证”绑定先保证可信再交付。若用于生产沟通关键不是图多漂亮而是失败可解释、路径可追踪、输出可复现。从技术意图到沟通物之间确实需要一个既好看、又可信、还能直接分享的中间层而基于原子校验的交互式 HTML 图是目前值得关注的一种实现路径。