企业官网建设流程全解析

1. 项目到底在解决什么问题

今天想认真聊一个我最近在 GitHub 上测下来觉得思路很对的项目：archify。一句话概括，它是一个能让 AI 代理自动生成可交互架构图的技能模块。你只需要用自然语言描述一个系统、一段业务逻辑，甚至直接指向一个代码库，AI 代理就能帮你梳理出组件、依赖、数据流，并产出一张能缩放、点击、高亮的架构图，而不是一张看完就不知道下一步点哪儿的静态 PNG。

这类项目的价值，得放在真实的软件维护场景里才能体会。我过去画架构图，基本逃不出三种方式：用 Draw.io 手拖框、用 PlantUML 手写描述、或者靠白板上墙拍照。三种方式的共同痛点是：图永远是"某个时间点的快照"。系统改了，图没改；别人问某个模块到底依赖什么，你得回去翻半天代码。而 archify 的思路是让 AI 代理充当"架构记录员"，随时描述、随时出图，直接把架构信息变成可以持续维护的动态资产。这一套玩法对技术负责人、后端开发、架构师和做系统文档治理的人都有参考价值，这篇就把我的实测过程和踩坑记录完整放出来。

1.1 技能模块，不是又一个画图工具

先得把"技能模块"这个词拆清楚。GitHub 上画架构图的工具很多，但大部分是独立应用——你打开它，手动建模、连线条、导出图片。archify 的定位不一样，它更像是给 AI 代理装上的一个"专业技能包"。

我理解它的工作方式是这样的：AI 代理（Agent）本来就擅长拆解任务，但它不一定知道"架构图"应该长成什么样、包含哪些信息、用什么格式表达。archify 这个技能模块，本质上就是把画架构图的专业方法论、提示词模板、输出格式定义和渲染逻辑打包在一起，让代理在需要时能直接调用。

这个设计有一个很明显的优势：可组合。你可以在同一个代理环境里同时挂上代码检索技能、架构图技能、文档生成技能。代理理解你的问题后，自己决定先用哪个技能、按什么顺序用。比如你说"把订单服务重构后的依赖关系整理成图"，它会先分析代码，再调用 archify 生成图，最后配合文字说明输出。整个过程不需要你在多个工具之间来回切换。

我在实际使用中最大的感受是，这种"技能化"设计让架构图的生成门槛变得非常低。过去画图的前提是你已经想清楚了架构，工具只是帮你表达；现在 archify 承担了一部分"替你思考"的工作，它会主动询问边界、推断依赖、发现潜在的外部调用。对还在需求梳理阶段、脑子里只有模糊轮廓的人来说，这种引导能力比画图本身更有价值。

1.2 可交互架构图，解决的是"看图"问题

为什么强调"可交互"？因为架构图的价值不在于画得好看，而在于能不能被人真正用起来。静态架构图的信息密度是固定的，节点和连线画上去之后，看的人只能被动接受。系统稍微复杂一点，几十个节点挤在一张图里，视觉上就成了一团毛线。

可交互架构图解决的是这个"信息过载"问题。它把大量关系信息藏在一层交互外壳下面：你可以点击一个服务节点，只看它上下游的依赖；可以按业务域过滤，隐藏无关模块；可以拖动布局，重点观察某条调用链；甚至可以悬停查看节点元数据。这些交互手段让同一张图在不同场景下呈现出不同视图，从"一张图打天下"变成"一张图自适应多种问题"。

archify 选择这种方式，我认为是和 AI 代理的产出特点有关的。AI 生成架构信息时，往往一次性给你一大坨结构化数据，里面实体、关系、属性全混在一起。如果直接平铺渲染成静态图，信息密度太高，根本没法看。而用可交互的方式承载这些数据，既保留了信息的完整性，又让读者可以按需探索。这算是把 AI 的"输出冗余"转化成了"交互深度"。

2. 拆开看：archify 的核心设计思路

很多开源项目一眼能看懂，但真到自己用就抓瞎。archify 属于那种"设计思路比代码体积更有嚼头"的项目。我建议你在跑通示例之前，先花半小时理解它的数据流，后面遇到问题会好排查很多。

2.1 从一句描述到结构化架构信息

archify 的管线可以分成三段：理解、结构化、渲染。理解阶段由大模型完成，输入是你对系统的描述，或者是一段代码目录树；结构化阶段是它最核心的部分——大模型把模糊的自然语言转成严格的架构数据模型，包括节点（服务、数据库、消息队列、外部系统）和边（调用、依赖、事件订阅）；渲染阶段再把结构化数据变成 HTML 中的可交互视图。

我用一个生活化的类比：这就像一个经验丰富的系统分析师坐在你面前，你跟他口述"我们有个会员系统，用户下单后要调积分服务，积分变更记录写进 MySQL，并且发一条消息给通知中心"。他听完不会直接画图，而是先在脑子里形成一张清单：有几个组件、组件之间是什么关系、哪些是外部依赖。然后才动手把清单变成正式图纸。archify 里的 LLM 就是那个分析师，而技能模块里精心设计的提示词和输出约束，就是分析师脑子里那张"清单模板"。

这个清单模板比想象中重要。没有约束的模型输出往往很散，一会儿用"调用"表示关系，一会儿又用"使用"，一会儿把数据库画成一个节点，一会儿又把表结构展开成五个节点。archify 通过输出格式约束（通常是指定 JSON Schema 或类似的严格格式），逼着模型按统一标准输出。这保证了后续渲染的一致性，也让你在不同项目之间看到的架构图风格统一。

2.2 交互层的输出结构：不只是图片

我看过不少声称"AI 生成架构图"的项目，最终输出要么是一张图片，要么是一段 Mermaid 文本。图片无法检索内部信息，Mermaid 文本虽然能表达关系，但交互能力有限。archify 的差异点在于，它生成的是一个完整的交互式视图。

从实现路径来看，比较合理的设计是：**模型先输出一个中间态的 JSON 架构模型，前端拿到这份 JSON 后，用图可视化库（比如 D3.js 或类似方案）把节点和关系渲染成可拖拽、可缩放、可点击的图形。**这样就把"数据生成"和"数据展示"彻底解耦了。JSON 是事实来源，渲染层只是事实的视觉化投影。你可以修改 JSON 之后重新渲染，也可以换一套渲染界面，而不需要重新让模型生成。

这种解耦带来一个很实用的玩法：你完全可以绕过默认的渲染界面，把 archify 产出的 JSON 接到自己的系统里。比如内部有个配置管理后台，想嵌入架构视图，只需要复用它的渲染组件，数据还是那份 JSON。我在试用时就是直接解析 JSON 文件，写了个脚本统计某个服务被哪些模块调用，效果很好，没有动任何模型相关代码。

2.3 为什么和本地模型是绝配

现在很多 AI 代理工具默认接的是云端大模型 API，但架构图场景有一个天然矛盾：**你想画的往往就是公司最核心的系统拓扑，其中可能包含敏感的服务名、网络地址、内部数据流。**把这些信息送到外部 API，很多团队是不放心的。

archify 这类技能模块很适合搭配本地模型使用，这也是我关注它的一个重要原因。本地模型（通过 Ollama、LM Studio、vLLM 这类工具跑在你自己机器上）保证架构数据不出内网，同时因为技能模块本身只是"方法论包"——提示词模板、数据格式定义、渲染代码——它对模型的推理能力有一定要求，但不是越强越好。

我实测下来，本地推理能力在中等偏上的模型（比如 32B 以上参数级别）已经能完成大部分架构抽取工作。小模型容易漏关系，尤其是隐式的跨服务调用很难识别；大模型虽然准确率高，但对硬件要求也高。实际部署时，我建议你根据项目规模做取舍：画单体应用架构，14B 级别的模型够了；画几十个微服务的系统拓扑，至少得准备 70B 级别的模型或者量化版本。这算是"AI 代理助手加本地模型"组合里一个比较典型的落地场景。

3. 实操记录：从 clone 项目到生成第一张可交互架构图

理论说再多，不如亲手跑一遍。这一节我把从 GitHub 拉取项目、配置模型、生成第一张图的全过程记录下来。注意项目迭代很快，具体命令可能和你 clone 到的版本有细微差异，但整体的流程是稳定的。

3.1 环境准备和最小安装

我是在一台 Ubuntu 22.04 服务器上做的测试，Python 版本 3.11，Node.js 版本 18。archify 的安装方式属于典型的 Python 项目风格，先建虚拟环境再装依赖：

git clone https://github.com/你的账户/archify.git cd archify python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt

如果你的使用场景主要靠浏览器渲染，别忘了渲染依赖可能涉及 Node 端的东西。我看到部分版本会在首次渲染时自动调用前端构建工具，如果报缺 npm 包，就进frontend目录执行npm install。整个过程没什么黑魔法，但有两个细节建议你注意。

第一，尽量用虚拟环境，别图省事装到系统全局。这个项目的依赖里有不少 AI 生态的库，和系统里其他 Python 工具容易冲突，虚拟环境能帮你把麻烦隔离掉。第二，如果你打算用本地模型，提前确认好推理框架的兼容性。比如 Ollama 默认的模型格式和项目调用的接口是否匹配，有些版本需要你额外装一个 OpenAI 兼容层。我一开始在接口配置上卡了二十分钟，其实就是没搞清楚这层关系。

3.2 配置模型接入

archify 的模型配置我做下来觉得挺灵活的。它支持多种接入方式，包括 OpenAI 兼容接口、本地推理框架的 HTTP 接口，以及一些代理框架原生支持的工具调用方式。你需要做的事，本质上就是把"模型服务地址"和"密钥"告诉它。

以我用的配置为例，编辑项目根目录下的.env文件：

MODEL_PROVIDER=openai_compatible MODEL_BASE_URL=http://localhost:11434/v1 MODEL_NAME=qwen2.5:32b MODEL_API_KEY=ollama

如果走云端 API，那MODEL_BASE_URL和MODEL_API_KEY换成对应服务的值和密钥，MODEL_NAME改成具体的模型名就行。这里有个判断标准：**只要模型服务提供的是 OpenAI 兼容的/v1/chat/completions接口，理论上都能直接接入。**现在 Ollama、vLLM、LM Studio 这些主流的本地推理工具都支持这个协议，所以配置路径基本是通用的。

我比较推荐先本地模型后云端模型的顺序，原因有两个：一是本地模型调试方便，不用反复等网络请求，迭代提示词时体感快很多；二是架构数据本来就敏感，直接用本地模型从一开始就避免了数据出网的问题。等你的提示词和流程稳定了，再切换到更强的云端模型做大规模分析，心态会稳很多。

3.3 喂入项目描述，跑通完整流程

配置好模型之后，我建议不要一上来就拿真实的大项目试，先用一个小场景跑通端到端流程。我的做法是新建了一个演示目录，模拟一个简化版的电商系统：

用户服务（用户注册、登录、资料查询） 商品服务（商品列表、库存查询、价格管理） 订单服务（创建订单、查询订单） 订单服务依赖用户服务和商品服务 订单创建后写 MySQL，同时发消息给 Kafka

然后运行 archify 的抽取命令。我测试时用的是类似这样的命令格式：

python -m archify extract --input ./demo-system.md --output demo-arch.json python -m archify render --input demo-arch.json --output demo-arch.html

第一条命令让代理根据描述文件生成结构化架构信息，输出 JSON；第二条命令拿到 JSON 渲染成交互式 HTML。跑完之后直接打开 HTML，应该能看到几个独立节点和依赖连线，鼠标悬停在节点上会有信息提示，点击某个服务还能过滤出它的上下游链路。

第一次看到输出时，我的感受是：它比我想象中"懂架构"。比如我说"订单服务依赖用户服务和商品服务"，它没有简单地把三者画成平级调用，而是把用户服务和商品服务识别为被依赖方，把订单服务识别为调用方，并且根据常识补充了"用户服务可能包含数据库节点"这类细节。当然这种补充有时候会过度，后面排查技巧里细说。

3.4 定制输出的几个实用技巧

跑通示例只是第一步，真正让 archify 好用起来的是定制化调整。我把测试过程中验证有效的几个技巧列一下。

第一，描述信息要带边界。直接说"画出系统架构"太含糊，模型会自己脑补一堆外围系统。我试下来最稳的格式是：明确列出有哪些模块、模块的职责、谁调用谁、外部系统边界在哪里。第二，善用"排除提示"。比如"忽略数据库表结构，只到数据库实例这一层"或者"不展示日志监控类基础设施"，这种负向约束能显著减少图中无关节点。第三，给节点定义分组标签。在描述里注明"核心交易域"、"营销域"、"基础支撑域"，输出 JSON 里的节点就会带上分组信息，渲染时可以直接按域着色。

还有一个容易忽略的地方：**产物 JSON 是人工可读的，别只当成中间格式。**我在测试中改了不少 JSON 内容，比如把模型误判的依赖关系改掉、补充吞吐量或负责人等元数据字段，然后重新 render，整个过程不需要重新调用模型。这让 archify 变成了一种"半自动"的架构工具：AI 出初稿，人来校对微调，最终结果完全可控。这种协作模式我认为是它未来在真实团队里能落地的关键。

4. 踩坑实录：常见问题速查与排查思路

任何和 LLM 相关的工具，使用体验里必然伴随玄学问题。archify 也不例外。下面这些坑我基本都踩过一轮，整理成速查表和排查思路，希望能帮你省点时间。

4.1 高频报错速查表

这些问题的共同特征是：错误信息不一定直接指向根因。比如 JSON 解析失败，表面上是格式问题，实际是上下文窗口被塞满了。所以我排查时养成了一个习惯——先看输入 token 数，再看模型输出原文，最后才怀疑代码层面的问题，顺序反了会非常浪费时间。

4.2 四个隐蔽坑位和排查顺序

第一个隐蔽坑是外部依赖识别不完整。架构图最怕的不是画错内部关系，而是漏掉外部系统。模型默认倾向于在给定描述范围内找关系，如果描述里没明确提到 Redis、Kafka、支付网关这类外部系统，它很可能根本不画。我测试时明明在代码里看到用了 Redis，架构图里却没有任何 Redis 节点。后来我学会了在描述里主动加上一句话："注意识别描述中隐含的外部依赖中间件"，情况改善很多。

第二个坑是循环依赖画成环。在微服务架构里，A 调 B、B 调 C、C 又调回 A 的情况很常见，模型会忠实地画成三角环。从架构图角度这没问题，但可交互界面里的布局算法遇到环有时候会卡顿或连线错位。我的处理方法是：分析 JSON 里的关系列表，找出成环的路径，手动标注"疑似循环依赖"标签，并在渲染时单独高亮，方便阅读者识别问题。

第三个坑是元数据污染。模型有时会把一些非架构信息填进字段，比如在节点描述里加一句"该服务性能较差需要优化"，这类主观判断混进架构数据里会破坏数据的严肃性。我现在的做法是，在提示词里明确要求节点描述只能包含客观技术信息，优化建议等主观内容放到单独的notes字段，不能在架构图默认视图里出现。

第四个坑我认为最值得提醒：**输入描述里的一句话，可能被放大成一堆节点。**比如我说"系统用了 MySQL 做存储"，模型可能把 MySQL 的 InnoDB、连接池、主从架构全展开成独立节点。对付这种过度展开的办法是设置抽象层级参数——明确告诉模型"只展示到服务实例层面，不展开中间件内部结构"。我每次新增项目都会先检查一次输出里有没有这种"意外展开"，早发现早止损，别等渲染完才开始后悔。

5. 我的使用感受与后续玩法

最后聊点实际使用后的体会。archify 给我的最大启发不是"AI 能画图"这件事本身，而是它把架构信息当作了一种可持续维护的数据资产，而不是一次性交付物。以前我画的架构图，过两个月就和代码分家了；现在我会定期把项目的架构描述更新一下，让代理重新抽取一遍，对比前后 JSON 的差异，就能直观看到系统架构的演变轨迹。这种用法超出了画图工具的范畴，更像是在做架构治理。

如果你打算把它接进自己的 AI 代理环境，我的建议是先查看项目文档里有没有标准的 skill 描述文件。目前不少开源代理框架都支持把类似 archify 的能力封装成一个SKILL.md或等价格式，里面写明技能用途、参数格式、调用约定。我实际接进代理测试后，体验确实比单独跑命令行好很多——直接在聊天窗口说一句"给我看下订单域和支付域的关系"，代理就会自动调用技能、生成 JSON、渲染视图，一步到位。

还有个小技巧分享给想深入用的朋友：不要只盯着默认渲染界面，试着基于它产出的 JSON 做自己的可视化。我花了半小时写了个脚本，把 JSON 里的调用关系统计成表格，再转成一个内部 Wiki 页面，团队里不熟悉命令行的人也能直接看。工具是死的，数据和技能模块的组合方式才是活的。我打算后续继续探索它和其他代理技能联动，比如让代理先做代码分析、再生成架构图、最后自动产出架构决策记录文档。这条路走通的话，架构设计这块的重复劳动会轻很多。