在开发者的日常里，"画架构图"可能是最容易被低估的时间黑洞。服务一多，问题就冒出来：Mermaid 的箭头开始打架；draw.io 虽然能控制细节，但每次加个模块、调整链路，都得重新挪方框、理连线；让 AI 直接输出 SVG 或 HTML 确实快，需求一改，已经排好的位置又要重画。

最近一个叫 Archify 的开源项目正是冲着这个痛点来的。它在 GitHub 上走红，截至原作者发稿已获得约 35.7K Star、2.3K Fork，并采用 MIT 协议。

它到底解决了什么问题？

一句话概括：Archify 是一个 Agent Skill，装进 Cursor、Claude Code、Codex CLI 或 OpenCode 里，让 AI 联网读需求、看代码，再接收管后续的结构保存、检查、渲染和交付。它的产出不是一段临时脚本，而是一份独立的、自包含的 HTML 文件——打开就能搜索节点、追踪路径、切换主题，需要时还能导出图片。

你说一句"用 Archify 画出 Browser -> API -> Redis -> PostgreSQL 的缓存回源过程"，Agent 会先理解这段描述，写出一份 Typed JSON IR；Archify 校验这份结构化源文件，再确定性地编译成 HTML 和 SVG。它不提供新模型，也没有拖拽画布，而是把"画图"这件事交给确定性的编译流程。

它是怎么工作的？

整条流程大概是这样的：

让人眼前一亮的地方在于迭代。假设第一版图已经画好，需求又来了：加 Redis、把鉴权移到左边、突出回滚链路。对一次性生成的 SVG 来说，这往往又是一次整图重写；而 Archify 留下了 JSON IR，节点、关系、强调内容都有明确字段，Agent 改 Redis 时只需碰相关对象，不必重排整张图。这份 JSON 还要经过 Schema、布局和输出检查，确认连线没有穿过无关节点、关系标签没压住其他线路，才会产出新的 HTML 和 SVG。

校验失败时，Archify 会返回机器可读的诊断结果，指出具体对象、测量数据和允许的修复方式，Agent 照单调整，比对着 Node.js 堆栈猜原因省事得多。

五种图表类型，按问题选

它把要讲的问题拆成五类：Architecture（系统结构）、Workflow（请求/审批/CI/CD 流程）、Sequence（API 调用链、缓存穿透）、Data Flow（数据管道/ETL）、Lifecycle（状态机/订单生命周期）。

讨论未落地的方案，给一段系统描述就行；画现有项目，就让 Agent 去读仓库中的核心组件、主调用链、外部依赖和系统边界。如果要求附带源码证据，架构节点还能关联到固定 Git Commit 下的文件与行号，读图时可回到代码核对。

和 Mermaid、draw.io 有什么不同？

三者的定位其实是互补的，而非互相替代。Mermaid 靠代码 DSL 渲染，强在通用语法和社区模板，但语法敏感，AI 生成时括号不匹配、布局错位是常事；draw.io 是 WYSIWYG 拖拽，强在精细手工控制和零学习成本，但不适合 AI 批量驱动；Archify 则专为"AI 编程代理"这个场景设计，走自然语言 → JSON → HTML 的路径，天然容错，外加校验和原子发布。

维度	Mermaid / PlantUML	draw.io / Excalidraw	Archify
驱动方式	代码 DSL	鼠标拖拽 GUI	自然语言 + Agent
AI 生成易错率	中（语法敏感）	不适配 AI	低（JSON IR 容错）
输出格式	SVG/PNG	私有格式/SVG	自包含 HTML + PNG/SVG/WebM
迭代方式	全量重写	手工改	精确补丁 + 最后已知好
可交互性	无	有限	节点搜索/路由追踪/故事播放
信任边界	无	无	有（typed schema 强制校验）

上手很简单

如果你已经在用 Codex、Claude Code、Cursor 或 OpenCode，一条命令全局安装即可：

npx skills add tt-a1i/archify -g

只想先体验、不想写入全局 Skill 目录，也可以临时交给 Codex：

npx skills use tt-a1i/archify@archify --agent codex

装好后不用记参数，直接在 Agent 对话里描述想要的图，比如"使用 Archify 画出一张高层运行时架构图，保留 8～12 个核心组件，突出一条主要路径，标出外部依赖与信任边界"。需要自检是否装好，在 Archify 目录运行 node bin/archify.mjs doctor 即可。

实际体验：一个真实仓库的成图

原作者拿开源的《SpringAI 智能面试平台》（2.0 版本，Star 3.1k+）做了测试。这个项目同时有 React 前端、Spring Boot API、语音面试 WebSocket、PostgreSQL、Redis Stream、对象存储和外部 AI 服务，正好能检验 Archify 对真实仓库的处理能力。

要求不算复杂：只保留 8～12 个核心组件，画出主要访问链路、异步任务和数据存储关系。最终生成的图把普通请求、RAG 流式响应、语音面试和异步消费者放在一张图里，底部再用三张说明卡片补充细节。后面作者看实际截图时发现，第一版 Spring Boot 外框把外部 AI Provider 和 PostgreSQL 也圈了进去，容易引起语义误解；去掉外框重新交付后，9 项 Showcase 检查全部通过，0 错误、0 警告。这张图还能直接切换成 Blueprint 风格去评审，节点和连线不用重算。

它也有边界

Archify 值得称道的地方在"出图之后"：继续修改时保留无关结构、交付前执行固定检查、关系可回到 JSON 源文件核对。但它的校验器检查的是格式、几何和已写入的关系，代码分析有没有漏掉组件或调用链，它无法证明——涉及真实项目时，仍需要熟悉系统的人做最终确认。

放在更长的时间线上看，这类"架构图跟着代码持续演进"的工具有一个很自然的判断：优秀的技术项目正在走向"文档完全自治"，也就是代码变动时由 CI/CD 自动运行逆向分析、生成最新架构图。不过 Archify 也面临一些开放问题——比如大单体仓库（1000+ 文件）里模型识别准确率会下滑，JSON 里的节点命名来自模型理解而非人类共识，以及跨仓库微服务架构的合成，都还是未完全解决的领域。

一句话建议

临时画一张简单流程图，Mermaid 最省事；需要盯着画布逐个调元素，draw.io 更顺手。而 Archify 适合另一种活：让 Coding Agent 根据系统描述或代码仓库起图，后面还要反复改、查关系，甚至对比一次 PR 前后的架构变化。它留 JSON 源文件，交付前跑固定校验，最后给一个能独立打开的 HTML——省下来的，主要是反复改图、重新排图和核对关系的时间。

项目地址：https://github.com/tt-a1i/archify