之前在业务迭代中维护微服务架构图时反复踩到同一个坑图更新不及时AI 画图又快但没人敢直接信任评审时每一条连线都说不清来源。后来关注到 Archify 这个开源项目它在 GitHub 上已经积累了 3.5 万 Star核心思路是把“AI 画架构图”这件事从单纯的绘图升级成“可验证、可追溯路径的架构建模”。这篇文章会围绕 Archify 展开讲清楚它的核心概念、安装使用、完整实战、如何在 Trae 这类 AI 编程 IDE 里以 Skill 方式集成以及常见问题与工程化建议。1. Archify 到底是什么AI 画架构图为什么需要“可验证、可追溯”1.1 一句话理解 ArchifyArchify 可以理解为 Architecture Verify也就是“架构 验证”。它不是简单地把一段文字转换成图片而是先把你对系统的描述解析成结构化的组件、连接、依赖关系再基于这些关系生成架构图。更重要的是它会输出一份验证报告告诉你这张架构图里是否存在循环依赖、协议不一致、服务直连数据库等架构问题。在我个人理解里Archify 更像是“能解释自己的架构图工具”。普通的 AI 画图工具给的是结果Archify 给的是“结果 依据 检查记录”。这也是它能在开源社区迅速获得关注的核心原因架构评审最怕的不是图丑而是图不可信。1.2 传统架构图和 AI 架构图的痛点传统的手工架构图维护成本很高。项目一迭代模块拆分、服务调用关系、数据库归属都会跟着变但文档里的图经常停留在三个月前。很多时候团队宁可去翻代码也不愿意相信那张架构图。而直接让 AI 生成架构图虽然速度快又带来三个新问题结果不可验证AI 是根据你的描述“猜”出来的结构没人知道它有没有理解错。来源不可追溯图上的一条连线到底来自哪段描述、哪条需求、哪次对话你无法定位。难以复用生成的是一张静态图片无法继续做规则校验、依赖分析、变更对比。如果在小型项目中这些问题还能忍。一旦到了微服务架构或者中大型系统架构图就不再是“一张图”而是团队沟通、评审、审计的公共语言。这时候Archify 这种“可验证、可追溯路径”的架构图工具就很有价值。1.3 Archify 的核心设计验证与追溯Archify 的工作流程可以概括成三条输入建模接受自然语言、Markdown 或 YAML 架构描述统一解析成内部模型。规则验证根据内置或自定义规则检查组件和连接是否合法。路径追踪生成架构图的同时保留每个节点和连线对应的来源信息形成可查询的追踪映射。用大白话说Archify 不只是帮你把架构图画出来它还会告诉你这张图是怎么来的里面有哪些问题是需要修改的每条连接能不能从图反查回描述文件。2. 用 Archify 前先把架构图这件事拆清楚2.1 架构图的常见分类架构图并不是只有一种很多初学者容易混为一谈。按使用场景不同常见的架构图类型包括类型主要描述内容常见使用场景业务架构图业务流程、组织角色、业务模块产品评审、业务规划系统架构图子系统、模块、接口关系技术方案设计微服务架构图服务拆分、调用链、数据存储微服务治理部署架构图服务器、网络、容器、中间件运维部署方案数据流图数据流转、存储、处理节点数据架构设计组织架构图部门、岗位、汇报关系人力组织展示Archify 更适合处理以“组件 连接关系”为核心的架构描述比如系统架构图、微服务架构图、部署架构图。你用文字描述系统里有哪些服务、哪些数据库、它们之间怎么调用Archify 就能生成对应的可视化结果。2.2 哪些场景适合用 AI Archify适合用 AI Archify 的场景有这几种新项目初始化产品需求还在讨论阶段团队需要快速产出第一版系统架构图。已有系统梳理系统代码很多想通过结构化描述重新整理服务依赖。架构评审评审前生成验证报告把架构约束放到规则里自动检查。文档编写输出 HTML、SVG 或图片格式的架构图直接嵌入技术方案。课程教学需要清晰讲解软件架构图、微服务架构图的生成过程。反过来如果你的架构描述本身就很含糊或者你希望工具直接从代码仓库自动逆向出完整架构那单纯靠 Archify 还不够需要搭配其他代码分析工具一起用。2.3 Archify 的输入与输出Archify 的输入可以是自然语言描述用一段话描述系统有哪些组件和调用关系。Markdown 文档按照指定格式编写架构说明。YAML/JSON 描述文件结构化定义组件、连接、分组、规则。输出一般包括架构图文件PNG、SVG、HTML 等格式。架构模型文件JSON 或 YAML保存组件、连接和属性。验证报告Markdown 或 JSON列出架构违规项。追溯映射节点 ID、连线 ID 对应的来源文件、行号或生成依据。这里建议优先使用结构化描述文件因为自然语言在复杂场景下容易产生歧义。3. 环境准备与快速上手指南3.1 环境要求不同版本的 Archify 安装方式有所不同以下示例以常见 CLI 工具的使用习惯为准具体命令请以你安装版本提供的帮助文档为准。需要的环境大致如下Node.js 18 或 Python 3.9取决于你选择的安装包。支持 SVG/HTML 展示的浏览器用于查看生成的架构图。一个代码编辑器建议使用 VS Code 或 Trae 这类支持 AI 插件的 IDE。示例项目结构按 Archify 初始化模板生成。这里不写死具体版本号因为开源工具版本迭代比较快你本地环境需要根据项目实际情况调整。3.2 安装与初始化假设你使用 npm 方式安装常见命令示例如下# 使用 npm 安装 Archify CLI示例命令 npm install -g archify/cli # 查看版本 archify --version # 在空目录中初始化架构项目 mkdir demo-arch cd demo-arch archify init执行 init 之后项目目录大概会生成这样的结构demo-arch/ ├── archify.yaml # 项目配置 ├── architecture.md # 架构描述文档 └── rules.yaml # 验证规则如果你使用的不是 npm 方式也可以通过官方提供的二进制包或容器镜像运行核心命令逻辑类似。3.3 最小示例从一句话到一张架构图先来看一个最简单的例子。在architecture.md中编写架构描述# 演示系统架构 用户通过浏览器访问网关网关把请求转发到订单服务和用户服务。 订单服务使用订单数据库保存数据用户服务使用用户数据库保存数据。然后运行生成命令# 示例命令具体参数以实际帮助为准 archify generate -i architecture.md -o output/预期会在output/目录下得到architecture.svg可视化架构图。architecture.json结构化模型数据。validation-report.md验证报告。Archify 会先从自然语言中抽取“用户、浏览器、网关、订单服务、用户服务、订单数据库、用户数据库”这些组件再识别出访问、转发、使用等关系最后生成架构图和验证结果。3.4 常用配置项说明下面是一份archify.yaml的示例配置project: name: demo-arch defaultView: system output: format: [svg, html, json] directory: output/ validation: rulesFile: rules.yaml failOnViolation: true render: layout: dagre theme: light配置说明project.name项目名称会显示在架构图标题位置。output.format输出格式可以同时输出多种格式。output.directory生成文件保存目录。validation.rulesFile指定验证规则文件路径。validation.failOnViolation如果验证不通过是否让命令返回失败状态。render.layout图的布局算法常见有 dagre、layered、grid 等。render.theme主题样式light 适合文档dark 适合演示。这些配置项的具体名称在不同版本中可能有变化但整体思路是一致的把项目信息、输出方式、校验策略和渲染参数分开管理。4. 完整实战微服务架构图生成与验证4.1 场景描述现在我们来做一个更完整的实战。假设要为一个电商系统生成微服务架构图系统核心组件包括前端应用API 网关用户服务订单服务商品服务消息队列用户数据库订单数据库商品数据库要求是前端只通过 HTTPS 访问网关网关负责路由各服务之间通过 HTTP 调用服务通过数据库连接访问自己的数据库不允许服务直连别人的数据库。4.2 编写架构描述文件推荐使用 YAML 描述文件字段语义更清晰。文件路径可以放在project/architecture.yamlproject: mall-system version: 1.0.0 components: - id: web name: 前端应用 type: frontend - id: gateway name: API网关 type: service - id: user-service name: 用户服务 type: service - id: order-service name: 订单服务 type: service - id: product-service name: 商品服务 type: service - id: user-db name: 用户数据库 type: database technology: MySQL - id: order-db name: 订单数据库 type: database technology: MySQL - id: product-db name: 商品数据库 type: database technology: MySQL - id: mq name: 订单消息队列 type: middleware technology: Kafka connections: - from: web to: gateway protocol: HTTPS - from: gateway to: user-service protocol: HTTP - from: gateway to: order-service protocol: HTTP - from: gateway to: product-service protocol: HTTP - from: order-service to: user-service protocol: HTTP - from: order-service to: mq protocol: KafkaProducer - from: order-service to: order-db protocol: JDBC - from: user-service to: user-db protocol: JDBC - from: product-service to: product-db protocol: JDBC这段描述的核心是组件定义和连接定义分离。先列出所有组件再说明组件间如何连接这样后续验证和追溯都方便。4.3 编写验证规则在project/rules.yaml中定义架构约束rules: - name: 服务禁止直连数据库 type: connection from: service to: database action: forbid message: 微服务不应直连数据库需要走数据访问层或独立存储服务。 - name: 前端只能访问网关 type: connection from: frontend to: service action: allow unless: to: gateway message: 前端应用只能访问API网关。 - name: 禁止循环依赖 type: dependency direction: bidirectional forbid: true message: 服务之间不能形成循环调用。这些规则看起来很朴素但实际落地时特别有用。比如“服务禁止直连数据库”可以把很多不规范的设计在生成架构图阶段就拦下来。注意这里的规则语法是示例思路具体结构要根据你使用的 Archify 版本语法调整。4.4 生成架构图与验证进入项目目录后执行# 生成架构图 archify generate -i architecture.yaml -o output/ # 执行架构验证 archify validate -i architecture.yaml -r rules.yaml如果架构描述符合规则命令会返回成功并输出类似下面的提示[Archify] 架构验证通过 检查节点9 检查连接10 违规项0如果违规验证报告会列出具体问题[Archify] 发现 1 个架构违规项 - 违规规则服务禁止直连数据库 - 涉及组件user-service - user-db - 连接协议JDBC这时你需要返回architecture.yaml把服务直连数据库的方式改为通过数据访问层或存储服务暴露接口。修改后重新运行验证。4.5 追溯架构变更来源架构图生成后如果想快速定位某个组件或连接来自哪里可以使用 trace 命令# 示例命令追溯某个组件的来源 archify trace -i architecture.yaml --component order-service预期输出类似order-service - 定义位置: architecture.yaml#L21 - 组件类型: service - 下游依赖: user-service, mq, order-db - 被依赖: gateway - 来源依据: 会话记录 2025-03-12 10:24为什么要做追溯因为架构图在评审阶段最大的问题就是“说不清来源”。可追溯路径能让你快速判断这条连接是需求里明确提出的还是 AI 自动脑补出来的或者是人工后期加的。这非常有利于团队协作。4.6 导出成 HTML 展示有些团队喜欢把架构图放到内网文档里随时查看。Archify 的常见用法是把图导出为 HTML 格式生成一个可缩放、可点击节点的网页文件archify generate -i architecture.yaml -o output/ -f html输出output/architecture.html后用浏览器打开就能查看。HTML 格式还有一个好处它可以直接嵌入到企业 Wiki 或文档系统里团队成员不用安装额外的架构图软件。5. 在 Trae / AI 编程 IDE 里使用 Archify Skill5.1 为什么需要 Skill很多开发者关心“Archify 怎么用在 Trae 这类 AI 编程 IDE 里”。其实核心思路是把 Archify 封装成一个 AI Agent 可调用的 Skill让 AI 助手在收到“帮我生成架构图”这类指令时自动完成架构描述读取、命令执行、验证报告解读等步骤。这样做的好处很明显不需要手动敲命令行。AI 可以结合当前项目的文件内容理解架构。生成失败时AI 能根据报错自动修正描述文件。5.2 Skill 的工作原理Archify Skill 本质上是给 AI 助手提供的一份结构化使用说明书内容包括使用场景。执行步骤。输入输出要求。常见注意事项。AI 编程 IDE 会在合适的时机加载这个 Skill根据里面的步骤调用外部命令。不同 IDE 的 Skill 机制不一定相同下面示例用于说明配置思路实际路径以你使用的产品和插件规范为准。5.3 配置示例假设你的 Trae 工程支持自定义 Skill可以将 Archify Skill 放在项目目录下的.trae/skills/archify-skill/SKILL.md# Archify Skill ## 目标 当用户需要生成、验证或查看系统架构图时使用 Archify 完成。 ## 使用步骤 1. 读取项目根目录的 architecture.yaml 或 architecture.md。 2. 如果存在架构变更先更新架构描述文件。 3. 运行命令生成架构图 archify generate -i architecture.yaml -o output/ 4. 运行验证命令 archify validate -i architecture.yaml -r rules.yaml 5. 如果验证失败阅读 output/ 下生成的验证报告并向用户解释违规原因。 6. 将架构图路径和验证结论返回给用户。 ## 注意事项 - 不要直接编辑 output/ 目录下自动生成的文件。 - 用户在描述架构时不够具体先列出假设让用户确认。 - 如果项目里已有名为 architecture.yaml 的文件以该文件为准。配置好之后在 Trae 里打开项目输入帮我用 Archify 生成当前系统的微服务架构图并检查是否存在架构违规。AI 会按照 Skill 里定义的步骤执行先找架构描述文件再运行生成命令然后处理验证结果。5.4 常见体验流程一次完成的体验大致是AI 读取architecture.yaml。AI 调用archify generate生成架构图。AI 调用archify validate检查违规项。AI 展示output/architecture.html给用户。如果验证不通过AI 会把违规项列出来并建议修改方式。这一个流程把“Archify AI Agent IDE”串起来了很适合团队内部把架构图维护固化到日常开发流程中。6. 常见问题与排查思路6.1 常见报错表问题现象常见原因解决思路生成结果为空描述文档中没有可识别的组件与连接检查是否使用了“谁连接谁”的明确句式或改用 YAML 描述验证失败提示循环依赖两个服务互相调用拆出异步消息或把其中一方改为依赖抽象接口图布局混乱组件很多但没有分组在 YAML 中使用 namespace/group 把服务按域分组Archify 命令找不到安装目录未加入 PATH重新安装或使用 npx archify 调用图与代码不一致架构描述文件长期未更新把架构描述纳入 Code Review设置定时检查和提醒AI 在 IDE 中不执行 SkillSkill 路径未被识别检查 IDE 文档中的 Skill 目录规范和命名约定HTML 架构图无法打开输出路径包含中文字符或特殊符号改用纯英文目录名6.2 生成图不像预期怎么办很多人第一次用会直接说“帮我画一下系统架构图”结果生成出来的内容比较泛。更好的做法是把架构图类型说清楚比如“画一张微服务架构图”或“画一张业务架构图”。如果想要的是一张 HTML 组织架构图也需要在描述中明确“展示部门、岗位和汇报关系”。如果仍然不理想建议分步骤来先让 Archify 输出组件清单。再让 Archify 输出连接关系。确认无误后再生成视图。这样处理能得到更稳定的结果。6.3 如何避免 AI 生成的架构图失真Archify 本身不会自动读代码它依赖你提供的架构描述。所以避免失真的关键有两条提供充分上下文包括接口文档、服务部署清单、数据库归属表等。让 AI 先生成中间产物先列出组件和连接再生成架构图。另外架构描述文件应该尽量结构化减少自由发挥空间。自然语言适合做第一版原型YAML 适合做长期维护版本。7. 最佳实践与工程建议7.1 使用结构化 DSL 描述架构优先使用 YAML 或 JSON 描述架构而不是长期依赖自然语言。组件、连接、属性分离能让 Archify 更加准确地建模也方便 Git 做 diff 审查。推荐做法是components: - id: service-a name: 服务A type: service connections: - from: service-a to: service-b protocol: HTTP这种结构即使以后切换到其他架构图工具迁移成本也很低。7.2 让验证规则先于生成存在建议在生成第一版架构图之前先定义好团队认可的架构约束。比如禁止服务直连数据库。禁止跨域依赖。禁止循环依赖。禁止未知协议。验证规则前置可以减少后期人工评审成本。7.3 记录生成路径和来源团队协作中架构图最怕的是“这张图是谁生成的、为什么这么画”。建议启用 Archify 的追溯功能并把追溯映射文件提交到 Git 仓库。这样每一条连接都能找到来源评审效率会高很多。7.4 与 CI/CD 集成架构验证不应该只停留在本地。更推荐把它接入 CI 流程在合并代码前自动检查。示例流水线如下name: arch-check on: [pull_request] jobs: arch: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: 安装 Archify run: npm install -g archify/cli - name: 生成架构图 run: archify generate -i architecture.yaml -o output/ - name: 验证架构约束 run: archify validate -i architecture.yaml -r rules.yaml这里需要注意流水线只是示例思路具体命令和触发条件要根据你使用的 CI 平台和 Archify 版本调整。架构违规时让流水线失败是一种很有效的工程约束。7.5 架构图资产化架构图应该被当作代码资产来维护而不是一个孤立的图片文件。建议把架构描述、验证规则、追溯映射都纳入版本管理。架构图从“图片”变成“数据”团队才能基于它做自动化分析、变更对比和影响面评估。8. 总结与实践建议Archify 的价值不在于画图本身而在于把架构图的生成过程变成可验证、可追溯路径的工程实践。如果你正在做微服务架构治理或架构文档固化建议先从一份简单的 YAML 架构描述开始让 Archify 生成第一版架构图再逐步补充验证规则最后接入 CI 流程。如果你刚开始接触 Archify 和 AI 编程也不用急着把所有规则配置好。先把当前系统的组件和连接梳理出来生成一张可以展示的架构图再慢慢完善验证环节。等团队习惯了这套流程架构评审会从“看图说话”变成“规则校验 来源追溯”效率会有比较明显的提升。