git-doctor

v1.0.2

Published

a month ago

Git 技术债务可视化与治理平台 - 深度分析 Git 历史，识别代码热点，量化技术债务，提供治理建议

0High
0Medium
0Low

weilei_kyle

git health analyzer repository diagnostics technical-debt hotspot code-quality visualization

Git Doctor

Git 技术债务可视化与治理平台

一款基于 Git 底层原理的仓库健康度诊断工具，直接解析 .git 对象库，深度分析 Git 历史，识别代码热点，量化技术债务，提供智能治理建议。

在线文档

核心特性

🔬 深度 Git 原理融合

直接解析 .git 对象库，不依赖 git 命令行
支持 Blob/Tree/Commit/Tag 四种对象类型解析
原生 Zlib 解压松散对象（loose objects）
读取 Pack 索引文件统计打包对象

📊 全方位仓库健康诊断

仓库体积分析：检测大文件、分析对象分布、生成瘦身建议
提交质量分析：Conventional Commits 规范检测、作者贡献统计
分支健康度：僵尸分支检测、已合并未删除分支识别
敏感信息扫描：内置 50+ 敏感模式规则，覆盖主流平台凭证

🔥 技术债务可视化

代码热点分析：识别高频修改文件，量化技术债务风险
TDI 技术债务指数：创新的多维度量化公式
热力图展示：可视化代码变更热度
贡献者画像：识别知识孤岛风险

🤖 AI 智能分析

集成 DeepSeek / Kimi 国产大模型
AI 智能生成提交消息、CHANGELOG、优化计划
AI 诊断助手交互式问答

🛡️ Git Hook 集成

Pre-commit Hook：敏感信息自动检测
Commit-msg Hook：提交消息规范检查
一键安装/卸载所有 Hook

功能截图

健康概览仪表盘

健康概览

代码热点热力图

热力图

技术债务分析

技术债务

贡献者画像

仓库管理

AI 诊断助手

AI助手

快速开始

环境要求

| 依赖项 | 版本要求 | 说明 | | --------------------- | --------- | ------------------ | | VS Code | >= 1.85.0 | 必需 | | Node.js | >= 16.x | 必需 | | Git | 已安装 | 必需 | | DeepSeek/Kimi API Key | - | 可选，用于 AI 功能 |

方式一：安装 VSIX 插件（推荐）

下载项目根目录的 git-doctor-1.0.0.vsix 文件
在 VS Code 中按 Ctrl+Shift+P 打开命令面板
输入 Extensions: Install from VSIX...
选择 VSIX 文件完成安装
重启 VS Code

方式二：从源码构建

# 克隆项目
git clone https://github.com/git-doctor/git-doctor.git
cd git-doctor

# 安装依赖
npm install

# 编译
npm run compile

# 打包 VSIX
npm run package

# 生成的 .vsix 文件可按方式一安装

方式三：CLI 命令行

# 全局安装
npm install -g .

# 查看帮助
git-doctor --help

# 运行完整诊断 (或用别名 check)
git-doctor analyze
git-doctor check

# 分析仓库体积 (或用别名 fat)
git-doctor size
git-doctor fat

# 分析提交质量 (或用别名 log)
git-doctor commits
git-doctor log

# 分析分支健康度 (或用别名 tree)
git-doctor branches
git-doctor tree

# 扫描敏感信息 (或用别名 leak)
git-doctor security
git-doctor leak

# 导出 HTML 报告 (或用别名 report)
git-doctor export -f html -o report.html
git-doctor report -f html -o report.html

使用指南

1. 运行完整诊断

打开任意 Git 仓库项目，使用以下方式之一：

点击侧边栏的 Git Doctor 图标（脉搏图标）
按 Ctrl+Shift+P，输入 Git Doctor: 运行完整诊断

诊断将分析以下维度：

仓库体积健康度
提交质量评分
分支健康状态
敏感信息风险

2. 代码热点分析

识别项目中的"问题热点"文件：

在侧边栏点击 代码热点 视图
点击 开始分析 或运行命令 Git Doctor: 分析代码热点
查看热力图：Git Doctor: 打开热力图

技术债务指数 (TDI) 计算公式：

TDI = Churn × BugFactor × Complexity × TimeDecay

- Churn 权重 40%: 文件修改频率
- BugFactor 权重 35%: Bug 修复关联度
- Complexity 权重 15%: 文件复杂度（大小）
- TimeDecay 权重 10%: 时间衰减（近期权重更高）

3. AI 智能分析

配置 AI 功能：

运行 Git Doctor: 配置 AI API Key
选择提供商（DeepSeek 或 Kimi）
输入 API Key

支持的 AI 功能：

Git Doctor: AI 生成提交消息 - 分析暂存区变更自动生成规范消息
Git Doctor: AI 生成 CHANGELOG - 根据提交历史生成版本日志
Git Doctor: AI 生成优化计划 - 基于诊断报告生成治理建议
Git Doctor: 打开 AI 诊断助手 - 交互式问答

4. Git Hook 管理

安装 Hook 保护代码质量：

Git Doctor: 安装所有 Git Hook

包含：

Pre-commit Hook：提交前自动扫描敏感信息
Commit-msg Hook：检查提交消息是否符合 Conventional Commits 规范

5. 导出诊断报告

支持多种格式导出：

HTML：可视化仪表盘报告
Markdown：易于分享的文本报告
JSON：程序化处理数据
Text：控制台输出格式

# CLI 导出
git-doctor export -f html -o report.html
git-doctor export -f markdown -o report.md
git-doctor export -f json -o report.json

命令列表

诊断与分析（7 个）

| 命令 | 说明 | | ---------------------------- | ---------------------------- | | Git Doctor: 运行完整诊断 | 运行所有诊断分析 | | Git Doctor: 分析仓库体积 | 分析 .git 目录大小和对象分布 | | Git Doctor: 分析提交质量 | 分析提交规范和质量 | | Git Doctor: 分析分支健康度 | 检测僵尸分支和分支规范 | | Git Doctor: 扫描敏感信息 | 扫描代码中的敏感信息 | | Git Doctor: 分析代码热点 | 识别高频修改文件 | | Git Doctor: 分析贡献者画像 | 分析团队贡献分布 |

AI 智能功能（8 个）

| 命令 | 说明 | | --------------------------------- | ---------------------- | | Git Doctor: 打开 AI 诊断助手 | 打开 AI 对话面板 | | Git Doctor: AI 生成提交消息 | 根据暂存区变更生成消息 | | Git Doctor: AI 生成 CHANGELOG | 根据提交历史生成日志 | | Git Doctor: AI 生成优化计划 | 生成仓库优化建议 | | Git Doctor: AI 分析热点建议 | AI 分析热点文件 | | Git Doctor: AI 生成债务治理计划 | 生成技术债务治理方案 | | Git Doctor: 配置 AI API Key | 配置 AI 服务 | | Git Doctor: 切换 AI 提供商 | 切换 DeepSeek/Kimi |

Hook 管理（9 个）

| 命令 | 说明 | | ----------------------------------- | -------------------- | | Git Doctor: 安装所有 Git Hook | 安装全部 Hook | | Git Doctor: 卸载所有 Git Hook | 卸载全部 Hook | | Git Doctor: 安装提交拦截 Hook | 安装 commit-msg hook | | Git Doctor: 卸载提交拦截 Hook | 卸载 commit-msg hook | | Git Doctor: 安装敏感信息检测 Hook | 安装 pre-commit hook | | Git Doctor: 卸载敏感信息检测 Hook | 卸载 pre-commit hook | | Git Doctor: 切换提交消息检查 Hook | 切换 commit-msg hook | | Git Doctor: 切换敏感信息检测 Hook | 切换 pre-commit hook | | Git Doctor: 扫描暂存区敏感信息 | 扫描已暂存文件 |

仓库管理（18 个）

| 命令 | 说明 | | ------------------------------- | ---------------------------- | | Git Doctor: 初始化向导 | 引导式初始化 Git 仓库 | | Git Doctor: 初始化 Git 仓库 | 快速初始化仓库 | | Git Doctor: 创建远程仓库 | 在 GitHub/GitCode 创建仓库 | | Git Doctor: 配置 Git 用户信息 | 配置 user.name 和 user.email | | 暂存所有 | git add . | | 取消暂存所有 | git reset HEAD | | 提交 | git commit | | 推送 | git push | | 拉取 | git pull | | 同步 | git pull && git push | | 发布分支 | 推送新分支到远程 | | 切换树形/列表视图 | 切换文件变更的显示模式 | | 切换分支 | 切换到其他本地分支 | | 新建分支 | 创建新的本地分支 | | 删除分支 | 删除本地分支 |

配置项

在 VS Code 设置中搜索 gitDoctor 可配置以下选项：

{
	// 大文件检测阈值（字节），默认 1MB
	"gitDoctor.largeFileThreshold": 1048576,

	// 僵尸分支判定天数，默认 90 天
	"gitDoctor.staleBranchDays": 90,

	// 提交信息最小长度
	"gitDoctor.commitMessageMinLength": 10,

	// 是否检测 Conventional Commits 规范
	"gitDoctor.enableConventionalCommits": true,

	// AI 配置
	"gitDoctor.ai.enabled": false,
	"gitDoctor.ai.provider": "deepseek", // deepseek 或 kimi
	"gitDoctor.ai.apiKey": "",
	"gitDoctor.ai.model": "", // 留空使用默认模型

	// 热点分析配置
	"gitDoctor.hotspot.churnThreshold": 10, // 热点判定的最小修改次数
	"gitDoctor.hotspot.timeRange": 90, // 分析时间范围（天）
	"gitDoctor.hotspot.excludePatterns": [
		// 排除的文件模式
		"**/node_modules/**",
		"**/dist/**",
		"**/*.lock"
	]
}

技术架构

系统架构图

┌─────────────────────────────────────────────────────────────────┐
│                        Git Doctor                                │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │  VS Code    │  │    CLI      │  │   Webview   │  用户界面层  │
│  │  Extension  │  │  Command    │  │   Panels    │             │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘             │
├─────────┴────────────────┴────────────────┴────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │   Health    │  │  Hotspot    │  │     AI      │  分析器层    │
│  │  Analyzers  │  │  Analyzer   │  │  Analyzer   │             │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘             │
├─────────┴────────────────┴────────────────┴────────────────────┤
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                    Git Parser Core                       │   │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐       │   │
│  │  │  Blob   │ │  Tree   │ │ Commit  │ │   Tag   │       │   │
│  │  │ Parser  │ │ Parser  │ │ Parser  │ │ Parser  │       │   │
│  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘       │   │
│  └─────────────────────────────────────────────────────────┘   │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                     .git 目录                            │   │
│  │  objects/  refs/  HEAD  config  hooks/                  │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

核心模块

src/
├── core/                    # 核心解析层
│   └── git-parser.ts        # Git 对象解析（1030 行）
│                            # - Zlib 解压松散对象
│                            # - Blob/Tree/Commit/Tag 解析
│                            # - SHA-1 哈希计算
│                            # - 文件历史追踪
│
├── analyzers/               # 分析器层
│   ├── size-analyzer.ts     # 仓库体积分析
│   ├── commit-analyzer.ts   # 提交质量分析
│   ├── branch-analyzer.ts   # 分支健康度分析
│   ├── security-scanner.ts  # 敏感信息扫描（50+ 规则）
│   ├── gitleaks-rules.ts    # 内置敏感信息规则集
│   ├── gitleaks-integration.ts # 敏感信息检测集成
│   ├── hotspot-analyzer.ts  # 代码热点分析（TDI 算法）
│   ├── contributor-analyzer.ts # 贡献者画像分析
│   └── report-generator.ts  # 报告生成器
│
├── ai/                      # AI 智能分析层
│   ├── deepseek-client.ts   # DeepSeek API 客户端
│   ├── kimi-client.ts       # Kimi API 客户端
│   └── ai-analyzer.ts       # AI 分析器
│
├── git/                     # Git 操作层
│   ├── hook-manager.ts      # Hook 管理
│   ├── repo-initializer.ts  # 仓库初始化
│   └── platform-api.ts      # GitHub/GitCode API
│
├── views/                   # 视图层
│   ├── tree-providers.ts    # TreeView 提供者
│   └── git-changes-provider.ts # Git 变更视图（支持树形/列表切换）
│
├── webview/                 # Webview 展示层
│   ├── dashboard.ts         # 健康仪表盘
│   ├── hotspot-panel.ts     # 热力图面板
│   ├── debt-dashboard.ts    # 技术债务仪表盘
│   └── ai-chat-panel.ts     # AI 对话面板
│
├── extension.ts             # VS Code 插件入口
└── cli.ts                   # CLI 命令行入口

技术栈

| 类别 | 技术 | | ------------- | -------------------------------- | | 开发语言 | TypeScript 5.3 | | 运行环境 | VS Code Extension API + Node.js | | 构建工具 | tsc (TypeScript Compiler) | | 打包工具 | vsce (VS Code Extension Manager) | | AI 集成 | DeepSeek API / Kimi API | | 模板引擎 | Handlebars | | Markdown 解析 | markdown-it | | CLI 框架 | Commander.js |

创新点

1. Git 底层直接解析

不依赖 git 命令，直接读取 .git 对象库：

// 解析松散对象
const compressed = fs.readFileSync(objectPath)
const decompressed = zlib.inflateSync(compressed)
const [type, size] = header.split(' ')

// 解析 Tree 对象结构
// mode SP name NUL sha(20bytes)
const entries = parseTreeObject(content)

// 解析 Commit 对象
// tree <sha>
// parent <sha>
// author <name> <email> <timestamp>
// committer <name> <email> <timestamp>
// <blank line>
// <message>

2. 技术债务量化算法 (TDI)

创新的多维度技术债务指数：

TDI = Σ(Churn_i × BugFactor_i × Complexity_i × TimeDecay_i)

其中：
- Churn: 文件修改频率（权重 40%）
- BugFactor: Bug 修复关联度（权重 35%）
- Complexity: 文件复杂度（权重 15%）
- TimeDecay: 时间衰减因子（权重 10%）
  - 180天内: 1.0 → 0.5 线性衰减

3. 内置敏感信息检测

内置 50+ 敏感模式规则，覆盖主流平台：

// 内置检测规则示例
const patterns = [
	/AKIA[0-9A-Z]{16}/, // AWS Access Key
	/ghp_[a-zA-Z0-9]{36}/, // GitHub Token
	/sk-[a-zA-Z0-9]{48}/, // OpenAI API Key
	/gsk_[a-zA-Z0-9]{52}/, // Groq API Key
	/AIza[0-9A-Za-z\-_]{35}/, // Google API Key
	/-----BEGIN RSA PRIVATE KEY-----/
	// ... 50+ 规则覆盖 AWS/GitHub/GitLab/Google/Azure 等
]

4. 双形态设计

同时支持 VS Code 插件和 CLI 命令行：

# VS Code 插件：图形化界面
# CLI：自动化/CI 集成
git-doctor analyze --json | jq '.healthScore'

性能说明

| 场景 | 预期性能 | | ------------------------------ | -------- | | 小型仓库（< 1000 commits） | < 1 秒 | | 中型仓库（1000-10000 commits） | 1-5 秒 | | 大型仓库（> 10000 commits） | 5-30 秒 |

优化策略：

Promise.all 并行运行多个分析器
增量扫描支持（since 参数）
流式 AI 响应减少等待时间
排除模式过滤无关文件

测试说明

功能测试

打开任意包含 .git 目录的项目
运行 Git Doctor: 运行完整诊断
验证侧边栏显示健康概览、代码热点、贡献者画像等信息

AI 功能测试

配置 DeepSeek 或 Kimi API Key
运行 Git Doctor: AI 生成提交消息 测试 AI 集成
运行 Git Doctor: 打开 AI 诊断助手 测试对话功能

CLI 测试

# 在 Git 仓库目录下运行
git-doctor check          # 完整诊断
git-doctor fat            # 体积分析
git-doctor log            # 提交分析
git-doctor tree           # 分支分析
git-doctor leak           # 安全扫描
git-doctor report -f html -o test-report.html  # 导出报告