pre-commit-ai-reviewer 0.1.0

基于 LangChain 的 Pre-commit Git 代码评审工具

AI Code Reviewer

基于 LangChain 的 Git 代码评审工具。使用 AI 对代码提交进行智能评审，支持根据不同 commit 类型进行针对性分析。

功能特性

• 智能 commit 类型识别: 自动解析 commit message 前缀（feat/fix/refactor/doc/config）
• 针对性评审: 根据不同 commit 类型使用专门的评审策略和提示词
• 灵活配置: 支持多种 LLM 提供商（OpenAI、Ollama、Azure OpenAI 等）
• 致命错误拦截: 发现严重问题时阻止提交
• 基于 LangChain: 使用最新的 LCEL 风格构建
• 自动初始化: init 命令自动创建配置文件和 pre-commit hook 配置

安装

从源码安装

# 克隆项目
git clone https://github.com/your-username/ai-code-reviewer.git
cd ai-code-reviewer

# 安装依赖（推荐使用虚拟环境）
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate  # Windows

pip install -e .

依赖要求

• Python >= 3.10
• langchain >= 0.3.0
• langchain-openai >= 0.2.0
• pydantic >= 2.0.0
• click >= 8.0.0
• gitpython >= 3.0.0

快速开始

1. 初始化配置

ai-code-reviewer init

此命令会创建两个文件：

1. .ai-reviewer.toml - AI 评审器配置文件
2. .git/hooks/commit-msg - Git commit-msg hook（自动安装）

重要提示：

• ⚠️ 必须在 Git 仓库根目录下运行此命令
• ✅ 自动验证 Git 仓库有效性
• ✅ 检测并智能处理已存在的 hooks
• ✅ 多重安全检查防止误操作

2. 编辑配置文件

编辑 .ai-reviewer.toml 设置你的 LLM 配置：

[llm]
model = "qwen3-coder:30b"          # 模型名称
api_key = ""                       # API Key（Ollama 可留空）
base_url = "http://localhost:11434/v1"  # API Base URL

[reviewer]
enabled_types = ["feat", "fix", "refactor", "doc", "config"]
max_file_size = 100000             # 跳过超过此大小的文件（字节）
excluded_patterns = ["*.lock", "package-lock.json", "*.min.js"]
output_file = ".ai-review-log.json"  # 评审日志文件

支持的 LLM 提供商：

提供商	base_url 示例
OpenAI	null（默认）
Ollama	"http://localhost:11434/v1"
Azure OpenAI	Azure 端点 URL
其他兼容服务	相应的 API 端点

3. 安装 Git Hooks

运行初始化命令会智能安装 commit-msg hook：

# init 命令会自动创建 .git/hooks/commit-msg
# 无需额外操作

智能安装特性：

• ✅ 自动检测：如果 hook 已存在，会检查是否包含 AI 代码评审功能
• ✅ 交互式追加：如果 hook 存在但未包含 AI 功能，会询问是否追加
• ✅ 安全验证：自动检查符号链接、路径遍历等安全问题
• ✅ 幂等性：多次运行不会重复安装

处理已存在的 hook：

如果你已经有其他 Git hooks（如 pre-commit、Husky 等），init 命令会：

1. 显示现有 hook 内容
2. 询问是否在现有内容后追加 AI 代码评审调用
3. 保留原有功能，不会破坏现有 hook

示例输出：

[警告] commit-msg hook 已存在: .git/hooks/commit-msg
现有内容：
#!/bin/sh
# Your existing hook content

是否在现有 hook 中追加 AI 代码评审功能？ [Y/n]:

4. 提交代码

现在正常提交代码即可触发 AI 评审：

git add .
git commit -m "feat: 添加用户认证功能"

重要说明：AI 评审会在你输入 commit message 之后执行，可以正确读取你当前的提交消息。

命令说明

init - 初始化配置

ai-code-reviewer init [选项]

选项：

• -p, --path <路径> - 指定配置文件保存路径
• -f, --force - 强制覆盖已存在的 commit-msg hook

功能： 创建以下文件：

• .ai-reviewer.toml - AI 评审配置文件
• .git/hooks/commit-msg - Git commit-msg hook（自动安装）

示例：

# 普通初始化（智能追加模式）
ai-code-reviewer init

# 强制覆盖已存在的 hook
ai-code-reviewer init --force

# 指定配置文件路径
ai-code-reviewer init --path /path/to/config.toml

行为说明：

1. 默认模式（无 --force）：

   • 如果 hook 不存在，创建新文件
   • 如果 hook 已存在且包含 AI 功能，显示成功消息
   • 如果 hook 已存在但不包含 AI 功能，询问是否追加

2. 强制模式（--force）：

   • 显示现有 hook 内容
   • 直接覆盖为 AI 代码评审 hook
   • ⚠️ 警告：会丢失原有 hook 内容

commit-msg-review - 用于 commit-msg hook

ai-code-reviewer commit-msg-review <commit-msg-file>

此命令由 Git commit-msg hook 自动调用，不需要手动执行。它会在输入 commit message 后执行 AI 评审。

review - 手动执行评审（可选）

ai-code-reviewer review

手动执行代码评审，用于测试或调试。注意：此命令可能无法获取到正确的 commit message。

check - 检查配置

ai-code-reviewer check

验证配置文件是否正确。

Commit 类型说明

只有以下类型的 commit 会触发评审：

类型	说明	评审重点
feat	新功能	功能完整性、逻辑正确性、边界条件、错误处理
fix	修复 bug	修复是否正确、是否引入新问题、副作用
refactor	重构	是否保持原有功能、是否有意外变更、合理性
doc	文档变更	文档准确性、逻辑正确性、与代码一致性
config	配置变更	配置有效性、合理性、结合 commit 信息分析

其他类型（如 style、test、chore、perf 等）会自动跳过评审。

评审级别

• critical (致命): 发现严重错误，会拦截提交

  • 安全漏洞
  • 严重逻辑错误
  • 破坏性变更
  • 明显的 bug

• warning (警告): 仅显示，不拦截

  • 潜在性能问题
  • 代码异味
  • 不完整的实现

• info (信息): 提示性建议

Git Hook 说明

本工具使用 Git commit-msg hook 而不是 pre-commit hook，这样可以：

1. ✅ 正确获取 commit message：在用户输入 commit message 后执行
2. ✅ 更准确的评审：可以结合 commit message 和代码变更进行评审
3. ✅ 支持强制提交：通过 -f 标志跳过评审

自动安装

运行 ai-code-reviewer init 会自动创建 .git/hooks/commit-msg 文件。

手动安装（如果需要）

如果需要手动安装 hook，创建 .git/hooks/commit-msg 文件：

#!/bin/sh
# AI Code Reviewer - commit-msg hook

COMMIT_MSG_FILE="$1"
ai-code-reviewer commit-msg-review "$COMMIT_MSG_FILE"

然后设置可执行权限：

chmod +x .git/hooks/commit-msg

跳过评审

方式一：使用 -f 强制提交标志（推荐）

在提交消息的最后添加 -f 标志，可以跳过 AI 审查直接提交：

git commit -m "feat: 紧急修复生产问题 -f"

这种方式适合紧急情况或不需要 AI 审查的提交。

方式二：使用 --no-verify

如果需要跳过所有 pre-commit hooks（不推荐），可以使用：

git commit --no-verify -m "your message"

项目结构

ai_code_reviewer/
├── __init__.py              # 主包入口
├── cli.py                   # CLI 命令处理
├── config.py                # 配置文件加载
├── git_helper.py            # Git 操作封装（diff、commit message）
├── commit_parser.py         # Commit 类型解析器
├── models/                  # Pydantic 数据模型
│   ├── config.py            # LLM 和 Reviewer 配置模型
│   └── review_result.py     # 评审结果模型
├── prompts/                 # LangChain 提示词模板
│   └── templates.py         # 各类型的专门提示词
├── parsers/                 # LLM 输出解析器
│   └── review_parser.py     # JSON 结果解析
└── chains/                  # LangChain 评审链
    └── review_chain.py      # LCEL 风格的评审链

输出示例

============================================================
  AI 代码评审报告
============================================================
Commit 类型: feat
总体评估: APPROVE
============================================================
摘要: 本次提交实现了用户认证功能，包含登录、注册和密码重置...
============================================================
发现问题: 3 个
============================================================
1. [警告] 代码异味
   文件: auth/login.py
   行号: 45
   描述: 在 check_password 函数中，使用了字符串比较而不是恒定时间比较...
   建议: 使用 hmac.compare_digest 进行恒定时间比较

2. [信息] 代码结构
   文件: auth/models.py
   描述: User 类缺少 email 字段的唯一性约束
   建议: 添加 unique=True 到 email 字段

3. [警告] 潜在问题
   文件: auth/views.py
   行号: 78
   描述: 错误处理不完整，未记录登录失败日志
   建议: 添加日志记录以便审计

============================================================
[通过] 评审完成

常见问题

Q: 如何使用 Ollama 本地模型？

A: 在 .ai-reviewer.toml 中配置：

[llm]
model = "qwen2.5-coder:latest"
api_key = ""  # 可留空
base_url = "http://localhost:11434/v1"

Q: 为什么我的 commit 没有触发评审？

A: 检查以下几点：

1. Commit message 是否以支持的类型前缀开头（feat/fix/refactor/doc/config）
2. 是否有暂存的代码变更
3. 配置文件中 enabled_types 是否包含该类型

Q: 如何禁用某个 commit 类型的评审？

A: 在 .ai-reviewer.toml 中修改 enabled_types：

[reviewer]
enabled_types = ["feat", "fix"]  # 只评审 feat 和 fix

Q: 评审日志保存在哪里？

A: 日志保存在配置文件指定的 output_file 路径，默认为 .ai-review-log.json。

开发

运行测试

pytest

代码格式化

black ai_code_reviewer/
ruff check ai_code_reviewer/

License

MIT License

贡献

欢迎提交 Issue 和 Pull Request！