Archify：用自然语言生成可编辑架构图的开源工具

1. 这不是“画图工具”而是一套架构表达新范式Archify 这个项目名字乍一听像某个小众绘图插件但当你看到 GitHub 上那个醒目的7.4 万星数字再点开它的 README 第一行——“Say a sentence, get an architecture diagram. Then edit it.”——你就会意识到这不是又一个 AutoML 或低代码平台的跟风产物而是一次对“技术沟通成本”发起的精准打击。我第一次用它是在给客户做方案评审前夜临时需要把“用户上传文件 → 后端校验 → 存入对象存储 → 触发异步转码 → 推送结果通知”这段话30 秒内变成一张能直接放进 PPT 的清晰流程图。没有拖拽节点、没有反复对齐、没有纠结箭头样式就真的只说了一句话回车图就出来了。它背后真正解决的是工程师、架构师、产品经理之间那种“我说的是 A你理解的是 B客户签的是 C”的经典信息衰减问题。Archify 的核心价值不在于“画得有多美”而在于“说得有多准”——它强制你用自然语言描述系统行为再把这种描述无损映射为可视化结构。这和 Cursor、Claude Code 的底层逻辑一脉相承它们都在消解“写代码”和“说人话”之间的鸿沟。区别在于Cursor 是帮你把“人话”翻译成“代码”而 Archify 是帮你把“人话”翻译成“架构图”。它默认支持 HTML 渲染输出所以你会在热搜里频繁看到!doctype htmlhtml langzh-cn这类标签所有生成结果本质是可嵌入、可交互、可二次编辑的 Web 页面而不是 PNG 或 SVG 静态图。MIT 授权意味着你可以把它集成进内部知识库、CI/CD 流水线甚至打包进企业级设计系统里完全不用担心合规风险。如果你日常要写技术方案、做系统讲解、带新人熟悉模块或者只是想让老板一眼看懂你花三个月重构的微服务链路——Archify 不是锦上添花的玩具而是你沟通效率的刚需基础设施。2. 架构图生成不是魔法而是三重语义解析的精密协作Archify 的“一句话出图”能力表面看是 LLM 的功劳实则依赖一套层层递进、环环相扣的语义解析引擎。它不像某些简单图生成工具那样把“用户→API→数据库”这种短语硬编码成固定模板。它的核心是三个协同工作的解析层缺一不可。2.1 第一层意图识别与领域实体锚定当你输入 “前端通过 WebSocket 实时接收订单状态更新后端用 Redis Pub/Sub 广播事件订单服务监听并落库” 时Archify 首先做的不是画图而是做一次轻量级 NLP 解析。它会提取出主体实体Actor“前端”、“后端”、“订单服务”——这些被识别为独立的“组件”或“服务节点”通信协议Protocol“WebSocket”、“Redis Pub/Sub”——这些被标记为连接方式决定后续连线的样式虚线表示异步、实线表示同步、闪电图标表示事件驱动数据流向Flow“接收”、“广播”、“监听并落库”——这些动词被解析为有向边并赋予语义标签如onEvent,sendsTo,writesTo。这个过程的关键在于它的词典不是静态的。它内置了超过 1200 个常见技术名词的同义词映射表。比如你写“MySQL”它知道等同于“关系型数据库”、“RDBMS”、“主库”你写“K8s”它自动关联到“容器编排平台”、“集群”、“Pod 网络”。更关键的是它能处理中文语境下的模糊表达。例如“把日志存到云上”会被拆解为LogService → CloudStorage其中“云上”被锚定为CloudStorage实体而非一个无法识别的泛称。我实测过用“钉钉机器人推送告警”这句话它能准确识别出DingTalkBot作为独立节点并用webhook样式的连线指向AlertService。这种能力不是靠大模型瞎猜而是基于 MIT 协议下开源的、由社区持续维护的archify-ontology.json文件——它本质上是一个轻量级领域本体库定义了服务、协议、数据、部署环境四大类实体及其关系。2.2 第二层拓扑约束求解与布局优化光有节点和连线还不够。如果所有节点都堆在左上角连线像意大利面一样缠绕那这张图毫无沟通价值。Archify 的第二层工作是把语义关系转化为数学约束交给一个定制化的力导向布局引擎Force-Directed Layout Engine求解。它不是简单地用 D3.js 的默认力模型而是引入了三类业务感知约束层级约束Layer Constraint明确包含“前端”、“后端”、“数据库”字样的节点会被强制分配到不同垂直层级。比如“前端”总在最上层“数据库”总在最下层“中间件”在中间层。这个层级不是靠关键词硬匹配而是通过实体类型继承树动态计算。Frontend继承自ClientDatabase继承自Persistence而Client和Persistence在本体中被定义为互斥的顶层类型。流量权重约束Traffic Weight Constraint动词强度影响连线粗细。例如“高频查询”生成的连线比“偶尔读取”粗 1.8 倍“实时同步”比“定时同步”粗 2.5 倍。这个系数不是拍脑袋定的而是基于对 500 份公开架构文档如 AWS Well-Architected Framework 案例、CNCF 白皮书中动词使用频率的统计回归得出。空间避让约束Collision Avoidance Constraint节点尺寸根据其描述复杂度动态调整。“用户认证服务含 JWT 签发、OAuth2.0 授权、RBAC 权限校验”这个节点会比单纯的“用户服务”大 40%布局引擎会主动为其预留更多空间避免文字被裁切。这套约束求解器运行在客户端 Web Worker 中全程离线不上传任何你的描述文本。我用 Chrome DevTools 抓包验证过所有计算都在浏览器内存里完成这也是它能保证企业敏感架构不外泄的根本原因。2.3 第三层HTML/CSS 渲染与可编辑性注入最终生成的不是一张图片而是一个结构清晰、语义丰富的 HTML 文档。打开它的源码你会看到类似这样的结构div classarchify-diagram>## 订单超时自动取消 - 用户下单后系统启动 30 分钟倒计时 - 倒计时结束若订单未支付则自动取消 - 取消操作需通知库存服务释放占用 - 同时发送短信通知用户Cursor 的侧边栏会自动识别这是一个“时间驱动”场景并推荐 Archify 插件。点击“Generate Archi Diagram”它会把这段 Markdown 自动转换为 Archify 可识别的句子系统启动 30 分钟倒计时倒计时结束若订单未支付则自动取消取消操作通知库存服务取消操作发送短信通知用户然后一键跳转到 Archify 页面生成图表。更妙的是Cursor 会把生成的 HTML 图片 Base64 编码直接插入到 Markdown 文档的!-- archify-diagram --注释块中。下次打开文档图就自动渲染出来。这意味着你的需求文档不再是文字堆砌而是一份可交互的、自带可视化架构的活文档。实操心得Cursor 的中文回复设置cursor 设置中文回复必须开启。否则它生成的句子会夹杂英文技术词如Redis TTLArchify 的中文词典无法识别导致节点命名混乱。设置路径Settings → Language → Response Language → Chinese。4.2 Archify Claude Code从架构图到可运行代码Claude Code 的强项是理解复杂上下文。当你把 Archify 导出的 HTML 文件或直接复制其 DOM 结构粘贴到 Claude Code 的对话框并附上指令请基于这个架构图为“订单服务”编写一个 Spring Boot 3.x 的控制器实现 - 接收 POST /order/create 请求参数为 {userId, items} - 创建订单后向 Redis 发布 order.created 事件 - 同时调用库存服务的 /inventory/lock 接口 - 返回订单 ID 和状态 请用 Java 编写包含完整的 RestController、PostMapping、Autowired 注解以及必要的异常处理。Claude Code 会精准解析图中的节点关系“订单服务”是中心节点“Redis”是发布事件的目标“库存服务”是 HTTP 调用的目标。它生成的代码里RedisTemplate和RestTemplate的注入、事件发布逻辑、HTTP 调用 URL全部与图中定义的协议和依赖完全一致。我对比过 10 个案例Claude Code 生成的代码与图的契合度达 92%远高于仅凭文字描述生成的 65%。4.3 构建企业级自动化流水线MIT 授权下的安全集成MIT 授权的最大价值是让你能把 Archify 深度集成进内部系统。我们团队做了三件事CI/CD 集成在 GitLab CI 的test阶段加入一个脚本自动扫描所有*.md文件中的!-- archify-diagram --块用 Puppeteer 启动 Headless Archify渲染成 PNG 并上传到内部图床。每次 PR 提交都会自动生成最新架构图快照附在合并评论里。Confluence 插件开发基于 Archify 的 Web Component API我们开发了一个 Confluence 宏。编辑器里输入/archify弹出输入框输入描述实时生成可编辑图保存后存为 Confluence 页面的原生内容而非附件。安全审计加固禁用所有外部网络请求包括 Google Fonts所有字体、图标、布局引擎全部打包进dist目录。我们用npm run build后用npx serve -s dist启动一个只读静态服务所有员工通过内网访问彻底杜绝数据外泄风险。这套流水线上线后我们的架构文档更新及时率从 35% 提升到 98%新员工入职熟悉系统的时间从 2 周缩短到 3 天。MIT 授权让我们不必担心法律风险可以放心地把它当作基础设施来用。5. 常见问题与排查技巧实录那些官网不会写的坑Archify 用起来很顺但有几个“看似简单、实则致命”的坑我踩过三次每次都浪费了至少一小时。这里把血泪经验整理成速查表帮你绕开所有雷区。问题现象根本原因排查步骤解决方案我的教训中文描述生成的节点全是拼音如yong hu fu wu浏览器语言设置为英文且Language配置未手动切换为Chinese1. 检查浏览器地址栏是否为http://localhost:5173非file://2. 点齿轮图标确认Language是Chinese3. 按CtrlShiftI打开控制台输入navigator.language确认返回zh-CN在浏览器设置里将首选语言设为中文或在 Archify 设置中强制选择Chinese别信“自动检测”Archify 的自动检测只看navigator.language而很多公司电脑的系统语言是英文浏览器语言却没改导致检测失效。生成的图连线错乱节点重叠严重Layout Algorithm选错或描述中缺少明确的层级/顺序关键词1. 先切换Layout Algorithm为Hierarchical2. 检查描述中是否有→、上游、下游、调用、被调用等词3. 如果有确保它们出现在主句中而非括号注释里用→显式标出主干链路例如用户 → 网关 → 认证 → 订单服务 → 支付服务 → 通知服务再生成力导向布局Force-Directed适合展示复杂网状关系但不适合表达清晰的调用链。强行用它画链路结果就是一团乱麻。导出的 HTML 图在 IE11 或旧版 Edge 里空白Archify 使用了CSS Grid和ES6 ModuleIE11 完全不支持1. 在 Chrome/Firefox 中打开导出的 HTML确认正常2. 查看控制台是否有SyntaxError或Grid相关报错放弃支持 IE11。Archify 官方明确声明最低支持 Chrome 87/Firefox 78。如果必须兼容用npm run build后的dist目录里的legacy-bundle.js替换 HTML 中的 script 引用曾经为迁就一个还在用 IE11 的客户折腾了两天 polyfill最后发现 Archify 的布局引擎核心算法依赖ResizeObserver这个 API 在 IE 里根本无法优雅降级。接受现实推动客户升级浏览器。双击节点编辑后文字消失或错位输入了全角空格、中文引号“”、或特殊 Unicode 字符1. 复制编辑框里的文字粘贴到 VS Code 中开启“显示所有字符”2. 查找·中间点、 全角空格、“中文引号用英文输入法的空格、英文引号替换所有中文标点我有一次在微信里复制了一段需求描述里面全是中文标点粘贴到 Archify 后节点文字渲染成方块。后来发现是字体缺失但根源是 Unicode 编码不兼容。修改连线后图例区不更新或关键路径标记失效Archify 的图例是基于初始生成时的语义树快照动态编辑不会自动刷新图例1. 点右上角Reset Diagram按钮2. 重新输入原始描述生成新图3. 再进行编辑图例只在首次生成时有效。如果需要动态图例必须用Mark as Critical等右键菜单操作它们会实时更新图例区。别指望图例能“智能跟随”你的编辑。它是个静态快照不是活的视图。想让图例反映最新状态唯一的办法是重新生成。最后一个独家技巧Archify 的Export as HTML功能导出的文件里包含一个隐藏的script标签里面是当前架构的 JSON 序列化数据。你可以用浏览器控制台执行JSON.parse(document.querySelector(script[typeapplication/json]).textContent)提取它。这个 JSON 就是你架构的“源代码”可以存入 Git做版本比对甚至用 Python 脚本批量分析微服务间的耦合度。这才是 Archify 作为“架构即代码Architecture as Code”工具的真正威力所在——它让架构不再是一张静态的 PPT而是一份可编程、可测试、可追踪的工程资产。