1. 这不是又一个“画图工具”，而是架构设计流程的断点重置

我第一次看到 archify 的 README 时，下意识点开了它的 demo 页面——不是 GitHub 仓库首页，而是直接跳转到一个纯 HTML 文件。页面加载完，我盯着那个自动生成的、带交互节点的微服务架构图看了足足两分钟：服务框能点击展开依赖细节，箭头悬停显示调用协议，右侧侧边栏实时同步当前选中组件的配置片段，甚至还能一键导出为 PlantUML 文本。那一刻我意识到，它根本没在解决“怎么画得更漂亮”这个老问题，而是在问：“为什么我们还要手动拖拽连线？为什么每次服务变更都要重绘整张图？为什么架构图永远比代码慢半拍？”

archify 的核心定位非常锋利：它不生成静态图片，而是生成可执行、可验证、可演进的架构描述载体。关键词里没有“Visio”“draw.io”“Lucidchart”，只有AI代理和HTML——这已经说明了一切。它把架构图从文档附件，变成了系统的一部分：一个用标准 HTML 构建、由 AI 代理驱动、嵌入开发流程的活体文档。你不需要安装任何客户端，不需要学习 DSL 语法，甚至不需要离开终端——只要你的服务定义（YAML/JSON/TOML）存在，archify 就能把它编译成一个可交互的 Web 页面。这不是“辅助工具”，这是把架构描述语言（ADL）直接落地为浏览器可运行实例的一次实践。它解决的不是“画图难”，而是“架构与代码脱节”这个根深蒂固的工程顽疾。对后端工程师来说，这意味着每次提交 service-config.yaml 后，CI 流水线自动产出最新架构图并推送到内部 Wiki；对 SRE 团队而言，意味着故障排查时直接点击告警服务名，就能看到它依赖的下游链路和当前健康状态；对新入职同学，意味着打开这个 HTML 页面，5 分钟内就能理解整个系统的通信骨架。它把“看图说话”的被动阅读，变成了“点图查证”的主动探索。

2. AI 代理如何“读懂”你的架构？解剖 archify 的三层解析引擎

很多人第一反应是：“AI 怎么可能理解我的微服务架构？”——这恰恰是 archify 最值得拆解的地方。它根本没用大语言模型去“理解语义”，而是构建了一套轻量、确定、可追溯的三层解析引擎。整个过程不依赖云端 API，全部在本地完成，这也是它能在 CI/CD 中稳定运行的关键。

2.1 第一层：结构化配置的标准化摄取（Ingestion Layer）

archify 不接受模糊的自然语言描述，它只认三类明确的输入源：

• OpenAPI/Swagger 规范文件（.json或.yaml）：自动提取servers、paths、components/schemas，识别服务端点、请求/响应结构、认证方式；
• Kubernetes Helm Chart values.yaml：解析replicaCount、image.repository、service.type、ingress.hosts等字段，映射出服务部署拓扑与网络暴露策略；
• 自定义 YAML 描述文件（archify.yaml）：提供最小化 Schema，仅需定义services列表，每个 service 包含name、type（api/db/cache/queue）、depends_on（服务名数组）、exposes（端口+协议）。例如：

services: - name: user-service type: api depends_on: [auth-db, notification-queue] exposes: [{port: 8080, protocol: http}] - name: auth-db type: db depends_on: [] exposes: [{port: 5432, protocol: postgres}]

提示：这一层的设计哲学是“拒绝猜测”。archify 明确要求输入必须结构化，因为真正的架构一致性来源于代码和配置，而非工程师的记忆或会议纪要。它把“谁该连谁”这个决策权，交还给版本控制里的 YAML 文件。

2.2 第二层：拓扑关系的确定性推理（Inference Layer）

拿到结构化数据后，archify 并不调用 LLM 做“推理”，而是执行一套硬编码的规则引擎：

1. 服务类型映射：根据type字段，自动分配图标（数据库用圆柱体、API 用立方体、消息队列用双箭头圆环）和默认颜色（蓝色系 API、绿色系 DB、橙色系 Queue）；
2. 依赖关系展开：对每个depends_on条目，递归查找目标服务是否存在；若不存在，标记为external（外部依赖），用虚线框+云朵图标表示；
3. 通信协议推断：若exposes中协议为http/https，则连线标注HTTP/1.1；若为postgres/mysql，则标注SQL；若为kafka/rabbitmq，则标注AMQP或Kafka Protocol；
4. 层级自动分组：基于依赖深度（user-service→auth-db深度为 1，auth-db→vault深度为 2），将服务自动分层，避免交叉连线。算法采用 BFS 遍历，确保前端服务总在上层，数据存储总在底层。

这个过程完全 deterministic（确定性）。同一份 YAML 输入，无论在哪台机器上运行，生成的拓扑结构绝对一致。它不“创造”关系，只“显影”关系——把隐含在配置中的连接逻辑，用可视化方式忠实还原。

2.3 第三层：HTML 交互层的声明式绑定（Rendering Layer）

最终输出不是一个 PNG，而是一个单页 HTML 文件（index.html），其核心是三部分：

• <archify-diagram>自定义元素：基于 Web Components 标准封装，内部使用 SVG 渲染节点与连线，所有交互事件（click/hover）均在此元素内处理；
• <archify-sidebar>侧边栏：通过># 检查 Node 版本（必须 >=18.0.0） node --version # 创建项目目录 mkdir order-arch && cd order-arch # 初始化最小化配置文件（注意：不是 package.json！） cat > archify.yaml << 'EOF' services: - name: order-api type: api depends_on: [payment-gateway, inventory-service, redis-cache, postgres-db] exposes: [{port: 3000, protocol: http}] - name: payment-gateway type: api depends_on: [postgres-db] exposes: [{port: 3001, protocol: http}] - name: inventory-service type: api depends_on: [redis-cache, postgres-db] exposes: [{port: 3002, protocol: http}] - name: redis-cache type: cache depends_on: [] exposes: [{port: 6379, protocol: redis}] - name: postgres-db type: db depends_on: [] exposes: [{port: 5432, protocol: postgres}] EOF

  注意：archify.yaml必须放在项目根目录，且文件名不能改。我试过改成infra.yaml，archify 直接报错No config file found，文档里没提这点，但源码里硬编码了文件名。

  3.2 生成与调试：一次命令，三重输出

  执行生成命令：

  npx archify@latest generate

  它会输出：

  ✅ Loaded config from archify.yaml ✅ Resolved 5 services and 9 dependencies ✅ Generated interactive diagram to ./dist/index.html ✅ Copied static assets to ./dist/ ✨ Done in 1.2s

  此时./dist/目录下有：

  • index.html（主页面）
  • archify.css（SVG 样式）
  • archify.js（交互逻辑）
  • assets/（图标字体文件）

  用浏览器直接打开index.html即可。但别急着点赞——先做两件事：

  1. 验证依赖完整性：点击order-api节点，侧边栏应显示其全部 4 个依赖。如果redis-cache显示为external，说明 YAML 里拼错了名字（比如写成redis_cache），archify 不会纠错，只会标记为外部。
  2. 测试导出功能：点击Copy PlantUML，粘贴到 PlantText 网站，确认生成的图与 HTML 页面一致。这是验证生成逻辑是否正确的黄金标准。

  3.3 集成到 CI/CD：GitHub Actions 的 5 行魔法

  这才是 archify 的真正价值所在。我在项目.github/workflows/architecture.yml中添加了以下步骤：

  name: Generate Architecture Diagram on: push: branches: [main] paths: ['archify.yaml', 'charts/**', 'openapi/**'] jobs: archify: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '18' - name: Generate Diagram run: npx archify@latest generate - name: Deploy to Pages uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./dist

  每次推送archify.yaml或 Helm Chart，GitHub Actions 就会自动生成最新架构图，并发布到https://<username>.github.io/<repo>/。团队成员无需任何操作，打开链接就是实时架构快照。我特意测试了并发推送：两个 PR 同时修改archify.yaml，Actions 自动排队执行，互不干扰。

  4. 它不能做什么？划清边界才能用好它

  archify 很强大，但绝非万能。我踩过几个典型误区，现在看来都是对工具定位的误读。

  4.1 不支持“动态发现”，只信任你给的配置

  有人问我：“能不能让它自动扫描 Kubernetes 集群，发现所有正在运行的服务？”答案是明确的：不能，也不该能。archify 的设计原则是“配置即架构”（Configuration as Architecture）。它认为，一个服务是否应该出现在架构图中，取决于它是否被明确定义在版本控制的配置里，而不是它此刻是否在 Pod 中 Running。如果某个服务临时起一个 Debug Pod，它不该出现在正式架构图中；反之，如果archify.yaml中定义了monitoring-stack，即使它还没部署，图中也应体现其规划位置。这种“声明式优先”的哲学，保证了架构图的权威性和可审计性。想实现自动发现？请用 Prometheus + Grafana 的 Service Discovery，那是运维监控的范畴，不是架构文档的范畴。

  4.2 不生成 UML 类图或时序图，专注系统级拓扑

  archify 输出的是System Context Diagram和Container Diagram（按 C4 模型），即“谁调用谁”的宏观通信关系。它不会分析 Java 代码生成类图，也不会解析 HTTP 请求日志生成时序图。如果你需要OrderService.process()方法内部调用了哪些 DAO，那该用 IDE 的 Call Hierarchy 功能；如果你想知道用户下单时，order-api到payment-gateway的完整调用链耗时，该用 OpenTelemetry 的 Trace。archify 只回答一个问题：“在这个系统里，有哪些组件？它们之间如何连接？”——足够清晰，绝不越界。

  4.3 HTML 输出是“最终产物”，不是“开发框架”

  有人试图修改dist/index.html里的 CSS 来定制主题，结果下次npx archify generate就被覆盖了。正确做法是：archify 提供了--theme参数，支持传入自定义 CSS 文件路径：

  npx archify generate --theme ./my-theme.css

  my-theme.css只需覆盖少量变量：

  :root { --archify-color-api: #2563eb; --archify-color-db: #059669; --archify-color-cache: #ea580c; --archify-font-family: "Inter", -apple-system, sans-serif; }

  它不会让你重写 SVG 渲染逻辑，因为那违背了“开箱即用、零维护”的初衷。你要做的，只是告诉它“用什么颜色”，而不是“怎么画”。

  5. 实战进阶：让 archify 成为你架构治理的神经末梢

  跑通 demo 只是开始。真正发挥价值，需要把它嵌入日常工程实践。分享三个我已在团队落地的进阶用法。

  5.1 架构合规性检查：把“禁止直连数据库”变成自动化红线

  我们规定：所有 API 服务禁止直连postgres-db，必须通过># 在 generate 后，运行合规检查 npx archify validate --rule "no-direct-db-access"

  这个validate命令会解析archify.yaml，检查是否存在type: api的服务，其depends_on直接包含postgres-db。如果发现，就失败并输出：

  ❌ Violation: order-api directly depends on postgres-db ✅ Fix: Add># 生成生产环境图 npx archify generate --config archify.prod.yaml --output dist/prod # 生成开发环境图 npx archify generate --config archify.dev.yaml --output dist/dev

  archify.dev.yaml中，postgres-db的type可设为local-db，图标自动换成笔记本电脑；depends_on可加入mock-sms-service。同一套服务定义，通过不同配置文件，生成完全不同的视图，无需维护多套代码。

  5.3 与文档系统深度集成：点击架构图，直达 Confluence 页面

  我们用confluence-page-id字段扩展archify.yaml：

  services: - name: order-api type: api confluence-page-id: "123456789" # ... 其他字段

  然后在archify.js的点击事件里，加入一行：

  // 当点击节点时 element.addEventListener('click', () => { const pageId = element.dataset.confluencePageId; if (pageId) { window.open(`https://your-company.atlassian.net/wiki/spaces/ENG/pages/${pageId}`, '_blank'); } });

  这样，点击图中的order-api，就直接跳转到 Confluence 上对应的详细设计文档。架构图不再是孤岛，而是通往所有技术资产的入口。

  6. 它为什么值得你今天就试试？一个架构师的坦白

  我用过 draw.io 手动画图，用过 Mermaid 写代码生成图，也用过商业工具订阅服务。archify 是第一个让我删掉所有其他架构图工具的。原因很简单：它把“画图”这个动作，从一个独立的、容易过时的、需要专门技能的环节，彻底消融进了开发工作流本身。

  当你修改archify.yaml时，你不是在“更新文档”，你是在声明系统契约；当 CI 自动推送新图时，你不是在“发布附件”，你是在广播架构变更；当新同事点击节点查看依赖时，他不是在“看示意图”，他是在执行架构查询。

  它不追求炫酷的动画，但每个 SVG 节点都带着>