一键生成高质量架构图：项目结构 + 第三方插件依赖，直接给你画出来

你有没有这种经历：

架构图画得像 PPT 手工艺，改个模块就要重画 😵
组件依赖越来越多，尤其接了第三方插件之后，谁在调用谁全靠猜
想跟同事解释“我们这个 Hermes 架构到底怎么串起来的”，一开口就乱

我最近碰到一个很顺手的工具（GitHub：github.com/Cocoon-AI/archite…）。

特点就一句话：把项目代码和依赖关系扫描一遍，然后自动输出一张“能看”的架构图。配色也挺舒服，不是那种看两眼就头疼的默认主题。

下面给你一套实操路线，照着做就能把图拿到手。

适合哪些场景（真的能省事）

你要给项目补文档：把图贴进 README / Wiki，立刻像个“成熟团队”
你要做技术评审：依赖关系一眼能看出“耦合点”
你在做插件化系统（比如 Hermes + 一堆第三方插件）：想确认插件到底挂在哪、谁在调用谁
你接手老项目：不问人，先让工具把大概结构吐出来

你会得到什么输出

不同工具实现不一样，但这类“架构图生成器”通常会给你这些结果（也是你最该关注的）：

模块/目录层级图：项目骨架
依赖关系图：模块 A 引用了模块 B、插件 X 依赖基础库 Y
可导出的图文件：常见是 SVG/PNG，或者 Mermaid/Graphviz 之类的可编辑格式

如果它能把“第三方插件”单独聚合成一个区域/泳道，那就更爽了：读图成本直接降一半。

开始前准备（别卡在环境上）

建议你准备这几样：

一个本地项目目录（可以是 Hermes 架构项目，也可以是任何仓库）
能跑命令行（macOS / Linux / Windows 都行）
如果工具需要大模型能力：准备好对应的 API Key（具体看仓库 README）

我个人更推荐 Docker 路线：少折腾，环境更干净。

跑起来：两条路线，选你顺手的

下面命令是“通用写法”，不同仓库的命令会有差异。你打开 github.com/Cocoon-AI/archite… 的 README，对照替换参数就行。

路线 A：按仓库 README 直接跑（最稳）

进入你的工作目录
把仓库拉下来

git clone https://github.com/Cocoon-AI/archite... 
cd archite...

按 README 安装依赖并运行

你要做的事很简单：把“待分析的项目路径”喂进去。

很多工具会长这样：

# 示例：把 /path/to/your/project 换成你的项目路径
archite --input /path/to/your/project --output ./out

跑完去 out/ 目录找图。

路线 B：Docker 一把梭（适合怕环境冲突的人）

如果仓库提供 Docker（不少会提供），你就用容器跑。

典型思路是：

示例（还是那句话，以 README 为准）：

docker run --rm \
  -v /path/to/your/project:/workspace/project \
  -v $(pwd)/out:/workspace/out \
  cocoon-ai/archite:latest \
  --input /workspace/project \
  --output /workspace/out

你会发现最爽的点：项目不需要做任何改造，分析完直接出图。

让图“更像人画的”：3 个你一定会用到的参数/设置

自动出图很好，但默认结果经常会“信息太多”。想让图变得可读，通常要做三件事。

1）控制分析范围：别把 `node_modules` 这种垃圾也画进去

你想看的，是核心模块、业务层、插件层。

建议你在配置里加忽略规则：

node_modules/
dist/、build/
coverage/
*.min.js
自动生成的代码目录

很多工具支持 .ignore 文件或参数：

node_modules
/dist
/build
coverage
**/*.min.*

2）把“第三方插件”单独分组

插件化系统最怕一张图糊成一锅粥。

你可以按目录或命名规则分组，比如：

/plugins/* 归为「Plugins」
/core/* 归为「Core」
/adapters/* 归为「Adapters」

图上能看到一个清晰结构：核心层在中间，插件围一圈挂着。你跟别人讲解也更顺。

3）输出可编辑格式：别把自己锁死在 PNG

PNG 适合贴文档。

你真要持续维护，尽量输出：

SVG：清晰、可缩放
Mermaid/Graphviz：可版本管理，改动有 diff

你甚至可以把生成的文本图丢进仓库：以后每次 CI 更新，图也跟着更新。

怎么读这张图（别光顾着“哇好看”）

拿到图之后，建议你按这条路线快速扫一遍：

核心入口在哪：一般是 main / app / bootstrap
核心模块有哪些：业务域、服务层、基础设施层
插件/第三方从哪里接入：是事件总线？hook？中间件链？注册表？
最粗的那几条依赖线：通常就是耦合重灾区

你会很快发现两类问题：

“这个模块怎么谁都依赖它”：可以考虑拆分或下沉成公共库
“插件怎么直接穿透到核心数据库层”：边界没守住，后面维护会炸

实战小抄：用它给 Hermes + 插件生态做一张能讲明白的图

如果你的系统是 Hermes 架构 + 第三方插件，你可以按这个思路组织输出：

Hermes Core：消息/任务调度、路由、执行器、生命周期
Plugin Runtime：插件加载、注册、权限、隔离
Third-party Plugins：支付、通知、存储、LLM Provider…

然后在图上盯住两点：

插件通过什么契约接入（接口/事件/协议）
插件能不能绕过契约直接调用内部实现（如果能，尽快补防线）

这张图做出来，你写技术方案会特别快：复制粘贴 + 画两条重点标注线就够了。

避坑清单（踩过才知道有多烦）

图太大：不是工具问题，是你没限范围。先只扫 core/ + plugins/
把敏感信息扫进去了：私有仓库、内部域名、密钥路径，输出前检查一遍再分享
依赖线多到像毛线团：关掉“细粒度依赖”，改成“模块级聚合”
分析结果怪怪的：多半是动态加载/反射/运行时注册导致静态分析不完整。别纠结，拿它当“地形图”，不是当真理
想一口气生成完美图：别。先生成可用版，能讲清 70% 就已经赢了

你可以立刻去做的事

去 GitHub 打开：github.com/Cocoon-AI/archite…
选一个你最熟的项目目录
只分析核心目录 + 插件目录
输出 SVG 或可编辑格式
把图贴到 README，顺手加一句“生成命令”，以后谁改架构谁负责更新

如果你愿意，把你项目的目录结构（不含业务敏感内容）贴出来，我可以帮你设计一套“分组规则”，让生成的图更像一张真正能用于评审的架构图。

一键把你的项目“画”成高质量架构图：连第三方插件依赖都能扒出来（附上手步骤）