MonkeyBlog

生命的意義在於編程

0%

基于AI的Git Commit Message生成工具：从思路到实践

Posted on Edited on In ,
Symbols count in article: 6.5k Reading time ≈ 6 mins.

基于AI的Git Commit Message生成工具：从思路到实践

在软件开发过程中，编写规范、清晰的commit message是一项重要但常被忽视的工作。良好的commit message不仅能帮助团队成员理解代码变更的目的和影响，还能为代码审查、版本追溯和自动化发布流程提供基础。然而，在日常开发中，开发者往往因为赶进度或习惯问题而忽略commit message的质量。本文将介绍一个基于AI的Git Commit Message生成工具，从思路、实现到使用全方位剖析这一解决方案。

背景思考

为什么需要规范的Commit Message？

规范的commit message具有以下几个关键价值：

  1. 提高代码可读性：清晰描述每次提交的目的和内容
  2. 便于版本追溯：快速定位特定功能或修复的引入时间
  3. 自动化支持：支持自动生成更新日志、版本号管理
  4. 团队协作：减少沟通成本，提高代码审查效率

传统痛点

然而，在实际开发中，我们常常面临以下问题：

  • 编写规范message需要额外时间和精力
  • 团队成员对规范理解不一致
  • 难以全面概括复杂的代码变更
  • 工作流ID（如Jira、Flow）需要手动关联

工具设计思路

基于上述背景，我们设计了一个基于AI的commit message生成工具，核心思路如下：

  1. 智能分析代码变更：自动分析git diff内容，理解代码变更的本质
  2. 规范化输出：生成符合团队约定格式的commit message
  3. 工作流集成：支持Flow ID等工作流标识的自动关联
  4. 便捷操作：提供一站式的commit和push操作体验

技术实现

核心架构

工具的核心架构包括以下几个部分：

  1. Git交互层：负责获取代码变更信息
  2. AI分析层：基于OpenAI API分析变更并生成message
  3. 交互层：提供用户交互界面和操作流程
  4. 工具集成层：与剪贴板、终端等系统组件集成

关键实现细节

1. Git变更分析

工具通过git diff和git status命令获取当前工作区的变更情况，并区分两种主要场景：

  • 已修改文件：通过git diff获取详细变更内容
  • 新增文件：通过git status识别新文件，并读取其内容
1
2
3
4
// 获取 git diff 变更
const gitDiff = execCommand('git diff');
// 执行 git status 获取当前分支的文件列表
const gitStatus = execCommand('git status');

代码解析：

  • execCommand 是一个封装了 Node.js 的 child_process.execSync 的工具函数，用于执行 shell 命令并捕获输出
  • 这里使用了两个 Git 命令来获取不同类型的变更信息：
    • git diff 获取已暂存文件的具体变更内容
    • git status 获取工作区状态，用于识别新增文件

2. AI提示工程

针对不同的变更场景，工具构建了专门的提示模板，引导AI生成符合规范的commit message：

1
2
3
4
5
// 修改文件场景
const prompt = `根据以下 git diff 变更，生成一个 git commit 信息，只需要返回文字和换行符，不需要返回其他的字符，需要包含：\n1. 变更修改的内容\n2. 变更修改的原因\n\n按照以下格式返回（使用实际的 flowId: ${flowId}）：\nfix(${flowId}): 修复xxx问题\n\n    - 详细变更点1\n    - 详细变更点2\n    - 详细变更点3\n    - 变更影响和意义总结\n`;

// 新增文件场景
const prompt = `根据以下新增文件的代码内容，生成一个 git commit 信息，只需要返回文字和换行符，不需要返回其他的字符，需要包含：\n1. 新增了哪些文件及其主要功能\n2. 新增的业务或技术价值\n\n按照以下格式返回（使用实际的 flowId: ${flowId}）：\nfeat(${flowId}): 新增xxx功能\n\n    - 新增了xxx文件，实现了xxx功能\n    - 主要逻辑说明\n    - 业务或技术价值总结\n`;

代码解析：

  • 提示工程是AI应用的核心，这里针对两种不同场景设计了不同的提示模板
  • 修改文件场景的提示侧重于变更内容和原因的分析
  • 新增文件场景的提示侧重于功能和价值的描述
  • 两种提示都明确指定了输出格式，确保生成的commit message符合规范

3. 用户交互流程

工具采用简洁的命令行交互方式，支持一站式操作：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// 询问是否 commit
const isCommit = await inquirer.prompt([
    {
        type: 'confirm',
        name: 'isCommit',
        message: '是否执行 commit？(default no)',
        default: false,
    }
]);

// 询问是否 push
const isPush = await inquirer.prompt([
    {
        type: 'confirm',
        name: 'isPush',
        message: '是否执行 git push？(default no)',
        default: false,
    }
]);

代码解析：

  • 使用 inquirer 库提供交互式命令行界面
  • 采用 confirm 类型的提示，让用户做出是/否的选择
  • 默认选项设为 false，避免误操作
  • 这种交互方式简洁明了，减少用户操作负担

4. 系统集成

工具还实现了与系统剪贴板的集成，方便用户直接复制使用：

1
2
3
4
5
6
7
8
9
10
// 复制到剪贴板
try {
    const tempFile = path.join(os.tmpdir(), `.temp_commit_msg_${Date.now()}`);
    fs.writeFileSync(tempFile, commitMessage, 'utf8');
    execCommand(`cat "${tempFile}" | pbcopy`);
    fs.unlinkSync(tempFile);
    console.log('\n✅ 已复制到剪贴板！');
} catch (copyError) {
    console.log('\n❌ 复制到剪贴板失败:', copyError.message);
}

代码解析：

  • 这段代码实现了跨平台的剪贴板复制功能
  • 先将生成的commit message写入临时文件
  • 然后使用系统命令（这里是macOS的pbcopy）将内容复制到剪贴板
  • 最后删除临时文件，避免垃圾文件残留
  • 整个过程有完善的错误处理机制

核心功能实现详解

AI 调用与处理

工具的核心功能是调用 OpenAI API 并处理返回结果：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
async function generateCommitMessageAndHandle({ prompt, aiContent }) {
    if (!OPENAI_API_KEY) {
        console.log('请设置 OPENAI_API_KEY 环境变量');
        process.exit(1);
    }
    const message = prompt + '\n' + aiContent;
    const response = await fetch(`${BASE_URL}/v1/chat/completions`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${OPENAI_API_KEY}`
        },
        body: JSON.stringify({
            model: process.env.MODEL,
            messages: [{ role: 'user', content: message }],
            temperature: 0.7
        })
    });
    const data = await response.json();
    if (!data.choices || !data.choices[0]) {
        console.log('API 响应格式错误:', data);
        process.exit(1);
    }
    const commitMessage = data.choices[0].message.content;
    // ... 后续处理代码
}

代码解析：

  • 函数接收两个参数：提示模板和待分析的代码内容
  • 首先检查API密钥是否设置，确保API调用的前提条件
  • 使用原生的fetchAPI发起HTTP请求，调用OpenAI的聊天补全接口
  • 设置temperature为0.7，平衡创造性和一致性
  • 对API响应进行错误处理，确保返回格式符合预期
  • 从响应中提取生成的commit message内容

新增文件处理

对于新增文件的处理，工具实现了智能的文件内容提取和截断：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
if (newFiles.length > 0) {
    // 有新增文件，走新增分析
    let filesContent = '';
    for (const file of newFiles) {
        try {
            const content = fs.readFileSync(path.join(currentDir, file), 'utf8');
            const lines = content.split('\n');
            let displayContent = content;
            if (lines.length > 400) {
                displayContent = lines.slice(0, 200).join('\n') + '\n...\n' + lines.slice(-200).join('\n');
            }
            filesContent += `文件: ${file}\n内容:\n${displayContent}\n\n`;
        } catch (e) {
            filesContent += `文件: ${file}\n读取失败: ${e.message}\n\n`;
        }
    }
    // ... AI处理代码
}

代码解析：

  • 遍历所有新增文件，读取其内容
  • 对于大文件（超过400行），只保留前200行和后200行，中间用省略号表示
  • 这种处理方式既能保证API请求不会过大，又能保留文件的关键信息
  • 完善的错误处理确保即使某个文件读取失败，整个流程也不会中断

Git操作集成

工具实现了与Git命令的无缝集成：

1
2
3
4
5
6
7
8
9
10
11
// 执行 git add 和 commit
console.log('\n执行 git add...');
execCommand('git add .');
console.log('✅ git add 成功！');
console.log('\n执行 git commit...');
execCommand(`git commit -m "${commitMessage.replace(/"/g, '\"')}"`);
console.log('✅ commit 成功！');

// 执行 git push
execCommand('git push');
console.log('✅ push 成功！');

代码解析：

  • 使用前面定义的execCommand函数执行Git命令
  • 在执行commit命令时，对生成的message中的双引号进行转义，避免命令行解析错误
  • 每个步骤都有清晰的日志输出，让用户了解当前进度
  • 这种集成方式使得整个工作流程一气呵成，大大提高了效率

使用指南

安装配置

  1. 全局安装

    1
    npm install -g generator-commit-message

  2. 临时使用

    1
    npx generator-commit-message flow-xxxx

  3. 环境配置

    在项目根目录创建.env文件：

    1
    2
    3
    OPENAI_API_KEY=your_api_key_here
    BASE_URL=your_api_base_url_here
    MODEL=gpt-3.5-turbo

使用流程

  1. 执行命令

    1
    gcm flow-22914

  2. 查看生成结果
    工具会自动分析代码变更，生成规范的commit message并显示

  3. 确认操作

    • 选择是否执行commit
    • 选择是否执行push

实际效果展示

代码修改场景

1
2
3
4
5
6
7
8
9
10
11
12
13
$ gcm flow-22914

生成的 commit message:

fix(flow-22914): 修复购物车数量更新时的状态同步问题

- 解决了购物车组件在数量变更时状态不同步的问题
- 优化了购物车数据更新的时序处理逻辑
- 修复了并发更新导致的数据不一致问题
- 确保购物车状态在各个组件间的正确同步

✅ 已复制到剪贴板！
? 是否执行 commit？(default no) (y/N)

新增文件场景

1
2
3
4
5
6
7
8
9
10
11
12
13
$ gcm flow-22914

生成的 commit message:

feat(flow-22914): 新增用户权限管理模块

- 新增了 UserPermission.vue 组件，实现权限列表展示功能
- 添加了权限查询、编辑和删除的交互逻辑
- 集成了角色权限的动态配置功能
- 提升了系统的权限管理灵活性和用户体验

✅ 已复制到剪贴板！
? 是否执行 commit？(default no) (y/N)

技术亮点与实践经验

亮点分析

  1. 智能化分析

    • 区分处理修改和新增文件场景
    • 自动提取变更的核心内容和意图

  2. 流程优化

    • 一站式完成从分析到提交的全流程
    • 自动复制到剪贴板减少手动操作

  3. 规范保障

    • 确保commit message格式一致
    • 自动关联工作流ID（Flow ID）

实践经验

在实际使用过程中，我们积累了以下经验：

  1. 提示工程至关重要

    • 精心设计的提示模板能显著提高AI输出质量
    • 针对不同场景定制不同提示策略

  2. 文件内容处理

    • 对大文件进行截断处理，避免超出API限制
    • 保留文件头尾，确保关键信息不丢失

  3. 错误处理

    • 完善的错误处理机制提高工具稳定性
    • 友好的错误提示改善用户体验

注意事项与最佳实践

使用注意事项

  1. API密钥安全

    • 不要将API密钥硬编码在代码中
    • 使用环境变量或配置文件管理敏感信息

  2. 网络依赖

    • 工具依赖网络访问AI API，确保网络畅通
    • 考虑API调用失败的降级策略

  3. 大型变更处理

    • 对于大型变更，考虑拆分为多个小commit
    • AI可能无法完全理解复杂的变更意图

最佳实践

  1. 定期审查生成质量

    • 定期检查AI生成的commit message质量
    • 根据实际使用效果调整提示模板

  2. 与团队规范结合

    • 根据团队的commit规范定制生成格式
    • 考虑与CI/CD流程集成，实现自动化检查

  3. 渐进式采用

    • 先在非关键项目中试用，积累经验
    • 逐步推广到更多项目和团队成员

未来展望

功能增强

  1. 多语言支持

    • 支持中英文等多语言commit message生成
    • 根据项目设置自动选择语言

  2. 本地模型集成

    • 支持本地运行的AI模型，减少API依赖
    • 提高数据安全性和响应速度

  3. 团队定制化

    • 支持团队自定义commit message模板
    • 学习团队历史commit风格，生成更符合团队习惯的内容

工具集成

  1. IDE插件

    • 开发VS Code、WebStorm等IDE插件
    • 提供图形化界面，进一步简化操作

  2. CI/CD集成

    • 与GitHub Actions、Jenkins等CI/CD工具集成
    • 自动检查commit message质量，提供改进建议

结语

基于AI的Git Commit Message生成工具不仅是一个技术工具，更是开发流程优化的实践。通过智能化手段解决传统痛点，它帮助开发团队在不增加额外负担的情况下提高代码管理质量。随着AI技术的不断进步，我们期待这类工具能在软件开发流程中发挥更大的价值。

无论是个人开发者还是大型团队，都可以从这一工具中受益，提升代码管理效率和质量。希望本文的分享能为您的开发工作带来启发和帮助。

本文介绍的工具已开源，欢迎访问 GitHub仓库 获取更多信息或贡献代码。如果这个工具对您有帮助，请给个⭐Star！