Metadata-Version: 2.5
Name: gitai-agent
Version: 0.2.0
Summary: 用大模型自动生成 Git 提交信息并推送的 AI Agent
Project-URL: Homepage, https://github.com/your-org/gitai-agent
Project-URL: Documentation, https://github.com/your-org/gitai-agent#readme
Project-URL: Repository, https://github.com/your-org/gitai-agent
Project-URL: Issues, https://github.com/your-org/gitai-agent/issues
Author: GitAI Team
License: MIT
License-File: LICENSE
Keywords: agent,ai,automation,commit,git,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.9
Requires-Dist: langchain-core>=0.3.0
Requires-Dist: langchain-openai>=0.2.0
Requires-Dist: langgraph>=0.2.0
Requires-Dist: litellm>=1.40.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: tomli>=2.0.1; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: pytest-cov>=4; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: docker
Requires-Dist: docker>=7.0.0; extra == 'docker'
Description-Content-Type: text/markdown

# GitAI - 用大模型自动生成 Git 提交信息

[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

一个基于大语言模型的 Git 提交辅助工具，能够自动分析代码变更，生成符合规范的提交信息，并可选推送到远程仓库。

## ✨ 特性

- 🤖 **智能生成**：基于大语言模型，自动生成高质量的 Git 提交信息
- 🌍 **多平台支持**：支持 OpenAI、Claude、Gemini、Ollama、DeepSeek、通义千问等 15+ 主流平台
- 📝 **规范提交**：支持 Conventional Commits 规范，自动生成格式化的提交信息
- 🌐 **多语言**：支持中文、英文、日文等多种语言的提交信息
- ⚙️ **灵活配置**：支持配置文件、环境变量、命令行参数三种配置方式
- 🔒 **安全可靠**：支持本地部署的 Ollama，代码不会上传到第三方服务
- 🚀 **自动推送**：可选自动推送到远程仓库，提高工作效率
- 💾 **智能记忆**：自动记住上次使用的命令参数，下次直接运行 `gitai` 即可复用

## 📦 安装

### 方式一：从源码安装（开发模式）

```bash
# 克隆项目
git clone <repository-url>
cd gitai

# 安装依赖（开发模式）
pip install -e .

# 或者直接运行模块
python -m gitai
```

### 方式二：从 PyPI 安装（发布后）

```bash
pip install gitai-agent
```

### 依赖要求

- Python 3.9 或更高版本
- Git（用于版本控制操作）

## 🚀 快速开始

### 1. 查看支持的平台

```bash
gitai --list-providers
```

### 2. 使用 Ollama 本地模型（推荐，无需 API Key）

```bash
# 确保已安装并启动 Ollama
# ollama pull qwen2.5-coder:7b
# ollama serve

# 使用本地模型生成提交信息
gitai -p ollama -m qwen2.5-coder:7b -y
```

### 3. 使用 OpenAI

```bash
# 设置 API Key
export OPENAI_API_KEY=sk-xxxx

# 生成并提交
gitai -p openai -m gpt-4o-mini -y
```

### 4. 使用 DeepSeek

```bash
# 设置 API Key
export DEEPSEEK_API_KEY=sk-xxxx

# 生成中文提交信息并推送
gitai -p deepseek -l zh -y --push
```

## 📖 使用指南

### 核心工作流

整个 Agent 的执行流程如下：

1. **检测变更**：默认自动执行 `git add -A`，将工作区和暂存区的改动都纳入分析范围。如果只想提交已暂存内容，可以使用 `--only-staged` 参数。

2. **生成提交信息**：将变更的统计信息、diff 内容、最近历史提交一起发送给大模型，支持 Conventional Commits 和简单摘要两种风格，还能指定语言（如中文）。

3. **人工确认或直接提交**：默认会展示生成的提交信息并询问确认：
   - `y` - 确认提交
   - `e` - 编辑提交信息
   - `r` - 重新生成
   - `n` - 取消操作
   
   使用 `-y` 参数可跳过交互确认。

4. **提交并推送**：确认后执行 `git commit`，添加 `--push` 参数会自动推送到远程仓库。如果当前分支没有上游，会自动设置 `-u origin <branch>`。

### 常见使用场景

| 场景 | 命令 | 说明 |
|------|------|------|
| 分析并提交 | gitai | 分析全部改动并提交（首次交互确认，后续复用上次参数） |
| 强制交互确认 | gitai -i | 覆盖上次保存的参数，强制进入交互模式 |
| 跳过确认直接提交 | `gitai -y` | 自动生成并提交 |
| 提交并推送 | `gitai -y --push` | 提交后推送到 origin |
| 指定平台和模型 | `gitai -p openai -m gpt-4o -y` | 使用 OpenAI GPT-4o |
| 使用 Ollama 本地模型 | `gitai -p ollama -m qwen2.5-coder:7b -l zh -y` | 本地部署，无需 API Key |
| 只提交已暂存内容 | `gitai --only-staged` | 不自动执行 git add |
| 只生成不提交 | `gitai --dry-run` | 查看生成的提交信息 |
| 查看支持的平台 | `gitai --list-providers` | 列出所有支持的平台 |
| 生成中文提交信息 | `gitai -l zh` | 使用中文生成提交信息 |
| 额外排除文件 | `gitai --exclude "*.csv" --exclude "data/*"` | 排除特定文件 |
| 使用自定义端点 | `gitai -p custom --api-base http://host/v1 -m my-model` | 接入任意 OpenAI 兼容服务 |

### 💾 智能记忆功能

GitAI 会自动记住你上次使用的命令参数，下次直接运行 `gitai` 即可复用，无需重复输入。

**工作原理：**

1. 当你使用特定参数运行 `gitai` 时（如 `gitai -p zhipu -y --push`），这些参数会被自动保存
2. 下次直接运行 `gitai`（不带任何参数）时，工具会自动加载并使用上次保存的参数
3. 参数状态文件保存在 `~/.config/gitai/last_args.json`（Windows: `C:\Users\<用户名>\.config\gitai\last_args.json`）

**使用示例：**

```bash
# 第一次：使用特定参数运行
gitai -p zhipu -y --push

# 之后：直接运行 gitai，自动复用 -p zhipu -y --push 参数
gitai

# 如果想使用不同的参数，直接指定即可（会覆盖上次保存的参数）
gitai -p ollama -m qwen2.5-coder:7b -y

# 再次直接运行，会使用最新的参数
gitai
```

**注意事项：**

- 只有当你显式提供参数时，才会保存参数状态
- 运行 `gitai --help`、`gitai --list-providers` 等查询命令不会保存参数
- 如果想恢复默认行为，可以删除状态文件：`rm ~/.config/gitai/last_args.json`
- 如果上次保存了 `-y` 参数，但这次想进入交互模式，可以使用 `-i` 或 `--interactive` 强制进入交互模式：
  ```bash
  # 上次保存的是 -y --push，这次强制进入交互模式
  gitai -i --push
  ```

## ⚙️ 配置方式

GitAI 支持三种配置方式，优先级从高到低：

1. **命令行参数**（如 `--model`、`--api-base`）
2. **环境变量**（`GITAI_*` 前缀）
3. **配置文件**（`.gitai.toml` 或 `~/.config/gitai/config.toml`）
4. **内置默认值**

### 配置文件

在项目根目录创建 `.gitai.toml` 文件：

```toml
[gitai]
# 大模型平台配置
provider = "ollama"
model = "qwen2.5-coder:7b"
api_base = "http://localhost:11434"

# 生成参数
language = "zh"
style = "conventional"
temperature = 0.2
max_diff_chars = 40000
max_file_chars = 12000

# Git 行为
auto_stage = true
auto_push = false
push_remote = "origin"

# 额外的项目约定
extra_instructions = """
- 这是一个 Python 项目，遵循 PEP 8
- scope 优先使用模块名：cli / config / llm / git
"""

# 排除的文件模式
exclude_patterns = [
    "*.lock",
    "package-lock.json",
    "*.min.js",
    "dist/*",
    "node_modules/*",
]
```

### 环境变量

复制 `.env.example` 为 `.env` 并设置相应的 API Key：

```bash
# 设置 OpenAI API Key
export OPENAI_API_KEY=sk-xxxx

# 或者使用 DeepSeek
export DEEPSEEK_API_KEY=sk-xxxx

# 配置 GitAI
export GITAI_PROVIDER=ollama
export GITAI_MODEL=qwen2.5-coder:7b
export GITAI_LANGUAGE=zh
export GITAI_AUTO_PUSH=false
```

### 查看生效的配置

```bash
gitai --print-config
```

## 🎯 提交信息风格

### Conventional Commits（默认）

严格遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：

```
<type>(<scope>): <subject>

<body>

<footer>
```

- **type**: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
- **scope**: 可选，模块名称（如 api, cli, deps）
- **subject**: 祈使句，小写开头，不超过 72 字符
- **body**: 详细描述改动（可选）
- **footer**: 破坏性变更说明（可选）

### Simple 模式

简单摘要风格，适合小型项目或个人项目：

```
<summary>

<body>
```

- **summary**: 简洁的摘要，不超过 72 字符
- **body**: 改动细节与原因（可选）

## 🔧 高级用法

### 自定义 OpenAI 兼容端点

任何提供 OpenAI 兼容 API 的服务都可以接入：

```bash
gitai -p custom --api-base http://your-host:8000/v1 -m your-model -y
```

### 编辑器集成

提交信息确认时可以选择编辑：

- 按 `e` 进入编辑模式
- 使用 `$EDITOR` 环境变量指定的编辑器
- 支持设置 `GITAI_EDITOR` 或 `GIT_EDITOR` 覆盖默认编辑器

### 跳过 Git Hooks

```bash
gitai -y --no-verify
```

### 查看帮助

```bash
gitai --help
```

## 🏗️ 项目结构

```
gitai/
├── gitai/
│   ├── __init__.py      # 包初始化
│   ├── __main__.py      # 模块入口
│   ├── agent.py         # Agent 主流程
│   ├── cli.py           # 命令行接口
│   ├── config.py        # 配置管理
│   ├── context.py       # 上下文构建
│   ├── git_utils.py     # Git 工具函数
│   └── llm.py           # 大模型调用层
├── tests/               # 测试文件
├── pyproject.toml       # 项目配置
├── .gitai.toml          # 示例配置文件
├── .env.example         # 环境变量示例
└── README.md            # 项目文档
```

## 🧪 开发

### 安装开发依赖

```bash
pip install -e ".[dev]"
```

### 运行测试

```bash
pytest
```

### 代码格式化

```bash
ruff format .
ruff check .
```

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。

## 🙏 致谢

- [litellm](https://github.com/BerriAI/litellm) - 统一的大模型调用层
- [Ollama](https://ollama.com/) - 本地大模型部署工具
- 所有贡献者和使用者

## 📞 联系方式

如有问题或建议，请提交 Issue 或联系项目维护者。