AI代理技能模块archify：从自然语言到可交互架构图的自动生成实践

1. 项目概述与核心思路拆解

1.1 这个项目到底解决什么问题

先聊一个很实在的问题：日常开发里，架构图这事有多让人头疼？

我见过不少团队，需求评审时在白板上画得飞起，等到写文档、做汇报、给新人讲系统的时候，就傻眼了——白板拍照模糊，Visio 画图费劲，Draw.io 导出的 SVG 丑得没法看，更别说遇到需求变更时，图上改一处连线，底下要挪半天节点。

archify 这个 GitHub 项目的定位就很清晰：它不是一个画图工具，而是一个“技能模块”——专门给 AI 代理用的、能自动生成可交互架构图的能力插件。换句话说，你不需要手动拖拽节点、连线、调整布局，而是用自然语言描述你的系统结构，AI 代理直接帮你生成一张能缩放、能点击、能查看详情的交互式架构图。

这个项目的核心价值在于：把“画图”这件事从手动操作变成了对话式生成，同时把静态图片升级为可交互的 HTML 产物，直接嵌入文档、网页或者本地预览。

我看到它时第一反应是：这恰好补上了 AI 编程链路里最容易被忽略的一环——代码能靠大模型生成，文档能靠大模型总结，但架构图长期停留在“人肉绘制”阶段。archify 走的是另一个方向：利用 AI 代理理解系统结构，再通过标准化渲染引擎输出可交互图表。

1.2 为什么选“技能模块”而不是独立应用

这里有个值得展开的设计思路。作者没有把 archify 做成一个需要单独部署、单独启动的服务，而是做成了 “skill” 形态。这个词在 Claude、OpenAI 等 Agent 生态里已经比较常见，它类似给 AI 代理装上一个“专项技能包”——包含预设的提示词、处理逻辑、输出模板和工具调用方式。

选择这种形态有几点实际考量：

• 集成成本低。使用者不需要理解内部实现，只需要在自己现有的 AI 代理流程里调用这个技能，就能获得“生成架构图”的能力。
• 与 Agent 工作流天然契合。现在的 AI 代理已经不是单纯的“问答机器人”，而是能感知上下文、调用工具、分步执行任务的智能体。技能模块就是给代理补充“特定领域能力”的组件，比单体应用更灵活。
• 便于版本演化和共享。GitHub 上托管一个技能模块，其他人可以直接 clone 下来集成到自己的代理配置里，相当于一个可复用的“乐高积木”。

如果类比的话，archify 之于 AI 代理，类似于“插件市场”之于 IDE——它不是 IDE 本身，但装了它，IDE 能干更多事。

1.3 项目的使用流程与适用人群

从实际使用角度来看，archify 的工作流大致是：

1. 用户向 AI 代理描述系统架构（比如“一个前后端分离的电商系统，前端 Next.js，后端 Spring Boot，数据库 MySQL，用 Redis 做缓存，Nginx 做反向代理”）。
2. 代理调用 archify 技能，解析这段描述，提取实体和关系。
3. archify 内部将解析结果映射为节点和连线，按照预设的布局算法生成图形数据。
4. 输出 HTML 格式的可交互架构图，支持缩放、平移、节点点击展开详情等操作。

这套流程适合的人群很广：后端工程师画服务依赖图，前端工程师画组件结构图，架构师画系统部署图，技术写作人员给文档配交互示意图，技术管理者做方案汇报——只要你是“需要用图表达系统结构”的人，都能从中省下不少时间。

2. 核心细节解析与技术原理解读

2.1 可交互架构图的实现方式

先聊聊“可交互”这三个字背后的技术含义。传统架构图是图片格式（PNG、SVG），画完就固定了，读者只能看，不能操作。archify 走的是“HTML + JavaScript”渲染方案，其交互能力通常基于以下几类技术实现：

• SVG 与 Canvas：用于绘制节点、连线、分组区域等图形元素。SVG 对 DOM 节点和事件绑定支持好，适合节点数量可控的架构图（一般几十个节点足够）；Canvas 性能更猛，适合超大规模节点渲染，但交互事件需要自己算命中检测。
• 缩放与平移：基于 viewBox 变换或者独立的 transform 状态管理，配合鼠标滚轮事件和拖拽事件。
• 节点折叠与展开：架构图里的分组（比如“业务层”“数据层”）可以展开看内部细节，也可以折叠成一个大节点，这对复杂系统特别有用。
• 点击详情弹层：点击某个节点弹出该组件的详细说明，比如技术栈、接口地址、依赖关系等。

作者选择 HTML 输出而非图片，我认为是刻意为之。因为架构图的核心价值是表达“结构”，而结构是分层的、动态的、可探测的——静态图片丢失了这种信息维度，可交互 HTML 则保留了阅读者的自主探索权。

2.2 AI 代理解析架构描述的底层逻辑

archify 作为 AI 代理的技能模块，其核心难点不在于后端渲染，而在于如何把模糊的自然语言转换成结构化的图形数据。我梳理了一下，这里面大概有三层逻辑：

第一层：实体识别。AI 代理需要从用户的描述中提取“有哪些东西”。比如“前端”“后端”“数据库”“缓存”“消息队列”，这些是图上的节点。注意，这些节点往往有类型属性（应用、中间件、存储、网关），代理需要根据语义去归类。

第二层：关系抽取。识别出“谁连谁”。比如“前端调用后端”“后端读写 MySQL”“后端订阅 Kafka 消息”，这些是图上的边。关系还可能带有方向性、类型（HTTP、RPC、消息、数据库访问）。

第三层：布局计算。拿到节点和关系之后，需要决定节点摆在哪里。常见的布局算法有分层布局（适合表达上下层依赖）、力导向布局（适合表达去中心化拓扑）、环形布局（适合表达对等集群）。archify 这类工具一般会根据图的特征自动选择布局，或者让用户通过参数指定。

这三层里，前两层考验 AI 代理的理解能力，第三层考验图形算法功底。作者把这二者结合，本质上是在做一个“自然语言 → 图结构 → 可视化坐标 → 可交互界面”的完整管线。

2.3 GitHub 项目落地中的工程化取舍

再看项目工程层面的细节。从仓库结构来看，archify 采用了“技能包 + 生成脚本 + 示例输出”的标准组织方式：

• 技能定义文件：描述了技能的名称、描述、参数形式和调用方式，让代理能识别什么时候该用这个技能。
• 处理逻辑模块：负责与 LLM 交互、解析结构化输出、生成图形数据。
• 渲染模板：HTML 模板，接收图形数据后渲染成可交互页面。
• 示例目录：提供了几个典型的架构图例子——应用架构图、数据流图、系统部署图，方便使用者快速理解产出效果。

这种工程组织方式的优点是模块边界清晰：技能定义和渲染逻辑解耦，想换渲染框架（比如换成 Mermaid、D3.js、或者自研渲染器）时不需要动 Agent 交互层。从设计哲学上说，作者遵循了“单一职责 + 面向接口”的原则，这也是技能模块能够跨平台复用的关键。

3. 实操过程与核心环节实现

3.1 本地快速体验的完整步骤

如果你想在本地跑起来体验一下，我给一套实测可行的操作路径。假设你已经具备基础的 Python 或 Node 环境（archify 这类项目通常用 JavaScript 或 Python 编写，具体以仓库 README 为准）。

第一步，拉取项目：

git clone https://github.com/your-archify-repo.git cd archify

第二步，安装依赖。如果是 Python 项目，通常用 pip 或者 uv；如果是 Node 项目，则用 npm 或 pnpm。这里我以 Python 举例：

python -m venv .venv source .venv/bin/activate pip install -r requirements.txt

第三步，配置 AI 代理的后端模型。archify 作为技能模块，通常需要对接一个 LLM 接口来充当“理解自然语言”的引擎。这里有两类选择：

• 云端模型：配置 OpenAI 兼容接口，填入 API Key 和模型名。适合对响应速度、理解能力要求高的场景。
• 本地模型：通过 Ollama 或 llama.cpp 启动本地模型，配置为 OpenAI 兼容模式。适合数据私密性要求高、或者不想产生 API 费用的场景。

提示：如果你用的是本地模型，建议选择参数规模较大的模型（如 13B 以上），因为架构描述中的实体和关系抽取需要一定的推理能力，小模型容易出现“漏提实体”或“关系方向搞反”的问题。

第四步，运行示例：

python main.py --input examples/ecommerce.txt --output output/ecommerce.html

打开生成的ecommerce.html，你会看到一张可以缩放、拖拽、点击节点的架构图。

3.2 自定义架构描述的最佳实践

工具本身不复杂，真正拉开使用体验差距的，是你怎么描述系统。我第一次尝试时写的是：

“有个电商系统，前端用 Vue，后端用 Spring Boot，数据库 MySQL，有 Redis 缓存。”

结果生成的图只有四个孤零零的节点，连线的语义也不清晰。后来我改成结构化描述，效果明显提升：

电商系统架构： - 用户通过浏览器访问前端应用（Vue 3，部署在 Nginx） - 前端应用通过 RESTful API 调用后端网关（Spring Cloud Gateway） - 网关将请求路由到订单服务（Spring Boot）和商品服务（Spring Boot） - 订单服务和商品服务通过 MyBatis 读写 MySQL 数据库（主从架构） - 订单服务和商品服务通过 Redis 缓存热数据 - 订单服务发送消息到 Kafka，库存服务消费 Kafka 消息实现库存扣减

对比一下就知道差异在哪里：

1. 明确节点类型：每个组件旁边标注了技术栈或角色（网关、服务、存储、中间件）。
2. 明确交互关系：每次“连接”都用动词描述（调用、读写、发送、消费），方便代理识别边的方向。
3. 按层组织顺序：从上到下依次是接入层、应用层、数据层，代理更容易推断分层布局。

如果你的系统比较复杂，我建议先用一句话概括整体，再逐个分层展开，让代理从“宏观到微观”理解你的意图。

3.3 定制渲染输出与集成到自动化流程

除了单独生成 HTML，archify 还可以嵌入到更大的自动化链路里。我在实际使用中做了两个改造，一个是加了“文档自动化生成”的环节——把架构图和设计文档打到同一个页面里，交付给团队时整洁省事；另一个是给 archify 接入了变化检测流程——代码仓库里的服务模块改了依赖关系后，自动触发重新生成架构图，确保图纸不“过期”。

具体实现上，核心就是写一个简单的脚本：

#!/bin/bash # 拉取最新代码变更描述，重新生成架构图 archify --input service_descriptions.md --output docs/arch.html git add docs/arch.html git commit -m "docs: 自动更新架构图"

这样架构图不再是“画一次就忘了”的静态资产，而是能随代码变更持续演化的活文档。这一点我觉得是 archify 这类工具最有杀伤力的应用场景——把架构图纳入 CI/CD 管线，才能让图纸真正跟上代码。

4. 常见问题与排查技巧实录

4.1 生成结果不符合预期的排查思路

我在试用过程中遇到最多的问题就是“图生成了，但不是我想要的”。归纳下来大致有这几类：

问题一：节点数量不足。明明描述了二十个组件，结果图里只有五六个节点。这通常是 LLM 在信息抽取时丢了实体。解决方法是把描述写得更显式：给每个重要组件单独列一行，不要让多个组件挤在一个句子里。从我的实测来看，结构化列表描述的实体召回率远高于散文式描述。

问题二：连线方向反了。比如“订单服务调用库存服务”，图上却画成库存服务指向订单服务。排查时先检查原文是不是用了被动语态，再就是你检验 LLM 是否有明确的“方向判定”指令。如果代理配置支持，可以在技能描述里强调“箭头方向表示调用发起方指向被调用方”。

问题三：布局乱成一团。几十个节点挤在一起，连线交叉严重。这种问题大概率是布局算法选择不当。处理办法是明确指定布局方式，比如“按访问链路从上到下分层布局”“按业务域分块布局”，或者调整画布尺寸参数，给图形更大的空间。

4.2 模型选型与响应不稳定的应对

用本地模型跑这个项目时，我最开始用的是 7B 参数的模型，结果实体识别经常漏，连线的描述也比较混乱。换到 13B 模型后效果有显著提升，但推理速度变慢了，每次生成要等二十秒以上。

如果你对实时性要求高，我建议这样搭配：

• 日常体验：使用云端 API 模型，速度快、理解准，不用担心资源占用。
• 敏感场景：使用本地 13B 以上模型，虽然慢一点，但数据不出本机，安全性更好。

另外，LLM 输出本身有随机性，同一段描述，两次生成的图可能略有差别。如果项目对一致性要求高，可以固定 temperature 参数（比如设置为 0.1~0.2），让输出更稳定。我在实际使用中，把 temperature 降下来之后，重复生成的图结构基本大差不差，细节上偶尔会有微调。

4.3 浏览器兼容与性能优化的实测观察

可交互 HTML 架构图在不同浏览器里的表现有差异。我分别在 Edge、Chrome、Safari 和 Firefox 中打开过生成结果，主要发现：

• Chrome 和 Edge 的 WebGL 硬件加速对超大画布拖拽比较友好，操作顺滑。
• Safari 对复杂 SVG 的阴影效果支持有点问题，偶尔会渲染成色块，暂时可以关掉阴影效果规避。
• Firefox 在缩放动画上偶尔有性能卡顿，如果节点数量超过两百个，建议切换成 Canvas 渲染模式。

如果你打算把架构图嵌进公司文档系统，建议先在一个内部页面做测试，确认渲染效果和交互行为都符合你团队浏览器的实际环境。

5. 扩展玩法与进阶实践思路

5.1 从架构图到文档体系的打通

架构图单独存在价值有限，真正让它发光的是“与其他文档联动”。我目前的用法是：

1. 架构图作为一个 iframe 嵌入 Confluence 或 Notion 页面。
2. 旁边配一段架构说明文档，引用图中的节点名称。
3. 再配上 API 清单和部署拓扑表，形成一套完整的系统说明页。

这样团队查阅系统设计时，不用来回翻多个文档，在一页上就能看到“图 + 文 + 接口 + 部署”的完整信息。

5.2 结合 DIPlay 等相似项目构建更完整的 Agent 技能栈

大家在 GitHub 上搜架构图相关项目时，可能还会看到DIPlay这类同方向的工具。我不建议把多个类似项目堆在一起用，更好的做法是：先选一个作为主力（archify 就很顺），看它缺什么，再用其他项目的能力做针对性补充。比如 archify 擅长系统架构图生成，DIPlay 可能在 UI 交互细节、特定场景的图类型上有差异，两者结合这时候就能既保证生成速度，又拿到更精致的表现力。

如果你的 AI 代理是基于差异化技能栈构建的，可以想象这样一套组合：archify 负责系统架构图，另一个技能负责接口文档生成，再有一个技能负责部署拓扑绘制，三个结果拼在同一份交付文档里。这套组合拳看似简单，但对于技术架构师、解决方案工程师来说，能省下的时间相当可观。

5.3 把生成能力做成团队共享服务

如果团队里多人都在用 archify，各自在自己电脑上装一份显然不是高效的做法。更合理的方案是：把它封装成一个内部微服务，通过 FastAPI 或者 Express 起一个 HTTP 接口，团队成员用同样的 Prompt 就能拿到架构图 HTML。

我当时是这样做的：

from fastapi import FastAPI from pydantic import BaseModel app = FastAPI() class ArchRequest(BaseModel): description: str title: str = "系统架构图" @app.post("/generate-arch") def generate_arch(req: ArchRequest): html = archify_generate(req.description, req.title) return {"html": html}

团队里其他人只需要调用这个接口，传入一段架构描述，拿到的是可直接嵌入网页的 HTML 字符串。这比每个人源码级使用要有价值得多。

6. 避坑指南与个人实操心得

6.1 这三个坑我替你踩过了

第一个坑：过度依赖 AI 自动布局。大部分情况下 AI 的布局算法足够用，但一旦图里超过三十个节点，自动布局就容易变得杂乱。我的解决办法是：描述时手动加上“分组”和“层级”提示，让代理优先按照人为经验划分的分区来布局，而不是让算法从头算。

第二个坑：忽略节点详情的信息组织。早期我生成的图只有节点名称，团队成员根本看不出这个节点到底是干什么的。后来我会在描述里顺手给每个重要节点写明功能注释和技术栈，这样生成的图点击节点时才能展示有价值的信息，而不是空有一个名字。

第三个坑：把架构图当作一次性产物。架构是会变的，今天画的图，三个月后可能完全不准确。如果你只是画一次然后存着，那不如不画。我给自己的要求是：至少每迭代一个版本更新一次架构图，最好是把上面提到的自动生成脚本挂到 CI 流程里。

6.2 让 AI 生成架构图更可控的三个参数心得

经过多轮实验，我发现有三个参数对上文提到的“可控性”影响最大：

如果说架构图生成是对 LLM 的结构化能力考验，那么这些参数就是“驯服”随机性的缰绳。每次我觉得“这次怎么生成得乱七八糟”，十有八九是参数没有针对场景调校好。

6.3 后续可扩展的方向

从我个人的经验来看，archify 往这个方向深入会有很大的想象空间：

• 导出格式扩展：除了 HTML，后续如果能导出 SVG、Markdown 内嵌的 Mermaid 源码，实用性会大增。
• 多人协同与评论：好的架构图往往不是一次画完的，而是团队反复讨论迭代出来的。加上评论、批注能力，它就从一个“绘图工具”变成了“架构协作工具”。
• 语境记忆与自动更新：如果 AI 能记住上次生成的架构，在描述变更时只做局部更新，而不是全量重新生成，效用会再上一个台阶。
• 与代码库直接联动：如果能扫描代码仓库中的配置、API 路由、依赖文件，自动推导出候选架构，再让 AI 代理基于这份候选做精修，想象空间就更大了。

我自己已经在试“代码库扫描 + 架构图生成”的连续动作了——从 Spring Boot 的pom.xml、Kubernetes 的deployment.yaml里提取关键信息，拼合进描述文本，再交给 archify 生成图。目前虽然还是半自动状态，但这个方向跑通之后，架构图才能真正成为“系统的投影”。

最后分享一点个人经验：这类工具能不能带来实际的效率提升，关键不在于工具本身多强大，而在于你是否愿意把画图这件小事从“手动模式”迁移到“对话模式”。刚开始你可能觉得描述系统比拖拽画图还累，但等你熟练了，你会发现写描述其实是在倒逼你把系统结构想得更清楚——很多人对系统说不清楚，等他们试着用一段话描述架构时，才意识到自己根本没有摸清系统的全貌。从这个角度说，archify 既是画图工具，也是一面帮助团队梳理系统认知的镜子。