<div align="center">

# Git Commit Genie

English version: [English README](../gitCommitGenie/README.md)

</div>

## 概述

Git Commit Genie 基于已暂存的 Git diff，使用主流大模型（OpenAI / DeepSeek / Anthropic / Gemini）自动生成高质量的 Conventional Commits 风格提交信息。内置仓库智能分析功能，自动理解项目结构和技术栈，为提交信息生成提供更好的上下文。支持可选"链式提示"模式（多步推理）与"用户模板"策略，显著提升结构一致性与团队风格统一。

优势：
- 避免在提交语句格式/措辞上反复纠结。
- 严格符合 Conventional Commits（类型、scope、BREAKING CHANGE）。
- 通过一个简单的模板文件定义 Body / Footers / 语气 / 词汇偏好。
- 支持多模型动态切换，快速选择最适合的提供商与模型。

## Usage
<img src="../gitCommitGenie/demo1.gif" width="300"/>

## 格式

默认生成的提交信息遵循 Conventional Commits 1.0.0 规范，详情见：https://www.conventionalcommits.org/zh-hans/v1.0.0/

基本格式：
```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

## Tips

- 少量 / 轻量级提交：优先选择轻巧快速的模型，生成更快、Token 消耗更低。
- 大型 / 多文件提交：再考虑切换更强的模型，以获得更好的理解与结构质量。
- 可随时通过命令面板运行 "Git Commit Genie: Manage Models" 切换模型。

## 核心特性

| 特性                     | 说明                                                                                                 |
| ------------------------ | ---------------------------------------------------------------------------------------------------- |
| 多模型提供商             | 支持 OpenAI、DeepSeek、Anthropic、Gemini等。                                                         |
| 仓库智能分析             | 自动分析项目结构、技术栈和架构，为提交信息生成提供上下文；支持手动刷新、实时更新和手动修改分析报告。 |
| 链式提示模式             | 多步：文件级摘要 → 结构化综合 → 校验修复，显著提升准确度与模板贴合度。                               |
| 用户模板策略             | 内置模板选择和创建功能，支持工作区和用户数据目录，抽取策略影响段落顺序、必填 footers、词汇偏好等。   |
| Conventional Commit 校验 | 头行格式（type(scope)!: desc），长度 ≤ 72，无句号。                                                  |
| Diff 感知                | 仅读取"已暂存"更改；自动推断类型（feat / fix / docs / refactor 等）。                                |
| Token 与速率保护         | 429 自动退避重试；Gemini 软限本地节流；并发可配置。                                                  |
| 状态栏集成               | 显示当前模型和分析状态，点击可访问功能菜单。                                                         |
| 生成取消                 | SCM 标题栏按钮可实时取消正在进行的生成。                                                             |
| 安全存储                 | API Key 使用 VS Code SecretStorage，不写入明文设置。                                                 |
| 国际化支持               | 内置英文、简体中文、繁体中文等多语言支持。                                                           |

## 工作流程

1. 暂存（Stage）你的变更。
2. 执行命令：`Git Commit Genie: AI Generate`（SCM 顶部按钮或命令面板）。
3. 若开启链式模式：
   - 并行生成文件级摘要
   - 综合分析类型与 scope
   - 应用模板策略（若有效）
   - 结构 + 风格自检与最小修复
4. 输出写入仓库提交框，可人工微调后提交。

未开启链式：使用单轮提示 → 更低延迟，但结构与风格细腻度稍弱。

## 安装

1. VS Code 市场搜索 “Git Commit Genie” 安装，或使用打包 `.vsix` 手动安装。
2. 命令面板运行 `Git Commit Genie: Manage Models` 选择 Provider、输入/替换 API Key、选择模型。
3. （可选）使用命令 `Git Commit Genie: Select/Create Template` 选择或创建模板文件。

## 运行要求

| 项       | 说明                        |
| -------- | --------------------------- |
| VS Code  | 版本需满足引擎 `^1.103.0`。 |
| Git 扩展 | 内置 `vscode.git`，需启用。 |
| 网络访问 | 调用所选 LLM 提供商。       |
| API Key  | 使用的每个提供商都需要。    |

## 配置项

所有设置位于：`Git Commit Genie`。

| Setting                                             | 类型    | 默认    | 说明                                                                                                                                         |
| --------------------------------------------------- | ------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `gitCommitGenie.autoStageAllForDiff`                | boolean | false   | 仅当暂存区为空时：临时将所有更改加入暂存用于生成 diff，生成后会自动还原暂存状态。谨慎使用，可能会把无关更改包含进提示。                      |
| `gitCommitGenie.chain.enabled`                      | boolean | false   | 启用链式多步提示生成提交信息（使得生成的提交信息更加详准确，且可以更加贴合用户模版，但将增加延迟与 Token 消耗）                              |
| `gitCommitGenie.chain.maxParallel`                  | number  | 2       | 链式提示并行 LLM 调用最大数量。谨慎增大以避免触发速率限制。                                                                                  |
| `gitCommitGenie.llm.maxRetries`                     | number  | 2       | API请求失败最大重试次数。                                                                                                                    |
| `gitCommitGenie.llm.temperature`                    | number  | 0.2     | Temperature（0–2），默认为 0.2。                                                                                                             |
| `gitCommitGenie.repositoryAnalysis.enabled`         | boolean | true    | 启用仓库分析以提供更好的提交信息生成上下文。                                                                                                 |
| `gitCommitGenie.repositoryAnalysis.excludePatterns` | array   | []      | 仓库分析扫描时要排除的文件模式（gitignore风格）。                                                                                            |
| `gitCommitGenie.repositoryAnalysis.updateThreshold` | number  | 10      | 更新仓库分析的提交次数阈值。                                                                                                                 |
| `gitCommitGenie.repositoryAnalysis.model`           | enum    | general | 用于仓库分析的模型。可选择所有供应商支持的模型，系统将自动切换到该模型所属的服务商；或选择“使用与commit message生成相同的模型”以复用主模型。 |
| `gitCommitGenie.commitLanguage`                     | string  | `auto`  | 生成的提交信息目标语言。选项：`auto`、`en`、`zh-CN`、`zh-TW`、`ja`、`ko`、`de`、`fr`、`es`、`pt`、`ru`、`it`。                               |
| `gitCommitGenie.typingAnimationSpeed`               | number  | 15      | 提交信息框打字动画速度，单位为每字符毫秒。设置 -1 关闭动画。                                                                                 |  |
| `gitCommitGenie.showUsageCost`                      | boolean | true    | 启用后在生成文本时弹出通知，显示本次生成的估计总费用。                                                                                       |


## 命令列表

| Command ID                                   | 标题                        | 作用                                         |
| -------------------------------------------- | --------------------------- | -------------------------------------------- |
| `git-commit-genie.generateCommitMessage`     | AI Generate                 | 基于已暂存更改生成提交信息。                 |
| `git-commit-genie.cancelGeneration`          | Stop                        | 取消当前生成。                               |
| `git-commit-genie.manageModels`              | Manage Models               | 选择提供商 / 输入或更换 API Key / 选择模型。 |
| `git-commit-genie.toggleChainMode`           | Toggle Chain Prompting      | 快速开启/关闭链式模式。                      |
| `git-commit-genie.selectTemplate`            | Select/Create Template      | 选择或新建提交信息模板文件。                 |
| `git-commit-genie.viewRepositoryAnalysis`    | View Repository Analysis    | 快速打开仓库分析报告。                       |
| `git-commit-genie.refreshRepositoryAnalysis` | Refresh Repository Analysis | 手动刷新仓库分析。                           |
| `git-commit-genie.cancelRepositoryAnalysis`  | Stop Repository Analysis    | 停止正在进行的仓库分析。                     |
| `git-commit-genie.genieMenu`                 | Menu                        | 打开Git Commit Genie功能菜单。               |
| `git-commit-genie.showRepositoryCost`        | Show Repository Cost        | 显示当前工作区累计消耗估算。                 |
| `git-commit-genie.resetRepositoryCost`       | Reset Repository Cost       | 重置当前工作区累计消耗估算。                 |

SCM 标题栏：根据状态显示“Generate commit message”或“Stop generate”按钮。

## 模板编写
使用命令 `Git Commit Genie: Select/Create Template` 选择或创建模板文件。

<img src="../gitCommitGenie//demo2.gif" width="600"/>

模版文件存在且非空时，系统尝试抽取“模板策略”。支持：
1. 自然语言偏好描述。
2. markdown模版编写。

完整指南： [English](./user-template-guide.md) | [中文](./user-template-guide.zh-CN.md)

最小示例：
```
Minimal Template
- Always include a body with Summary and Changes.
- Use imperative, no trailing period.
- Always include a `Refs` footer (use `Refs: N/A` when missing).
- Prefer: add, fix, refactor; Avoid: update.
```

## 链式模式 vs 单轮模式

| 模式 | 优点                             | 缺点                 | 适用场景                |
| ---- | -------------------------------- | -------------------- | ----------------------- |
| 链式 | 结构最佳，模板贴合度高，分类更准 | 延迟更高，Token 更多 | 多文件 / 需严格风格统一 |
| 单轮 | 快速，成本低                     | 结构细腻度较低       | 小变更 / 临时修复       |

通过命令或设置切换。

## 安全与隐私

- API Key 使用 SecretStorage，不以明文写入 settings.json， 不会以任何形式上传到互联网，仅保存在本地。
- 仅发送“已暂存 diff”中的文件名与修改上下文；不包括未暂存或未跟踪文件。
- 无遥测 / 分析数据收集。

## 常见问题（Troubleshooting）

| 现象                      | 原因                | 解决                                    |
| ------------------------- | ------------------- | --------------------------------------- |
| "No staged changes found" | 未暂存任何文件      | 使用 Source Control 或 `git add` 暂存。 |
| 生成内容空泛              | 模板不明确          | 尝试编写结构化的模版                    |
| 频繁 429                  | 并行过高 / 模板过大 | 降低 `chain.maxParallel`。              |
| 状态栏无“· Thinking”      | 未启用链式          | 使用命令或设置开启。                    |
| 重复要求输入 API Key      | 秘钥被清除          | 重新运行 Manage Models。                |


## 许可证

MIT

## 致谢

- [Conventional Commits](https://conventionalcommits.org/) - https://github.com/conventional-commits/conventionalcommits.org
- OpenAI / DeepSeek / Anthropic / Gemini 模型生态

---

让提交信息不再痛苦。