Metadata-Version: 2.4
Name: commit-ai-guardian
Version: 0.2.9
Summary: Git commit 前 AI 自动代码审查工具 — 支持 OpenAI/MiniMax/DeepSeek/Kimi，自定义审核规则和案例
Project-URL: Homepage, https://github.com/tingkl/ai-review
Project-URL: Documentation, https://github.com/tingkl/ai-review/blob/main/README.md
Project-URL: Repository, https://github.com/tingkl/ai-review
Project-URL: Issues, https://github.com/tingkl/ai-review/issues
Project-URL: Changelog, https://github.com/tingkl/ai-review/blob/main/CHANGELOG.md
Author: tingkl
License: MIT
Keywords: ai,code-quality,code-review,deepseek,developer-tools,git,hook,kimi,llm,minimax,openai,pre-commit,static-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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 :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: gitpython>=3.1
Requires-Dist: openai>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Description-Content-Type: text/markdown

<div align="center">

# 🛡️ Commit AI Guardian

**AI 驱动的 Git pre-commit 代码审查工具**

在每次 `git commit` 前自动拦截代码风险，守护代码质量

[![Python](https://img.shields.io/badge/Python-3.10%2B-blue?style=for-the-badge&logo=python)](https://python.org)
[![PyPI](https://img.shields.io/pypi/v/commit-ai-guardian?style=for-the-badge&logo=pypi&color=green)](https://pypi.org/project/commit-ai-guardian/)
[![License](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](LICENSE)

</div>

---

## 📋 目录

- [🚀 30 秒快速开始](#-30-秒快速开始)
- [✨ 核心能力](#-核心能力)
- [📦 安装与升级](#-安装与升级)
- [⚙️ 配置](#-配置)
- [🖥️ 在线体验](#-在线体验)
- [📖 命令参考](#-命令参考)
- [📝 案例格式](#-案例格式)
- [🔧 网络代理](#-网络代理)
- [❓ 常见问题](#-常见问题)
- [📚 更多文档](#-更多文档)

---

## 🚀 30 秒快速开始

```bash
# 1. 安装
uv tool install commit-ai-guardian

# 2. 进入项目初始化
cd your-project
cag install

# 3. 配置 API Key
cag configure

# 4. 完成！以后每次 git commit 自动审查
```

> 💡 **无需修改任何代码**，安装即生效

---

## ✨ 核心能力

### 🔍 5 大审核维度

| 维度 | 检查内容 | 典型问题 |
|------|----------|----------|
| 🐛 **Bug 检测** | 逻辑错误、边界条件、资源泄漏 | 空指针、死循环、数组越界 |
| 🎨 **代码风格** | 命名规范、格式、注释 | 变量命名不清、缺少注释 |
| ⚡ **性能问题** | 算法复杂度、内存、缓存 | N+1 查询、内存泄漏 |
| 🛡️ **最佳实践** | 设计模式、错误处理、安全 | 未处理异常、SQL 注入 |
| 📝 **文档完整** | 函数文档、参数说明 | 复杂函数无注释 |

> **📌 注释的重要作用**
>
> 代码中的注释是开发者写的**意图说明**，比代码本身更直接。
>
> **这不是 AI 天生懂注释，而是我们在 system prompt 里明确规定的**：
> > "代码中的注释是开发者写的意图说明，比代码本身更直接。判断代码是否正确时，要参考注释的说明。如果注释明确解释了某个做法的原因，要尊重注释的判断。**当注释与案例出现冲突时，以注释为准。注释的优先级高于案例。**"
>
> 本工具在审核时会**优先参考注释的判断**：
> - ✅ 注释明确解释了某个做法的原因 → 尊重注释，不报错
> - ✅ 注释说明了边界情况的处理逻辑 → 视为合理实现
> - ✅ **注释与案例冲突时 → 以注释为准**（注释优先级高于案例）
> - ❌ 仅凭代码表面就下结论（可能误解意图）
>
> **建议**：在容易引起误解的代码旁添加注释，能显著降低误报率。注释 = 审核规则的一部分，**且优先级高于案例**。

### 📝 自定义审核规则（Prompt）

决定 **"怎么审"** —— 切换 AI 的审核视角：

- **📐 标准审核**：全面检查 5 大维度（默认）
- **🔒 安全优先**：专注 SQL 注入、XSS、权限绕过
- **⚡ 性能优先**：专注算法复杂度、N+1 查询、内存泄漏

```
.ai-review/prompts/
├── default.md    # 标准审核
├── security.md   # 安全优先
└── performance.md # 性能优先
```

### 📚 自定义案例系统

决定 **"查什么"** —— 让 AI 按你的团队规范审核：

```yaml
---
title: "Vue 组件命名规范"
category: "代码风格"
severity: "warning"
---

## 正确
UserProfile.vue

## 错误
user-profile.vue
```

> 🎯 相当于 **把团队规范编程化**，AI 参考案例精准审核

### 🔄 四级 JSON 容错

AI 返回 JSON 经常出问题，内置四层容错不卡死：

```
┌─────────────────────────────────────────────────────┐
│  L1 本地修复 → L2 修复 AI → L3 Schema → L4 兜底     │
│                                                      │
│  过滤think标签    最多重试3次    字段校验    日志记录  │
│  代码块匹配       带对话历史     类型检查    阻断提交  │
│  括号补全                                        │
└─────────────────────────────────────────────────────┘
```

---

## 📦 安装与升级

### 安装

#### 推荐方式：PyPI

```bash
uv tool install commit-ai-guardian
```

#### 其他方式

```bash
# GitHub（最新开发版）
uv tool install git+https://github.com/tingkl/ai-review.git

# GitLab（公司内部）
uv tool install git+ssh://git@124.223.189.152:7022/gaoq/ai-review.git
```

| 方式 | 场景 | 稳定性 |
|------|------|--------|
| PyPI | 普通用户、生产环境 | ⭐⭐⭐⭐⭐ |
| GitHub | 开发者贡献 | ⭐⭐⭐ |
| GitLab | 公司内部 | ⭐⭐⭐ |

### 升级

```bash
# 升级到最新版本（uv 自动追踪安装来源）
uv tool upgrade commit-ai-guardian

# 或使用封装命令
cag upgrade
```

> uv 内部记录了包的原始安装来源（PyPI/GitHub/GitLab），`upgrade` 命令会自动从正确的源升级。

### 卸载

```bash
uv tool uninstall commit-ai-guardian
```

---

## ⚙️ 配置

### 两级配置机制

```
全局配置 ~/.commit_ai_guardian/config.yaml
         │
         ▼ 项目配置覆盖全局
         
项目配置 .ai-review/config.yaml  ← 优先级更高
```

### 常用配置

```yaml
api_key: "sk-xxx"                    # API 密钥
model: "deepseek-v4-pro"             # 模型（推荐 DeepSeek V4，1M上下文）
api_base: "https://api.deepseek.com/v1"
language: "zh-CN"                    # 审核语言
severity_threshold: "warning"        # 阻断阈值
case_format: "compact"               # 案例格式
temperature: 0.3                     # 随机性
max_tokens: 8192                     # 最大返回长度
```

### 模型推荐

| 服务商 | 推荐模型 | 上下文 | 特点 |
|--------|----------|--------|------|
| **DeepSeek** | `deepseek-v4-pro` | 1M | 最强代码能力，推荐 |
| **Kimi** | `kimi-k2.6` | 256K | 最新版本 |
| **MiniMax** | `MiniMax-M3` | 128K | 编程专项 |
| **OpenAI** | `gpt-4o` | 128K | 通用能力强 |

---

## 🖥️ 在线体验

不用安装，浏览器直接体验完整功能：

**👉 [https://tingkl.github.io/ai-review/demo/](https://tingkl.github.io/ai-review/demo/)**

支持：选择模型 ✓ 配置审核规则 ✓ 加载案例 ✓ 自定义 Prompt ✓

---

## 📖 命令参考

```bash
cag install          # 安装 pre-commit 钩子
cag install --force  # 强制覆盖（备份原 hook）
cag uninstall        # 卸载
cag configure        # 交互式配置
cag status           # 查看配置状态
cag review           # 手动审查暂存区
cag audit            # 全量审查
cag upgrade          # 升级版本
```

---

## 📝 案例格式

```markdown
---
title: "SQL 注入防护"
category: "安全"
severity: "error"
---

## 场景描述
用户输入直接拼接到 SQL...

## 正确做法
使用参数化查询

## 错误示例
const sql = `SELECT * FROM users WHERE id = ${id}`
```

> 📂 放在 `.ai-review/cases/` 下，支持子目录按语言组织

---

## 🔧 网络代理

公司内网或 Clash/V2Ray 规则模式需要配置：

```yaml
# ~/.commit_ai_guardian/config.yaml
proxy: "http://127.0.0.1:7890"   # Clash
proxy: "http://127.0.0.1:10809"  # V2RayN
proxy: "http://127.0.0.1:6152"  # Surge
```

> Clash 开 **全局/TUN 模式** 不需要配置

---

## ❓ 常见问题

**Q: 为什么审查没有触发？**
A: 确认已执行 `cag install`，运行 `cag status` 检查状态。

**Q: API Key 怎么获取？**
A: 访问 AI 服务商控制台（DeepSeek/OpenAI 等），在 API 管理页面创建。

**Q: 提交被拦截了怎么办？**
A: 根据 AI 反馈修改代码后重提交。确认无风险可用 `git commit --no-verify` 跳过。

**Q: 支持哪些语言？**
A: 所有文本文件，Python/JS/Java/Go/Vue/Markdown 等。

---

## 📚 更多文档

| 文档 | 内容 | 适合 |
|------|------|------|
| [STUDY.md](STUDY.md) | 设计原理与常见问题 | 初学者 |
| [TECHNICAL.md](TECHNICAL.md) | 架构设计、Prompt 工程 | 开发者 |

---

<div align="center">

**[GitHub](https://github.com/tingkl/ai-review)** · **[PyPI](https://pypi.org/project/commit-ai-guardian/)** · **[在线 Demo](https://tingkl.github.io/ai-review/demo/)**

MIT License

</div>
