# AIpr-Review

**Repository Path**: yzzcode/aipr-review

## Basic Information

- **Project Name**: AIpr-Review
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-29
- **Last Updated**: 2026-05-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AIpr-Review — 轻量化 AI PR 代码评审工具

输入 GitHub PR 链接，自动生成覆盖**总结、风险、规范、建议、优化**五大维度的 AI 评审报告。

## 核心设计：让 AI 评审"靠谱"

AI 代码评审的核心挑战不是"能不能评"，而是**评得对不对**——模型幻觉会凭空捏造不存在的文件和行号，主观偏好会产生大量"建议加注释"式的无效噪音，上下文不足则会导致误判。AIpr-Review 从三个层面解决这一问题：

### 1. 上下文理解 — 让模型看到该看的代码

| 机制 | 说明 |
|------|------|
| **智能声明定位** | 不机械扩展 ±N 行，而是向上查找变更行所在的函数/类声明，在 patch 头部注入 `[context: def authenticate_user()]` 标注，帮助 LLM 理解"这段代码属于谁" |
| **声明块边界裁剪** | 计算变更所在函数/类的起止行号，大函数只保留声明附近上下文，小函数保留完整代码块 |
| **行号标注注入** | 为每个 hunk 生成新文件行号对照表（`__new hunk__ (lines 10-15)`），让 LLM 引用行号时有据可依 |
| **文件优先级排序** | 核心代码(0) > 新增文件(1) > 测试文件(2) > 配置/文档(3) > 自动生成文件(4)，确保评审预算优先分配给最有价值的代码 |
| **五级渐进压缩** | 全量上下文 → 裁剪上下文 → 丢弃删除文件详情 → 低价值文件摘要化 → 仅核心文件，逐级适应 token 预算，避免粗暴截断导致的信息丢失 |

### 2. 误报控制 — 过滤低价值的"正确废话"

AI 评审最常见的噪音是建议"加文档注释""删未使用导入""用更具体的异常类型"——这些建议技术上没错，但价值极低。AIpr-Review 采用**先过滤、再反思**的两段式管线：

**Stage 1 — 硬过滤规则（Regex，零 token 开销）**

预定义正则规则集，自动移除已知的低价值建议类型：

| 规则 | 目标 | 示例 |
|------|------|------|
| `docstring_type_hint` | 文档/类型注解建议 | "建议为函数添加文档字符串" |
| `unused_import` | 未使用导入建议 | "移除未使用的 import 语句" |
| `exception_type` | 异常类型建议 | "建议使用更具体的异常类型" |

规则按维度定向生效（如 `docstring_type_hint` 只在 suggestion/standard/optimization 维度触发，summary/risk 维度不受影响）。

**Stage 2 — LLM 自我反思（二次评分）**

```
初评 → LLM 质量审核员 → 逐条打分(0-10) → 阈值过滤(默认≥3)
```

- 对每条评审意见按 0-10 分二次评分
- 0-3 分（低价值）：误报、纯风格偏好、与变更无关
- 4-6 分（中等价值）：有参考意义但非关键
- 7-10 分（高价值）：逻辑缺陷、安全漏洞、并发问题等关键发现
- 评分同时附 `should_keep` 布尔标记和删除理由，前端可展示过滤明细

### 3. 漏报控制 — 让模型不遗漏关键问题

**Prompt 层面：**
- 系统 Prompt 明确安全性优先（"优先关注安全漏洞、数据泄露、权限控制等问题"）
- 要求按严重程度排序（高风险 > 中风险 > 低风险 > 建议）
- 五维度结构化输出确保覆盖完整性（总结/风险/规范/建议/优化，每类无内容标注"无"）

**Stage 3 — 行号校验：验证引用真实性**

LLM 有时会"幻觉"出不存在的文件路径和行号。行号校验模块：
- 从评审文本自动提取所有 `**文件:行号**` 和 `文件:行号` 格式的引用
- 与 PR 的实际 diff hunk 行号范围做比对验证
- 支持文件名模糊匹配（review 中说 `utils.py`，能匹配 `deep/nested/utils.py`）
- 标记无效引用（文件不存在于 PR / 行号不在变更范围内），返回校验报告

**上下文包含 old 行号：** 校验集合同时包含 old_line 和 new_line，因为 LLM 可能引用被删除行的行号。

## 端到端管线

```
GitHub PR URL
  → PRParser: API 查询 + diff 解析 + 声明定位
  → ContextFetcher: 五级压缩 + 行号标注
  → LLMClient: Prompt 组装 + /chat/completions 调用 + 指数退避重试
  → ReviewParser: Markdown → 五维度结构化
  → [Stage 1] FilterRules: 硬过滤低价值建议
  → [Stage 2] Reflector: LLM 二次评分 + 阈值过滤
  → [Stage 3] Validator: 行号引用真实性校验
  → ReviewStore: JSON 持久化 + 历史查询
  → MarkdownRenderer: → HTML 渲染
```

前端可通过开关独立启用/禁用三阶段质量控制，方便对比过滤前后的评审质量变化。

## 技术栈

| 层 | 技术 |
|---|---|
| 后端 | Python 3.13 + FastAPI + httpx + Pydantic |
| 前端 | Vue 3 (Composition API) + Vite 5 + Element Plus + axios |
| LLM | OpenAI-compatible `/chat/completions` 协议 |
| 存储 | JSON 文件（单用户，无数据库） |

## 项目结构

```
aipr-review/
├── backend/
│   ├── app/
│   │   ├── main.py                    # FastAPI 入口
│   │   ├── core/                       # 配置 / 日志 / 异常处理 / 常量
│   │   ├── models/pr_models.py         # Pydantic 数据模型
│   │   ├── router/
│   │   │   ├── health.py               # 健康检查
│   │   │   ├── pr_router.py            # PR 解析接口
│   │   │   ├── llm_router.py           # LLM 测试接口
│   │   │   └── review_router.py        # 核心评审接口（含三阶段质量控制）
│   │   ├── service/
│   │   │   ├── github_client.py        # GitHub API 客户端
│   │   │   ├── pr_parser.py            # PR URL 解析
│   │   │   ├── diff_parser.py          # Diff 解析 + 智能声明定位
│   │   │   ├── context_fetcher.py      # 五级上下文构建与压缩
│   │   │   ├── review_prompts.py       # Prompt 工程（系统角色 + 输出格式 + 评审规则）
│   │   │   ├── llm_client.py           # LLM API 客户端（重试 + 流式）
│   │   │   ├── review_parser.py        # Markdown 评审 → 结构化
│   │   │   ├── review_filter_rules.py  # [Stage 1] 硬过滤规则引擎
│   │   │   ├── review_reflector.py     # [Stage 2] LLM 自我反思 + 阈值过滤
│   │   │   ├── review_validator.py     # [Stage 3] 行号引用校验
│   │   │   ├── review_quality_config.py# 质量控制配置（规则 + Prompt + 阈值）
│   │   │   ├── review_store.py         # JSON 文件持久化
│   │   │   └── markdown_renderer.py    # Markdown → HTML
│   │   └── utils/
│   ├── tests/                          # 130 个测试
│   ├── data/reviews/                   # 评审结果存储（运行时生成）
│   ├── .env
│   ├── requirements.txt
│   └── run.py
├── frontend/
│   ├── src/
│   │   ├── views/
│   │   │   ├── ConfigPage.vue          # 模型配置
│   │   │   └── ReviewPage.vue          # PR 评审（含质量开关）
│   │   ├── components/
│   │   │   └── ReviewResult.vue        # 评审结果渲染
│   │   ├── api/index.js                # axios + 5 个后端接口
│   │   ├── router/index.js
│   │   └── styles/global.css
│   ├── vite.config.js
│   └── package.json
├── docs/                               # 设计文档 & 实施计划
└── README.md
```

## API 端点

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/health` | 健康检查 |
| POST | `/api/pr/parse` | 解析 PR URL |
| POST | `/api/pr/context` | 获取 PR 评审上下文 |
| POST | `/api/llm/test` | 测试 LLM 连接 |
| POST | `/api/llm/review` | 独立 LLM 评审 |
| POST | `/api/review` | **端到端评审**（含三阶段质量管线） |
| POST | `/api/review/parse` | 解析 Markdown 评审文本 |
| POST | `/api/review/html` | Markdown → HTML 渲染 |
| GET | `/api/review/history` | 历史评审列表（分页+搜索） |
| GET | `/api/review/{id}` | 单条评审详情（含质量控制明细） |

`POST /api/review` 返回的质量控制字段：

| 字段 | 说明 |
|------|------|
| `review_parsed` | 经 Stage 1+2 过滤后的最终评审结果 |
| `review_parsed_unfiltered` | 原始评审结果（用于对比过滤效果） |
| `hard_filter_removed` | Stage 1 硬过滤移除的意见列表（含规则名、原因、内容预览） |
| `reflection_data` | Stage 2 LLM 反思评分明细（dimension, issue_index, score, reason, should_keep） |
| `line_validation` | Stage 3 行号校验结果（每个引用的 valid 标记和 reason） |

## 快速开始

### 环境要求

- Python 3.11+
- Node.js 18+

### 后端

```bash
cd backend
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env         # 编辑 .env 填写 LLM_API_KEY 等
python run.py                # 启动 → http://localhost:8000
```

### 前端

```bash
cd frontend
npm install
npm run dev                  # 启动 → http://localhost:3000
```

### 使用

1. 访问 `http://localhost:3000`，填写 API Key / Base URL / Model Name，点击"测试连接"
2. 点"保存配置"，切换到"PR 评审"页
3. 输入 GitHub PR URL，点击"开始评审"
4. 前端默认开启三阶段质量控制（自我反思 / 硬过滤 / 行号校验），可通过开关独立关闭
5. 查看评审结果，或从右侧抽屉查看历史记录

### 配置说明

| 变量 | 必填 | 说明 |
|------|------|------|
| `LLM_API_KEY` | 是 | 大模型 API Key |
| `LLM_BASE_URL` | 否 | 模型接口地址 |
| `LLM_MODEL_NAME` | 否 | 模型名称 |
| `GITHUB_TOKEN` | 否 | GitHub Token（公开 PR 可不填，避免 API 限流建议填写） |
| `SERVER_PORT` | 否 | 服务端口，默认 8000 |

## 开发进度

| Phase | 内容 | 状态 |
|-------|------|------|
| 1 | 后端工程骨架 + 项目规划 | ✅ |
| 2 | GitHub PR 解析 + Diff 结构化 | ✅ |
| 3 | LLM 客户端 + 评审 Prompt + 上下文构建 | ✅ |
| 4 | 端到端评审 + 三阶段质量控制 + 持久化 + HTML 渲染 | ✅ |
| 5 | 前端工程 + 质量开关 + 历史管理 | ✅ |
| 6 | 结果渲染优化 + 导出 + 文档 | 📋 计划中 |

## 测试

```bash
cd backend
pytest                          # 130 passed, 1 skipped
```

## 许可证

个人自研课程作业项目，仅供学习交流使用。