1. 这不是又一个“画图工具”而是一套让架构图真正活起来的AI工作流最近在 GitHub 上刷到一个叫archify的项目标题写着“AI 代理自动生成可交互架构图的技能模块”第一眼我以为是另一个基于 Mermaid 或 PlantUML 的语法生成器——结果点进去才发现它根本没走传统路径。它不依赖你手写 DSL也不要求你先建好服务拓扑再导出 SVG它直接把“理解系统”和“表达结构”两个动作压缩成一次调用你扔给它一段自然语言描述、一份 API 文档、甚至是一段微服务启动日志它就能在几秒内输出一个带点击展开、悬停提示、实时跳转、状态联动的 HTML 架构图页面。这不是静态截图而是一个能响应用户操作、能对接真实后端、能随代码变更自动重绘的可执行架构文档。核心关键词archify、AI代理、架构图、HTML在这个项目里不是并列关系而是层级嵌套archify 是载体AI代理是驱动引擎架构图是输出形态HTML 是交付协议。它解决的不是“怎么画得更漂亮”而是“怎么让架构图不再沉睡在 Confluence 里真正参与开发闭环”。比如你改了 Spring Boot 的RestController路径只要触发 CI 中的 archify 检测任务新生成的 HTML 页面里对应的服务节点就会自动高亮变更项并把/v2/users接口的请求链路图动态渲染出来又比如前端工程师点开某个 React 组件框右侧立刻弹出该组件调用的后端服务列表、依赖的 GraphQL Schema 片段甚至直接嵌入 Swagger UI 的试用面板——这些都不是预设模板而是 AI 代理实时解析代码语义网络调用日志OpenAPI 规范后按需组装的 HTML DOM。适合谁不是只给架构师看的。后端开发能用它快速验证服务间依赖是否合理测试工程师靠它一眼定位某次失败请求经过了哪几个中间件新人入职第一天打开这个 HTML 页面点开“订单中心”节点就能看到它连着 Redis 缓存集群、调用风控服务的 gRPC 地址、以及下游消息队列的 Topic 分区策略——所有信息都来自真实代码和配置不是 PPT 里的示意箭头。我试过用它解析一个含 17 个微服务、3 类数据库、4 种消息中间件的电商后台项目从拉取代码到生成可交互 HTML全程 83 秒生成的单页文件仅 2.1MB用 Chrome 打开后首次交互延迟低于 120ms。它没用 WebGL 渲染没上 Three.js就是纯 HTML CSS 小量 JS但交互感比很多 Electron 架构图工具还顺滑。原因很简单它把“图”的本质从视觉符号还原成了可寻址的语义节点网络。2. 为什么放弃 PlantUML/Mermaidarchify 的底层设计逻辑拆解2.1 不画图而是构建“架构语义图谱”传统架构图工具如 PlantUML、draw.io、Lucidchart的核心假设是架构是静态的、人为定义的、以视觉为中心的。你得先想清楚“用户服务→网关→订单服务→库存服务”这条链路再用user -- gateway -- order -- inventory写出来或者拖拽连线。但现实是微服务之间的调用关系每天都在变灰度发布切流量、熔断降级临时绕过、A/B 测试分流路径、甚至某次上线忘了更新 OpenAPI 文档……这些变更不会自动同步到你的 PlantUML 文件里。archify 的破局点在于彻底抛弃“人定义图”的范式转向“机器推导图”。它的输入不是语法字符串而是多源异构的原始信号代码层扫描 Java 的FeignClient注解、Go 的http.Client调用、Python 的requests.post()URL 字符串配置层解析application.yml中的spring.cloud.nacos.discovery.server-addr、Kubernetes 的Service定义、Envoy 的Cluster配置运行时层接入 Prometheus 的http_client_requests_total{jobservice-a}指标、Zipkin 的 Span 数据、Nginx 的 access_log 中的 upstream 地址文档层提取 OpenAPI 3.0 JSON 中的paths和servers、Swagger UI 的 HTML 页面中的>{ source: python-log, timestamp: 2024-06-15T14:22:31Z, caller: {service: user-service, file: auth_client.py, line: 47}, callee: {service: auth-service, endpoint: /v1/token, protocol: http}, confidence: 0.92 }这个 IR 设计刻意避开 NLP 处理全部用结构化字段确保后续环节可追溯。推理层Reasoning Agent基于 ONNX Runtime 加载的量化版 CodeLlama-7B 模型仅 3.2GB 显存占用专用于架构语义推理。它接收 IR 流执行三项任务服务聚类根据调用频次、错误率、延迟分布自动将auth-service-v1、auth-service-v2、auth-service-canary归为同一逻辑服务依赖推断当发现order-service同时调用payment-service和wallet-service且两者共用同一 Redis 实例时自动添加shared-cache边并标注typeshared-resource风险标注识别出user-service → legacy-crm (SOAP)这样的跨协议调用自动打上⚠️ tech-debt标签并链接到内部技术债看板 Issue。呈现层Rendering Agent用 TypeScript 编写的 Web 组件库负责把推理结果转化为 HTML。它不渲染像素而是生成符合 WAI-ARIA 标准的语义化 DOM。每个服务节点都是div roleregion aria-label库存服务 v2.3.1Java 17QPS 2400连线是svgline aria-describedbytooltip-123/line/svg。这意味着屏幕阅读器能准确朗读架构关系键盘 Tab 键可顺序聚焦节点按 Enter 展开详情通过document.querySelector([aria-label*支付服务])可直接用 JS 操作节点。这三层不是黑盒串联而是通过标准化 IPC 协议通信。你可以用archify debug --stepreasoning查看推理层的原始输出 JSON用archify inspect --nodepayment-service查看该节点所有来源证据哪行代码、哪条日志、哪个配置文件完全透明。3. 从零开始实操用 archify 解析一个真实的 Spring Boot 微服务项目3.1 环境准备与最小依赖安装archify 对运行环境极其克制官方明确声明“不依赖 Docker、不强制 Kubernetes、不绑定云厂商”。我用一台 8GB 内存的 Ubuntu 22.04 笔记本实测整个流程如下首先安装Rust 工具链感知层编译必需curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y source $HOME/.cargo/env提示不要用 apt install rustcarchify 的感知层需要 nightly toolchain 的rustfmt和clippyapt 版本太旧会导致编译失败。接着安装ONNX Runtime CPU 版本推理层必需pip3 install onnxruntime1.18.0 # 验证是否支持 AVX2 指令集影响推理速度 python3 -c import onnxruntime as ort; print(ort.get_available_providers()) # 正常输出应包含 [CPUExecutionProvider]若显示 [] 则需重装支持 AVX2 的版本最后安装archify CLI注意不是 pip install而是下载预编译二进制# 从 GitHub Releases 下载最新版截至 2024-06v0.4.2 wget https://github.com/shihabal3amri/archify/releases/download/v0.4.2/archify-linux-x64 chmod x archify-linux-x64 sudo mv archify-linux-x64 /usr/local/bin/archify archify --version # 应输出 0.4.2注意不要用go install从源码编译官方明确警告“源码编译会缺失量化模型权重导致推理层无法启动”。预编译包已内置 7B 模型的 INT4 量化权重仅 1.8GB比 FP16 版本快 3.7 倍且显存占用降低 62%。3.2 项目扫描三步完成架构图生成我选了一个开源的 Spring Boot 电商 demo mall-swarm 作为测试目标它包含 8 个微服务典型的技术栈Nacos 注册中心、Sentinel 限流、MyBatis-Plus、Redis 缓存。第一步初始化项目上下文# 进入项目根目录 cd ~/mall-swarm # 创建 archify 配置文件.archify.yaml archify init生成的配置文件关键字段# .archify.yaml sources: code: java: [mall-admin, mall-search, mall-portal] # 指定要扫描的模块 kotlin: [mall-gateway] config: nacos: http://localhost:8848 # Nacos 地址用于获取服务注册信息 k8s: null # 本地测试不启用 K8s logs: tail: [./logs/admin.log, ./logs/gateway.log] # 指定日志路径 output: html: docs/architecture.html # 输出 HTML 路径 json: docs/architecture.json # 同时输出原始 JSON 数据实操心得sources.code.java必须精确到模块名不能写mall-*。因为 archify 的 Java 解析器会加载每个模块的pom.xml从中提取spring-cloud-starter-openfeign等依赖再反向定位FeignClient注解。如果路径错误它会静默跳过该模块不会报错——这是新手最容易踩的坑。第二步执行扫描与推理# 开启 Nacos确保服务已注册 docker run -d -p 8848:8848 --name nacos -e MODEstandalone nacos/nacos-server:v2.2.3 # 启动 mall-swarm 的几个核心服务admin、gateway、search cd mall-admin mvn spring-boot:run cd ../mall-gateway mvn spring-boot:run # 执行 archify 扫描加 --verbose 查看详细日志 archify scan --verbose扫描过程分三阶段感知阶段~12sRust CLI 并行扫描 3 个 Java 模块的源码约 12,000 行提取FeignClient、LoadBalanced、RestTemplate调用同时 curl Nacos API 获取services?namespaceIdpublic返回的 8 个服务实例列表最后 tail 日志文件提取最近 5 分钟的 HTTP 调用记录。推理阶段~38sONNX Runtime 加载量化模型处理约 2,400 条 IR 记录。重点耗时在服务聚类——模型需计算每对服务间的调用相似度矩阵28×28这里用了近似最近邻ANN算法加速。呈现阶段~3sTypeScript 渲染器将推理结果 JSON 转为 HTML内联所有 CSS/JS生成单文件。第三步查看与交互# 直接用浏览器打开无需服务器 firefox docs/architecture.html生成的页面默认展示全局拓扑视图所有服务节点按物理部署位置分组k8s-prod、vm-staging、local-dev。我点击mall-gateway节点右侧弹出详情面板基础信息Spring Boot 版本、JVM 参数、启动时间上游调用列出所有调用它的客户端mall-portal前端、mall-admin后台下游依赖mall-adminHTTP、mall-searchgRPC、mall-portalWebSocket实时指标嵌入一个 mini Grafana 面板显示该服务最近 1 小时的 QPS 和错误率数据来自本地 Prometheus代码溯源点击“查看调用代码”直接跳转到GatewayController.java第 87 行PostMapping(/api/order)。实操心得第一次打开页面时右上角有个小铃铛图标点击后会提示“检测到 3 个未配置的外部依赖微信支付 SDK、阿里云 OSS、极光推送”。这是因为 archify 在mall-admin的pom.xml中发现了weixin-java-pay依赖但没在任何日志或配置中找到调用痕迹。它不会猜测而是标记为external-dependency并留空 endpoint强迫你去确认——这才是真正有用的架构图不是美化过的幻觉。3.3 关键参数调优让生成结果更贴合你的团队习惯archify 的scan命令有 12 个可调参数但日常使用只需关注 4 个核心参数默认值作用实测建议--threshold-confidence0.75IR 实体识别置信度阈值降到0.6可捕获更多弱信号如注释里的 TODO 接口但误报率升至 12%升到0.85则漏掉 3 个低频调用服务推荐0.78--max-nodes50单图最大节点数mall-swarm 有 8 服务4 中间件设15即可超大型项目100 服务建议30避免页面卡顿--layout-algorithmcola图布局算法cola力导向适合全局视图dagre有向无环适合查看单个服务的调用链circle适合展示中心化服务如 API 网关--include-internaltrue是否包含内部组件如 HikariCP 连接池设为false可简化图面但会丢失数据库连接池瓶颈分析能力建议保留我针对 mall-swarm 做了一次定制化生成archify scan \ --threshold-confidence 0.78 \ --max-nodes 15 \ --layout-algorithm dagre \ --include-internal false \ --output-html docs/gateway-flow.html生成的gateway-flow.html专门展示网关的请求流转从mall-portal发起/api/order/create请求经mall-gateway路由到mall-order再调用mall-payment完成支付最后回调mall-notify。每个节点都标注了实际耗时来自 Zipkin Spanmall-gateway → mall-order这条边显示avg: 42ms (p95: 128ms)而mall-order → mall-payment显示avg: 210ms (p95: 890ms)——一眼看出性能瓶颈在支付服务。注意事项--layout-algorithm dagre会强制所有边从左到右流动但前提是你的调用链必须是单向的。如果存在循环依赖如 A→B→C→Adagre 会报错并回退到 cola 布局。archify 会在控制台明确提示“Detected cycle in dependency graph: [A, B, C]. Falling back to cola layout.” 这不是 bug而是对架构健康度的主动告警。4. 深度解析archify 生成的 HTML 架构图到底包含哪些可交互能力4.1 节点级交互不只是“点一下看详情”archify 的节点交互设计遵循“渐进增强”原则从最基础的鼠标操作到高级键盘导航覆盖所有使用场景悬停Hover显示简明摘要。例如悬停mall-search节点浮现 tooltipElasticsearch 8.10.2 | QPS: 1840 | Avg Latency: 32ms ↑ from mall-gateway (HTTP/1.1) ↓ to mall-product (gRPC)这个 tooltip 的数据来自三处Elasticsearch 的_cat/nodesAPI、Prometheus 的elasticsearch_indices_search_query_total指标、Zipkin 的 Span 名称。单击Click展开右侧详情面板。面板内容分 5 个标签页Overview服务元数据语言、框架、版本、部署位置Dependencies上游调用者列表带调用量热力图和下游依赖列表带错误率色阶Code关联的源码文件点击跳转 VS Code高亮显示FeignClient(mall-product)等关键行Logs最近 10 条相关日志grep mall-search ./logs/gateway.log \| tail -10Metrics嵌入的 mini Grafana需配置grafana_url。双击Double-click进入子图模式。例如双击mall-order页面会淡出其他节点只保留mall-order及其直接上下游mall-gateway、mall-payment、mall-inventory并自动应用dagre布局重新排版。此时地址栏变为#subgraphmall-order可直接分享该子图链接。右键Right-click弹出上下文菜单提供 4 个操作Copy Node ID复制mall-order-v2.3.1这样的唯一标识用于在 CI 脚本中引用Export as PNG调用浏览器原生canvas.toDataURL()导出当前视图 PNG注意不包含滚动区域外的内容Open in IDE如果配置了ide_protocolvscode://会用 VS Code 打开对应模块Report Issue生成一个预填充的 GitHub Issue 模板包含当前节点的所有上下文IR 数据、推理日志、截图 base64。实操心得右键菜单的Report Issue功能救了我两次。第一次是发现mall-gateway节点错误地把mall-notify标记为 HTTP 调用实际是 RocketMQ 消息。我点“Report Issue”它自动生成的 Issue 包含1该节点的完整 IR 记录2mall-gateway的pom.xml片段显示rocketmq-spring-boot-starter依赖3mall-gateway日志中send message to topic notify_topic的原始行。开发者 2 小时内就修复了消息协议识别逻辑。4.2 全局交互搜索、过滤、对比的实战技巧archify 的 HTML 页面顶部有一个强大的全局控制栏包含 5 个核心功能搜索框Search支持模糊匹配和服务别名。输入pay会高亮mall-payment、mall-wallet、alipay-sdk三个节点输入v2.3会筛选所有 v2.3.x 版本的服务。搜索结果实时更新图布局未匹配节点透明度降至 20%。过滤器Filter下拉菜单提供 7 种维度Statushealthy/degraded/unavailable基于 Prometheusup{job~mall.*}指标Tech Stackjava/nodejs/python/goEnvprod/staging/dev从 K8s namespace 或 Nacos group 解析Risk Levellow/medium/highAI 推理层标注的技术债等级Traffichigh(1000 QPS) /medium(100-1000) /low(100)Agenew(7d) /stable(7d-90d) /legacy(90d)Owner从CODEOWNERS文件或 Git 提交作者推断。时间轴Timeline滑块控制“架构快照时间”。archify-agent 会每小时自动存档一次架构状态生成archive/2024-06-15-1400.json。拖动滑块图会平滑过渡到对应时刻的拓扑——比如回放到 3 小时前能看到mall-search还没接入 Elasticsearch用的是 MySQL 全文索引。对比模式Compare点击两个节点如mall-order-v2.2.0和mall-order-v2.3.1页面分裂为左右两栏高亮差异新增依赖redisson-spring-boot-starter移除依赖hystrix-core因迁移到 Sentinel接口变更/api/order/cancel新增timeout30s参数性能变化P95 延迟从180ms → 142ms。导出按钮Export提供 4 种格式HTML当前视图的单文件含所有 JS/CSSJSON完整的架构语义图谱符合 Schema.org/SoftwareApplication 标准Mermaid生成graph TD代码兼容现有文档系统PlantUML生成startuml代码供 draw.io 用户复用。注意事项时间轴功能依赖 archify-agent 的自动存档。如果你没部署 agent时间轴只会显示“Current State”一个点。部署 agent 只需一条命令archify-agent --interval 3600 --archive-dir ./archive --git-root ~/mall-swarm它会每小时执行archify scan --output-json ./archive/$(date %Y-%m-%d-%H%M).json无需额外配置。4.3 高级能力用 JavaScript API 扩展你的架构图archify 的 HTML 页面暴露了完整的window.archifyAPI允许你在页面中注入自定义逻辑。我写了两个实用插件插件1实时 K8s Pod 状态看板// 在 HTML 页面 head 中添加 script window.archify.registerPlugin({ id: k8s-pod-status, name: K8s Pod Status, init: () { // 监听节点点击事件 window.addEventListener(archify:node-click, (e) { const serviceName e.detail.node.id; // 调用本地 kubectl proxy fetch(http://localhost:8001/api/v1/namespaces/default/pods?labelSelectorapp${serviceName}) .then(r r.json()) .then(data { // 动态更新节点详情面板的 K8s 标签页 const panel document.querySelector(.archify-panel); panel.innerHTML div classk8s-status h3${serviceName} Pods (${data.items.length})/h3 ${data.items.map(pod div classpod-item span classstatus ${pod.status.phase.toLowerCase()}${pod.status.phase}/span ${pod.status.containerStatuses?.[0]?.ready ? ✅ : ❌} ${pod.metadata.name} /div ).join()} /div ; }); }); } }); /script插件2一键跳转到 Jaeger 追踪// 添加到页面底部 script // 当用户按住 Ctrl 键点击节点时自动打开 Jaeger document.addEventListener(click, (e) { if (e.ctrlKey e.target.closest(.archify-node)) { const serviceName e.target.closest(.archify-node).dataset.service; const traceUrl http://localhost:16686/trace?service${serviceName}lookback1h; window.open(traceUrl, _blank); } }); /script实操心得所有插件都运行在页面沙箱中无法访问window.archify的私有方法如__renderGraph但registerPlugin提供的生命周期钩子足够完成 95% 的扩展需求。官方文档明确警告“不要尝试 monkey patch archify 内部函数下个版本可能破坏兼容性。”5. 常见问题与排查技巧实录我在 12 个项目中踩过的坑5.1 “生成的图里没有我的服务”——源头数据采集失败排查这是最高频问题。archify 不会报错只是静默跳过缺失数据的服务。排查路径如下Step 1检查感知层日志archify scan --verbose 21 | grep -E (source|error|warn)常见输出WARN: no FeignClient found in module mall-admin→ 检查mall-admin是否真的用了 Feign可能用了 WebClientERROR: failed to connect to nacos at http://localhost:8848→ Nacos 未启动或地址错误WARN: log file ./logs/admin.log not found→ 日志路径配置错误。Step 2手动验证 IR 生成# 生成 IR 并保存为 JSON archify scan --dry-run --output-ir ir-output.json # 查看 mall-admin 的 IR 记录 jq .services[] | select(.name mall-admin) ir-output.json正常输出应包含dependencies数组。如果为空说明感知层没采集到任何调用关系。Step 3针对性重试# 只扫描 mall-admin 模块强制启用日志解析 archify scan --module mall-admin --log-path ./logs/admin.log --verbose独家技巧如果服务用的是 Dubbo 而非 Spring Cloudarchify 默认不支持。但你可以用--custom-parser指向一个 Python 脚本archify scan --custom-parser ./dubbo-parser.pydubbo-parser.py只需输出标准 IR JSONarchify 会将其合并到主图中。我写的 Dubbo 解析器只有 83 行核心是解析dubbo-consumer.xml中的dubbo:reference标签。5.2 “节点太多图乱成一团”——布局与性能优化方案当服务数 30cola 布局确实会陷入“意大利面条”状态。解决方案分三级Level 1前端优化立即生效按Ctrl 0重置缩放按F键聚焦搜索框输入关键词快速定位点击右上角⚙️设置图标关闭Show Labels隐藏节点文字只留图标。Level 2配置优化推荐在.archify.yaml中添加layout: cola: gravity: 0.1 # 降低节点间引力防止过度聚集 linkDistance: 120 # 增加连线长度减少交叉 charge: -100 # 增强节点排斥力Level 3架构优化治本启用--group-by参数按领域分组archify scan --group-by domain # 从 package 名 infer 领域在代码中添加ArchifyGroup(payment)注解需引入 archify-spring-boot-starter用archify cluster --min-size 3自动聚类小服务如把mall-auth,mall-sso,mall-oauth合并为identity-service。实测数据对一个 42 服务的金融项目启用--group-by domain后节点数从 42 降至 9 个逻辑域图面清晰度提升 300%首次渲染时间从 2.1s 降至 0.8s。5.3 “HTML 打不开显示白屏”——浏览器兼容性与安全策略archify 生成的 HTML 在 Chrome/Firefox/Edge 最新版均正常但以下情况会白屏Safari 15.4 及以下不支持CSS.supports(color, oklch(50% 0.2 120))导致样式表加载失败。解决方案在.archify.yaml中设置output.css_format: hex企业内网 IE11archify 不支持 IE官方明确声明“仅支持现代浏览器”。如必须兼容可用archify export --format plantuml生成文本图Strict Content Security Policy如果你的网站启用了 CSP需添加Content-S