GitArchitectureDiagram：AI Agent 工具实践指南

团队讨论GitArchitectureDiagram时，我会先把用途说清楚：将任何 GitHub 存储库转变为交互式工程工作区。一旦进入软件开发环节，依赖、接口和异常处理往往比主路径更影响采用会直接影响交付，这也是我最关心的风险。更实际的做法是在隔离分支完成一个可回滚的小任务，同时核对安装步骤、接口契约、测试结果和错误信息，不要直接在关键项目上。我的判断是，它更适合需要可检查开发流程而非单次演示的工程师；若眼下没有这类需求，先保留观察即可。

Git 架构图

明白。可视化。强调。提炼。构建。

Git 架构图将 GitHub 存储库转换为交互式、图表优先的工作区，用于架构理解、软件层次结构、存储库思维导图、基于源代码的 Genius 指导、项目提取和开发人员就绪的导出。

将 GitHub 主机名替换为您的 Git 架构图主机名，并打开与分析工作区相同的存储库路径。

由 Amine Saoud ibn al-Bashir 创建 - ProAmineOfficial / Pro_Amine LLC。
根据 MIT 许可证 开源。

官方工作区

黑暗的工作空间

轻型工作空间

移动工作空间

平板电脑工作区

出口项目

macOS-style 底座交互

Dock 导航和项目图计数

项目文件提取

通过替换主机名打开任何存储库

示例存储库：

https://github.com/ProAmineOfficial/Driver-NanoKit-ESP32-of-T.U.M-Pro_Amine-IC

生产域形式：

https://gitarchitecturediagram.com/ProAmineOfficial/Driver-NanoKit-ESP32-of-T.U.M-Pro_Amine-IC

存储库在 Git 架构图中打开并开始分析。

同样的想法也适用于存储库路径，例如：

/owner/repo
/owner/repo/tree/<branch-or-commit>/<folder>
/owner/repo/blob/<ref>/<file>#L12-L20

永久链接可以保留分析的提交、选定的文件、选定的行和当前视图。

你得到什么

三个导航层

Git 架构图将全局导航、存储库操作和工作区视图分开。

1. 全局应用程序头

• 工作空间
• 浏览
• GitHub
• 主题
• API 设置

2. 存储库命令栏

• 存储库身份和存储库搜索
• 分支并提交
• 游览
• 亮点
• 信息
• 变焦
• 全屏
• 出口
• 刷新
• 永久链接
• 文件
• 天才
• 面板布局切换

3. 居中视图底座

• 系统图
• 建筑
• 层次结构
• 思维导图
• 图表
• 来源
• 天才
• 出口项目
• 出口
• 构建

每个停靠项目都有自己的线条图标。

活动视图使用带有小指示点的琥珀色状态。在桌面上，扩展坞使用基于邻近度的放大：指针下方的图标增长最多，相邻图标逐渐增长，并且图标上升而不会导致布局重排。

触摸、窄屏和简化动作布局使用更简单的交互。

图优先工作区

存储库页面以一个大型分析画布为中心。

工作区的设计使得存储库上下文在用户在架构、层次结构、源代码、思维导图、Genius、导出和面向构建的视图之间移动时保持可见。

该接口支持：

• 黑暗主题
• 浅色主题
• 桌面
• 平板电脑
• 移动
• 全屏
• 交互式变焦
• 基于抽屉的文件和 Genius 面板

亮点

突出显示可以隔离存储库的重要区域，包括：

• 关键架构
• 入口点
• 核心部件
• 数据流
• API流量
• 前端
• 后端
• 存储
• 外部服务
• AI 组件
• 硬件
• 安全关键部件
• 构建和部署
• 测试
• 文档
• 高依赖节点
• 天才亮点
• 自定义请求，例如 authentication flow

不相关的节点可能会变暗，而选定的节点和路径会被强调。

突出显示结果可以标记为：

• 源自来源
• 天才诠释
• 关键词匹配

软件层次结构

软件层次结构答案：

这个软件是如何组织的？

而不仅仅是：

文件在哪里？

它可以暴露：

• 应用层
• 框架和 SDKs
• 服务
• APIs
• 存储
• 司机
• 面向硬件的层
• 测试
• 部署
• 关键文件
• 入口点

可能的角色徽章包括：

• ENTRY POINT
• CORE
• PUBLIC API
• CRITICAL
• EXTERNAL

嵌入式存储库可以使用嵌入式特定的层名称。

存储库思维导图

存储库思维导图组织项目概念，而不仅仅是文件夹结构。

它可以包括：

• 建筑学
• README特点
• 入口点
• 基础设施
• 依赖关系
• 文档
• 测试

选择一个概念可以：

• 在天才中解释一下
• 在系统图中突出显示它
• 在建筑中突出它
• 显示相关的层次结构分支
• 显示相关文件

系统地图及导览

系统图提供了存储库组件如何组合在一起的更高级别视图。

导游可以：

• 将相机移动到当前节点
• 突出显示通往那里的边缘
• 解释当前步骤
• 遵循主流
• 尊重简化运动设置

系统映射输出可以区分存储库支持的证据和模型推理。

天才和经过验证的证据

Genius 旨在将经过验证的存储库证据与 AI 解释分开。

对于基于源的答案，服务器可以验证：

• 存储库
• 分析提交
• 文件路径
• 源代码行
• 逐字引用

对照分析的 GitHub 快照。

界面可以区分：

• 来源已验证
• 天才推理

仅浏览器提供的文本并不能使引文可信。

出口

可以从存储库命令栏和 Dock 中进行快速导出。

支持的快速输出包括：

• PNG
• SVG
• 复制美人鱼
• 下载美人鱼
• README 图片
• README 徽章

两个导出入口点使用相同的导出系统。

出口项目

导出项目 是项目级导出工作区。

它将项目知识分组为可重用的开发人员输出。

克隆存储库

为分析的存储库生成精确的克隆工作流程并提交。

git clone https://github.com/owner/repository.git
cd repository
git checkout <commit>

凭证绝不会包含在生成的克隆命令中。

项目文件

项目文件可以提供：

• 总结
• 统计数据
• 目录结构
• 重要文件
• 文件内容

行动可以包括：

• 全部复制
• 下载.txt
• 下载.md

提取可以使用分析的文件，或者在配置的限制内，使用整个存储库存档。

项目图

支持的图表导出包括：

• 建筑
• 系统图
• 软件层次结构
• 存储库思维导图
• 绘制图表

可用的格式可以包括：

• PNG
• SVG
• 美人鱼
• README 图片
• README 徽章

项目技能

项目技能可以分为：

• 有证据的观察技能
• 推荐技能并附理由

导出格式可以包括：

• 降价
• 文本
• JSON

天才发展输出

天才可以生成：

• 开发提示
• 构建类似的应用程序
• MVP计划
• 前端计划
• 后端计划
• API计划
• 数据库规划
• 应用程序蓝图
• 实施路线图

AI / 开发者上下文

可重用的项目知识可以包括：

• AI-就绪上下文
• 开发者包
• 项目知识包
• 项目重建包

经过验证的源材料和 Genius 推理应该保持明显的分离。

项目文件提取

项目文件将存储库上下文转换为 AI 助手、文档或开发人员入门的可移植文本。

提取物可以包括：

• 存储库摘要
• 语言和大小统计
• 目录结构
• 重要文件
• 相关文件内容
• 估计上下文大小
• 估计令牌数
• 包括过滤器
• 排除过滤器
• 最大文件限制

绝不能读取 .env 等凭证文件和私钥。

大型存储库在配置的存档、解压大小、文件大小和保留文本限制下进行处理。

如何选择文件

分析器从存储库证据开始，例如：

• README 文件
• 体现
• 声明的入口点
• 本地 imports/includes

然后它会跟踪相关文件的引用。

当有更强大的核心应用程序文件可用时，可以降低示例和测试的优先级。

分析的文件可以记录它们被选中的原因。

本地运行

需要 Node.js 22.12 或更高版本。

git clone https://github.com/ProAmineOfficial/GitArchitectureDiagram.git
cd GitArchitectureDiagram
npm ci
npm start

然后打开存储库路径，例如：

http://localhost:3000/ProAmineOfficial/Driver-NanoKit-ESP32-of-T.U.M-Pro_Amine-IC

无需 AI 提供者密钥即可分析公共存储库。

可选的 AI 提供商

工作区可以支持用户或操作员配置的提供程序，包括：

• OpenAI
• 克洛德
• 双子座
• 基米

在发送外部 AI 请求之前，该界面可以显示提供商、型号、请求大小和输出限制。

切勿提交 .env 或提供商凭据。

从终端生成文档

npm run analyze -- ProAmineOfficial/Driver-NanoKit-ESP32-of-T.U.M-Pro_Amine-IC   --max-files 24   --output .genius

当需要可重现的快照时，可以提供特定的参考。

开发和测试

npm run dev
npm run check
npm test
npm run test:browser
npm run build

该项目包括：

• 自动化节点测试
• 浏览器与 Playwright 进行检查
• GitHub 用于确定性摄取测试的 API 仿真
• 浏览器和 Workers 兼容的构建输出

范围和安全性

存储库分析有意受到限制。

典型的保障措施包括以下限制：

• 文件数
• 每个文件的大小
• 保留文本
• 树的大小
• 档案大小
• 解压后的存储库大小

Generated/vendor 文件夹、可能的凭证文件、符号链接和二进制文件可以被跳过，同时在有用的存储库结构中仍然保持可见。

当逐个文件夹分析时，大型单一存储库效果最佳。

作为存储库分析的一部分，不会执行、构建或安装已分析的存储库代码。

项目愿景

Git 架构图的构建是为了使复杂的存储库更容易理解、探索、记录、导出和扩展。

该平台汇集了：

• 建筑可视化
• 系统图
• 软件层次结构
• 存储库思维导图
• 根植于源头的天才指导
• 项目提取
• 开发人员就绪的导出
• AI-辅助开发准备

目标很简单：

明白。可视化。强调。提炼。构建。

内置

• Node.js
• 美人鱼
• DOMPurify
• 标记的
• 弗拉特
• IBM 丛

第三方许可证仍归其各自作者所有。