feat(README): 优化项目描述与功能说明，增强用户引导与配置指引
This commit is contained in:
parent
36ef93f4f2
commit
dee11ba411
227
README.md
227
README.md
|
|
@ -1,167 +1,158 @@
|
||||||
# AutoCommit
|
# 🤖 AutoCommit
|
||||||
|
|
||||||
> 一个智能的 Git 提交助手，使用 LLM 自动生成规范的提交消息并提交暂存的文件。
|
> 自动生成符合 Conventional Commits 规范的 Git 提交消息，基于大语言模型（LLM）智能分析代码变更。
|
||||||
|
|
||||||
## ✨ 特性
|
AutoCommit 利用 LLM（如 Qwen、OpenAI 等）理解你的代码改动，自动生成语义清晰、格式规范的提交信息，并支持一键提交。告别“fix bug”、“update file”这类模糊提交！
|
||||||
|
|
||||||
- **智能生成**：使用大语言模型自动分析代码变更，生成专业、规范的提交消息
|
|
||||||
- **🔧 高度可配置**：支持多种 LLM 提供商（OpenAI 兼容 API）
|
|
||||||
- **🎯 规范遵循**：自动生成符合 [Conventional Commits](https://www.conventionalcommits.org/) 规范的消息
|
|
||||||
- **⚡ 快速便捷**：一键生成并提交，提升开发效率
|
|
||||||
- **🔍 安全检查**：内置配置检查和连接测试
|
|
||||||
- **🎨 美观界面**：使用 Rich 库提供美观的命令行界面
|
|
||||||
- **🔄 异步支持**：支持异步操作，响应快速
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📦 安装
|
## ✨ 特性
|
||||||
|
|
||||||
```bash
|
- ✅ 自动分析 `git diff --staged` 内容
|
||||||
git clone <repository-url>
|
- ✅ 生成符合 [Conventional Commits](https://www.conventionalcommits.org/) 规范的提交消息
|
||||||
cd autocommit
|
- ✅ 支持主流 LLM（Qwen、OpenAI、Ollama、DeepSeek 等）
|
||||||
pip install -e .
|
- ✅ 本地配置管理（`~/.autocommit/config.yaml`）
|
||||||
```
|
- ✅ 安全预览模式（不自动提交）
|
||||||
|
- ✅ 支持自定义系统提示词（system prompt）
|
||||||
|
- ✅ 支持代理与自定义 API 地址
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🚀 快速开始
|
## 🚀 快速开始
|
||||||
|
|
||||||
### 1. 配置（推荐交互式）
|
### 1. 安装
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pip install autocommit
|
||||||
|
```
|
||||||
|
|
||||||
|
> 要求 Python ≥ 3.8
|
||||||
|
|
||||||
|
### 2. 配置（首次使用必做）
|
||||||
|
|
||||||
|
推荐使用交互式配置向导：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 交互式配置向导
|
|
||||||
autocommit config interactive
|
autocommit config interactive
|
||||||
|
|
||||||
# 或直接设置
|
|
||||||
autocommit config set --api-key "sk-your-api-key" --model "qwen3-14b"
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 2. 测试连接
|
或手动设置关键参数：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
autocommit check
|
# 设置 API 密钥和模型（以 Qwen 为例）
|
||||||
|
autocommit config set --api-key "sk-your-api-key" --model "qwen3-14b"
|
||||||
|
|
||||||
|
# 可选：设置自定义 API 地址（如使用 FastChat 或本地部署）
|
||||||
|
autocommit config set --api-url "http://localhost:8000/v1"
|
||||||
```
|
```
|
||||||
|
|
||||||
|
> 配置文件默认保存在 `~/.autocommit/config.yaml`
|
||||||
|
|
||||||
### 3. 使用 AutoCommit
|
### 3. 使用 AutoCommit
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 1. 先将文件添加到暂存区
|
# 1. 添加你要提交的文件
|
||||||
git add .
|
git add .
|
||||||
|
|
||||||
# 2. 使用 AutoCommit 生成提交消息并提交
|
# 2. 自动生成并提交
|
||||||
autocommit
|
autocommit
|
||||||
|
|
||||||
# 3. 或者仅生成消息，不自动提交（预览模式）
|
# 3. 或仅预览提交消息（不实际提交）
|
||||||
autocommit --dry-run
|
autocommit test-commit
|
||||||
|
```
|
||||||
|
|
||||||
|
✅ 成功！你的提交将类似：
|
||||||
|
```
|
||||||
|
feat(auth): implement JWT token refresh logic
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📖 详细使用说明
|
## 🛠️ 命令详解
|
||||||
|
|
||||||
### 基本使用流程
|
| 命令 | 说明 |
|
||||||
|
|------|------|
|
||||||
|
| `autocommit` | 自动生成提交消息并执行 `git commit`（需有暂存文件） |
|
||||||
|
| `autocommit test-commit` | **仅生成消息并打印**，不执行提交（安全预览） |
|
||||||
|
| `autocommit check` | 检查当前配置是否有效，测试与 LLM 的连接 |
|
||||||
|
| `autocommit check --test` | 发送一个固定测试提示，验证 LLM 能否正常响应 |
|
||||||
|
| `autocommit config interactive` | 启动交互式配置向导 |
|
||||||
|
| `autocommit config set [OPTIONS]` | 手动设置配置项（如 `--api-key`, `--model`, `--system-prompt` 等） |
|
||||||
|
| `autocommit config show` | 显示当前配置（敏感信息已脱敏） |
|
||||||
|
|
||||||
```bash
|
> 💡 主命令 `autocommit` **不接受任何参数**（如 `--model`、`--dry-run`）。所有配置必须提前通过 `config set` 完成。
|
||||||
# 完整工作流示例
|
|
||||||
git add .
|
|
||||||
autocommit
|
|
||||||
```
|
|
||||||
|
|
||||||
### 命令行选项
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 显示帮助信息
|
|
||||||
autocommit --help
|
|
||||||
|
|
||||||
# 仅生成消息，不实际提交（预览模式）
|
|
||||||
autocommit --dry-run
|
|
||||||
|
|
||||||
# 指定模型生成
|
|
||||||
autocommit --model "qwen3-14b"
|
|
||||||
|
|
||||||
# 检查工具状态
|
|
||||||
autocommit check
|
|
||||||
|
|
||||||
# 测试消息生成
|
|
||||||
autocommit check --test
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## ⚙️ 配置管理
|
## 🔧 配置选项
|
||||||
|
|
||||||
```bash
|
支持以下配置项（可通过 `config set` 修改）：
|
||||||
# 显示当前配置
|
|
||||||
autocommit config show
|
|
||||||
|
|
||||||
# 交互式配置向导
|
| 参数 | 说明 | 示例 |
|
||||||
autocommit config interactive
|
|------|------|------|
|
||||||
|
| `provider` | LLM 服务商 | `qwen`, `openai`, `ollama`, `deepseek` |
|
||||||
|
| `model` | 模型名称 | `qwen3-14b`, `gpt-4o`, `llama3` |
|
||||||
|
| `api_key` | API 密钥 | `sk-xxxxxx` |
|
||||||
|
| `api_url` | 自定义 API 地址（可选） | `http://localhost:8000/v1` |
|
||||||
|
| `proxy` | HTTP/HTTPS 代理（可选） | `http://127.0.0.1:7890` |
|
||||||
|
| `system_prompt` | 自定义系统提示词（可选） | `"You are a helpful git commit message generator..."` |
|
||||||
|
|
||||||
# 设置特定配置项
|
> ⚠️ 敏感信息（如 `api_key`）不会在 `config show` 中明文显示。
|
||||||
autocommit config set \
|
|
||||||
--api-key "sk-your-key" \
|
|
||||||
--base-url "https://your-api-endpoint.com/v1" \
|
|
||||||
--model "qwen3-14b" \
|
|
||||||
--timeout 30
|
|
||||||
|
|
||||||
# 清除所有配置
|
|
||||||
autocommit config clear
|
|
||||||
```
|
|
||||||
|
|
||||||
### 配置说明
|
|
||||||
|
|
||||||
#### 支持的 LLM 提供商
|
|
||||||
- OpenAI
|
|
||||||
- DashScope（通义千问）
|
|
||||||
- Ollama
|
|
||||||
- **其他兼容 OpenAI API 的服务**
|
|
||||||
|
|
||||||
#### 配置文件位置
|
|
||||||
`~/.config/autocommit/config.yaml`
|
|
||||||
|
|
||||||
#### 示例配置
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
llm:
|
|
||||||
api_key: "sk-your-api-key"
|
|
||||||
base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
|
|
||||||
model: "qwen3-14b"
|
|
||||||
timeout: 30
|
|
||||||
max_tokens: 1000
|
|
||||||
temperature: 0.7
|
|
||||||
extra_body:
|
|
||||||
enable_thinking: false
|
|
||||||
system_prompt: |
|
|
||||||
你是一个专业开发者，请根据以下 git diff 生成一条符合 Conventional Commits 规范的中文 commit message。
|
|
||||||
要求：50字以内，不要解释，不要引号，只输出 message 本身。
|
|
||||||
diff:
|
|
||||||
auto_save: true
|
|
||||||
```
|
|
||||||
|
|
||||||
> 💡 示例代码变更：
|
|
||||||
> ```python
|
|
||||||
> def hello_world():
|
|
||||||
> - print("Hello, World!")
|
|
||||||
> + print("Hello, OpenAI!")
|
|
||||||
> ```
|
|
||||||
> 生成的提交消息：`feat: update greeting message`
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🔧 高级功能
|
## 🧪 测试与调试
|
||||||
|
|
||||||
### 自定义提示词
|
- **测试 LLM 连通性**：
|
||||||
|
```bash
|
||||||
|
autocommit check
|
||||||
|
```
|
||||||
|
|
||||||
你可以修改系统提示词以适应特定需求：
|
- **测试提交消息生成逻辑**（使用真实或示例 diff）：
|
||||||
|
```bash
|
||||||
|
autocommit test-commit
|
||||||
|
```
|
||||||
|
|
||||||
```bash
|
- **查看详细日志**（调试用）：
|
||||||
autocommit config set --system-prompt "你是一个前端开发者，请根据代码变更生成提交消息，重点描述 UI 变化。"
|
```bash
|
||||||
```
|
# 设置环境变量开启调试
|
||||||
|
export AUTOCOMMIT_DEBUG=1
|
||||||
|
autocommit
|
||||||
|
```
|
||||||
|
|
||||||
### 异步模式
|
---
|
||||||
|
|
||||||
对于大量文件或复杂的代码库，工具会自动使用异步模式提高性能。
|
## 📝 注意事项
|
||||||
|
|
||||||
### 多语言支持
|
- 必须在 **Git 仓库根目录** 中运行，且 **有暂存的更改**（`git add` 过的文件）。
|
||||||
|
- 如果没有暂存内容，`autocommit` 会报错并退出。
|
||||||
|
- `test-commit` 命令在无暂存时会使用**内置示例 diff** 进行演示。
|
||||||
|
- 不同 LLM 提供商的 `model` 名称可能不同，请参考对应文档。
|
||||||
|
|
||||||
通过修改系统提示词，可以支持多种语言的提交消息（如英文、中文、日文等）。
|
---
|
||||||
|
|
||||||
|
## 🌐 支持的 LLM 提供商
|
||||||
|
|
||||||
|
| 提供商 | 配置 `provider` 值 | 备注 |
|
||||||
|
|--------|-------------------|------|
|
||||||
|
| 阿里通义千问（Qwen） | `qwen` | 推荐使用 DashScope API |
|
||||||
|
| OpenAI | `openai` | 支持 GPT-3.5 / GPT-4 |
|
||||||
|
| Ollama（本地） | `ollama` | 需运行 `ollama serve` |
|
||||||
|
| DeepSeek | `deepseek` | 需 API Key |
|
||||||
|
| 兼容 OpenAI 协议的服务器 | 任一 + `--api-url` | 如 FastChat、vLLM |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📄 许可证
|
||||||
|
|
||||||
|
MIT License
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🙌 贡献与反馈
|
||||||
|
|
||||||
|
欢迎提交 Issue 或 PR！
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
> Made with ❤️ for developers who care about clean Git history.
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue