wonder
275e5cc886
- 01-architecture.md: 架构概览 - 02-backend-services.md: 后端服务层 - 03-frontend-interaction.md: 前端交互设计 - 04-database-design.md: 数据库设计 - 05-api-reference.md: API 接口文档 - 06-sse-streaming.md: SSE 流式传输 - 07-llm-integration.md: LLM 集成 - 08-deployment.md: 部署运维 - 09-development-guide.md: 开发指南 - 10-troubleshooting.md: 故障排查
174 lines
6.1 KiB
Markdown
174 lines
6.1 KiB
Markdown
# 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
|