docs: 添加 10 份技术文档，README 改为中文

- 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: 故障排查
2026-06-23 22:38:43 +08:00
parent 6f0fabf934
commit 275e5cc886
11 changed files with 4877 additions and 87 deletions
@@ -1,135 +1,173 @@
 # PR-Helper

-AI-powered PR description generator and code review tool. Self-hosted, designed for internal/local use.
+AI 驱动的 PR 描述生成器和代码审查工具。自托管设计，专为内部/本地使用。

-## Features
+## 功能特性

- **PR Description Generation** — Select commits from an interactive Git graph, get a structured PR description via LLM
- **AI Code Review** — Per-file analysis with severity ratings, inline suggestions on the diff view
- **Interactive Git Graph** — D3.js visualization with click-to-select base/head refs
- **Diff Viewer** — Split/unified view powered by diff2html with syntax highlighting
- **Review Notes** — Add markdown notes at overall, file, or suggestion level
- **PDF Export** — Generate printable review reports
- **Repository Caching** — Cloned repos are cached with configurable expiry
+- **PR 描述生成** — 从交互式 Git 图形中选择提交，通过 LLM 生成结构化 PR 描述
+- **AI 代码审查** — 按文件分析，严重程度评级，在差异视图中内联显示建议
+- **交互式 Git 图形** — D3.js 可视化，点击选择 base/head 引用
+- **差异查看器** — diff2html 驱动的分割/统一视图，支持语法高亮
+- **审查笔记** — 在整体、文件或建议级别添加 Markdown 笔记
+- **PDF 导出** — 生成可打印的审查报告
+- **仓库缓存** — 克隆的仓库缓存，可配置过期时间

-## Quick Start
+## 快速开始

-### Docker (recommended)
+### Docker（推荐）

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

-Open http://localhost:8080.
+打开 http://localhost:8080。

-### Manual Build
+### 手动构建

-Requirements: Go 1.22+, CGO enabled (for SQLite), Chromium (for PDF export)
+要求：Go 1.22+，CGO 启用（用于 SQLite），Chromium（用于 PDF 导出）

 ```bash
-# Install dependencies
+# 安装依赖
 go mod download

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

-# Run
+# 运行
 ./pr-helper
 ```

-Server listens on `:8080` by default.
+服务器默认监听 `:8080` 端口。

-## Configuration
+## 配置

-### LLM Settings (required)
+### LLM 设置（必需）

-Navigate to **Settings** (`/settings`) and configure:
+导航到 **设置** (`/settings`) 并配置：

-| Setting | Description | Default |
-|---------|-------------|---------|
-| API Endpoint | OpenAI-compatible API URL | `https://api.openai.com/v1` |
-| API Key | Your API key | (empty) |
-| Model | Model name | `gpt-4o` |
+| 设置 | 说明 | 默认值 |
+|------|------|--------|
+| API 端点 | OpenAI 兼容 API URL | `https://api.openai.com/v1` |
+| API 密钥 | 您的 API 密钥 | (空) |
+| 模型 | 模型名称 | `gpt-4o` |

-Works with any OpenAI-compatible API: OpenAI, Deepseek, Ollama, vLLM, etc.
+支持任何 OpenAI 兼容 API：OpenAI、Deepseek、Ollama、vLLM 等。

-### Review Settings
+### 审查设置

-| Setting | Description | Default |
-|---------|-------------|---------|
-| Top-N Files | Max files to analyze per review (0 = all) | `20` |
-| Concurrency | Parallel file analyses | `5` |
+| 设置 | 说明 | 默认值 |
+|------|------|--------|
+| Top-N 文件数 | 每次审查分析的最大文件数 (0 = 全部) | `20` |
+| 并发数 | 并行文件分析数 | `5` |

-### Cache Settings
+### 缓存设置

-| Setting | Description | Default |
-|---------|-------------|---------|
-| Max Age (days) | Auto-cleanup threshold | `7` |
-| Max Size (MB) | Total cache size limit | `5000` |
+| 设置 | 说明 | 默认值 |
+|------|------|--------|
+| 最大保留天数 | 自动清理阈值 | `7` |
+| 最大缓存大小 (MB) | 总缓存大小限制 | `5000` |

-### Environment Variables
+### 环境变量

-| Variable | Description | Default |
-|----------|-------------|---------|
-| `PORT` | Server port | `8080` |
-| `GIN_MODE` | Gin mode (`debug`/`release`) | `debug` |
-| `DATA_DIR` | Data directory path | `./data` |
-| `CHROME_BIN` | Chromium binary path (for PDF) | `/usr/bin/chromium-browser` |
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `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` |

-## Usage
+## 使用方法

-1. **Clone a repo** — Paste a Git URL on the homepage, optionally provide credentials for private repos
-2. **Browse the graph** — View branches, tags, and commit history in the interactive D3.js graph
-3. **Select refs** — Click nodes in the graph or use the dropdown selectors to pick base and head
-4. **Generate PR description** — Navigate to Generate, select refs, click Generate
-5. **Run code review** — Navigate to Review, configure Top-N and concurrency, click Start Review
-6. **Add notes** — Click into any suggestion or the overall section to add markdown notes
-7. **Export PDF** — Click Export PDF to download a formatted report
+1. **克隆仓库** — 在首页粘贴 Git URL，可选提供私有仓库的认证信息
+2. **浏览图形** — 在交互式 D3.js 图形中查看分支、标签和提交历史
+3. **选择引用** — 点击图形中的节点或使用下拉选择器选择 base 和 head
+4. **生成 PR 描述** — 导航到"生成"，选择引用，点击"生成"
+5. **运行代码审查** — 导航到"审查"，配置 Top-N 和并发数，点击"开始审查"
+6. **添加笔记** — 点击任何建议或整体部分添加 Markdown 笔记
+7. **导出 PDF** — 点击"导出 PDF"下载格式化报告

-## API Routes
+## API 路由

-### Pages
+### 页面

-| Method | Path | Description |
-|--------|------|-------------|
-| GET | `/` | Homepage — clone form and cached repos |
-| GET | `/repo/:id` | Repository — Git graph and diff viewer |
-| GET | `/repo/:id/generate` | PR description generation |
-| GET | `/repo/:id/review` | AI code review |
-| GET | `/settings` | Settings page |
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/` | 首页 — 克隆表单和已缓存仓库 |
+| GET | `/repo/:id` | 仓库详情 — Git 图形和差异查看器 |
+| GET | `/settings` | 设置页面 |

 ### API

-| Method | Path | Description |
-|--------|------|-------------|
-| POST | `/api/repos` | Clone repository (SSE stream) |
-| GET | `/api/repos` | List cached repositories |
-| DELETE | `/api/repos/:id` | Delete repository cache |
-| POST | `/api/repos/:id/cleanup` | Trigger cache cleanup |
-| GET | `/api/repos/:id/graph` | Git graph data (JSON) |
-| GET | `/api/repos/:id/refs` | Branches and tags |
-| GET | `/api/repos/:id/commits` | Commit log for a ref |
-| GET | `/api/repos/:id/diff` | Diff between two refs |
-| POST | `/api/repos/:id/generate` | Generate PR description (SSE) |
-| POST | `/api/repos/:id/review` | AI code review (SSE) |
-| GET | `/api/repos/:id/review/analyses` | List past reviews |
-| GET | `/api/repos/:id/review/analyses/:aid` | Get single review |
-| POST | `/api/repos/:id/review/notes` | Save a review note |
-| GET | `/api/repos/:id/review/notes` | Get review notes |
-| POST | `/api/repos/:id/review/pdf` | Generate PDF report |
-| GET | `/api/settings` | Get settings |
-| PUT | `/api/settings` | Update settings |
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| 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` | 更新设置 |

-## Tech Stack
+## 技术栈

- **Backend**: Go, Gin, SQLite (go-sqlite3), go-git, chromedp
- **Frontend**: Go html/template, HTMX, D3.js, diff2html, Tailwind CSS
- **LLM**: OpenAI-compatible API with SSE streaming
+| 层级 | 技术 |
+|------|------|
+| 后端 | Go、Gin、MySQL、go-git |
+| 前端 | Go html/template、HTMX、D3.js、diff2html、Tailwind CSS |
+| LLM | OpenAI 兼容 API (SSE 流式传输) |
+| 部署 | Docker |

-## Security
+## 项目结构

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

-## License
+## 技术文档
+
+详细的技术文档位于 [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