企业官网建设流程全解析

在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/completions，archify 走起来就没障碍。

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_BASE="http://127.0.0.1:11434/v1" export ARCHIFY_LLM_MODEL="qwen2.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 也不是 Mermaid

4.1 四类方案摆在一起看

有人可能说，用 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 问题、原因与解决方案

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 流程里，也许你会开始期待下一次架构评审。