【开源看AI】GitDiagram：AI帮你理解任意代码库的架构

推荐语

开发者的福音，一键可视化代码库架构，提升协作效率。

核心内容：
1. GitDiagram：自动将GitHub仓库结构转换成交互式架构图
2. 核心特性：智能转换、交互式组件、私有仓库支持
3. 使用流程及AI如何分析和理解复杂代码库

杨芳贤

53A创始人/腾讯云(TVP)最具价值专家

产品定位 ?

"将任意GitHub仓库转化为交互式系统设计/架构图，一键可视化项目结构。"

GitDiagram是一个开源工具，能够自动将GitHub仓库结构转换成交互式系统架构图，帮助开发者快速理解项目架构。它不仅可以展示项目的总体结构，还允许用户点击组件直接导航到源文件和相关目录，大幅提高代码理解和团队协作效率。?

其Github地址为： 

https://github.com/ahmedkhaleel2004/gitdiagram

关键特性 ✨

• 智能转换：瞬间将任意GitHub仓库转化为系统设计图。?
• 交互式组件：点击图中组件直接跳转到源文件和目录。
• 私有仓库支持：通过GitHub token访问私有代码库。?
• 自定义图表：通过用户指令定制图表样式和内容。
• URL捷径：只需将GitHub URL中的"hub"替换为"diagram"即可查看其架构图。

使用场景 ?

• 新项目上手：快速理解陌生代码库的整体架构。
• 团队协作：向团队成员清晰展示项目结构，促进沟通。
• 文档编写：生成可视化图表用于技术文档。?
• 代码审查：通过整体结构图辅助代码审查过程。
• 教学培训：为新人讲解系统架构设计理念。

使用流程 ?

下面以分析一个开源项目为例，介绍如何使用GitDiagram来可视化项目架构。

第一步：访问GitDiagram网站（https://gitdiagram.com/），输入你想要分析的GitHub仓库地址。

第二步：等待AI分析仓库结构，这个过程根据仓库大小可能需要几秒到几分钟不等。如果有缓存，秒级返回；如果没有，要等等。 以最近大热的MCP TypeScript SDK为例：

https://github.com/modelcontextprotocol/typescript-sdk

第三步：查看生成的架构图，可以看到系统的整体结构、各组件之间的关系。

每个组件都是可交互的，点击即可跳转到对应的源代码文件或目录，方便深入了解具体实现：

第四步：生成的图表是Mermaid.js代码，可以直接拷贝；或者导出为PNG图片。

AI如何理解代码架构 ?

GitDiagram背后的核心是强大的LLM，它是如何分析和理解复杂代码库的呢？这个过程分为三个关键步骤：

1. 仓库数据提取：系统首先从GitHub API获取仓库的文件树结构、README内容和其他关键元数据。这些原始数据成为AI的输入来源。

2. 多阶段智能分析：GitDiagram采用了精心设计的三阶段提示工程（Prompt Engineering）处理流水线：

• 最后，系统将解释和组件映射信息一并发送给AI模型
• 使用SYSTEM_THIRD_PROMPT指导AI生成符合标准的Mermaid.js图表代码
• 生成的图表包含丰富的交互事件，允许用户点击任何组件直接跳转到GitHub上的相应文件或目录
• 系统自动处理这些点击事件，智能判断路径是文件还是目录，并构建正确的GitHub URL

• 第三阶段：生成Mermaid图表 ?

• 系统将第一阶段生成的解释回传给AI模型
• 通过SYSTEM_SECOND_PROMPT指导AI将每个识别出的组件精确映射到实际文件或目录路径
• 这个映射过程是创建交互式图表的关键环节，它建立了可视化组件与实际代码文件的联系
• AI会分析目录结构，确定哪些文件最能代表特定组件的功能

• 第二阶段：组件映射 ?

• 系统首先使用GitHub API获取代码库的完整文件树和README内容
• 智能过滤算法自动剔除不相关文件（如node_modules、图片资源等）
• LLM（现在使用OpenAI o3-mini，原来使用过Claude-3.5-Sonnet）模型分析这些精简数据，生成代码库结构的详细解释
• 这一步骤使用prompts.py中的SYSTEM_FIRST_PROMPT来指导AI从文件结构中识别关键组件和系统架构

• 第一阶段：分析代码库结构 ?

整个生成过程采用流式处理返回进度更新，用户可以实时看到图表从无到有的生成过程，这也是GitDiagram的一大特色。系统还实现了智能缓存机制，避免重复生成相同代码库的图表，大大提高了效率。对于特别大型的代码库，GitDiagram还提供了API密钥选项，让用户使用自己的OpenAI密钥进行处理，突破默认限制。

1. 动态渲染与交互：前端使用Mermaid.js将生成的图表代码转换为可视化图形，并添加交互性，使用户可以点击任何组件深入了解。

值得一提的是，GitDiagram最初使用Claude 3.5 Sonnet进行代码理解，现在已切换到OpenAI的o3-mini模型，在处理大型代码库方面表现出色。AI不仅能够识别文件结构，还能理解代码间的依赖关系，甚至推断出设计模式和架构决策。

技术栈与实现 ?

GitDiagram采用了现代全栈架构设计：

• 前端：基于Next.js 15、TypeScript、Tailwind CSS和ShadCN UI组件构建，使用App Router模式组织代码，通过Server Components和Server Actions提高性能。

• 后端：使用FastAPI（Python）处理仓库数据提取和AI处理流程，包括复杂的提示工程和API调用管理。

• 数据库：采用PostgreSQL搭配Drizzle ORM进行类型安全的数据库操作，使用Neon Database提供serverless PostgreSQL服务。

• AI集成：通过API调用大型语言模型，实现代码库分析和架构图生成，使用复杂的提示工程提取准确信息。

• 部署：前端部署在Vercel，后端运行在EC2实例上，通过GitHub Actions实现CI/CD流程。

AI辅助开发实践 ?

通过查看项目代码，我们发现GitDiagram的开发过程中大量借助了Cursor这款AI编程工具，这是"氛围编程"（Vibe Coding）的绝佳实践案例。项目中的.cursor/rules目录包含了作者为AI助手设置的上下文规则，帮助AI更好地理解和参与项目开发。

作者在summary.mdc文件中精心编写了项目概述，为Cursor的AI助手提供了全面的项目背景：

• 项目概述：清晰描述了GitDiagram的核心功能和价值
• 关键特性：列举了系统的主要功能点
• 技术栈：详细说明了前后端使用的所有技术
• 架构设计：拆分为前端、后端、数据库和AI集成四大模块
• 项目结构：指明了各目录的用途
• 开发设置：提供了环境搭建指南

这种做法极大地提高了AI助手对项目的理解能力，使得AI能够提供更加精准和有价值的代码建议。通过让AI了解整个项目的架构和技术选型，开发者可以获得更加契合项目上下文的代码生成和问题解决方案。

有趣的是，GitDiagram本身就是一个帮助开发者理解代码库的AI工具，而它的开发过程也充分利用了AI的力量。这种"AI辅助开发AI工具"的模式，展示了现代软件开发的新范式，也验证了作者对AI技术的深刻理解和灵活应用。

对于想要尝试AI辅助编程的开发者来说，GitDiagram的开发方式提供了一个值得参考的模板：创建详细的项目概述文档，明确技术栈和架构设计，使用规范化的代码结构，这些都能帮助AI更好地理解项目上下文，提供更精准的协助。

本地部署 ?

如果你想在自己的环境中运行GitDiagram，可以按照以下步骤操作：

# 克隆仓库git clone https://github.com/ahmedkhaleel2004/gitdiagram.gitcd gitdiagram
# 安装依赖pnpm install
# 配置环境变量cp .env.example .env# 编辑.env文件，添加必要的API密钥
# 启动后端docker-compose up --build -d
# 启动本地数据库chmod +x start-database.sh./start-database.sh
# 初始化数据库结构pnpm db:push
# 启动前端开发服务器pnpm dev

完成上述步骤后，你可以通过访问localhost:3000使用GitDiagram。如果需要查看和操作数据库，可以运行pnpm db:studio。

小结思考 ?

GitDiagram让代码库可视化变得前所未有的简单，它利用AI的力量自动分析和理解代码结构，为开发者提供了一个强大的工具。不过，目前也有一些值得改进的地方：

• 对超大型仓库的处理可能需要较长时间，优化分析速度是一个挑战。
• 生成的图表有时可能过于复杂，需要更智能的简化算法。
• 对特定编程语言的特性理解还有提升空间，比如更好地识别不同框架的设计模式。

随着AI技术的不断发展，GitDiagram未来可能会在代码理解方面取得更大突破，让开发者能够更轻松地理解复杂系统架构，提高开发效率。

你是否经常为了理解新项目的代码结构而烦恼？不妨试试GitDiagram，让AI帮你轻松破解代码库的奥秘！