From dee11ba4114a959eae7918b4bc395cabbb923a69 Mon Sep 17 00:00:00 2001 From: songsenand Date: Fri, 6 Feb 2026 09:55:09 +0800 Subject: [PATCH] =?UTF-8?q?feat(README):=20=E4=BC=98=E5=8C=96=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E6=8F=8F=E8=BF=B0=E4=B8=8E=E5=8A=9F=E8=83=BD=E8=AF=B4?= =?UTF-8?q?=E6=98=8E=EF=BC=8C=E5=A2=9E=E5=BC=BA=E7=94=A8=E6=88=B7=E5=BC=95?= =?UTF-8?q?=E5=AF=BC=E4=B8=8E=E9=85=8D=E7=BD=AE=E6=8C=87=E5=BC=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 227 ++++++++++++++++++++++++++---------------------------- 1 file changed, 109 insertions(+), 118 deletions(-) diff --git a/README.md b/README.md index a4f5bbf..03c627b 100644 --- a/README.md +++ b/README.md @@ -1,167 +1,158 @@ -# AutoCommit +# 🤖 AutoCommit -> 一个智能的 Git 提交助手，使用 LLM 自动生成规范的提交消息并提交暂存的文件。 +> 自动生成符合 Conventional Commits 规范的 Git 提交消息，基于大语言模型（LLM）智能分析代码变更。 -## ✨ 特性 - -- **智能生成**：使用大语言模型自动分析代码变更，生成专业、规范的提交消息 -- **🔧 高度可配置**：支持多种 LLM 提供商（OpenAI 兼容 API） -- **🎯 规范遵循**：自动生成符合 [Conventional Commits](https://www.conventionalcommits.org/) 规范的消息 -- **⚡ 快速便捷**：一键生成并提交，提升开发效率 -- **🔍 安全检查**：内置配置检查和连接测试 -- **🎨 美观界面**：使用 Rich 库提供美观的命令行界面 -- **🔄 异步支持**：支持异步操作，响应快速 +AutoCommit 利用 LLM（如 Qwen、OpenAI 等）理解你的代码改动，自动生成语义清晰、格式规范的提交信息，并支持一键提交。告别“fix bug”、“update file”这类模糊提交！ --- -## 📦 安装 +## ✨ 特性 -```bash -git clone -cd autocommit -pip install -e . -``` +- ✅ 自动分析 `git diff --staged` 内容 +- ✅ 生成符合 [Conventional Commits](https://www.conventionalcommits.org/) 规范的提交消息 +- ✅ 支持主流 LLM（Qwen、OpenAI、Ollama、DeepSeek 等） +- ✅ 本地配置管理（`~/.autocommit/config.yaml`） +- ✅ 安全预览模式（不自动提交） +- ✅ 支持自定义系统提示词（system prompt） +- ✅ 支持代理与自定义 API 地址 --- ## 🚀 快速开始 -### 1. 配置（推荐交互式） +### 1. 安装 + +```bash +pip install autocommit +``` + +> 要求 Python ≥ 3.8 + +### 2. 配置（首次使用必做） + +推荐使用交互式配置向导： ```bash -# 交互式配置向导 autocommit config interactive - -# 或直接设置 -autocommit config set --api-key "sk-your-api-key" --model "qwen3-14b" ``` -### 2. 测试连接 +或手动设置关键参数： ```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 ```bash -# 1. 先将文件添加到暂存区 +# 1. 添加你要提交的文件 git add . -# 2. 使用 AutoCommit 生成提交消息并提交 +# 2. 自动生成并提交 autocommit -# 3. 或者仅生成消息，不自动提交（预览模式） -autocommit --dry-run +# 3. 或仅预览提交消息（不实际提交） +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 -# 完整工作流示例 -git add . -autocommit -``` - -### 命令行选项 - -```bash -# 显示帮助信息 -autocommit --help - -# 仅生成消息，不实际提交（预览模式） -autocommit --dry-run - -# 指定模型生成 -autocommit --model "qwen3-14b" - -# 检查工具状态 -autocommit check - -# 测试消息生成 -autocommit check --test -``` +> 💡 主命令 `autocommit` **不接受任何参数**（如 `--model`、`--dry-run`）。所有配置必须提前通过 `config set` 完成。 --- -## ⚙️ 配置管理 +## 🔧 配置选项 -```bash -# 显示当前配置 -autocommit config show +支持以下配置项（可通过 `config set` 修改）： -# 交互式配置向导 -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..."` | -# 设置特定配置项 -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` +> ⚠️ 敏感信息（如 `api_key`）不会在 `config show` 中明文显示。 --- -## 🔧 高级功能 +## 🧪 测试与调试 -### 自定义提示词 +- **测试 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.