AI Commit Helper

AI 驱动的 Git Commit 助手，自动分析代码变更并生成规范的提交信息。

功能特性

• 🤖 AI 智能分析：自动分析代码 diff，生成符合 Conventional Commits 规范的提交信息
• 🔗 自动关联卡片：智能匹配云效卡片，自动关联相关需求
• ⚠️ 大变更提醒：检测大变更并给出拆分建议
• 💬 交互式确认：生成后允许编辑、修改或取消
• 📊 研发效能统计：配合后端服务，自动生成研发日报/周报

安装

全局安装（推荐）

npm install -g ai-commit-helper

项目内安装

npm install --save-dev ai-commit-helper

快速开始

1. 初始化

在项目目录中执行：

ai-commit init

这会在 .git/hooks/prepare-commit-msg 安装 Git Hook。

2. 配置

设置 API 服务地址：

ai-commit config --api-url http://47.238.150.245:8100

3. 使用

正常使用 git 提交：

git add .
git commit

AI 会自动分析代码变更并提示你确认提交信息。

命令说明

ai-commit init

在当前项目初始化 AI Commit Hook。

ai-commit remove

移除 AI Commit Hook。

ai-commit analyze

手动分析当前暂存区的代码变更：

ai-commit analyze
# 或指定项目
ai-commit analyze --project YOUR_PROJECT_ID

ai-commit config

配置选项：

# 设置 API 地址
ai-commit config --api-url http://47.238.150.245:8100

# 查看当前配置
ai-commit config --list

项目配置

在项目根目录创建 .ai-commit.json 文件：

{
  "projectId": "your-yunxiao-project-id",
  "autoCommit": false
}

配置项说明：

• projectId：云效项目ID，用于关联卡片
• autoCommit：是否自动提交（不提示确认），默认 false

API 服务

本工具需要配合后端 API 服务使用。

默认 API 地址

• 本地: http://localhost:8100
• 远程: http://47.238.150.245:8100

API 端点

• POST /webhook/commit - 提交代码分析
• GET /api/cards/project/{project_id} - 获取项目卡片
• POST /api/cards/{card_id}/link-commit - 关联提交到卡片

工作流程

git add .
    ↓
git commit
    ↓
Hook 触发
    ↓
获取暂存区 diff
    ↓
调用 AI 服务分析
    ↓
显示建议的提交信息
    ↓
用户确认/编辑/取消
    ↓
完成提交

提交信息格式

AI 生成的Conventional Commits](提交信息遵循 [https://www.conventionalcommits.org/) 规范：

<type>(<scope>): <description>

[optional body]

[optional footer]

示例：

• feat(auth): 添加用户登录功能
• fix(api): 修复订单查询接口的 NPE 问题
• docs(readme): 更新安装说明

环境要求

• Node.js >= 16.0.0
• Git >= 2.0
• 后端 API 服务

开发

# 进入客户端目录
cd ai-devops-system/client

# 安装依赖
npm install

# 链接到全局（本地开发）
npm link

# 测试
ai-commit --version
ai-commit --help

发布到 NPM

首次发布

# 1. 登录 NPM
npm login

# 2. 进入客户端目录
cd client

# 3. 首次发布需要修改包名为非作用域（如果需要）
# 或直接发布
npm publish --access public

版本更新发布

使用 publish.sh 脚本：

cd client

# 赋予执行权限（仅首次）
chmod +x publish.sh

# 发布
./publish.sh patch   # 补丁版本 1.0.0 -> 1.0.1
# 或
./publish.sh minor   # 次版本   1.0.0 -> 1.1.0
# 或
./publish.sh major  # 主版本   1.0.0 -> 2.0.0

版本号规则：

• patch (补丁): Bug 修复，小改动，如 1.0.0 → 1.0.1
• minor (次版本): 新功能，向后兼容，如 1.0.0 → 1.1.0
• major (主版本): 重大变更，不向后兼容，如 1.0.0 → 2.0.0

验证发布成功

# 查看已发布版本
npm view @ai-devops/commit-helper versions

# 全局安装测试
npm install -g @ai-devops/commit-helper
ai-commit --version

故障排除

AI 服务连接失败

❌ 错误: 网络错误: connect ECONNREFUSED

解决：检查后端服务是否运行，或修改配置指向正确的 API 地址：

ai-commit config --api-url http://your-server:8100

Hook 未触发

解决：检查 Hook 是否正确安装：

ls -la .git/hooks/prepare-commit-msg

如果不存在，重新运行 ai-commit init

许可证

MIT