内容
# 智能提交 🤖
[](https://badge.fury.io/py/smart-commit-ai)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://pepy.tech/project/smart-commit-ai)
一个基于人工智能的 git 提交信息生成器，具有仓库上下文感知功能，使用 Python 和 Typer 构建。
## 为什么选择 Smart Commit？
作为开发者，我们知道良好提交信息的重要性。它们作为历史记录，帮助调试，促进代码审查，并使协作变得顺畅。但说实话，始终如一地写出详细、有意义的提交信息是 **困难** 的。
### 问题
**时间压力与上下文切换**：当你同时处理多个项目时，在不同的代码库、技术和上下文之间切换，编写深思熟虑的提交信息变得越来越困难。曾经是你工作流程自然一部分的事情，现在却成了瓶颈。
**认知负荷**：在代码中深耕数小时后，你最不想做的就是切换到写文档。你的大脑处于“代码模式”，而不是“文档模式”。
**项目间的一致性**：每个项目都有其自己的约定、技术栈和提交模式。当你在一天内处理3-4个不同的代码库时，保持一致性几乎是不可能的。
**恶性循环**：糟糕的提交信息导致糟糕的项目历史。当你需要理解发生了什么变化以及原因（在调试、代码审查或新团队成员入职时），像“修复东西”或“更新”这样的模糊信息毫无价值。
### 解决方案
Smart Commit 理解您的代码库上下文——技术栈、最近的提交模式、文件更改和项目结构。它生成有意义且详细的提交信息，能够：
- **捕捉“为什么”**：不仅仅是更改了什么，还有更改背后的原因
- **保持一致性**：遵循您项目已建立的模式和约定
- **节省脑力**：让 AI 处理文字描述，而您专注于代码
- **保留历史**：创建一个丰富的、可搜索的项目时间线，真正帮助未来的您
**差异示例：**
而不是：
```
fix auth bug
update dependencies
refactor components
```
您将得到：
```
fix(auth): resolve JWT token expiration handling
- Fix race condition in token refresh mechanism
- Add proper error handling for expired tokens
- Update token validation middleware
- Add unit tests for edge cases
This resolves the issue where users were unexpectedly logged out
during active sessions due to improper token lifecycle management.
```
Smart Commit 将您的提交历史转变为一个有价值的项目资源，讲述您的代码库演变的故事。
## 特性
- 🧠 **AI驱动**：使用 OpenAI GPT 和 Anthropic Claude 模型生成有意义的提交信息
- 📁 **仓库上下文**：分析您的仓库结构、技术栈和最近的提交
- ⚙️ **可配置**：支持全局和本地配置以及传统提交格式
- 🖥️ **CLI接口**：丰富的交互式命令行界面，使用 Typer
- 🔧 **MCP Server**：模型上下文协议服务器，用于与 AI 助手集成
- 🎯 **智能过滤**：每个仓库的忽略模式和自定义规则
- 📝 **交互式编辑**：在提交之前编辑生成的信息
- 🏗️ **上下文文件**：包含项目文档以增强理解
- 🎨 **自定义模板**：可配置的提交信息格式和示例
- 🪝 **Git Hooks**：通过 git hooks 自动生成提交信息
- 🔒 **安全性**：敏感数据检测以防止提交秘密
- 📊 **提交拆分**：智能分析建议如何拆分大型提交
- 💾 **缓存**：缓存提交信息以加快重复生成的速度
- 🔐 **隐私模式**：从 AI 提示中排除文件路径和上下文文件
## 安装
### 需求
- Python 3.10 或更高版本
- Git 仓库（用于生成提交信息）
- 你选择的 AI 提供商的 API 密钥（由于 [LiteLLM](https://litellm.ai) 的支持，支持 100 多种模型）
### 使用 uv（推荐）
```bash
```
# 如果还没有安装uv，请执行以下命令
curl -LsSf https://astral.sh/uv/install.sh | sh
# 安装并作为工具运行（系统范围安装）
uv tool install smart-commit-ai
# 在任何仓库中使用该工具
sc generate
```
### 使用 pip
```bash
pip install smart-commit-ai
```
# 安装带有Anthropic支持的版本
pip install smart-commit-ai[anthropic]
# 安装所有可选依赖
pip install smart-commit-ai[all]
```
## 快速设置
`smart-commit` 主要通过环境变量进行配置，这样既安全又灵活。
```bash
```
# 设置你的AI模型和API密钥
export AI_MODEL="openai/gpt-4o" # 或 "claude-3-sonnet-20240229", "gemini/gemini-1.5-pro" 等等。
export AI_API_KEY="your-super-secret-api-key"
# 您可以将这些添加到您的 .bashrc、.zshrc 或 shell 配置文件中，以使其永久生效。
```
`AI_MODEL` 可以设置为 `litellm` 支持的任何模型。有关可用提供者和模型名称的完整列表，请参阅 [LiteLLM Provider Documentation](https://docs.litellm.ai/docs/providers)。
您还可以运行设置命令以保存一个备用配置文件：
```bash
```
# 这将指导您保存配置文件。
smart-commit setup
```
## 使用方法
### 生成提交信息
```bash
```
# 为暂存的更改生成提交信息
smart-commit generate
# 添加额外的上下文
smart-commit generate --message "修复用户身份验证问题"
# 无需确认的自动提交
smart-commit generate --auto
# 干运行（仅生成消息）
smart-commit generate --dry-run
# 非交互模式
smart-commit generate --no-interactive
```
### 配置管理
```bash
```
# 初始化配置（可选的示例仓库配置）
smart-commit config --init
# 编辑配置
smart-commit config --edit
# 显示当前配置
smart-commit config --show
# 本地仓库配置
smart-commit config --init --local
```
### 仓库分析
```bash
```
# 显示当前仓库的详细信息
smart-commit context
# 显示特定仓库的详细信息
smart-commit context /path/to/repo
```
### 提交拆分分析
分析暂存的更改并获取拆分为逻辑提交的建议：
```bash
```
# 分析并建议提交组
smart-commit analyze
# 别名: sc analyze
# 显示每个组的详细文件信息
smart-commit analyze --detailed
```
示例输出：
```
暂存更改分析
文件数：12
行数：+283 -210
💡 检测到 2 个逻辑提交组：
组 1：源代码更改 (4 个文件)
└─ 相关源代码功能更改
• smart_commit/cli.py
• smart_commit/config.py
• smart_commit/templates.py
• smart_commit/utils.py
组 2：测试 (8 个文件)
└─ 单独的测试更改以便于审查和 CI 验证
• tests/test_cli.py
• tests/test_config.py
... 还有 6 个文件
建议的工作流程：
1. git reset # 取消暂存所有文件
1. 暂存并提交源代码更改：
git add "smart_commit/cli.py" "smart_commit/config.py" ...
sc generate
2. 暂存并提交测试：
git add "tests/test_cli.py" "tests/test_config.py" ...
sc generate
```
### Git Hooks 集成
安装 git hooks 以自动生成提交信息：
```bash
```
# 安装 prepare-commit-msg 钩子
smart-commit install-hook
# 别名：sc install-hook
# 强制安装（覆盖现有的钩子）
smart-commit install-hook --force
# 卸载钩子
smart-commit uninstall-hook
```
安装后，运行 `git commit`（不带 `-m`）将自动生成一个提交信息，使用 smart-commit。
**安全提示**：该钩子会自动检测潜在的敏感数据（API 密钥、令牌等），并在提交之前提醒您。
### 缓存管理
Smart-commit 缓存生成的消息以提高性能：
```bash
# 查看缓存统计信息
smart-commit cache stats
# 清除所有缓存的消息
smart-commit cache clear
# 仅清除过期的缓存条目
smart-commit cache clear-expired
```
### 隐私模式
从 AI 提示中排除文件路径和上下文文件：
```bash
```
# 使用隐私模式生成
smart-commit generate --privacy
```
在处理敏感代码库时，或者当您希望最小化发送给AI提供商的数据时，这个功能非常有用。
## 配置
Smart-commit 支持全局和本地配置：
- **全局**: `~/.config/smart-commit/config.toml`
- **本地**: 在你的仓库中 `.smart-commit.toml`
### 增强的配置选项
现在的配置包含了增强的功能，以便更好地生成提交信息：
```toml
[ai]
model = "gpt-4o"
api_key = "your-api-key"
max_tokens = 500
temperature = 0.1
[template]
max_subject_length = 50
max_recent_commits = 5 # 要分析的最近提交数量
include_body = true
include_reasoning = true
conventional_commits = true
```
# AI指导的自定义示例格式
example_formats = [
"""feat: 添加用户认证系统
- 实现基于JWT的认证
- 添加登录和登出端点
- 包含使用bcrypt的密码哈希
- 为受保护的路由添加认证中间件
这使得用户会话安全，并保护敏感端点免受未经授权的访问。"""
]
# 增强的提交类型前缀及其描述
[template.custom_prefixes]
feat = "用于新功能"
fix = "用于修复错误"
docs = "用于文档更改"
style = "用于格式更改"
refactor = "用于代码重构"
test = "用于测试更改"
chore = "用于维护任务"
perf = "用于性能改进"
build = "用于构建系统更改"
ci = "用于CI/CD更改"
revert = "用于还原更改"
# 特定于仓库的配置与增强上下文
[repositories.my-project]
name = "my-project"
description = "我的精彩项目"
absolute_path = "/absolute/path/to/project" # 访问上下文文件的显式路径
tech_stack = ["python", "react", "docker"]
ignore_patterns = ["*.log", "node_modules/**"]
context_files = ["README.md", "CHANGELOG.md"] # 包含在AI上下文中的文件
# 综合提交规范
[repositories.my-project.commit_conventions]
breaking = "在页脚使用 BREAKING CHANGE: 来标识需要主版本升级的重大变更"
scope = "在类型后使用括号中的范围: feat(auth): 添加登录系统"
subject_case = "使用小写的祈使语气: '添加功能' 而不是 '添加了功能' 或 '添加功能过了'"
subject_length = "保持主题行在50个字符以内以提高可读性"
body_format = "正文换行在72个字符处，对于多个更改使用项目符号"
body_separation = "用空行将主题与正文分开"
present_tense = "使用现在时: '更改' 而不是 '更改过' 或 '更改中'"
no_period = "主题行末尾不要加句号"
why_not_what = "解释为什么进行更改，而不仅仅是说明更改了什么"
atomic_commits = "确保每个提交都是一个单一的逻辑更改"
test_coverage = "在添加新功能时包含测试更改"
docs_update = "在更改公共 API 或行为时更新文档"
## 仓库上下文特性
Smart-commit 自动检测并使用：
- 📊 **技术栈**：语言、框架和工具
- 🌿 **分支信息**：活跃分支和当前分支
- 📝 **最近提交**：可配置的最近提交数量用于模式分析
- 📁 **文件结构**：仓库组织
- 🔍 **项目元数据**：README 描述和项目信息
- 📚 **上下文文件**：包含在 AI 上下文中的项目文档
- 🎯 **绝对路径**：多仓库设置中精确的文件位置
- 🚫 **忽略模式**：自定义模式以排除文件分析
- 🗂️ **提交约定**：项目特定的提交信息指南
## MCP Server 集成
Smart-commit 包含对 MCP (模型上下文协议) 服务器的支持，以便与像 Claude Desktop 这样的 AI 助手进行集成。
### 作为 MCP Server 运行
```bash
```
# 直接运行 MCP 服务器
python -m smart_commit.mcp
# 或在您的 MCP 客户端配置中使用它
```
### MCP客户端配置
将以下内容添加到您的MCP客户端配置中（例如，Claude Desktop）：
```json
{
"mcpServers": {
"smart-commit": {
"command": "python",
"args": ["-m", "smart_commit.mcp"]
}
}
}
```
### 可用的 MCP 工具
- `analyze_repository`: 分析仓库结构和上下文
- `generate_commit_message`: 生成 AI 驱动的提交信息
- `get_staged_changes`: 获取当前暂存的更改
- `configure_smart_commit`: 更新配置设置
- `get_repository_context`: 获取详细的仓库信息
- `quick_setup`: 快速配置设置
- `show_configuration`: 显示当前配置
### MCP 资源
- `repository://current`: 当前仓库信息
- `config://smart-commit`: 智能提交配置
### MCP 提示
- `commit_message_template`: 提交信息生成的模板
- `repository_analysis_prompt`: 仓库分析的模板
## 高级功能
### 安全性：敏感数据检测
Smart-commit 会自动扫描您暂存的更改，以查找潜在的秘密和敏感数据：
**检测到的模式：**
- API 密钥（AWS、GitHub、Stripe、Google 等）
- 身份验证令牌（JWT、Bearer tokens、OAuth）
- 私钥和证书
- 数据库连接字符串
- 密码和秘密
- 敏感文件（.env、credentials.json、私钥等）
当检测到敏感数据时：
```bash
```
# 交互模式 - 提示确认
smart-commit generate
# Git hook 模式 - 在提交信息编辑器中显示警告
git commit # 打开带有警告信息的编辑器
# 非交互模式 - 自动中止
smart-commit generate --no-interactive --dry-run
```
在 git hook 中的示例警告：
```
# ⚠️ 检测到敏感数据
#
# smart-commit 检测到您的更改中可能包含敏感数据：
#
# 潜在的秘密：
# - AWS Access Key: 1 次出现
# - 通用 API 密钥：2 次出现
#
# 请检查您的更改并：
# 1. 移除敏感数据后再试，或者
# 2. 运行 'sc generate --auto' 来查看并覆盖，如果这是测试数据，或者
# 3. 手动提交使用 'git commit -m "your message"'
```
**最佳实践：**
- 使用环境变量存储秘密
- 将敏感文件添加到 `.gitignore`
- 使用秘密管理工具（Vault、AWS Secrets Manager 等）
- 仅对测试/模拟数据覆盖警告
### 自定义忽略模式
添加模式以忽略特定文件或更改：
```toml
[repositories.my-project]
ignore_patterns = [
"*.log",
"node_modules/**",
"dist/**",
"*.generated.*"
]
```
### 增强理解的上下文文件
包含特定文件以提供额外的AI上下文：
```toml
[repositories.my-project]
absolute_path = "/home/user/projects/my-project"
context_files = [
"README.md",
"CHANGELOG.md",
"docs/contributing.md",
"API_REFERENCE.md"
]
```
AI将读取这些文件，并利用其内容更好地理解您的项目结构，从而生成更相关的提交信息。
### 自定义提交类型及描述
定义项目特定的提交类型及其清晰描述：
```toml
[template.custom_prefixes]
feat = "用于新功能"
fix = "用于修复错误"
hotfix = "用于关键生产修复"
security = "用于与安全相关的更改"
deps = "用于依赖更新"
config = "用于配置更改"
```
### 最近提交分析
配置要分析的最近提交数量，以检查模式一致性：
```toml
[template]
max_recent_commits = 10 # 分析最近的10个提交以查找模式
```
这有助于保持与您现有提交风格和约定的一致性。
## 示例
### 基本用法
```bash
```
# 暂存你的更改
git add .
# 生成提交信息
smart-commit generate
```
示例输出：
```
生成的提交信息：
feat: 添加用户认证系统
- 实现基于JWT的认证
- 添加登录和登出端点
- 创建用户会话管理
- 使用bcrypt进行密码哈希
此更改引入了一个完整的认证系统，以确保用户访问的安全性并有效管理会话。
```
### 带增强上下文
```bash
```
# 生成附加上下文
smart-commit generate -m "解决 GitHub 问题 #123"
# 自动提交
smart-commit generate --auto
# 详细输出
smart-commit generate --verbose
```
### 使用上下文文件设置仓库
```bash
# 为你的项目初始化本地配置
smart-commit config --init --local
# 将提示：“是否包含示例仓库配置？ [y/N]”
# 这将创建包含上下文文件的配置
# 编辑 .smart-commit.toml 以指定您的上下文文件：
[repositories.my-project]
name = "my-project"
description = "我的精彩项目描述"
absolute_path = "/full/path/to/project"
context_files = ["README.md", "docs/ARCHITECTURE.md"]
```
### 多仓库工作流
对于在多个仓库中工作的开发者：
```toml
```
# 全局配置在 ~/.config/smart-commit/config.toml
[repositories.frontend-app]
name = "frontend-app"
description = "React 前端应用"
absolute_path = "/home/dev/projects/frontend-app"
tech_stack = ["react", "typescript", "tailwind"]
context_files = ["README.md", "package.json"]
[repositories.backend-api]
name = "backend-api"
description = "Python FastAPI 后端"
absolute_path = "/home/dev/projects/backend-api"
tech_stack = ["python", "fastapi", "postgresql"]
context_files = ["README.md", "requirements.txt", "docs/API.md"]
[repositories.mobile-app]
name = "mobile-app"
description = "React Native 移动应用"
absolute_path = "/home/dev/projects/mobile-app"
tech_stack = ["react-native", "typescript", "expo"]
context_files = ["README.md", "app.json", "docs/SETUP.md"]
```
这使得 Smart Commit 能够自动理解您正在工作的任何仓库的上下文，并生成适当的提交信息。
## 环境变量
- `EDITOR`: 用于交互式消息编辑的首选编辑器（默认: nano）
## 故障排除
### 常见问题
**"未找到暂存的更改"**
- 确保您已使用 `git add` 暂存您的更改
- 检查您是否在一个 git 仓库中
**"API 密钥未配置"**
- 运行 `smart-commit setup` 来配置您的 API 密钥
**"AI 提供者错误"**
- 验证您的 API 密钥是否有效并且有足够的额度
- 检查您的互联网连接
- 尝试切换到不同的模型
**"未找到配置"**
- 运行 `smart-commit config --init` 来创建初始配置
- 检查配置文件是否存在于 `~/.config/smart-commit/config.toml`
**"未找到上下文文件"**
- 验证您在仓库配置中的 `absolute_path` 是否正确
- 检查指定位置是否存在上下文文件
- 如果未设置 `absolute_path`，请使用相对于仓库根目录的路径
### 调试模式
```bash
```
# 以详细输出模式运行以进行调试
smart-commit generate --verbose
# 显示配置详情
smart-commit config --show
# 分析仓库上下文
smart-commit context
```
## 开发
### 设置开发环境
```bash
```
# 克隆仓库
git clone https://github.com/subhayu99/smart-commit.git
cd smart-commit
# 如果您还没有安装 uv，请执行以下命令
curl -LsSf https://astral.sh/uv/install.sh | sh
# 安装开发依赖
uv pip install -e ".[dev]"
# 安装所有可选依赖
uv pip install -e ".[all]"
### 运行测试
```bash
```
# 运行测试
pytest
# 运行带覆盖率的测试
pytest --cov=smart_commit
```
### 代码质量
```bash
```
# 格式化代码
black smart_commit/
isort smart_commit/
# 类型检查
mypy smart_commit/
# 运行 pre-commit 钩子
pre-commit run --all-files
```
### 构建和发布
```bash
```
# 构建包
uv build
# 发布到 PyPI（仅限维护者）
uv publish
```
## 贡献
1. Fork 这个仓库
2. 创建一个功能分支 (`git checkout -b feature/amazing-feature`)
3. 进行你的修改
4. 如果适用，添加测试
5. 运行测试套件 (`pytest`)
6. 用描述性的信息提交你的更改
7. 推送到你的分支 (`git push origin feature/amazing-feature`)
8. 创建一个 Pull Request
## 许可证
MIT 许可证 - 详细信息请参见 [LICENSE](LICENSE) 文件。
## 路线图
### 已完成 ✅
- [x] Git hooks 集成
- [x] 通过 LiteLLM 支持 100+ 人工智能模型（OpenAI、Anthropic、Google 等）
- [x] 提交信息缓存以提高性能
- [x] 敏感数据检测
- [x] 隐私模式
- [x] 提交拆分分析
- [x] 命令别名（例如，`sc` 代表 `smart-commit`）
### 计划中 🚧
- [ ] 自定义提交信息格式的插件系统
- [ ] 与流行的 Git 图形用户界面集成
- [ ] 预提交钩子集成
- [ ] 团队/组织共享配置
- [ ] 支持 CI/CD 集成的 Webhook
- [ ] VS Code 扩展
- [ ] 提交信息质量评分
- [ ] 与问题跟踪系统（GitHub、Jira 等）集成
- [ ] 提交信息验证和代码检查
- [ ] 基于 AI 的代码审查建议
## 支持
- 📖 [文档](https://github.com/subhayu99/smart-commit#readme)
- 🐛 [错误报告](https://github.com/subhayu99/smart-commit/issues)
- 💡 [功能请求](https://github.com/subhayu99/smart-commit/issues)
- 💬 [讨论](https://github.com/subhayu99/smart-commit/discussions)
---
由 [Subhayu Kumar Bala](https://github.com/subhayu99) ❤️ 制作
连接信息
猜你喜欢
暂无推荐服务器