在GitHub上逛项目的时候我被一个叫 archify 的项目勾住了视线。一句话概括它是一套给 AI 代理用的技能模块目标是让代理根据你的文字描述或者代码仓库自动产出一张可交互的架构图。不是那种画完就定死的静态图片而是能拖拽、缩放、点开节点看依赖详情的 HTML 页面。对需要经常输出微服务架构图、系统梳理文档和技术方案评审材料的人来说这几乎是把最耗时的“排版”环节直接外包了出去。如果你已经在用 Claude、OpenClaw 这类代理框架或者只是想本地挂个模型试试水它都能接进去。下面我会从设计思路、部署步骤到实战案例和踩坑记录完整拆一遍。1. 别急着画图先搞懂这张图要解决什么问题1.1 手工画架构图为什么让人头疼我以前画系统架构图用的还是最传统的路子打开 draw.io一个方块一个方块地拉。画二十个节点的图还能忍一旦到了微服务规模五十个节点加上数据库、缓存、消息队列、网关麻烦就来了。对齐要命、分组要命、拉线要命最要命的是图一放大就糊成一团评审会上别人问某个服务到底连了哪几个存储你还得现场数线。这种痛苦本质上不是因为懒而是因为架构图的维护成本被严重低估了。代码在持续变更服务在持续拆分可图的更新永远滞后。画一张图花两小时之后每次改动都要再花半小时调整布局最后干脆不更新了图变成“仅供历史参考”。做技术方案、带新人、排查线上故障都需要一张“信得过”的图。这才是真需求架构图的核心价值不是“好看”而是把系统里那些隐性的依赖关系明确地摆出来。1.2 AI 代理出头抽关系比画图更合适近半年大模型普及之后很多人试过让 ChatGPT 直接生成架构图得到的往往是 Mermaid 代码。小图能看复杂一点的系统一生成就是乱线缠成一团排版完全不可控。问题出在分工上——大模型擅长从非结构化文本里抽取实体和关系但不擅长做精确、稳定的几何布局。你让它一口气既负责理解系统又负责规划坐标结果通常是两头都塌。archify 这类技能模块之所以靠谱就是因为它把这件事拆成了两段大模型只负责“抽取”把服务、存储、调用关系整理成结构化数据渲染交给专门的脚本和模板用成熟的布局算法去摆节点、画连线、做交互。这就像写代码时的分工LLM 负责写业务逻辑编译器负责生成目标代码谁也不越界。AI 代理的价值不是替代掉整条流水线而是让整条流水线里最需要理解力的那一环自动化。1.3 交互能力从“锦上添花”变成刚需很多人不理解为什么非要“可交互”。静态图用 print 发群里不也够吗真不够。系统到一定规模一张平面图塞不下所有信息强行塞进去就是“蜘蛛网”。交互图的好处是分层查看默认看到的是分组后的顶级视图想深入某个模块就点进去链路高亮、节点详情、端口信息都藏在面板里。这跟地图应用的逻辑一样你先 zoom out 看全局再 zoom in 看街道而不是在一张图里把全世界所有路名都标注出来。单个 HTML 文件的产品形态也很有优势离线可以打开分享给同事不用额外装软件嵌入文档站或者知识库也很方便。过去想在评审材料里放一张“能点开看链路”的图得花不少功夫做前端页面现在 AI 代理跑一遍直接输出成品。2. 拆解 archify一个 AI 代理的“出图技能”2.1 技能模块到底是个什么概念“技能模块”这个说法用过 Claude Skills 或者 OpenClaw 的人应该不陌生。它的本质是一个带说明文件的工具包目录核心是一份SKILL.md加上若干可执行脚本。SKILL.md的开头有元信息声明这个技能叫什么、什么时候触发、大概做什么正文里则描述具体的操作步骤和注意事项。代理在跟用户聊天时会根据任务描述自动匹配技能命中之后按说明书调用脚本、编排模型调用、输出结果。archify 就是这样一个技能你把它放进代理的 skills 目录它就成了代理的“专业能力”。打个比方平时 Agent 是个全能实习生你给它装上 archify相当于递给它一本画架构图的专业手册外加一套现成的出图工具。它不需要重新发明方法只需要按手册执行。2.2 输入侧喂给 archify 的三种料按我对这类项目常见实现的理解输入一般有几种形态。第一种是“代码仓库路径”。代理扫描目录结构提取构建配置和依赖声明文件比如package.json、pom.xml、go.mod、docker-compose.yml等同时看一眼目录分层生成一份粗粒度的模块清单再交给大模型判断每个模块的职责和依赖关系。对开源项目或者遗留系统做架构梳理时这种输入最常用。第二种是“自然语言描述”。你直接用大白话说“前端有 A 页面后端有 B 服务存储用 MySQL 和 Redis它们之间是这样调用的”archify 会把你描述里的实体和关系结构化再渲染成图。这种方式最轻量适合快速验证想法也是大多数人第一次上手时用的方式。第三种是“已有的图表文本”。有些系统里已经维护着 Mermaid 或 PlantUML 描述只是排版不好看、交互不够用。部分实现会支持直接把这些文本解析成内部的结构化数据然后重新排版输出成可交互 HTML。相当于给旧图做了一次“交互化改造”。2.3 输出侧为什么是单个 HTML 文件输出端我看过几个类似项目的通用做法基本都是生成一个自包含的 HTML内嵌 SVG 拓扑、样式和交互脚本。没有外链 CDN没有依赖本地服务打开文件就能用。单文件的优势前面说过离线可用、分享方便、可嵌入文档站点。渲染层通常会做这么几件事按分组渲染节点比如接入层、业务层、数据层各占一块区域节点之间画有向连线线上可以标注协议、端口或者调用方式鼠标悬停显示摘要点击节点会在侧面板展示更详细的元信息顶部还可以放一个过滤框输入服务名能快速定位到相关节点和链路。从使用体验上讲它更像一个小型架构浏览器而不是一张静态图。3. 照着做把 archify 接进你的 AI 代理3.1 环境准备实操前先把基础环境弄利索。我这里以 Python 工作流为例因为 skill 里的解析脚本大多用 Python 写的如果你的代理框架是 Node 生态流程类似只是命令不同。建议用虚拟环境隔离依赖别把系统 Python 环境搞乱了。python -m venv .venv source .venv/bin/activate pip install -r requirements.txt # 以仓库实际 requirements 为准模型这块推荐先接本地推理服务比如 Ollama 跑 qwen2.5-coder 或类似支持工具调用的模型。原因很简单免费、数据不出机器、调试方便。如果你有云端 OpenAI 兼容接口也可以但注意公司网络策略和敏感数据问题。接口层面只要兼容/v1/chat/completionsarchify 走起来就没障碍。3.2 安装 skill 到代理不同代理框架的 skills 目录路径不一样我用的是 OpenClaw 风格的目录结构Claude Desktop 等其他框架的路径大同小异以你本机的实际目录为准。# 进入到项目仓库目录后把技能复制到代理的 skills 目录 cp -r archify ~/.openclaw/skills/archify # 验证是否注册上 claw skill list | grep archify这一步走完代理就已经具备调用 archify 的能力了不需要重新编译也不需要“安装服务”。这也是 skill 机制的优势目录即插即用删掉目录就卸载。注意复制完目录后确认SKILL.md在archify目录的根一级别多套了一层目录导致代理找不到描述文件。3.3 配置模型和输出路径我习惯把模型地址、模型名、输出目录用环境变量配置这样切换模型或者调整输出位置不用改代码也方便接入 CI。export ARCHIFY_LLM_BASEhttp://127.0.0.1:11434/v1 export ARCHIFY_LLM_MODELqwen2.5-coder:14b export ARCHIFY_OUTPUT_DIR./arch_output这里解释一下为什么要用 OpenAI 兼容接口而不是各家私有 SDK兼容接口是事实上的工业标准Ollama、vLLM、llama.cpp server 这些本地推理方案都支持切模型的时候只需要改地址和模型名不用重写调用逻辑。类似“写 SQL 用标准语法不绑定具体数据库”的思路。3.4 第一次实战文本描述生成微服务架构图环境配好之后在代理里输入这样一段话请使用 archify 技能根据以下服务清单生成一张微服务架构图API 网关、用户服务、订单服务、支付服务、库存服务、消息队列、MySQL、Redis。依赖关系用户、订单、库存、支付都连接 MySQL 和 Redis订单服务调用支付服务和库存服务所有外部请求先经过网关。运行过程大致分四步代理识别到“架构图”关键词后加载SKILL.md按说明调用解析脚本脚本把你的自然语言描述整理成抽取请求模型返回节点和边的 JSON渲染脚本套用模板生成 HTML。整个流程一两分钟就能完成。第一次跑的时候有个细节很典型模型第一次返回的 JSON 里把“消息队列”识别成了“服务”类型导致图上出现了一个奇怪的中间节点。archify 的校验逻辑检测到类型不符合 schema自动让模型做了一次修正最后才出图。这件事给我留下的印象很深——技能模块的自愈能力比画图本身更有价值。生成的 HTML 文件会输出到ARCHIFY_OUTPUT_DIR下文件名类似arch-diagram-时间戳.html直接双击就能在浏览器里打开拖动节点、缩放画布、点击查看详情都没问题。3.5 用已有代码仓库生成架构图省 token 的两个经验第二种输入形态更实用也更容易踩坑让 archify 分析整个代码仓库。如果直接让模型去读全部源码token 很快就会爆掉而且代码里大量实现细节对架构图没有帮助。我试过比较稳的流程是“脚本预解析 模型精加工”两阶段。先让脚本扫一遍仓库自动收集目录结构、依赖清单、模块入口生成一份精简的候选模块表再把这几十行结构化摘要交给模型让它判断模块职责和依赖关系。这样模型处理的不是几万行源码而是一张“项目骨架清单”既省 token 又不容易被细枝末节带偏。实际操作里的 prompt 可以这么写用 archify 分析当前目录下的 demo 项目生成架构图重点关注服务间 HTTP 调用和数据库访问关系。先做预解析再输出结果。跑完之后我建议你核对三样东西模块分组是否合理、跨组依赖是否正确、有没有凭空多出来的“幻觉模块”。我遇到过模型把测试目录理解成了独立服务也在一次分析中看到它把定时任务标成了“数据审计模块”。这些都需要人工兜底模型终究只是加速器不是百分百可靠的架构师。4. 横向对比为什么不是 draw.io 也不是 Mermaid4.1 四类方案摆在一起看方案生成方式交互能力更新成本适合场景draw.io / Visio手工拖拽一般可做简单链接高图与代码脱节机房拓扑、精细排版、一次性交付图PlantUML文本生成静态图弱基本无交互中改文本再生成追求确定性的流程图、UMLMermaid文本生成图弱GitHub 仓库内渲染方便中README 里的简单流程图、时序图archifyAI 抽取 交互式 HTML强节点点击、链路高亮低代码变更后重跑系统架构梳理、微服务依赖可视化、文档站嵌入有人可能说用 ChatGPT 直接卷 Mermaid 不也一样试过复杂系统的人应该都有体会Mermaid 对简单图友好超过二十个节点后要么报布局错误要么线从图的这头穿到那头几乎没法读。PlantUML 的排版比 Mermaid 更可控但依然是静态图且语法也很繁琐。draw.io 是万能手绘工具可它的产出没法自动跟上代码演进维护成本完全在人。4.2 什么时候不建议用 archify技术选型不能只听优点也得知道边界。我的观点是一是画三五个节点的简易流程图真没必要上 archify。杀鸡用牛刀花在配置模型和验证输出上的时间比手动画图还长。二是需要严格几何精确、等距对齐的图比如机房机柜部署图、网络设备端口连线图这类图要求的是物理位置准确而不是逻辑关系清晰AI 自动布局反而添乱。三是对内网环境有严格要求的团队本地模型是底线。跑一个 14B 参数的模型一张普通显卡或 32G 内存起步如果机器配置不够生成质量和速度都会很难受。所以 archify 的定位不是“替代所有画图工具”而是接管“自动生成与持续更新”这一层它擅长的是把“系统里到底有哪些东西、怎么连着”这件事说清楚。至于最终要不要再导出成规范图片、要不要在特定位置手动微调那是另一码事。5. 实战复盘拿一套开源后台系统练手5.1 从 clone 到架构图的全过程很多朋友喜欢拿开源后台管理系统练手我也一样。我这次直接用一套典型的微服务风格后台功能模块类似芋道那些开源项目来测试 archify。流程是这样的把代码仓库 clone 到本地后让代理运行 archify 预解析先扫出大概的模块列表。后台系统常见的分组马上出来了网关模块、认证模块、系统管理模块、定时任务模块、监控模块底下是 MySQL 和 Redis 这些基础设施。脚本继续读构建配置提取出服务间的 starter 依赖关系整理成候选依赖清单再交给模型做语义确认。渲染出来的第一版图里分组还算对依赖也基本正确。但有个明显问题定时任务模块被模型标成了“data-audit”显然是把 job 相关的类名联想到了数据审计。我在对话里补了一句“这个模块是定时任务不参与业务链路”让它重新生成那一块就老实了。5.2 让图“活起来”迭代更新架构图这套流程最让人舒服的地方是当代码里新增了一个模块时不需要重画任何东西。我重新执行一次 archify它会基于上次的 JSON 结果做增量调整新的模块加进对应分组已有依赖保留只更新变化的部分。生成的第二版图跟我手动维护的图对比基本能对齐。这就是我前面强调的“低成本更新”。架构文档最大的敌人是过期如果每次代码变更都能顺手刷新架构图并且把图嵌到文档站或 PR 描述里评审的人看到的永远是最新状态。这种感觉用传统画图工具给不了。5.3 一个容易被忽略的细节布局参数交互图里最影响观感的不是颜色是布局。第一次生成的图节点多的时候会挤成一团。后来我翻了下渲染脚本发现布局部分用的是力导向算法有几个参数可以调初始半径、节点间斥力系数、迭代次数。在节点很多时我会把斥力系数稍微调大一点让服务节点之间不要贴太近分组之间也可以设置更明显的间距视觉上会清爽很多。这个属于锦上添花的优化不影响功能但直接影响别人拿到图时的第一印象。毕竟架构图是要给人看的观感也是可用性的一部分。6. 常见问题与避坑速查表6.1 问题、原因与解决方案问题常见原因排查与解决代理不触发 archifySKILL.md 的 frontmatter 里没有写触发关键词检查 description 中是否包含“架构图、拓扑、architecture、依赖关系”等触发词模型输出 JSON 解析失败模型返回了 markdown 代码块包裹或格式错乱开启 schema 校验失败后自动让模型重新生成并设置最多重试次数生成的节点重叠、连线混乱节点较多时布局参数不合适调大力导向布局的斥力系数增加分组间距必要时手动固定少数关键节点位置token 消耗远超预期把整个源码目录直接提交给了模型先用脚本做预解析只提交目录骨架、依赖配置和模块摘要输出的 HTML 文件太大节点和样式重复内联引用了大量外部素材合并公共样式、按需加载图标资源尽量把单个文件控制在 5MB 以内本地模型生成质量差模型参数规模太小换 13B 以上并具备工具调用能力的模型对复杂系统分批分析再合并生成的图里出现幻觉模块模型根据类名/文件名联想过度人工核对一次模块清单把误判项在 prompt 中显式排除再重新生成6.2 我自己踩过最深的坑刚开始接入时我遇到的最诡异的问题是代理确实装了 skill但总不调用它。排查了半天才发现SKILL.md的 frontmatter 里 description 写得过于抽象说的是“generate diagrams for software systems”代理跟用户对话时根本没把这句话跟“帮我画一张架构图”关联起来。后来我学到一个技巧把触发描述写具体直接罗列同义触发词比如“架构图、系统拓扑、服务依赖图、architecture diagram、dependency graph”。代理匹配技能靠的是语义相似度关键词越具体命中率越高。这就是那种“文档里不会告诉你但实际用的时候卡你一小时”的隐藏细节。7. 顺着 archify 能往哪走三条延展玩法7.1 接进 OpenClaw给 ROS 机器人系统做可视化社区里已经有人在把类似思路带到 OpenClaw 上配合 ROS 机器人系统做拓扑可视化。ROS 本身就是一套分布式节点架构node、topic、service 天然构成一张大图但官方的 rqt_graph 显示复杂系统时往往乱到没法看。用 archify 的思路让代理解析 ROS 的 launch 文件、topic 列表和节点间通信关系输出一张可交互的“机器人系统关系图”理解整个机器人软件栈的效率会高很多。这就是“技能模块 领域数据源”的组合拳archify 只是第一块积木。7.2 让架构图变成“活的文档”我在实际项目中还做了一件事把 archify 接进了项目仓库的自动检查流程。每次代码合并后自动跑一遍预解析对比新生成的架构图 JSON 和上一版的差异把变化服务列在变更记录里。这样架构图不是一份孤立的文档而是跟着代码库一起演进的“活资产”。做架构评审的时候直接对比两个版本的依赖变化比翻 commit 记录高效得多。7.3 从图反向生成检查清单架构图本身是结构化的 JSON 数据意味着它能二次加工而不只是一张给人看的图。我试过从一个微服务系统生成的 JSON 里自动统计“被依赖最多的服务”做成脆弱节点清单也试过把节点关系转换成部署时的启动顺序建议。这些东西都是顺手用几行脚本就能从 JSON 里捞出来的属于意外的副产品。架构图的生成过程已经把系统的关系数据资产化了一次后续能做的比“看图”多得多。最后再分享一点个人体会。用 archify 跑完十几张图后我最大的感受不是“画图变快了”而是整个流程逼着代理把系统里那些默认的、隐式的依赖关系显性化。你会在核对输出的时候发现自己对系统的理解其实存在不少盲区。如果你也在做架构梳理、写技术方案或者带新人读代码库我建议花半小时把 archify 接进你的代理先拿一个最熟悉的项目跑一遍收获会比看十篇介绍都直观。跑通之后再试试把生成的交互式 HTML 嵌到文档站或者 PR 流程里也许你会开始期待下一次架构评审。