PR-Helper/README.md

# PR-Helper

AI 驱动的 PR 描述生成器和代码审查工具。自托管设计，专为内部/本地使用。

## 功能特性

- **PR 描述生成** — 从交互式 Git 图形中选择提交，通过 LLM 生成结构化 PR 描述
- **AI 代码审查** — 按文件分析，严重程度评级，在差异视图中内联显示建议
- **交互式 Git 图形** — D3.js 可视化，点击选择 base/head 引用
- **差异查看器** — diff2html 驱动的分割/统一视图，支持语法高亮
- **审查笔记** — 在整体、文件或建议级别添加 Markdown 笔记
- **PDF 导出** — 生成可打印的审查报告
- **仓库缓存** — 克隆的仓库缓存，可配置过期时间

## 快速开始

### Docker（推荐）

```bash
docker compose up --build
```

打开 http://localhost:8080。

### 手动构建

要求：Go 1.22+，CGO 启用（用于 SQLite），Chromium（用于 PDF 导出）

```bash
# 安装依赖
go mod download

# 构建
CGO_ENABLED=1 go build -o pr-helper .

# 运行
./pr-helper
```

服务器默认监听 `:8080` 端口。

## 配置

### LLM 设置（必需）

导航到 **设置** (`/settings`) 并配置：

| 设置 | 说明 | 默认值 |
|------|------|--------|
| API 端点 | OpenAI 兼容 API URL | `https://api.openai.com/v1` |
| API 密钥 | 您的 API 密钥 | (空) |
| 模型 | 模型名称 | `gpt-4o` |

支持任何 OpenAI 兼容 API：OpenAI、Deepseek、Ollama、vLLM 等。

### 审查设置

| 设置 | 说明 | 默认值 |
|------|------|--------|
| Top-N 文件数 | 每次审查分析的最大文件数 (0 = 全部) | `20` |
| 并发数 | 并行文件分析数 | `5` |

### 缓存设置

| 设置 | 说明 | 默认值 |
|------|------|--------|
| 最大保留天数 | 自动清理阈值 | `7` |
| 最大缓存大小 (MB) | 总缓存大小限制 | `5000` |

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `PORT` | 服务器端口 | `8080` |
| `GIN_MODE` | Gin 模式 (`debug`/`release`) | `debug` |
| `DATA_DIR` | 数据目录路径 | `./data` |
| `MYSQL_HOST` | MySQL 主机地址 | `127.0.0.1` |
| `MYSQL_PORT` | MySQL 端口 | `3306` |
| `MYSQL_USER` | MySQL 用户名 | `root` |
| `MYSQL_PASSWORD` | MySQL 密码 | (空) |
| `MYSQL_DATABASE` | MySQL 数据库名 | `pr_helper` |

## 使用方法

1. **克隆仓库** — 在首页粘贴 Git URL，可选提供私有仓库的认证信息
2. **浏览图形** — 在交互式 D3.js 图形中查看分支、标签和提交历史
3. **选择引用** — 点击图形中的节点或使用下拉选择器选择 base 和 head
4. **生成 PR 描述** — 导航到"生成"，选择引用，点击"生成"
5. **运行代码审查** — 导航到"审查"，配置 Top-N 和并发数，点击"开始审查"
6. **添加笔记** — 点击任何建议或整体部分添加 Markdown 笔记
7. **导出 PDF** — 点击"导出 PDF"下载格式化报告

## API 路由

### 页面

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/` | 首页 — 克隆表单和已缓存仓库 |
| GET | `/repo/:id` | 仓库详情 — Git 图形和差异查看器 |
| GET | `/settings` | 设置页面 |

### API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/repos` | 克隆仓库 (SSE 流) |
| GET | `/api/repos` | 列出已缓存仓库 |
| DELETE | `/api/repos/:id` | 删除仓库缓存 |
| POST | `/api/repos/:id/cleanup` | 触发缓存清理 |
| POST | `/api/repos/:id/pull` | 拉取更新 |
| GET | `/api/repos/:id/graph` | Git 图形数据 (JSON) |
| GET | `/api/repos/:id/refs` | 分支和标签 |
| GET | `/api/repos/:id/commits` | 提交日志 |
| GET | `/api/repos/:id/diff` | 两个引用之间的差异 |
| POST | `/api/repos/:id/generate` | 生成 PR 描述 (SSE) |
| POST | `/api/repos/:id/review` | AI 代码审查 (SSE) |
| GET | `/api/repos/:id/review/analyses` | 列出历史审查 |
| GET | `/api/repos/:id/review/analyses/:aid` | 获取单个审查 |
| POST | `/api/repos/:id/review/notes` | 保存审查笔记 |
| GET | `/api/repos/:id/review/notes` | 获取审查笔记 |
| GET | `/api/settings` | 获取设置 |
| PUT | `/api/settings` | 更新设置 |

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端 | Go、Gin、MySQL、go-git |
| 前端 | Go html/template、HTMX、D3.js、diff2html、Tailwind CSS |
| LLM | OpenAI 兼容 API (SSE 流式传输) |
| 部署 | Docker |

## 项目结构

```
PR-Helper/
├── main.go              # 应用入口
├── config/              # 配置加载
├── database/            # 数据库初始化和迁移
├── handlers/            # HTTP 处理器 (页面 + JSON API + SSE)
├── models/              # 数据模型
├── services/            # 业务逻辑 (Git 操作、LLM 调用、缓存管理)
├── templates/           # Go HTML 模板
├── static/              # CSS (Tailwind)、JS、第三方库
├── data/                # 克隆的仓库缓存
└── docs/                # 技术文档
```

## 技术文档

详细的技术文档位于 [docs/](docs/) 目录：

| 文档 | 说明 |
|------|------|
| [01-architecture.md](docs/01-architecture.md) | 架构概览 — 项目结构、技术栈、数据流 |
| [02-backend-services.md](docs/02-backend-services.md) | 后端服务层 — Git、LLM、PR 生成、代码审查 |
| [03-frontend-interaction.md](docs/03-frontend-interaction.md) | 前端交互设计 — SSE、D3.js 图形、差异查看器 |
| [04-database-design.md](docs/04-database-design.md) | 数据库设计 — 表结构、索引、迁移策略 |
| [05-api-reference.md](docs/05-api-reference.md) | API 接口文档 — 完整的 RESTful API 参考 |
| [06-sse-streaming.md](docs/06-sse-streaming.md) | SSE 流式传输 — 协议、实现、错误处理 |
| [07-llm-integration.md](docs/07-llm-integration.md) | LLM 集成 — 配置、提示模板、流式调用 |
| [08-deployment.md](docs/08-deployment.md) | 部署运维 — Docker、反向代理、监控 |
| [09-development-guide.md](docs/09-development-guide.md) | 开发指南 — 环境搭建、代码规范、测试 |
| [10-troubleshooting.md](docs/10-troubleshooting.md) | 故障排查 — 常见问题和解决方案 |

## 安全

**无认证机制。** 请勿暴露到公网。仅限内部/本地使用。

## 许可证

MIT