企业官网建设流程全解析

1. 项目缘起与核心定位

第一次看到 archify 这个项目标题的时候，我的直觉是：这东西解决的是一个长期被忽视的痛点。做过后端开发或者系统设计的人都知道，架构图这玩意儿，画起来费时间，维护起来更费时间。代码改了，架构图没改，过两个月再看那张图，跟考古似的，完全对不上。archify 的思路很直接——既然 AI 代理已经能写代码、能读代码、能理解项目结构了，那为什么不让它顺手把架构图也画了？而且不是画一张死图，是画一张可交互的图。

这个项目的核心定位是一个技能模块，也就是说它不是独立运行的软件，而是挂载在 AI 代理体系下的一个能力单元。你可以把它理解成给 AI 代理装了一双专门看架构的眼睛和一双专门画架构的手。它做的事情是：读取你的项目代码或配置，分析模块之间的依赖关系、调用链路、数据流向，然后自动生成一张可交互的架构图。这张图不是静态图片，而是可以在浏览器里缩放、拖拽、点击查看节点详情的 HTML 页面。

适合谁来用？我梳理了一下，大概三类人最需要：第一类是中小团队的技术负责人，手里管着几个微服务，每次汇报都要重新画架构图，烦得不行；第二类是刚接手遗留项目的开发者，面对一坨代码不知道从哪看起，需要一张全局视图来建立认知；第三类是做技术文档或技术分享的人，需要频繁更新架构图但不想每次都手动调整。如果你属于这三类中的任何一类，archify 值得花时间研究一下。

我实测下来的感受是，它最大的价值不在于画得多好看，而在于“自动”和“可交互”这两个词。自动意味着你不需要手动维护，代码变了重新跑一遍就行；可交互意味着看图的人可以自己探索，不用你在旁边解释“这个框代表什么”。这两点结合起来，架构图的维护成本从“每次都要重画”降到了“每次重新生成”。

2. 核心机制拆解：AI 代理如何理解并生成架构图

2.1 技能模块的运作原理

archify 作为一个技能模块，它的运作方式跟传统的架构图工具完全不同。传统工具比如 Draw.io、PlantUML、Mermaid，本质上是你告诉它画什么它就画什么，它不理解你的代码。archify 的逻辑是反过来的：它先去理解你的代码，然后自己决定画什么。

具体来说，这个技能模块的工作流大致分三步。第一步是扫描与解析，AI 代理会遍历你指定的项目目录，识别出关键文件——比如微服务项目里的 pom.xml、build.gradle、package.json、Dockerfile、docker-compose.yml，以及各个服务的主入口文件和配置文件。第二步是关系推断，代理会根据文件内容推断出服务之间的调用关系、依赖关系、数据存储关系。比如它看到服务 A 的配置文件里引用了服务 B 的地址，就会在图上画一条从 A 到 B 的连线。第三步是图结构生成与渲染，代理把推断出的关系转换成图数据结构，然后生成一个可交互的 HTML 页面。

这里有个关键点：archify 不是简单地做静态代码分析。它借助了 AI 代理的语义理解能力，能处理一些模糊的情况。比如你的配置文件里写的是环境变量而不是硬编码的地址，传统工具可能就识别不出来了，但 AI 代理可以根据上下文推断出这个环境变量指向的是哪个服务。这是它比传统工具聪明的地方。

2.2 为什么选择可交互 HTML 而不是静态图片

这个问题我一开始也想过，静态图片不是更简单吗？但实际用下来，可交互 HTML 的优势非常明显。静态图片的问题在于信息密度和可读性之间的矛盾：图画得太细，字小得看不清；图画得太粗，又丢失了关键信息。可交互 HTML 解决了这个矛盾——默认展示全局概览，点击某个节点才展开详细信息。

从技术实现角度看，可交互架构图通常基于 SVG 或 Canvas 渲染，配合 JavaScript 做交互逻辑。archify 生成的页面我拆开看过，用的是 SVG + D3.js 或者类似的图形库，节点和连线都是 DOM 元素，支持缩放、拖拽、点击事件。这意味着你可以把它直接嵌到内部文档系统里，也可以单独部署成一个静态页面，团队里任何人打开浏览器就能看。

还有一个容易被忽略的好处：可交互 HTML 是文本格式的，可以纳入版本管理。每次代码变更后重新生成的架构图，可以通过 git diff 看到具体哪些节点和连线发生了变化。这对于追踪架构演进非常有价值。静态图片做不到这一点，二进制文件的 diff 没有意义。

2.3 与主流架构图工具的对比

我把 archify 和几种常见的方案做了个对比，方便你判断它适不适合你的场景。

从表里可以看出来，archify 的核心优势场景是“代码频繁变更且需要持续维护架构图”的情况。如果你的项目架构半年不变一次，那用 PlantUML 手写可能更可控。但如果你的项目每周都在加服务、改接口，那 archify 的自动化能力就是刚需。

3. 从零搭建：实操过程与关键配置

3.1 环境准备与前置条件

在开始之前，你需要确认几件事。首先，你得有一个可用的 AI 代理环境。archify 是作为技能模块挂载的，所以它依赖宿主代理的能力。目前主流的 AI 代理平台都支持自定义技能模块的加载，具体方式各平台略有差异，但核心逻辑都是把技能描述文件和执行脚本放到指定目录，然后在对话中触发。

其次，你的项目代码需要有一定的结构化程度。什么意思呢？如果你的项目是一个巨大的单体应用，所有代码都在一个目录里，那 archify 能分析出的架构信息会比较有限。但如果你的项目是微服务架构，或者至少是按模块划分了清晰的目录结构，那 archify 就能发挥出最大价值。我实测下来，微服务项目、前后端分离项目、多模块 Maven/Gradle 项目，效果最好。

第三，你需要准备一个输出目录。archify 生成的 HTML 文件需要有个地方存放，建议单独建一个docs/architecture/目录，方便后续管理和部署。

注意：在运行 archify 之前，建议先确认你的项目依赖描述文件是完整的。比如 Maven 项目的 pom.xml 里是否声明了所有内部依赖，docker-compose.yml 里是否列出了所有服务。这些文件是 archify 推断关系的主要依据，如果它们本身就不完整，生成的架构图也会缺胳膊少腿。

3.2 技能模块的加载与触发

加载 archify 技能模块的过程，不同 AI 代理平台的操作方式不太一样，但大体思路是一致的。你需要把技能的描述文件（通常是一个 Markdown 或 YAML 格式的说明）放到代理的技能目录下，描述文件里要写清楚这个技能叫什么、做什么用、接受什么参数、输出什么结果。

触发方式一般有两种。一种是在对话中直接说“帮我生成这个项目的架构图”，代理识别到意图后会调用 archify 技能。另一种是显式调用，比如输入/archify --path ./my-project --output ./docs/architecture/。我建议用显式调用，因为参数可控，不容易出错。

这里有个实操心得：第一次运行的时候，建议先在一个小项目上测试，确认整个流程跑得通。不要一上来就拿一个几十个服务的大项目去跑，万一中间某个环节卡住了，排查起来很麻烦。我一开始就是拿一个只有三个微服务的小项目试的，跑通之后再逐步扩大范围。

3.3 参数配置与输出定制

archify 支持一些参数来定制输出结果，虽然不同版本的参数名可能略有差异，但核心配置项大致如下：

# 基本用法 archify --path ./project-root --output ./docs/architecture/ # 指定分析深度 archify --path ./project-root --depth 3 --output ./docs/architecture/ # 排除特定目录 archify --path ./project-root --exclude "node_modules,dist,test" --output ./docs/architecture/ # 指定输出格式 archify --path ./project-root --format html --output ./docs/architecture/

--depth参数控制分析深度。深度为 1 时只分析顶层服务之间的关系，深度为 2 时会展开到服务内部的模块，深度为 3 时会进一步展开到关键类或函数级别。我一般用深度 2，既能看清服务间关系，又不会因为节点太多而眼花缭乱。

--exclude参数很重要。默认情况下 archify 会扫描所有目录，但像node_modules、dist、test这些目录里的内容对架构分析没有帮助，反而会增加噪音。建议在配置里把这些目录排除掉。

输出格式目前主要是 HTML，但有些版本也支持导出为 JSON 或 Mermaid 格式。JSON 格式适合做二次开发，比如你想把架构数据接入自己的监控系统。Mermaid 格式适合嵌入 Markdown 文档。

3.4 生成结果的解读与验证

archify 跑完之后，你会得到一个 HTML 文件。用浏览器打开，应该能看到一张可交互的架构图。但这里有个关键步骤不能省：验证生成的图是否准确。

AI 推断出来的关系不一定全对。我遇到过几种典型情况：一是把测试代码里的依赖也画进去了，导致图上多了一些不该有的连线；二是某些通过消息队列异步通信的服务，代理没有识别出来，图上缺了连线；三是环境变量指向的服务，代理推断错了目标。

验证的方法很简单：拿生成的图和你的实际架构对照一遍。重点看几个地方——服务之间的调用方向对不对，数据存储节点有没有遗漏，外部依赖有没有标出来。发现错误后，可以调整配置重新生成，或者在生成的 HTML 上手动修正（如果 archify 支持编辑功能的话）。

提示：建议把验证这一步固化到流程里。每次重新生成架构图后，花五分钟对照检查一下。特别是当项目有重大架构调整时，AI 的推断可能会出错，人工验证能避免把错误的架构图传播出去。

4. 实战中的常见问题与排查技巧

4.1 生成结果不准确怎么办

这是最常见的问题，也是我踩坑最多的地方。生成结果不准确通常有几个原因，对应的排查思路也不一样。

第一个原因是项目结构不清晰。如果你的项目目录层级混乱，文件命名没有规律，AI 代理很难准确推断出模块边界。解决办法是先整理项目结构，至少做到按功能或按服务划分目录。这不是为了 archify，是为了整个项目的可维护性。

第二个原因是依赖声明不完整。比如你的服务 A 通过 HTTP 调用服务 B，但配置文件里只写了 B 的地址，没有说明这是服务间调用。AI 代理可能会把它当成一个普通的外部链接。解决办法是在配置文件里加上注释或元数据，帮助代理理解。比如在 docker-compose.yml 里给服务加上labels说明。

第三个原因是代理的推断逻辑有偏差。这种情况比较难排查，因为你看不到代理的思考过程。我的经验是，先检查输入数据（项目文件）是否完整，如果输入没问题但输出还是不对，那就可能是代理的推断逻辑需要调整。有些版本的 archify 支持自定义推断规则，可以针对特定模式做配置。

4.2 架构图节点过多导致不可读

当项目规模较大时，生成的架构图可能会包含几十甚至上百个节点，这时候图就变得不可读了。解决这个问题有几个思路。

第一个思路是分层展示。不要试图在一张图里展示所有细节，而是分成多个层次。顶层图只展示服务之间的关系，点击某个服务后再展开该服务内部的模块图。archify 的可交互特性天然支持这种分层展示，关键是要配置好层级关系。

第二个思路是过滤。通过--exclude参数排除掉不重要的节点，或者通过--focus参数只展示与某个服务相关的子图。我一般会生成两张图：一张全局概览图，只展示核心服务；一张详细图，展示某个特定服务的内部结构。

第三个思路是分组。把功能相关的服务归为一组，在图上用不同的颜色或边框区分。这样即使节点很多，读者也能快速定位到自己关心的部分。

4.3 与现有文档系统的集成

生成的架构图如果只是孤零零一个 HTML 文件，价值有限。更好的做法是把它集成到现有的文档系统里。我试过几种集成方式，各有优劣。

最简单的方式是把 HTML 文件放到静态文件服务器上，然后在文档里加个链接。这种方式零成本，但架构图和文档是分离的，更新不同步。

进阶一点的方式是用 iframe 嵌入。在文档页面里用 iframe 引入架构图 HTML，这样架构图更新后，文档页面自动更新。但 iframe 在移动端的体验不太好，而且有些文档平台不支持 iframe。

最彻底的方式是把架构图数据接入文档生成流程。比如用 archify 生成 JSON 格式的架构数据，然后用自定义脚本把数据渲染成文档平台支持的格式。这种方式最灵活，但需要一定的开发工作量。

4.4 常见问题速查表

5. 进阶玩法与扩展思路

5.1 结合 CI/CD 实现架构图自动更新

archify 最让我兴奋的一点是它可以和 CI/CD 流程结合。思路很简单：在 CI 流水线里加一个步骤，每次代码合并到主分支后自动运行 archify，生成最新的架构图并部署到文档站点。这样架构图就永远是新的，不需要任何人手动维护。

具体实现方式取决于你用的 CI 工具。以常见的 GitHub Actions 为例，你可以在 workflow 文件里加一个 job，在代码检出后运行 archify 命令，然后用 deploy 步骤把生成的 HTML 推到静态站点。关键是要把 archify 的运行环境配置好，确保 CI 环境里有必要的依赖。

这个玩法有一个前提：你的项目结构要足够规范，AI 代理能稳定地推断出架构关系。如果每次生成的图都差异很大，那自动更新反而会造成混乱。建议先在本地稳定运行一段时间，确认输出结果一致后再接入 CI。

5.2 多项目架构图的统一管理

如果你手里有多个项目，每个项目都生成一张架构图，管理起来会比较分散。一个扩展思路是做一个统一的架构图门户，把所有项目的架构图聚合到一个页面上。

实现方式可以是这样：每个项目在 CI 里生成架构图 HTML 后，推送到一个统一的目录，目录结构按项目名组织。然后做一个索引页面，列出所有项目的架构图链接。更进一步，可以做一个搜索功能，输入服务名就能找到它在哪个项目的架构图里。

这个玩法适合技术负责人或架构师，需要对自己管辖的所有项目有一个全局视图。我试过用简单的静态站点生成器来做这个门户，效果还不错，成本也低。

5.3 架构变更追踪与告警

架构图不仅能看当前状态，还能用来追踪变更。思路是每次生成架构图时，把图数据（JSON 格式）存档一份，然后对比前后两次的数据，找出新增、删除、修改的节点和连线。

这个能力在微服务架构下特别有价值。比如某个服务突然多了一个对其他服务的依赖，这可能是开发人员无意中引入的耦合，通过架构变更追踪就能及时发现。再比如某个服务被意外删除了，架构图上会少一个节点，也能触发告警。

实现这个功能需要一些开发工作：写一个对比脚本，解析两次生成的 JSON 数据，输出差异报告。然后把差异报告接入告警系统，比如发到团队群里或邮件通知。我目前还在摸索阶段，但初步效果已经能看出价值了。

5.4 与 AI 代理的其他技能联动

archify 作为 AI 代理的一个技能模块，理论上可以和其他技能联动。比如结合代码审查技能，在审查代码时自动检查是否引入了新的架构依赖；结合文档生成技能，在生成 API 文档时自动嵌入相关的架构图片段。

这种联动的价值在于把架构意识融入到日常开发流程中，而不是等到专门画图的时候才想起来。开发人员在提交代码时就能看到自己的改动对架构的影响，这比事后补图要有意义得多。

不过联动的前提是各个技能之间的数据格式要统一。如果 archify 输出的 JSON 格式和其他技能期望的格式不一致，就需要做一层转换。这是目前比较麻烦的地方，希望后续版本能在这方面做改进。

6. 个人实操体会与建议

用了这段时间，我最大的体会是：archify 这类工具的价值不在于替代人工画图，而在于把架构图的维护成本降到足够低，低到你可以把它当成代码的一部分来管理。以前架构图是“文档”，写完就过时；现在架构图是“构建产物”，每次代码变更都会重新生成。

如果你打算尝试 archify，我的建议是从小项目开始，先跑通流程，再逐步扩大范围。不要一上来就追求完美的架构图，先接受一个“大致准确”的版本，然后在实际使用中逐步调整配置。架构图这东西，有用比好看重要得多。

另外，不要完全依赖 AI 的推断结果。AI 代理再聪明，也不如你自己了解你的项目。把 archify 当成一个起点，它帮你画出 80% 的框架，剩下的 20% 靠人工修正。这个分工方式，目前来看是最务实的。