用 AI 扫描代码库,一键生成可视化架构文档

AI 几秒钟就能写出代码，人类理解它需要几个小时。

跳过理解，代码库就变成了黑盒 — 即使对你自己而言。

随着 AI 编程的普及，项目开发速度越来越快，代码库也变得越来越庞大。你是否也曾遇到过这样的困扰：几个月后回头看自己的项目，已经记不清整体架构是什么样、数据是如何流转的？

难题：AI 时代的代码理解困境

最近X博主分享了一个普遍现象：”用 AI 开发项目越来越大，想回头看自己的代码库，架构是什么样的、数据怎么流转的，反而越来越模糊。”

这确实是许多开发者的真实写照。AI 帮我们快速生成代码，但快速迭代的代价是：

• • 架构认知滞后：代码生成速度 > 理解速度
• • 文档更新延迟：往往忘记更新架构文档
• • 团队协作困难：新人难以快速理解项目结构
• • 重构风险增高：不了解全局就动手改代码

解决方案：Oh-my-mermaid

Oh-my-mermaid 是一个开源自维护工具，专门解决这个问题。它能够：

• • 自动扫描代码库：AI 深度分析项目结构
• • 生成可视化文档：自动创建 Mermaid 架构图
• • 递归分析：遇到复杂逻辑自动拆解
• • 多视角展示：架构、数据流、外部集成等维度

一分钟上手

使用 Oh-my-mermaid 只需要两步：

1. 安装配置

npm install -g oh-my-mermaid && omm setup

一条命令自动检测并配置所有已安装的 AI 编程工具。

2. 扫描分析

在你的 AI 编程工具中输入：

/omm-scan

就这么简单，AI 会自动分析你的整个代码库。

核心特性

1. 智能递归分析

Oh-my-mermaid 不是简单的文件遍历，它会：

• • 识别复杂的逻辑节点
• • 自动进行递归分析
• • 拆解出带有独立图表的嵌套子元素
• • 在本地生成清晰的目录树

生成的文件结构示例：

.omm/├── overall-architecture/           ← 视角│   ├── description.md│   ├── diagram.mmd│   ├── context.md│   ├── main-process/               ← 嵌套元素│   │   ├── description.md│   │   ├── diagram.mmd│   │   └── auth-service/           ← 更深层嵌套│   │       └── ...│   └── renderer/│       └── ...├── data-flow/└── external-integrations/

2. 多维度架构视角

每个元素最多包含 7 个字段：

• • description：功能描述
• • diagram：Mermaid 图表
• • context：上下文信息
• • constraint：约束条件
• • concern：关注点
• • todo：待办事项
• • note：备注信息

3. 交互式查看器

运行 omm view 即可打开交互式查看器：

• • 可展开/收起嵌套元素
• • 多个视角切换查看
• • 支持搜索和导航

广泛的 AI 工具支持

Oh-my-mermaid 支持主流的 AI 编程工具：

一条命令就能完成所有配置，无需手动操作。

云端协作

通过 ohmymermaid.com，你可以：

• • 将架构文档同步到云端
• • 默认私有存储
• • 与团队成员共享
• • 生成公开分享链接

一条命令完成云端操作：

omm login && omm link && omm push

实际应用场景

1. 个人项目维护

定期扫描代码库，保持架构文档最新，避免遗忘项目结构。

2. 团队知识传递

新人入职时，只需查看生成的架构文档，快速理解项目全貌。

3. 重构前规划

在重大重构前，用 Oh-my-mermaid 全面了解现有架构，降低重构风险。

4. 技术文档生成

自动生成符合 Conventional Commits 的技术文档，省去手动绘制时间。

开始使用

如果你也遇到了”项目已经大到自己都记不清架构”的困扰，不妨试试 Oh-my-mermaid。

安装后只需在 AI 编程工具里输入一条指令，就能获得比手绘更专业的架构文档。

开源项目获取方式：关注公众号「光影织梦」，回复 oh-my-mermaid 获取项目地址。

如果你的项目已经大到自己都记不清架构了，用它扫一遍，比手动画图省事不少。