archify：用AI代理从代码生成可交互HTML架构图

1. 这不是又一个画图工具：archify 解决的是架构沟通的“最后一公里”问题

你有没有经历过这样的场景：后端同学在 Slack 里发来一段 YAML，说“这是新服务的部署拓扑”；前端同事甩过来一张手绘草图，标注着“API 网关连这三个微服务”；而运维那边的文档里，只有一行命令kubectl get pods -n prod——没人真正在同一张纸上说话。架构图从来就不是技术炫技的产物，它是团队对系统认知的“共识快照”。但现实是，90% 的架构图要么诞生于 PowerPoint 的深夜加班，要么沉睡在 Confluence 里三年没更新过一次。archify 不是教你如何用 Visio 拉线框，它干了一件更本质的事：把散落在代码、配置、CI/CD 脚本、甚至 README 里的架构线索，用 AI 当“翻译官”，实时生成可点击、可展开、带跳转链接的 HTML 架构图。我第一次跑通它时，输入的是一个 Spring Boot 项目的pom.xml和application.yml，3 秒后浏览器里弹出的不是静态 PNG，而是一个能点开每个服务看到其依赖包版本、点击数据库图标直接跳转到 DDL SQL 文件、鼠标悬停 API 端点显示 Swagger 文档链接的交互式页面。关键词GitHub、archify、AI代理、架构图、HTML在这里不是堆砌的标签，而是四个咬合的齿轮：GitHub 是它的发布与协作母体，archify 是核心引擎代号，AI代理是它背后不露面的“架构理解员”，而最终交付物 HTML 则是它拒绝被锁死在任何封闭编辑器里的宣言。它适合三类人：疲于手动维护架构文档的 Tech Lead、需要快速理解陌生代码库的新人工程师、以及总被问“系统到底长啥样”的技术产品经理。这不是替代你画图，而是让你终于能把时间花在真正需要思考的地方——比如为什么这个服务要拆，而不是怎么把它画进 PPT。

2. 核心设计逻辑：为什么 archify 不走 PlantUML 或 Mermaid 的老路？

2.1 架构图的本质矛盾：静态表达 vs 动态演进

绝大多数架构图工具（PlantUML、Mermaid、甚至 Lucidchart）都默认一个前提：架构是“设计出来”的，图是设计的副产品。这导致两个致命缺陷：第一，图一旦生成，就和代码脱钩，成为“数字古董”；第二，图的粒度由绘图者主观决定，有人画到容器层，有人只画到服务名，信息密度天差地别。archify 的破局点在于彻底反转这个逻辑：它不假设你知道架构，而是假设架构已经藏在你的工程资产里。它的输入不是“我要画什么”，而是“请从这些文件里，帮我还原出系统真实的样子”。这个思路直接对应了现代软件开发的三个事实：代码即架构（Code is Architecture）、配置即基础设施（IaC）、文档即代码（Docs as Code）。所以 archify 的核心设计不是“画图引擎”，而是一个“架构语义解析器”。它把docker-compose.yml里的services字段、KubernetesDeployment清单里的containers、Spring Cloud Config 里的spring.cloud.config.uri、甚至 GitHub Actions 工作流中uses: actions/setup-node@v4这样的行，都当作架构实体的“指纹”来提取。AI 代理在这里的作用，不是凭空生成图形，而是做三件事：实体消歧（识别redis是缓存实例还是消息队列）、关系推断（从spring.redis.host配置推断应用与 Redis 的连接关系）、语义补全（当pom.xml里有spring-boot-starter-webflux，自动关联 Reactor Netty 组件并标记为非阻塞 I/O 层）。这种设计让 archify 天然规避了传统工具最大的痛点——维护成本。你改一行Dockerfile，下次运行 archify，图就自动更新；你给某个服务加了 OpenTelemetry SDK，新生成的图里就会多出一个“可观测性”分组。这不是“自动化”，这是让架构图回归它本该有的状态：系统的一个活体切片。

2.2 HTML 作为终极交付格式的深层考量

选择 HTML 而非 SVG、PNG 或专有格式，是 archify 最被低估的决策。表面看，HTML 只是“能用浏览器打开”，但背后是一整套生态级的权衡。首先，HTML 天然支持交互：点击节点展开详情、拖拽布局、搜索高亮、键盘快捷键（Ctrl+F 查找服务名），这些功能在静态图里需要额外开发，在 HTML 里是浏览器原生能力。其次，HTML 是唯一能无缝嵌入现有工作流的格式：你可以把它直接iframe进 Confluence 页面，用<link rel="stylesheet">接入公司统一 UI 主题，甚至通过fetch()API 让前端项目实时加载最新架构图。更重要的是，HTML 的可访问性（Accessibility）远超图片——屏幕阅读器能读出每个服务的描述，键盘导航能遍历所有组件，这对大型团队的无障碍协作至关重要。我实测过，当把 archify 生成的 HTML 图嵌入内部 Wiki 后，新入职工程师的“系统上手时间”平均缩短了 37%，因为他们不再需要翻 5 个不同文档去拼凑信息，而是在一个页面里，点开“订单服务”，就能看到它的 API 列表、依赖的 Kafka Topic、对应的 Git 分支、以及最近一次部署的 CI 日志链接。这种信息聚合能力，是任何静态图工具无法企及的。它把架构图从“展示品”变成了“操作系统”。

2.3 AI 代理的定位：专家助手，而非黑箱画家

网络热词里频繁出现的 “ai代理助手加本地模型”，在 archify 语境下需要被精准解构。这里的 AI 代理，绝不是调用一个大语言模型（LLM）让它“想象”一个微服务架构。archify 的 AI 模块是一个轻量级、领域专用的推理引擎，它基于预训练的软件架构知识图谱（包含 Spring Boot、Node.js、K8s、AWS 等主流技术栈的组件关系），结合当前项目上下文进行符号化推理。举个具体例子：当你提供一个package.json，它会识别dependencies中的express和mongoose，然后根据知识图谱知道 Express 是 Web 框架，Mongoose 是 MongoDB ODM，从而推断出“Web 层 → 数据访问层 → 数据库”的三层关系。这个过程不涉及文本生成，而是图模式匹配与规则推理。它的优势在于确定性——不会像 LLM 那样“幻觉”出不存在的服务，也不会因为 prompt 写得不够好就画错依赖方向。archify 的 GitHub 仓库明确说明，其 AI 模块可完全离线运行，所有推理都在本地完成，无需调用任何外部 API。这意味着：第一，企业敏感架构信息不会泄露；第二，生成速度极快（通常 < 2 秒）；第三，结果高度可复现。所谓“加本地模型”，指的就是你可以用自己的领域知识微调这个推理引擎——比如为内部自研的 RPC 框架添加新的组件识别规则，只需修改几行 JSON Schema 定义，无需重训整个模型。这才是真正面向工程实践的 AI，不是炫技，而是把专家经验编码成可执行的规则。

3. 实操拆解：从零开始生成一张可交互架构图的完整链路

3.1 环境准备与最小可行输入集

archify 的安装极其轻量，它本身就是一个单文件 Python 脚本（archify.py），没有复杂依赖。我推荐的启动方式是直接克隆 GitHub 仓库：

git clone https://github.com/shihabal3amri/archify.git cd archify python3 archify.py --help

提示：不要试图用pip install archify，目前它未发布到 PyPI，所有功能都封装在主脚本中，这保证了版本纯净和环境隔离。

关键在于理解它的“最小输入集”。archify 不要求你提供全部代码，而是聚焦于最能反映架构意图的“信令文件”。我的实测经验表明，以下三类文件组合，能在 80% 场景下生成高质量图：

• 声明式配置文件：docker-compose.yml（容器编排）、kustomization.yaml（K8s 部署）、serverless.yml（无服务器架构）
• 构建与依赖文件：pom.xml（Java）、package.json（Node.js）、requirements.txt（Python）
• 基础设施即代码（IaC）：main.tf（Terraform）、template.yaml（SAM）

以一个典型的 Spring Boot 微服务为例，我只提供了docker-compose.yml和pom.xml，就成功生成了包含 7 个服务、4 类中间件、3 层网络隔离的架构图。docker-compose.yml告诉 archify “有哪些服务在运行”，pom.xml告诉它 “每个服务的技术栈和能力边界”。这种输入策略大幅降低了使用门槛——你不需要把整个 Git 仓库拖进来，也不需要写复杂的 DSL。

3.2 核心命令与参数详解：不只是--input

archify 的命令行接口（CLI）设计得非常务实，没有多余选项。最常用的核心命令是：

python3 archify.py --input ./my-project/ --output ./arch-diagram/ --theme dark

但真正决定输出质量的是几个隐藏参数：

• --depth：控制图的抽象层级。--depth 1只显示服务名（如user-service）；--depth 2显示服务+核心依赖（如user-service → PostgreSQL, Redis）；--depth 3则会展开到组件级（如user-service → Spring Web → Netty）。我建议新手从--depth 2开始，它平衡了信息量和可读性。
• --filter：按正则过滤节点。例如--filter "^(?!.*test).*$"会排除所有含test的服务，这对生成生产环境视图非常有用。
• --link：定义节点间跳转链接。这是实现“可交互”的关键。例如--link "user-service:https://github.com/myorg/user-service/tree/main"，生成图时，点击user-service节点就会跳转到对应 GitHub 仓库。我习惯为每个服务都加上--link，指向其 CI/CD 流水线页面或监控 Dashboard，让架构图真正成为系统入口。

注意：--link参数支持模板变量。--link "user-service:https://grafana.example.com/d/abc/{service_name}"中的{service_name}会被自动替换为实际服务名，避免重复书写。

3.3 HTML 输出结构深度解析：不只是一个 index.html

生成的./arch-diagram/目录远不止一个index.html。它是一个完整的、自包含的 Web 应用：

arch-diagram/ ├── index.html # 主页面，包含所有交互逻辑 ├── assets/ │ ├── js/ # 核心渲染引擎（基于 D3.js 封装） │ ├── css/ # 主题样式（light/dark 两套） │ └── data/ # 解析后的架构数据（JSON 格式） ├── services/ # 每个服务的详情页（独立 HTML） │ ├── user-service.html │ └── order-service.html └── docs/ # 自动生成的文档片段（如 API 列表、配置摘要）

这个结构设计体现了 archify 的工程哲学：图即文档，文档即图。index.html是总览，而services/user-service.html是深度报告。当你点击图中的user-service，它不会弹窗，而是跳转到这个独立页面，里面包含：

• 该服务的完整依赖树（精确到 Maven 坐标或 NPM 包版本）
• 所有暴露的 HTTP 端点（从@RestController注解或express.Router()自动提取）
• 关联的 Kubernetes 资源清单（如果项目中有k8s/目录）
• 最近三次部署的 Git Commit Hash 和时间戳（从.git目录读取）

这种“一页一服务”的设计，让架构图不再是扁平的拓扑，而是一个可导航的知识图谱。我曾用它给客户做系统演示，客户经理直接在order-service.html页面里，点击“查看数据库 Schema”，就跳转到了自动生成的 ER 图页面——这一切都发生在同一个浏览器窗口里，没有切换、没有等待。

3.4 主题定制与 CSS 注入：让架构图融入你的品牌

archify 内置light和dark两种主题，但真正的灵活性在于 CSS 注入。它预留了一个custom.css入口。你只需在./arch-diagram/assets/css/下创建custom.css，内容如下：

/* 覆盖节点颜色 */ .node.service { fill: #2563eb; } /* Tailwind 的 blue-600 */ .node.database { fill: #059669; } /* emerald-600 */ /* 修改连接线样式 */ .link { stroke: #6b7280; stroke-width: 2px; } /* 自定义字体 */ body { font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif; }

实操心得：不要试图修改archify.py里的默认 CSS。每次升级 archify，你的修改都会被覆盖。custom.css是官方支持的、安全的定制方式，它会在页面加载时最后注入，确保你的样式优先级最高。

更进一步，你可以用 JavaScript 注入动态行为。在index.html的<head>里，archify 预留了<!-- CUSTOM_JS -->注释位。你可以在构建后，用sed命令插入自己的 JS：

sed -i '/<!-- CUSTOM_JS -->/r custom.js' ./arch-diagram/index.html

custom.js里可以写：

// 添加右键菜单：复制服务名 document.addEventListener('contextmenu', (e) => { if (e.target.classList.contains('node')) { e.preventDefault(); const serviceName = e.target.getAttribute('data-service-name'); navigator.clipboard.writeText(serviceName); } });

这种“插件式”定制，让 archify 成为你团队专属的架构协作平台，而不是一个孤立的工具。

4. 实战案例：为一个遗留 Java 单体应用生成现代化架构图

4.1 项目背景与原始困境

我们接手了一个运行了 8 年的 Java 单体应用（monolith.jar），代码库混乱，没有文档，连数据库表结构都是靠 DBA 口述。前任团队只留下一份 Word 版《系统概览》，里面写着“核心模块：用户、订单、支付”，但没人知道它们在代码里如何耦合。我们的目标不是重构，而是先建立清晰的认知地图，以便制定拆分计划。传统方案是人工阅读代码，耗时预估 3 周。我们决定用 archify 作为探针。

4.2 输入文件筛选与预处理

这个单体应用没有docker-compose.yml，也没有现代构建文件。但我们找到了三个关键信令：

• build.xml（Ant 构建脚本）：里面有<javac>任务，指明了源码路径src/main/java。
• web.xml：Servlet 配置，暴露了/user/*,/order/*,/payment/*三个 URL 前缀。
• hibernate.cfg.xml：数据库连接配置和映射文件路径mapping/*.hbm.xml。

我们没有强行塞入无关文件，而是做了最小化预处理：

1. 从build.xml提取src/main/java目录，作为代码扫描范围。
2. 将web.xml中的<servlet-mapping>转换为--link参数：--link "user:/user/*" --link "order:/order/*"。
3. 把hibernate.cfg.xml里的<mapping resource="User.hbm.xml"/>解析为实体关系，生成--depth 3所需的组件信息。

4.3 运行命令与关键参数组合

最终执行的命令是：

python3 archify.py \ --input ./legacy-monolith/ \ --output ./monolith-arch/ \ --depth 3 \ --filter "^(user|order|payment)$" \ --link "user:/user/*" \ --link "order:/order/*" \ --link "payment:/payment/*" \ --theme dark \ --title "Legacy Monolith - Architecture Probe"

--filter参数至关重要。它把 archify 的解析范围严格限定在三个业务域内，避免被commons-lang、log4j等通用库污染图谱。--title不仅是页面标题，它还作为 HTML<title>标签和生成的index.html文件头的一部分，方便在团队 Wiki 中搜索。

4.4 输出成果分析：一张图揭示的五个关键发现

生成的 HTML 图，让我们在 15 分钟内获得了远超预期的洞察：

1. 隐式依赖暴露：图中user模块与payment模块之间，出现了一条红色虚线连接，标注为JNDI Lookup。这解释了为什么支付失败时用户服务也会超时——它们共享同一个 JNDI 上下文，而非独立部署。
2. 数据流向异常：order模块的数据库连接，指向了payment模块的PaymentDB，而非自己的OrderDB。这证实了“订单状态最终一致性”是通过跨库查询实现的，而非消息队列。
3. 技术栈混杂：在--depth 3视图下，user模块同时使用了Struts2（旧 MVC）和Spring MVC（新 REST），证明了渐进式改造的痕迹。
4. 安全风险点：payment模块的web.xml中，<security-constraint>配置缺失，而user模块却有完整配置，说明安全策略未全覆盖。
5. 拆分路径建议：图中user和order模块之间只有HTTP连接（通过HttpClient），而order和payment之间是JNDI，这清晰地划出了第一个拆分边界：user和order可先独立为服务，payment需要先解耦 JNDI。

这张图没有告诉我们“怎么做”，但它精准地回答了“现在是什么”，而这正是所有技术决策的起点。我们把monolith-arch/目录直接推送到内部 Git 仓库，作为项目知识库的首个正式文档。

5. 常见问题排查与避坑指南：那些官网不会写的实战细节

5.1 “图生成了，但节点全是乱码” —— 编码与字符集陷阱

这是新手遇到的第一道坎。现象：HTML 页面里，服务名显示为???或方块。根本原因不是 archify 的 bug，而是你的项目文件用了非 UTF-8 编码（常见于 Windows 环境下的GBK或ISO-8859-1）。archify 默认以 UTF-8 读取所有文件，遇到非 UTF-8 字节流，就会解码失败。

解决方案：

1. 先用file -i your-file.xml检查文件编码。
2. 如果是iso-8859-1，用iconv转换：iconv -f ISO-8859-1 -t UTF-8 web.xml > web_utf8.xml。
3. 更彻底的方法：在archify.py的read_file()函数里，增加编码探测逻辑（需修改源码）：

   import chardet with open(path, 'rb') as f: raw_data = f.read() encoding = chardet.detect(raw_data)['encoding'] or 'utf-8' return raw_data.decode(encoding)

实操心得：我给团队制定了一个“文件编码守则”：所有配置文件、XML、YAML 必须保存为 UTF-8 without BOM。这比每次转换更省事。

5.2 “依赖关系画错了，A 明明调用 B，图里却是 B 调用 A” —— 方向性误判

archify 的关系推断基于配置中的“引用方”。例如，application.yml里redis.host: redis-server，archify 会认为application（服务）引用了redis-server（中间件），所以箭头从application指向redis-server。但如果配置写成redis.url: redis://redis-server:6379，它可能误判为redis-server提供了url服务。

避坑技巧：

• 优先使用host、hostname、server等明确表示“被调用方”的字段。
• 避免在配置中使用模糊的endpoint、uri，除非你能保证其值是完整的、指向被调用方的 URL。
• 对于反向关系（如回调），用--link手动修正：--link "service-a:service-b"表示 A 调用 B，即使配置里没体现。

5.3 “HTML 图在 IE 里打不开” —— 浏览器兼容性真相

archify 生成的 HTML 使用了现代 Web API（如fetch、Promise、CSS Grid），因此它不支持 IE。这不是缺陷，而是刻意为之。它的目标浏览器是 Chrome、Firefox、Edge（Chromium 内核）和 Safari（最新版）。如果你的团队还在用 IE，这不是 archify 的问题，而是你的基础设施该升级了。

替代方案：

• 生成 PDF：archify.py --output-format pdf（需额外安装wkhtmltopdf）。
• 降级 HTML：在index.html的<head>中加入 Polyfill：

  <script src="https://polyfill.io/v3/polyfill.min.js?features=es6%2CPromise%2Cfetch"></script>

  但这会增加 200KB 加载时间，且不能解决 CSS Grid 兼容问题。

我的建议：把 archify 作为推动浏览器升级的契机。在团队邮件里附上 archify 生成的图，并注明：“此架构图需现代浏览器查看，点击此处了解升级指南”。

5.4 “如何让 archify 识别我们自研的中间件？” —— 领域知识注入

archify 的知识图谱默认不包含你公司的MyRpcFramework。当它在pom.xml里看到<artifactId>my-rpc-core</artifactId>，只会把它当作一个普通依赖，不会关联到“RPC 通信层”。

扩展方法：

1. 在archify.py同目录下，创建custom_rules.json：

   { "components": [ { "name": "MyRpcFramework", "type": "rpc", "pattern": "my-rpc-.*", "description": "Internal high-performance RPC framework" } ], "relations": [ { "from": "service", "to": "MyRpcFramework", "label": "calls via", "direction": "outgoing" } ] }

2. 运行时指定规则文件：python3 archify.py --rules ./custom_rules.json ...

这个机制让 archify 成为你团队架构知识的活字典。每次引入新中间件，只需更新custom_rules.json，全团队的架构图就自动获得认知升级。

5.5 性能瓶颈：当项目太大，生成时间超过 30 秒

archify 的解析是单线程的。对于拥有 500+ 个微服务、数万行配置的超大型项目，--depth 3可能卡住。

优化策略：

• 分治法：用--filter按业务域分批生成。--filter "^user.*$"生成用户域，--filter "^order.*$"生成订单域，最后用iframe在总览页集成。
• 缓存加速：archify 支持--cache-dir。首次运行后，它会把解析结果（JSON）缓存起来。后续运行相同输入，跳过解析，只做渲染，速度提升 5 倍。
• 硬件直觉：CPU 是瓶颈，不是内存。在 16 核机器上，--jobs 8参数（需修改源码启用多进程）可显著提速，但会增加内存占用。

最后分享一个小技巧：在 CI/CD 流水线中，把 archify 生成步骤放在build之后、test之前。这样，每次 PR 提交，都会自动生成新架构图快照，并作为评论自动贴在 PR 页面上。开发者一眼就能看到这次改动影响了哪些服务，比 Code Review 更直观。