AI 如何生成架构图？visual-explainer 使用方法解析

AI 画架构图的时候，怎么才不会把十几个模块堆成一张糊成一团的网？我常用的办法是让 visual-explainer 先把信息分个类：是「关系类」还是「说明类」——关系类的交给 Mermaid 画，模块职责、实现细节这类用 CSS 卡片展示，要是元素太多，就把两种方式结合起来用。

先把架构需求捋成可核对的具体任务

要是只甩一句「帮我画个架构图」，最后大概率得到一张好看但空泛的图。我一般会这么提需求：让 Agent 先读取当前仓库，把入口、服务、数据存储、外部依赖和关键调用都列出来，再用 visual-explainer 生成 HTML 格式的架构说明；而且要求每个节点都必须对应真实的文件或模块，拿不准的关系得明确标出来。

不同内容该怎么选呈现方式？

• 流程、管线、状态机和决策树这类：用 Mermaid 实现
• 序列图、ER 图、类关系、C4 架构、拓扑图这类：还是优先用 Mermaid
• 模块职责、实施计划和大段文字说明：用 CSS Grid 卡片展示
• 元素超过 15 个的话：用小型 Mermaid 概览搭配详细卡片，别硬塞在一张图里
• 对比项、审计内容和状态矩阵：用语义化 HTML 表格

为什么 Mermaid 不能只套个 pre 标签就完事？

官方 Skill 明确要求得用 diagram-shell 结构。图的外层得有缩放、重置和展开控件，视口支持拖动，还能按 Ctrl/Cmd 加滚轮缩放；关系复杂的话优先用自上而下的 flowchart TD 布局。我一般还会检查长标签会不会换行、分支会不会横向溢出，还有普通桌面宽度下节点文字能不能看清。

一个可以直接发给 Agent 的需求示例

使用 visual-explainer 读取当前项目。先找出入口、核心服务、数据库和外部接口；再用小型 Mermaid 展示主调用链；随后用卡片补充各模块职责、文件位置和风险；最后输出自包含 HTML 到 ~/.agent/diagrams/。

哪些结果需要返工？

• 节点名称在代码里搜不到，或者箭头方向没有实际文件做依据
• 整张图缩得只剩色块，还没拆成概览加细节的结构
• 页面依赖构建步骤，脱离项目环境就没法直接打开
• 宽表格、代码块或者 Mermaid 画布太宽，导致页面横向溢出

说白了，它更像是「把已核验的信息排版成好读的页面」，而不是凭空给代码库猜架构。先让 Agent 找证据，再让 Skill 选合适的呈现形式，生成的结果才经得起复查。