# ai-code-review

**Repository Path**: elfbobo_admin_admin/ai-code-review

## Basic Information

- **Project Name**: ai-code-review
- **Description**: 基于 AI 的自动化代码审查工具，支持智谱 GLM、Anthropic Claude 和 OpenAI 模型，集成 Git Hooks 和 GitLab CI/CD。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-02-27
- **Last Updated**: 2026-03-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Code Review

# .gitlab-ci.yml
stages:
  - review

ai-code-review:
  stage: review
  script:
    - |
      echo "🔍 Running AI Code Review..."
      
      # 确定分支
      if [ "$CI_PIPELINE_SOURCE" = "merge_request_event" ]; then
        BASE_BRANCH="$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
        COMPARE_BRANCH="$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"
      else
        BASE_BRANCH="$CI_DEFAULT_BRANCH"
        COMPARE_BRANCH="$CI_COMMIT_BRANCH"
      fi
      
      echo "Base: $BASE_BRANCH"
      echo "Compare: $COMPARE_BRANCH"
      
      # 使用本地安装的ai-review
      /path/to/ai-code-review/dist/cli.js review \
        --base "$BASE_BRANCH" \
        --compare "$COMPARE_BRANCH" \
        --format html \
        --output "review-reports" \
        --fail-on high
  artifacts:
    when: always
    paths:
      - review-reports/
    expire_in: 1 week
  allow_failure: false

## 功能特性

- 🔍 **智能代码审查**: 支持智谱 GLM、Anthropic Claude 和 OpenAI 模型分析代码变更，识别安全性、性能、代码质量等问题
- 📊 **多维度分析**: 支持安全漏洞、性能问题、代码规范、最佳实践等多种审查类别
- 🔗 **Git 集成**: 支持 pre-commit 和 pre-push 钩子，在提交前自动审查
- 🚀 **GitLab CI/CD**: 原生支持 GitLab Merge Request 自动审查
- 📝 **多格式报告**: 支持 Markdown、HTML、JSON 格式的审查报告
- ⚙️ **灵活配置**: 支持配置文件和环境变量配置，可自由切换 AI 提供商

## 安装

```bash
# 克隆或下载项目
git clone <repository-url>
cd ai-code-review

# 安装依赖
npm install

# 构建
npm run build

# 全局安装（可选）
npm link
```

## 快速开始

### 1. 配置 API Key

根据选择的 AI 提供商，创建 `.env` 文件：

**智谱（默认）：**

```env
ZHIPU_API_KEY=your_zhipu_api_key_here
```

**Anthropic：**

```env
ANTHROPIC_API_KEY=your_anthropic_api_key_here
```

**OpenAI：**

```env
OPENAI_API_KEY=your_openai_api_key_here
```

或设置环境变量：

```bash
# 智谱
export ZHIPU_API_KEY=your_zhipu_api_key_here

# Anthropic
export ANTHROPIC_API_KEY=your_anthropic_api_key_here

# OpenAI
export OPENAI_API_KEY=your_openai_api_key_here
```

### 2. 初始化配置

```bash
ai-review init
```

这将创建 `.ai-review.yml` 配置文件。

### 3. 运行审查

```bash
# 审查当前分支与 main 分支的差异
ai-review review

# 审查暂存的更改
ai-review review --staged

# 指定分支比较
ai-review review --base develop --compare feature/my-feature

# 生成 HTML 报告
ai-review review --format html

# 同时生成多种格式报告
ai-review review --format markdown html json
```

## 命令行选项

### `ai-review review`

执行代码审查。

| 选项 | 说明 | 默认值 |
|------|------|--------|
| `-b, --base <branch>` | 基准分支 | main |
| `-c, --compare <branch>` | 比较分支 | HEAD |
| `-s, --staged` | 仅审查暂存更改 | false |
| `-f, --format <formats...>` | 输出格式 (markdown/html/json，支持多个格式) | markdown |
| `-o, --output <path>` | 报告输出目录 | ./review-reports |
| `--config <path>` | 配置文件路径 | |
| `--fail-on <level>` | 失败阈值级别 | high |
| `--quiet` | 静默模式 | false |
| `--debug` | 显示详细错误堆栈跟踪 | false |

### `ai-review init`

初始化配置文件。

### `ai-review hook`

管理 Git 钩子。

```bash
# 安装 pre-commit 钩子
ai-review hook install --type pre-commit

# 安装 pre-push 钩子
ai-review hook install --type pre-push

# 卸载钩子
ai-review hook uninstall --type pre-commit
```

### `ai-review gitlab`

生成 GitLab CI/CD 配置。

```bash
ai-review gitlab --output .gitlab-ci.yml
```

## 配置文件

`.ai-review.yml` 配置示例：

### 白名单功能

白名单功能允许您将特定的问题列入白名单，不再进行检测。每个白名单规则支持以下字段：

| 字段 | 说明 | 示例 |
|------|------|------|
| `filePathPattern` | 文件路径模式（支持通配符） | `src/utils/*.ts` |
| `category` | 问题类别（可选） | `security` |
| `titlePattern` | 问题标题模式（可选，支持正则表达式） | `硬编码的 API 密钥` |
| `descriptionPattern` | 问题描述模式（可选，支持正则表达式） | `.*测试密钥.*` |
| `lineStart` | 行号范围开始（可选） | `10` |
| `lineEnd` | 行号范围结束（可选） | `20` |
| `description` | 规则描述（可选） | `测试文件中的安全问题不影响生产环境` |

白名单规则会按照顺序匹配，只要问题满足任何一个规则的条件，就会被排除。

### 白名单实现原理

白名单功能的实现基于以下核心逻辑：

1. **规则遍历**：系统会按照配置的顺序遍历所有白名单规则
2. **多条件匹配**：对于每个规则，会依次检查以下条件：
   - 文件路径模式是否匹配
   - 问题类别是否匹配（如果规则指定了类别）
   - 问题标题模式是否匹配（如果规则指定了标题模式）
   - 问题描述模式是否匹配（如果规则指定了描述模式）
   - 行号范围是否匹配（如果规则指定了行号范围）
3. **过滤逻辑**：只要问题满足任何一个规则的所有条件，就会被视为在白名单中，从而被过滤掉

### 技术细节

#### 文件路径匹配
- 支持通配符模式，如 `src/**/*.ts` 匹配 `src` 目录及其子目录下的所有 TypeScript 文件
- 内部将通配符模式转换为正则表达式进行匹配

#### 模式匹配
- `titlePattern` 和 `descriptionPattern` 支持正则表达式
- 如果正则表达式无效，会回退到简单的字符串包含检查

#### 行号范围检查
- 只有当问题有行号信息时才会进行行号范围检查
- 行号范围是闭区间，包含 `lineStart` 和 `lineEnd`

### 白名单最佳实践

1. **精确匹配**：尽量使用多个条件组合，使规则更精确，避免误排除
2. **规则顺序**：将更具体的规则放在前面，更通用的规则放在后面
3. **添加描述**：为每个规则添加 `description` 字段，说明排除原因，便于后续维护
4. **定期审查**：定期审查白名单规则，移除不再需要的规则

```yaml
# AI 提供商配置
provider: zhipu  # 可选值: zhipu, anthropic, openai

# AI 模型配置
model: glm-4.5  # 智谱模型
# model: claude-sonnet-4  # Anthropic 模型
# model: gpt-4o  # OpenAI 模型
maxTokens: 4096
temperature: 0.3

# 输出配置
outputFormat: markdown
outputPath: ./review-reports

# Git 配置
baseBranch: main
compareBranch: HEAD

# 审查类别
categories:
  - security        # 安全漏洞
  - performance     # 性能问题
  - code-quality    # 代码质量
  - best-practices  # 最佳实践
  - bug-risk        # 潜在 Bug
  - maintainability # 可维护性

# 排除文件模式
excludePatterns:
  - node_modules/**
  - dist/**
  - "*.lock"
  - "*.min.js"

# 白名单规则
whitelist:
  # 示例 1: 排除日志工具中的硬编码 API 密钥警告
  - filePathPattern: "src/utils/logger.ts"
    category: security
    titlePattern: "硬编码的 API 密钥"
    description: "日志工具中的测试密钥，已确认安全"
  # 示例 2: 排除测试文件中的所有安全问题
  - filePathPattern: "test/**/*.ts"
    category: security
    description: "测试文件中的安全问题不影响生产环境"
  # 示例 3: 排除特定文件特定行的问题
  - filePathPattern: "src/config/index.ts"
    category: security
    lineStart: 10
    lineEnd: 20
    description: "配置文件中的临时密钥，将在部署时替换"

# 最大差异大小
maxDiffSize: 50000
```

## Git Hooks 集成

### Pre-commit Hook

在每次提交前自动审查暂存的更改：

```bash
ai-review hook install --type pre-commit
```

如果发现高危或严重问题，提交将被阻止。

### Pre-push Hook

在推送前自动审查分支差异：

```bash
ai-review hook install --type pre-push
```

## GitLab CI/CD 集成

### 1. 添加 CI 变量

在 GitLab 项目设置中添加对应的 API Key：

**智谱（默认）：**
- `ZHIPU_API_KEY`: 智谱 API Key

**Anthropic：**
- `ANTHROPIC_API_KEY`: Anthropic API Key

**OpenAI：**
- `OPENAI_API_KEY`: OpenAI API Key

**通用配置：**
- `REVIEW_PROVIDER`: (可选) 指定使用的提供商 (zhipu/anthropic/openai)
- `GITLAB_TOKEN`: (可选) 用于在 MR 中发布评论

### 2. 配置 CI Pipeline

将 `.gitlab-ci.yml` 添加到项目根目录，或合并到现有配置：

```yaml
include:
  - remote: 'https://your-domain/ai-review/.gitlab-ci.yml'
```

### 3. MR 自动审查

当创建 Merge Request 时，CI 会自动：

1. 运行 AI 代码审查
2. 生成审查报告
3. (可选) 在 MR 中发布评论摘要
4. 根据审查结果决定是否允许合并

## 审查类别说明

| 类别 | 说明 |
|------|------|
| security | SQL 注入、XSS、认证问题、敏感数据暴露 |
| performance | 性能瓶颈、内存泄漏、N+1 查询 |
| code-quality | 代码异味、复杂度、重复代码 |
| best-practices | 框架规范、设计模式、编码标准 |
| bug-risk | 边界情况、错误处理、竞态条件 |
| maintainability | 可读性、文档、命名规范 |

## 严重级别

| 级别 | 说明 | 示例 |
|------|------|------|
| critical | 严重安全漏洞或致命 Bug | SQL 注入、认证绕过 |
| high | 高风险问题 | XSS、敏感信息泄露 |
| medium | 中等风险 | 性能问题、代码异味 |
| low | 低风险 | 命名不规范、缺少注释 |
| info | 建议性信息 | 可优化的代码结构 |

## 输出示例

### Markdown 报告

```markdown
# AI Code Review Report

**Generated:** 2024-01-15 10:30:00
**Commit:** `abc12345`
**Branch:** feature/auth → main

## Summary

| Metric | Count |
|--------|-------|
| 🔴 Critical | 1 |
| 🟠 High | 2 |
| 🟡 Medium | 3 |
| 🔵 Low | 5 |
| ⚪ Info | 2 |

**Overall Risk:** HIGH
**Recommendation:** BLOCK

## Issues

### 📄 src/auth/login.ts

#### 🔴 [CRITICAL] SQL Injection Vulnerability
...
```

## 最佳实践

1. **渐进式采用**: 先在开发分支启用，确认效果后再应用到主分支
2. **调整阈值**: 根据项目需求调整 `--fail-on` 级别
3. **排除文件**: 合理配置 `excludePatterns` 避免审查无关文件
4. **定期审查报告**: 查看报告了解代码质量趋势

## 故障排除

### API Key 无效

**智谱：**
```
Error: API key is required. Set it in .env file or environment variable.
```

**Anthropic：**
```
Error: API key is required. Set it in .env file or environment variable.
```

**OpenAI：**
```
Error: API key is required. Set it in .env file or environment variable.
```

确保 `.env` 文件中设置了对应提供商的正确 API Key，并且 `provider` 配置与 API Key 匹配。

### Git 差异获取失败

```
Error: Failed to get git diff
```

确保指定的基准分支存在，并且当前在 Git 仓库中运行。

### 报告目录权限问题

```
Error: EACCES: permission denied
```

确保有权限创建 `outputPath` 指定的目录。

## 许可证

MIT