docs: 重写 README，添加安装配置和 API 参考文档

2026-06-20 00:06:17 +08:00
parent 446bb987f4
commit e571a33dd2
1 changed files with 133 additions and 1 deletions
@@ -1,3 +1,135 @@
 # PR-Helper

-🤗 帮助生成 PR 信息，Review 代码
+AI-powered PR description generator and code review tool. Self-hosted, designed for internal/local use.
+
+## 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
+
+## Quick Start
+
+### Docker (recommended)
+
+```bash
+docker compose up --build
+```
+
+Open http://localhost:8080.
+
+### Manual Build
+
+Requirements: Go 1.22+, CGO enabled (for SQLite), Chromium (for PDF export)
+
+```bash
+# Install dependencies
+go mod download
+
+# Build
+CGO_ENABLED=1 go build -o pr-helper .
+
+# Run
+./pr-helper
+```
+
+Server listens on `:8080` by default.
+
+## Configuration
+
+### LLM Settings (required)
+
+Navigate to **Settings** (`/settings`) and configure:
+
+| 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` |
+
+Works with any OpenAI-compatible API: OpenAI, Deepseek, Ollama, vLLM, etc.
+
+### Review Settings
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| Top-N Files | Max files to analyze per review (0 = all) | `20` |
+| Concurrency | Parallel file analyses | `5` |
+
+### Cache Settings
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| Max Age (days) | Auto-cleanup threshold | `7` |
+| Max Size (MB) | Total cache size limit | `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` |
+
+## 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
+
+## API Routes
+
+### 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 |
+
+### 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 |
+
+## 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
+
+## Security
+
+**No authentication.** Do not expose to the public internet. Intended for internal/local use only.
+
+## License
+
+MIT