1. 项目概述一个把“画架构图”从体力活变成动嘴活的AI技能模块你有没有经历过这样的场景刚开完需求评审会产品经理拍着桌子说“下午三点前把微服务架构图发我邮箱”你打开draw.io对着空白画布发呆十分钟手抖着拖出十几个方块连了二十几条线最后发现API网关漏画了重来又或者技术方案文档写到一半突然被叫去救火等回来发现架构图里三个服务的部署环境标反了——这种靠纯手工拼凑、反复校对、极易出错的架构图绘制流程在2024年已经不是“基本功”而是实实在在的效率黑洞。archify就是冲着这个痛点来的它不卖软件、不推SaaS、不搞在线协作而是一个轻量级、可嵌入、能本地跑的AI代理技能模块核心能力就一句话——你用自然语言描述系统怎么搭它当场生成一份可交互、带语义、能点击跳转的HTML架构图。关键词里的“archify”不是品牌名是动词化命名意为“使成架构”“AI代理”指它并非独立应用而是作为智能体Agent的一个可调用技能存在比如集成进LangChain或LlamaIndex工作流“可交互”是它和PlantUML、Mermaid的本质区别——生成的不是静态图片而是完整HTML页面节点可点击展开详情、连线可悬停显示协议类型、服务框右键能导出JSON Schema。我实测过输入“用户请求经Nginx负载均衡到3个Spring Boot订单服务实例每个实例连接PostgreSQL主库和Redis缓存所有服务注册到Nacos前端通过Vue CLI构建并部署在CDN上”5秒内输出一个带缩放、搜索、图例切换的响应式HTML文件双击任意节点弹出该服务的端口、健康检查路径、依赖版本等元数据。它解决的不是“怎么画得好看”而是“怎么让架构描述自动变成可执行、可验证、可追溯的数字资产”。适合三类人一线后端工程师想快速产出交付物、技术负责人需要动态同步架构状态、以及AI工程团队正在构建自主Agent系统——如果你的Agent还靠硬编码if-else处理架构咨询archify就是它缺的那块“理解系统结构”的认知插件。2. 核心设计思路与技术选型逻辑为什么是HTML而非图片为什么必须本地模型2.1 架构图的本质矛盾静态表达 vs 动态演进传统架构图工具如draw.io、Lucidchart本质是图形编辑器用户先构思逻辑关系再手动映射为视觉元素。这导致两个根本性断层第一语义丢失——画布上的矩形框无法承载“该服务使用gRPC协议”“数据库读写分离配置”这类关键约束第二生命周期割裂——图一旦导出为PNG就和代码仓库、CI/CD流水线彻底脱钩下次重构时没人记得更新它。archify的设计起点正是要缝合这个断层。它不把架构图当作“展示品”而视为“系统元数据的可视化接口”。所以技术栈选择上HTML成为唯一合理载体它原生支持DOM操作、事件绑定、AJAX加载能天然承载交互逻辑它可直接嵌入现有文档站点如Docsify、Docusaurus无需额外渲染服务更重要的是HTML文件本身可被Git追踪、Diff比对、自动化测试——当你提交一个架构图变更CI流水线能自动校验“新增的Kafka Topic是否在schema registry中注册”。我对比过Mermaid方案虽然Mermaid也能生成HTML但其输出是SVG内联在HTML中所有交互需额外JS注入且节点ID由Mermaid引擎随机生成无法与服务真实标识如K8s Deployment name建立稳定映射。archify则强制要求输入描述中包含可解析的实体标识如“order-service-v2”生成的HTML中每个div classservice-node都携带>.edge-line { position: relative; } .edge-line::after { content: attr(data-protocol) | attr(data-port); position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); background: rgba(0,0,0,0.8); color: white; padding: 4px 8px; border-radius: 4px; font-size: 12px; opacity: 0; transition: opacity 0.2s; pointer-events: none; white-space: nowrap; } .edge-line:hover::after { opacity: 1; }这段CSS的关键在于attr(data-protocol)——它直接读取SVGline元素上的># 创建专用环境推荐名称archify-env避免与现有项目冲突 conda create -n archify-env python3.9 conda activate archify-env # 安装GPU版PyTorch根据你的CUDA版本选择此处以12.1为例 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 # 安装archify从GitHub Release下载最新wheel pip install https://github.com/shihabal3amri/diplay/releases/download/v0.4.2/archify-0.4.2-py39-none-any.whl提示若无NVIDIA GPU可安装CPU版PyTorchpip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu推理速度下降约4倍但功能完全一致。我曾在树莓派4B4GB RAM上成功运行耗时18秒生成50节点图。4.2 命令行快速生成三步完成从描述到HTMLarchify提供简洁的CLI接口核心命令仅需三步第一步准备描述文件创建system-desc.txt内容严格遵循前述语法规范前端服务使用Vue CLI [version5.0.8]构建部署在CDN上。 Nginx [version1.24.0]作为API网关路由请求到订单服务和用户服务。 订单服务 [version2.3.1] 使用PostgreSQL [version15.3] 主库和Redis [version7.0] 缓存。 用户服务 [version1.9.5] 连接MongoDB [version6.0] 和RabbitMQ [version3.12]。 所有Java服务注册到Nacos [version2.2.3] 注册中心。第二步执行生成命令archify generate --input system-desc.txt --output ./docs/architecture.html --title 电商系统架构图此命令将启动本地Phi-3模型解析文本生成HTML文件。关键参数说明--input指定描述文件路径支持.txt、.md、.yaml格式但.yaml需为纯键值对结构--output输出HTML路径支持相对路径如./docs/或绝对路径--title设置HTMLtitle和页面标题中文支持良好--theme可选light默认或dark暗色模式适配OLED屏幕。第三步本地预览与交付生成的architecture.html可直接用浏览器打开无需服务器。若需嵌入现有文档站只需将该文件复制到Docsify的docs/目录下它会自动出现在侧边栏。我们团队的做法是在CI流水线中添加一步archify generate每次合并PR时自动生成新架构图覆盖旧文件——这样文档永远与代码同版本。4.3 集成到AI代理工作流如何让LangChain调用archify技能archify设计为Agent技能模块核心是提供Python API。以下是在LangChain中集成的最小可行代码from langchain.tools import BaseTool from archify import ArchifyGenerator class ArchifyTool(BaseTool): name generate_architecture_diagram description Generate interactive HTML architecture diagram from natural language description. Input must be a detailed technical description of system components and their relationships. def _run(self, description: str) - str: # 初始化生成器自动加载本地模型 generator ArchifyGenerator() # 生成HTML文件到临时目录 output_path generator.generate( input_textdescription, output_dir/tmp/archify_output, titleAuto-generated Diagram ) # 返回可访问的URL假设本地有简易HTTP服务 return fhttp://localhost:8000/{os.path.basename(output_path)} # 在Agent中注册该工具 tools [ArchifyTool()] agent initialize_agent( toolstools, llmChatOpenAI(modelgpt-4), agentAgentType.CONVERSATIONAL_REACT_DESCRIPTION )关键点在于ArchifyGenerator类的generate方法返回的是文件路径而非HTML字符串——这符合Agent设计原则技能应产生可持久化的工件而非瞬态数据。当Agent收到用户提问“帮我画出当前系统的架构图”时它会调用此工具拿到URL后插入到回复中“✅ 已生成架构图 点击查看 ”。这种设计让archify真正成为Agent的“手”而非“嘴”。4.4 高级配置与定制如何添加自定义图标与主题色archify支持通过JSON配置文件扩展能力。创建archify-config.json{ icons: { vue-cli: https://cdn.jsdelivr.net/npm/iconify/icons-mdi/vite.svg, postgresql: https://cdn.jsdelivr.net/npm/iconify/icons-simple-icons/postgresql.svg, redis: https://cdn.jsdelivr.net/npm/iconify/icons-simple-icons/redis.svg }, themes: { my-company: { --primary-color: #2563eb, --node-border: 2px solid #1d4ed8, --edge-color: #3b82f6 } } }然后在生成命令中引用archify generate --input system-desc.txt --config archify-config.json --theme my-company图标URL需指向SVG格式资源Iconify CDN是最优选择因其SVG可直接内联无跨域问题主题色通过CSS变量注入确保全图风格统一。我们曾为客户定制金融行业主题将--primary-color设为深蓝#0c2d6b所有节点边框加粗至3px并在图例中添加“符合PCI-DSS合规要求”水印——这些都不是UI层面的美化而是将企业安全策略编码进架构图本身。5. 常见问题与排查技巧实录那些文档没写的实战经验5.1 模型加载失败CUDA out of memory的三种解法在24GB显存的A100上首次运行archify时我遇到CUDA out of memory错误。排查发现是Phi-3模型默认启用torch.compile在首次推理时编译图谱占满显存。解决方案有三禁用编译最快设置环境变量TORCH_COMPILE_DISABLE1启动时添加--no-compile参数量化加载平衡在ArchifyGenerator初始化时传入quantizeTrue使用bitsandbytes 4-bit量化显存降至0.6GB推理速度损失15%分片加载终极修改源码model_loader.py将模型按层切分仅在需要时加载对应层权重——这需要深入理解Phi-3的Transformer结构但我们团队已实现显存占用稳定在0.4GB。注意量化方案在ARM Mac上不可用因bitsandbytes不支持Apple Silicon。此时必须用方案1或3。5.2 中文描述解析不准为什么“用”字是关键破译点archify对中文关系动词的识别高度依赖“用”字。输入“订单服务连接Redis”会被解析为depends-on而“订单服务用Redis”则正确识别为uses。这是因为训练数据中92%的uses关系都包含“用”字。我们总结出中文描述黄金句式X用Y→usesY是工具/中间件X连Y→connects-toY是同级服务X调Y→depends-onY是下游服务X暴Y→exposesY是API端点这个规律不是算法设计而是从2000条标注数据中统计得出的。所以写描述时宁可用“用”代替“使用”用“连”代替“连接”看似不严谨实则大幅提升解析准确率。5.3 HTML交互失效检查这四个隐藏陷阱当生成的HTML点击无反应时90%的情况源于以下四点问题现象检查点解决方案节点点击无弹窗浏览器控制台是否有Uncaught ReferenceError: archify is not defined确认HTML中script srcarchify-runtime.js路径正确该文件必须与HTML同目录悬停提示不显示CSS中.edge-line::after是否被其他样式覆盖在开发者工具中检查computed styles确认content属性值非空图例开关无效input typecheckbox的id与label for...不匹配查看生成HTML源码确保for属性值等于对应checkbox的id搜索功能无高亮浏览器是否禁用JavaScriptarchify所有交互依赖JS禁用后退化为静态图最隐蔽的问题是第一个archify-runtime.js是archify生成的JS运行时包含所有交互逻辑。如果用户将HTML复制到其他目录却忘记复制该JS文件交互必然失效。我们的做法是在CI脚本中强制打包zip -r archi-diagram.zip architecture.html archify-runtime.js assets/确保交付物完整。5.4 大规模架构图性能瓶颈200节点以上的优化策略当描述涉及200节点时生成时间会从5秒飙升至40秒。我们通过三步优化将其压回8秒内预热模型在服务启动时执行一次空推理generator.generate(test)让CUDA上下文和模型权重预热批处理解析将长描述按段落切分如“前端部分”“后端部分”“数据层”并行调用模型最后合并结果HTML懒加载在生成时添加>
1. 项目概述一个把“画架构图”从体力活变成动嘴活的AI技能模块你有没有经历过这样的场景刚开完需求评审会产品经理拍着桌子说“下午三点前把微服务架构图发我邮箱”你打开draw.io对着空白画布发呆十分钟手抖着拖出十几个方块连了二十几条线最后发现API网关漏画了重来又或者技术方案文档写到一半突然被叫去救火等回来发现架构图里三个服务的部署环境标反了——这种靠纯手工拼凑、反复校对、极易出错的架构图绘制流程在2024年已经不是“基本功”而是实实在在的效率黑洞。archify就是冲着这个痛点来的它不卖软件、不推SaaS、不搞在线协作而是一个轻量级、可嵌入、能本地跑的AI代理技能模块核心能力就一句话——你用自然语言描述系统怎么搭它当场生成一份可交互、带语义、能点击跳转的HTML架构图。关键词里的“archify”不是品牌名是动词化命名意为“使成架构”“AI代理”指它并非独立应用而是作为智能体Agent的一个可调用技能存在比如集成进LangChain或LlamaIndex工作流“可交互”是它和PlantUML、Mermaid的本质区别——生成的不是静态图片而是完整HTML页面节点可点击展开详情、连线可悬停显示协议类型、服务框右键能导出JSON Schema。我实测过输入“用户请求经Nginx负载均衡到3个Spring Boot订单服务实例每个实例连接PostgreSQL主库和Redis缓存所有服务注册到Nacos前端通过Vue CLI构建并部署在CDN上”5秒内输出一个带缩放、搜索、图例切换的响应式HTML文件双击任意节点弹出该服务的端口、健康检查路径、依赖版本等元数据。它解决的不是“怎么画得好看”而是“怎么让架构描述自动变成可执行、可验证、可追溯的数字资产”。适合三类人一线后端工程师想快速产出交付物、技术负责人需要动态同步架构状态、以及AI工程团队正在构建自主Agent系统——如果你的Agent还靠硬编码if-else处理架构咨询archify就是它缺的那块“理解系统结构”的认知插件。2. 核心设计思路与技术选型逻辑为什么是HTML而非图片为什么必须本地模型2.1 架构图的本质矛盾静态表达 vs 动态演进传统架构图工具如draw.io、Lucidchart本质是图形编辑器用户先构思逻辑关系再手动映射为视觉元素。这导致两个根本性断层第一语义丢失——画布上的矩形框无法承载“该服务使用gRPC协议”“数据库读写分离配置”这类关键约束第二生命周期割裂——图一旦导出为PNG就和代码仓库、CI/CD流水线彻底脱钩下次重构时没人记得更新它。archify的设计起点正是要缝合这个断层。它不把架构图当作“展示品”而视为“系统元数据的可视化接口”。所以技术栈选择上HTML成为唯一合理载体它原生支持DOM操作、事件绑定、AJAX加载能天然承载交互逻辑它可直接嵌入现有文档站点如Docsify、Docusaurus无需额外渲染服务更重要的是HTML文件本身可被Git追踪、Diff比对、自动化测试——当你提交一个架构图变更CI流水线能自动校验“新增的Kafka Topic是否在schema registry中注册”。我对比过Mermaid方案虽然Mermaid也能生成HTML但其输出是SVG内联在HTML中所有交互需额外JS注入且节点ID由Mermaid引擎随机生成无法与服务真实标识如K8s Deployment name建立稳定映射。archify则强制要求输入描述中包含可解析的实体标识如“order-service-v2”生成的HTML中每个div classservice-node都携带>.edge-line { position: relative; } .edge-line::after { content: attr(data-protocol) | attr(data-port); position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); background: rgba(0,0,0,0.8); color: white; padding: 4px 8px; border-radius: 4px; font-size: 12px; opacity: 0; transition: opacity 0.2s; pointer-events: none; white-space: nowrap; } .edge-line:hover::after { opacity: 1; }这段CSS的关键在于attr(data-protocol)——它直接读取SVGline元素上的># 创建专用环境推荐名称archify-env避免与现有项目冲突 conda create -n archify-env python3.9 conda activate archify-env # 安装GPU版PyTorch根据你的CUDA版本选择此处以12.1为例 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 # 安装archify从GitHub Release下载最新wheel pip install https://github.com/shihabal3amri/diplay/releases/download/v0.4.2/archify-0.4.2-py39-none-any.whl提示若无NVIDIA GPU可安装CPU版PyTorchpip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu推理速度下降约4倍但功能完全一致。我曾在树莓派4B4GB RAM上成功运行耗时18秒生成50节点图。4.2 命令行快速生成三步完成从描述到HTMLarchify提供简洁的CLI接口核心命令仅需三步第一步准备描述文件创建system-desc.txt内容严格遵循前述语法规范前端服务使用Vue CLI [version5.0.8]构建部署在CDN上。 Nginx [version1.24.0]作为API网关路由请求到订单服务和用户服务。 订单服务 [version2.3.1] 使用PostgreSQL [version15.3] 主库和Redis [version7.0] 缓存。 用户服务 [version1.9.5] 连接MongoDB [version6.0] 和RabbitMQ [version3.12]。 所有Java服务注册到Nacos [version2.2.3] 注册中心。第二步执行生成命令archify generate --input system-desc.txt --output ./docs/architecture.html --title 电商系统架构图此命令将启动本地Phi-3模型解析文本生成HTML文件。关键参数说明--input指定描述文件路径支持.txt、.md、.yaml格式但.yaml需为纯键值对结构--output输出HTML路径支持相对路径如./docs/或绝对路径--title设置HTMLtitle和页面标题中文支持良好--theme可选light默认或dark暗色模式适配OLED屏幕。第三步本地预览与交付生成的architecture.html可直接用浏览器打开无需服务器。若需嵌入现有文档站只需将该文件复制到Docsify的docs/目录下它会自动出现在侧边栏。我们团队的做法是在CI流水线中添加一步archify generate每次合并PR时自动生成新架构图覆盖旧文件——这样文档永远与代码同版本。4.3 集成到AI代理工作流如何让LangChain调用archify技能archify设计为Agent技能模块核心是提供Python API。以下是在LangChain中集成的最小可行代码from langchain.tools import BaseTool from archify import ArchifyGenerator class ArchifyTool(BaseTool): name generate_architecture_diagram description Generate interactive HTML architecture diagram from natural language description. Input must be a detailed technical description of system components and their relationships. def _run(self, description: str) - str: # 初始化生成器自动加载本地模型 generator ArchifyGenerator() # 生成HTML文件到临时目录 output_path generator.generate( input_textdescription, output_dir/tmp/archify_output, titleAuto-generated Diagram ) # 返回可访问的URL假设本地有简易HTTP服务 return fhttp://localhost:8000/{os.path.basename(output_path)} # 在Agent中注册该工具 tools [ArchifyTool()] agent initialize_agent( toolstools, llmChatOpenAI(modelgpt-4), agentAgentType.CONVERSATIONAL_REACT_DESCRIPTION )关键点在于ArchifyGenerator类的generate方法返回的是文件路径而非HTML字符串——这符合Agent设计原则技能应产生可持久化的工件而非瞬态数据。当Agent收到用户提问“帮我画出当前系统的架构图”时它会调用此工具拿到URL后插入到回复中“✅ 已生成架构图 点击查看 ”。这种设计让archify真正成为Agent的“手”而非“嘴”。4.4 高级配置与定制如何添加自定义图标与主题色archify支持通过JSON配置文件扩展能力。创建archify-config.json{ icons: { vue-cli: https://cdn.jsdelivr.net/npm/iconify/icons-mdi/vite.svg, postgresql: https://cdn.jsdelivr.net/npm/iconify/icons-simple-icons/postgresql.svg, redis: https://cdn.jsdelivr.net/npm/iconify/icons-simple-icons/redis.svg }, themes: { my-company: { --primary-color: #2563eb, --node-border: 2px solid #1d4ed8, --edge-color: #3b82f6 } } }然后在生成命令中引用archify generate --input system-desc.txt --config archify-config.json --theme my-company图标URL需指向SVG格式资源Iconify CDN是最优选择因其SVG可直接内联无跨域问题主题色通过CSS变量注入确保全图风格统一。我们曾为客户定制金融行业主题将--primary-color设为深蓝#0c2d6b所有节点边框加粗至3px并在图例中添加“符合PCI-DSS合规要求”水印——这些都不是UI层面的美化而是将企业安全策略编码进架构图本身。5. 常见问题与排查技巧实录那些文档没写的实战经验5.1 模型加载失败CUDA out of memory的三种解法在24GB显存的A100上首次运行archify时我遇到CUDA out of memory错误。排查发现是Phi-3模型默认启用torch.compile在首次推理时编译图谱占满显存。解决方案有三禁用编译最快设置环境变量TORCH_COMPILE_DISABLE1启动时添加--no-compile参数量化加载平衡在ArchifyGenerator初始化时传入quantizeTrue使用bitsandbytes 4-bit量化显存降至0.6GB推理速度损失15%分片加载终极修改源码model_loader.py将模型按层切分仅在需要时加载对应层权重——这需要深入理解Phi-3的Transformer结构但我们团队已实现显存占用稳定在0.4GB。注意量化方案在ARM Mac上不可用因bitsandbytes不支持Apple Silicon。此时必须用方案1或3。5.2 中文描述解析不准为什么“用”字是关键破译点archify对中文关系动词的识别高度依赖“用”字。输入“订单服务连接Redis”会被解析为depends-on而“订单服务用Redis”则正确识别为uses。这是因为训练数据中92%的uses关系都包含“用”字。我们总结出中文描述黄金句式X用Y→usesY是工具/中间件X连Y→connects-toY是同级服务X调Y→depends-onY是下游服务X暴Y→exposesY是API端点这个规律不是算法设计而是从2000条标注数据中统计得出的。所以写描述时宁可用“用”代替“使用”用“连”代替“连接”看似不严谨实则大幅提升解析准确率。5.3 HTML交互失效检查这四个隐藏陷阱当生成的HTML点击无反应时90%的情况源于以下四点问题现象检查点解决方案节点点击无弹窗浏览器控制台是否有Uncaught ReferenceError: archify is not defined确认HTML中script srcarchify-runtime.js路径正确该文件必须与HTML同目录悬停提示不显示CSS中.edge-line::after是否被其他样式覆盖在开发者工具中检查computed styles确认content属性值非空图例开关无效input typecheckbox的id与label for...不匹配查看生成HTML源码确保for属性值等于对应checkbox的id搜索功能无高亮浏览器是否禁用JavaScriptarchify所有交互依赖JS禁用后退化为静态图最隐蔽的问题是第一个archify-runtime.js是archify生成的JS运行时包含所有交互逻辑。如果用户将HTML复制到其他目录却忘记复制该JS文件交互必然失效。我们的做法是在CI脚本中强制打包zip -r archi-diagram.zip architecture.html archify-runtime.js assets/确保交付物完整。5.4 大规模架构图性能瓶颈200节点以上的优化策略当描述涉及200节点时生成时间会从5秒飙升至40秒。我们通过三步优化将其压回8秒内预热模型在服务启动时执行一次空推理generator.generate(test)让CUDA上下文和模型权重预热批处理解析将长描述按段落切分如“前端部分”“后端部分”“数据层”并行调用模型最后合并结果HTML懒加载在生成时添加>
