archify
生成可验证架构图，自包含HTML交付
预览
详细介绍
是由开发者tt-a1i发起并持续维护的开源AI代理图表生成技能，核心定位是“将代码库或系统描述一键转换为精美的、可验证的交互式系统地图”——它不满足于做一份通用的Mermaid样式增强或零散的绘图提示词，而是将架构图、工作流图、时序图、数据流图、生命周期图等5大图表类型、4种视觉预设、暗色/亮色双主题、有限动效、架构变更Delta对比、来源证据追溯、语义节点搜索、角色对比与故事导览等10余项核心能力整合于一套即插即用的技能体系中，全部配有npx skills add tt-a1i/archify一键安装、类型化JSON IR中间表示、原子化交付前验证（schema/layout/HTML/SVG/路由五重检查）、自包含HTML单文件输出（含PNG/SVG/WebM/1200×630分享卡片导出）和交互式Proof Lab演示画廊。市面大多AI图表生成工具要么是泛泛的“画一个架构图”式提示（缺乏设计规范与验证），要么是只能输出Mermaid文本的轻量工具（缺乏视觉定制与交互深度）——但很少有项目能将“编辑级的视觉品质”与“可验证的工程化交付”同时做到，Archify解决的正是这个问题。
一、Archify是什么
Archify采用“AI代理技能+类型化JSON IR+原子化验证”三位一体的使用体验，通过GitHub完全开源发布，采用MIT许可证。项目由开发者tt-a1i发起，是 v1.0的分支与重写，Archify 2.x在此基础上增加了主题、导出、类型化渲染器、验证、可访问性、交互和统一CLI。项目支持Cursor、Claude Code、Codex CLI、OpenCode等主流AI编码代理，提供npx skills add tt-a1i/archify -g一键安装，以及无需永久安装的试用命令npx skills use tt-a1i/archify@archify --agent codex。项目提供、和。
Archify的运作机制与市面常见的“通用绘图提示”或“Mermaid代码生成器”有本质区别。它不是一句“帮我画一个架构图”的泛泛指令，也不是一个只能输出文本描述或依赖外部渲染器的轻量工具，而是一套布局判断优先、类型化中间表示、原子化验证驱动的图表工程框架。其工作流分为五步：生成——代理根据用户描述创建类型化JSON IR（中间表示）；验证——内置验证器和布局规则检查源文件，失败时以机器可读JSON精确定位问题；预览（可选）——桌面会话监视源文件，仅在验证通过后刷新，失败时保留最后已知良好的制品；交付——渲染候选文件并通过所有检查后原子性地替换目标文件；迭代——代理更新源文件，无关结构保持稳定。项目提供了5大图表类型：架构图（Architecture） 展示组件、服务、存储与信任边界；工作流图（Workflow） 展示CI/CD、审批、工具调用与运行手册；时序图（Sequence） 展示API调用、缓存、认证与异步追踪；数据流图（Data Flow） 展示管道、血缘、PII与消费者；生命周期图（Lifecycle） 展示状态、重试、等待与终态。每种图表类型均有明确的适用场景和提示词指引。Archify明确声明自己“不是通用绘图编辑器，也不是Mermaid主题”，而是“将技术意图转化为沟通制品”。
二、Archify能做什么
Archify的核心能力可以精炼地概括为：绘、验、比、溯、享，围绕这五大维度提供了从系统描述到可分享系统地图的完整路径，覆盖技术图表创作的全方位需求，具体包括：
五大图表类型的精准生成（绘） ——不是“随便画个图”，而是“为你的需求匹配最合适的图表类型与视觉语言”。用户只需在对话中描述系统或指定仓库，Archify即可生成对应的交互式技术地图。项目提供4种视觉预设（含signal-flow信号流、classic经典、editorial编辑出版风格等），支持暗色/亮色双主题一键切换，以及可选的有限动效（animation: "trace"）让图表“活起来”。输出为自包含的HTML单文件，无需任何外部依赖即可在浏览器中打开、交互和分享。
原子化验证与交付质量保障（验） ——不是“画完就交”，而是“验证不通过就不交付”。Archify在交付前强制执行五重原子化检查：schema验证、layout验证、HTML/SVG验证、路由验证和标签到路由的间距验证——全部通过后，制品才替换最后已知的良好输出。失败时返回的不是Node堆栈或模糊的重试猜测，而是稳定的规则代码、精确的受检主体、实测证据以及仅支持的修复控制项。验证信息以机器可读JSON输出，diagnostics[]数组精确定位问题，supportedFixes指明可用的修复手段。项目还提供了standard和showcase两种质量配置文件。
架构变更Delta对比（比） ——不是“改了之后说不清变了什么”，而是“Before/Delta/After三态精确呈现每一次变更”。Archify支持在合并前审查架构变更：比较两个经过验证的快照，以Before / Delta / After三态呈现，精确展示新增、删除、变更、移动和重新路由的事实。命令示例：node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json。对于生产部署评审，Archify可启用deployment-ownership工程配置文件——当缺少负责人、单区域部署、私有数据库作用域或命名边界跨越时关闭（fail closed），验证的是作者声明的事实而非实时基础设施。
来源证据追溯与可信交互（溯） ——不是“AI编造的拓扑”，而是“可追溯到源码的系统地图”。Archify的交互式图表支持语义节点搜索（/快捷键）、上游/下游可达性追溯（聚焦节点后点击Upstream/Downstream）、精确路由探测（R或PATH）、角色对比（L或LENS）和引导式故事导览（P播放有限章节）——所有这些交互都复用作者声明的节点和关系，而非凭空编造拓扑或声称运行时影响。证据回溯的架构节点会标记SRC n，并打开锚定到单个公共提交的Git验证文件和行范围。
一键导出与多格式分享（享） ——不是“只能截图”，而是“专业级的交付物工厂”。Archify的导出菜单支持PNG复制到剪贴板、静态或带动效的SVG/WebM下载。分享卡片（Share Card） 功能可生成1200×630的规范图像，适用于README、发布说明或社交媒体。追溯路由后，路由分享卡下载该作者路径为1200×630 PNG，同时保留完整图表作为上下文。追溯上游/下游可达性后，可达性分享卡捕获该精确读数，不声称运行时影响。
三、Archify适合谁用
Archify的内容设计使其适配各类需要通过系统化的图表工具提升技术沟通效率的开发者、架构师与团队，核心聚焦那些“Mermaid图表太简陋、Draw.io图表太随意、PPT画图太耗时且无法版本控制”，希望从“随手画图”升级为“可验证、可追溯、可分享的专业图表创作”的人群，主要涵盖以下几类：
软件架构师与技术负责人——需要绘制系统架构图、部署拓扑图、数据流图等专业图表，用于技术文档、架构评审或对外分享。Archify的5大图表类型、4种视觉预设和架构变更Delta对比，让架构图从“能看”升级为“经得起评审和版本对比”。
AI编码代理的重度使用者——已经在用Cursor、Claude Code、Codex等AI编码代理进行开发，希望代理能直接生成可交互、可分享的技术图表，而非输出Mermaid代码或文本描述。Archify作为代理技能，让“在聊天中生成图表”成为原生体验。
技术文档工程师与开发者布道师——需要为技术文档、API文档、博客文章或演讲PPT配图。Archify输出的自包含HTML单文件可直接嵌入文档或截图使用，1200×630分享卡片为README和社交媒体提供了规范的配图格式。
平台工程与SRE团队——需要为生产部署评审准备架构图，并确保图表包含负责人、部署区域、数据库作用域和边界跨越等关键信息。Archify的deployment-ownership工程配置文件在信息缺失时关闭（fail closed），让架构图成为可验证的交付物而非“大概画一下”。
希望从“随手画图”升级为“工程化图表创作”的开发者——不满足于用Mermaid或Draw.io画“能看就行”的图表，希望理解“好的技术图表应该是什么样的”。Archify的布局判断优先理念（代理选择层级、间距、路由和强调，而非通用自动布局）、原子化验证流程和类型化JSON IR，本身就是一份浓缩的技术图表工程最佳实践教材。
四、Archify的应用场景是什么
基于其内容设计与定位，Archify的应用场景主要围绕系统架构可视化、架构变更评审、技术文档配图和部署合规审查，覆盖从个人创作到团队协作的多个场景，具体包括：
系统架构可视化与文档配图场景——团队需要为系统设计文档、ADR或技术方案评审准备架构图。Archify提供了一条“在聊天中描述系统或指定仓库→选择图表类型（架构图/工作流图等）→选择视觉预设与主题→生成自包含HTML→导出分享卡片或PNG/SVG”的完整路径。输出的图表既符合技术图表的专业规范，又具备可交互的深度。
架构变更评审与PR审查场景——团队在合并PR之前需要审查架构变化。Archify的Before/Delta/After三态对比让审查者精确看到新增、删除、变更、移动和重新路由的事实。命令node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json生成可分享的Delta报告。这种“变更即制品”的工作流，让架构评审从“口头描述变了什么”升级为“精确展示变了什么”。
生产部署合规审查场景——平台工程团队需要确保每个服务在部署前满足合规要求——有明确的负责人、部署在指定区域、数据库作用域清晰、边界跨越已声明。Archify的deployment-ownership工程配置文件在信息缺失时关闭（fail closed），验证的是作者声明的事实而非实时基础设施。这种“合规即验证”的设计，让架构图从“参考材料”升级为“合规交付物”。
技术演讲与博客配图场景——技术布道者或开发者需要为技术演讲或博客文章配图。Archify输出的自包含HTML可以全屏截图或导出PNG/SVG后嵌入演讲PPT或博客，1200×630分享卡片为社交媒体预告提供了规范的配图格式。有限动效让图表在演示时“活起来”，而prefers-reduced-motion尊重用户的动效偏好。
遗留系统理解与文档化场景——团队需要理解一个缺乏文档的遗留系统的架构。Archify可以“追踪一个代码库或系统描述”，生成交互式系统地图。来源证据追溯功能让架构图中的节点可以打开Git验证的文件和行范围——不是“AI猜的拓扑”，而是“可追溯到源码的系统地图”。
五、Archify为什么值得关注
Archify之所以值得关注，核心在于它将“技术图表创作从依赖零散工具和直觉升级为可验证、可追溯、可分享的工程化技能”，并具备“布局判断优先、原子化验证、架构Delta对比、来源证据追溯、自包含HTML交付”的独特价值，具体体现在以下几点：
从“通用自动布局”到“布局判断优先”的设计哲学。大多数图表工具依赖通用自动布局算法——节点随机排列、箭头堆叠在中点。Archify坚持布局判断优先：代理选择层级、间距、路由和强调；共享自动端点以确定性方式分布，而非将所有箭头堆叠在一个中点上。这种“代理做设计判断、工具做确定性渲染”的分工，让图表从“算法生成的随机排布”升级为“有意图的视觉设计”。
从“画完就交”到“原子化验证”的质量文化。大多数图表工具只负责“生成”，不负责“质量”。Archify在交付前强制执行五重原子化检查——schema、layout、HTML/SVG、route和label-to-route clearance——全部通过后才替换最后已知的良好输出。失败时返回的不是Node堆栈，而是稳定的规则代码、精确的受检主体和仅支持的修复控制项。验证信息以diagnostics[]数组精确定位问题，supportedFixes指明可用的修复手段。这种“画完必审、审完再交、交必有据”的质量文化，在图表生成工具中极为罕见。
从“口头描述变更”到“Before/Delta/After三态对比”的评审革命。架构评审中最常见的问题是“这次PR到底改了架构的哪些部分”——口头描述模糊、代码diff难以直观呈现架构变化。Archify的架构变更Delta对比将两个经过验证的快照以Before/Delta/After三态呈现，精确展示新增、删除、变更、移动和重新路由的事实。这种“变更即可视化制品”的能力，让架构评审从“猜变了什么”升级为“精确看到变了什么”。
从“AI编造的拓扑”到“来源证据追溯”的可信交互。大多数AI生成的图表是“黑盒”——你无法知道图中的节点和关系来自哪里。Archify的交互式图表支持证据回溯：架构节点标记SRC n，打开锚定到单个公共提交的Git验证文件和行范围。聚焦、上游/下游可达性、精确路由、角色对比和故事导览等所有交互都复用作者声明的节点和关系，而非凭空编造拓扑或声称运行时影响。这种“来源可追溯、事实可验证”的设计，让AI生成的图表从“可能编造”升级为“可信交付物”。
从“依赖外部渲染器”到“自包含HTML单文件”的交付自由。Mermaid图表需要特定渲染器，Draw.io图表需要特定编辑器。Archify输出的图表是自包含的HTML单文件——所有SVG、CSS、JavaScript和交互逻辑内联其中。双击即可在浏览器中打开，无需安装任何软件、无需网络、无需特定授权。导出支持PNG、SVG、WebM和1200×630分享卡片。这种“零依赖”的交付方式，让图表从“需要特定环境才能查看”升级为“一个文件，随处打开，永久可读”。
从“单平台专属”到“跨4种编码代理”的覆盖广度。大多数AI图表生成工具只支持一两种平台。Archify支持Cursor、Claude Code、Codex CLI、OpenCode等4种主流AI编码代理，并提供npx skills add一键安装和npx skills use临时试用两种路径。用户无论在哪个平台上工作，都能获得一致的图表生成体验。
开源MIT + 活跃迭代的社区承诺。Archify采用MIT许可证，完全开源免费。项目从Cocoon-AI/architecture-diagram-generator v1.0分叉后，在2.x版本中增加了主题、导出、类型化渲染器、验证、可访问性、交互和统一CLI。截至2026年7月，项目已有122次提交，最新提交为2026年7月27日。项目欢迎Issue、PR和真实世界的图表贡献。
现实挑战与生态成熟度。Archify并非没有短板。首先，项目明确将“自动Mermaid解析、通用自动布局、托管分享和WYSIWYG编辑”排除在当前范围之外——用户需要接受“代理驱动的生成+验证驱动的交付”工作流，而非所见即所得的拖拽编辑。其次，项目目前主要面向技术图表（架构/工作流/时序/数据流/生命周期），对于产品图表、用户旅程图等非技术图表类型的覆盖有限。再次，项目目前主要以英文提供，对非英语用户有一定语言门槛。最后，项目依赖于AI编码代理的推理能力来生成类型化JSON IR——如果代理对系统描述的理解不够准确，输出的图表质量会直接受限。
但恰恰是这些“短板”构成了Archify在AI辅助图表创作开源生态中的独特位置：它不是一份可以“一键生成完美图表”的魔法工具，也不是一个“替代所有绘图工具”的银弹，而是为那些希望用系统化的、可验证的、可追溯的方式创作技术图表、从“随手画图”升级为“工程化图表交付”的架构师、开发者、技术文档工程师和平台工程团队准备的图表创作技能框架。
