Generate conventional commit messages from code changes or diff.

SKILL.md

---
name: git-commit-helper
description: Generate conventional commit messages from code changes or diff.
version: 1.0.0
author: Hazy
triggers:
  - commit message
  - git commit
  - 提交信息
  - 生成提交消息
  - write a commit
---

# Git Commit Helper

## 目标

根据用户提供的代码变更内容（git diff 输出或口头描述），智能分析改动范围和类型，生成符合 **Conventional Commits** 规范的提交消息候选方案。

## 触发条件

当用户请求生成 Git 提交消息时激活，常见触发语句包括：
- "commit message for this change"
- "帮我写一个 commit"
- "生成 Git 提交信息"
- "为这次改动写提交消息"

## Conventional Commits 规范参考

提交消息格式：
```
<type>(<scope>): <short description>

[optional body]

[optional footer(s)]
```

### 类型（type）定义

| 类型 | 说明 | 示例 |
|------|------|------|
| `feat` | 新功能 | `feat(auth): add OAuth2 login support` |
| `fix` | 修复 bug | `fix(api): handle null pointer in user endpoint` |
| `docs` | 文档变更 | `docs(readme): update installation instructions` |
| `style` | 代码格式（不影响功能） | `style(lint): fix indentation in utils.ts` |
| `refactor` | 重构（非新功能、非修复） | `refactor(database): simplify query builder` |
| `perf` | 性能优化 | `perf(render): reduce re-renders in list component` |
| `test` | 测试相关 | `test(auth): add unit tests for login flow` |
| `chore` | 构建过程或辅助工具变动 | `chore(deps): update react to v18.2.0` |
| `ci` | CI/CD 配置变更 | `ci(github): add automated testing workflow` |

### 破坏性变更标识

如果改动包含 **BREAKING CHANGE**，需在类型后添加 `!` 或在正文/脚注中明确标注：
```
feat(api)!: change authentication endpoint response format

BREAKING CHANGE: The /api/auth/login endpoint now returns a different JSON structure.
```

## 操作指南

### 步骤 1：接收输入

询问用户提供以下任一形式的输入：
- **git diff 输出**：用户粘贴 `git diff` 或 `git diff --staged` 的完整输出
- **口头描述**：用户用自然语言描述本次改动的内容

如果用户未提供具体内容，主动询问：
> "请提供 git diff 输出，或描述本次代码改动的内容（例如：添加了用户登录功能、修复了空指针异常等）。"

### 步骤 2：分析改动

基于用户输入，执行以下分析：

#### 2.1 识别改动文件与模块
- 提取被修改的文件路径
- 推断所属模块/范围（scope），如：`auth`, `ui`, `api`, `database`, `config` 等
- 如果涉及多个模块，选择最主要的一个或使用通用范围（如 `core`）

#### 2.2 判断改动类型
根据改动内容确定 type：
- **新增功能/接口/组件** → `feat`
- **修复错误/异常/bug** → `fix`
- **更新 README/注释/文档** → `docs`
- **调整代码格式/空格/缩进** → `style`
- **代码结构优化（无功能变化）** → `refactor`
- **提升性能/减少资源消耗** → `perf`
- **新增/修改测试用例** → `test`
- **依赖更新/配置文件调整** → `chore`
- **CI/CD 脚本变更** → `ci`

#### 2.3 检测破坏性变更
检查是否存在以下情况：
- API 接口签名变更（参数、返回值）
- 数据库 schema 重大调整
- 移除已公开的功能或配置项
- 行为逻辑发生不兼容改变

如果存在，标记为 **BREAKING CHANGE**。

### 步骤 3：生成提交消息候选

生成 **3 条**不同详细程度的推荐提交消息：

#### 候选 1：简洁版（单行）
格式：`<type>(<scope>): <short description>`
- 短描述不超过 50 字符
- 使用祈使句（如 "add" 而非 "added"）
- 首字母小写，末尾无句号

#### 候选 2：标准版（含正文）
格式：
```
<type>(<scope>): <short description>

<detailed body explaining what and why>
```
- 正文解释改动的背景和原因
- 每行不超过 72 字符
- 与短描述之间空一行

#### 候选 3：完整版（含脚注）
格式：
```
<type>(<scope>): <short description>

<detailed body>

BREAKING CHANGE: <description of breaking change>

Closes #123
```
- 包含破坏性变更说明（如适用）
- 包含关联的 issue/pr 编号（如适用）

### 步骤 4：呈现结果

以清晰的结构化格式输出：

```markdown
## 📝 推荐的提交消息

### 选项 1：简洁版
```
<commit message>
```

### 选项 2：标准版
```
<commit message with body>
```

### 选项 3：完整版
```
<commit message with body and footer>
```

## 🔍 分析说明
- **改动类型**：<type> - <解释为什么选择此类型>
- **影响范围**：<scope> - <解释如何确定此范围>
- **破坏性变更**：是/否 - <如有，说明原因>
```

### 步骤 5：交互优化

提供后续操作建议：
- "需要我将某条消息复制到剪贴板吗？"
- "是否需要调整某个选项的描述？"
- "是否要生成英文版本的提交消息？"

## 示例对话

### 示例 1：用户提供 git diff

**用户**：
```
commit message for this change

diff --git a/src/auth/login.ts b/src/auth/login.ts
index abc123..def456 100644
--- a/src/auth/login.ts
+++ b/src/auth/login.ts
@@ -10,6 +10,15 @@ export class AuthService {
+  async loginWithOAuth2(provider: string): Promise<User> {
+    // implementation
+  }
```

**助手**：
```markdown
## 📝 推荐的提交消息

### 选项 1：简洁版
```
feat(auth): add OAuth2 login support
```

### 选项 2：标准版
```
feat(auth): add OAuth2 login support

Implement OAuth2 authentication flow to allow users to login with third-party providers like Google and GitHub.
```

### 选项 3：完整版
```
feat(auth): add OAuth2 login support

Implement OAuth2 authentication flow to allow users to login with third-party providers like Google and GitHub.

- Add loginWithOAuth2 method to AuthService
- Support multiple provider configurations
- Handle token exchange and user profile retrieval

Closes #42
```

## 🔍 分析说明
- **改动类型**：feat - 新增了 OAuth2 登录功能
- **影响范围**：auth - 改动集中在认证模块
- **破坏性变更**：否 - 仅新增方法，未修改现有接口
```

### 示例 2：用户口头描述

**用户**：
```
帮我写一个 commit，我修复了一个 bug，当用户输入为空时，搜索功能会崩溃
```

**助手**：
```markdown
## 📝 推荐的提交消息

### 选项 1：简洁版
```
fix(search): handle empty input to prevent crash
```

### 选项 2：标准版
```
fix(search): handle empty input to prevent crash

Add input validation to search function to gracefully handle empty or null queries instead of throwing an exception.
```

### 选项 3：完整版
```
fix(search): handle empty input to prevent crash

Add input validation to search function to gracefully handle empty or null queries instead of throwing an exception.

- Check for empty/null input before processing
- Return empty results array for invalid queries
- Add unit tests for edge cases

Fixes #156
```

## 🔍 分析说明
- **改动类型**：fix - 修复了导致崩溃的 bug
- **影响范围**：search - 问题出现在搜索功能
- **破坏性变更**：否 - 仅增强健壮性，未改变接口行为
```

## 注意事项

1. **语言一致性**：如果代码库主要使用英文注释/文档，提交消息使用英文；否则可使用中文
2. **范围可选性**：如果无法明确范围，可省略 `(scope)` 部分
3. **避免冗余**：短描述不要重复类型信息（如不要写 "feat: add new feature"）
4. **时态规范**：使用祈使句现在时（"add" 而非 "added" 或 "adds"）
5. **特殊字符**：避免在短描述中使用句号、感叹号等标点

## 常见问题处理

### 问题 1：改动涉及多个模块
**解决方案**：
- 选择最主要的模块作为 scope
- 或使用通用范围如 `core`, `app`, `multiple`
- 在正文中详细说明各模块的改动

### 问题 2：无法确定改动类型
**解决方案**：
- 优先询问用户意图（"这是新功能还是修复？"）
- 根据代码上下文推断
- 默认使用 `chore` 作为保守选择

### 问题 3：用户提供的 diff 不完整
**解决方案**：
- 基于已有信息做出最佳推断
- 明确告知用户分析的局限性
- 建议提供更完整的 diff 以获得更准确的结果

## 扩展功能（可选）

如果环境支持，可实现以下增强：

1. **自动复制**：调用系统剪贴板 API 复制选中的提交消息
2. **Git 集成**：直接执行 `git commit -m "<message>"`
3. **模板保存**：允许用户保存常用的提交消息模板
4. **历史建议**：基于项目历史提交记录优化推荐风格