From 8a8b336237d3509c856a66af1bd9d18b4befcc16 Mon Sep 17 00:00:00 2001 From: jeffusion Date: Thu, 5 Mar 2026 10:14:21 +0800 Subject: [PATCH] docs: update README and Chinese docs for multi-provider LLM architecture Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) --- README.md | 49 ++++++++++++++++++++++---------------------- docs/README.zh-CN.md | 49 ++++++++++++++++++++++---------------------- 2 files changed, 50 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 8c6a8b2..14de08e 100644 --- a/README.md +++ b/README.md @@ -2,31 +2,31 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -AI-powered code review assistant for Gitea. Automatically reviews Pull Requests and commits using OpenAI, providing intelligent code quality analysis with both summary comments and line-level feedback. +AI-powered code review assistant for Gitea. Automatically reviews Pull Requests and commits using pluggable LLM providers (OpenAI Compatible, OpenAI Responses API, Anthropic, Google Gemini), providing intelligent code quality analysis with both summary comments and line-level feedback. **[ไธญๆ–‡ๆ–‡ๆกฃ](./docs/README.zh-CN.md)** ## Features -- ๐Ÿค– **AI Code Review** - Automatic review of PRs and commits using OpenAI models +- ๐Ÿค– **AI Code Review** - Automatic review of PRs and commits using pluggable LLM providers - ๐Ÿ“ **Line-Level Comments** - Precise feedback on specific code changes - ๐Ÿ”„ **Dual Review Engines** - Legacy (simple) or Agent-based (multi-agent) review modes - ๐Ÿ”” **Feishu Notifications** - Integrated notification system for PR events -- ๐ŸŽ›๏ธ **Admin Dashboard** - Web UI for managing repository webhooks and configuration +- ๐ŸŽ›๏ธ **Admin Dashboard** - Web UI for managing repository webhooks and LLM provider configuration - ๐Ÿ” **Secure Webhooks** - HMAC-SHA256 signature verification ## Architecture ``` โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” -โ”‚ Gitea Server โ”‚โ”€โ”€โ”€โ”€โ–ถโ”‚ Gitea Assistant โ”‚โ”€โ”€โ”€โ”€โ–ถโ”‚ OpenAI API โ”‚ -โ”‚ (Webhooks) โ”‚ โ”‚ (Hono + Bun) โ”‚ โ”‚ โ”‚ +โ”‚ Gitea Server โ”‚โ”€โ”€โ”€โ”€โ–ถโ”‚ Gitea Assistant โ”‚โ”€โ”€โ”€โ”€โ–ถโ”‚ LLM Gateway โ”‚ +โ”‚ (Webhooks) โ”‚ โ”‚ (Hono + Bun) โ”‚ โ”‚ (Multi-Provider)โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ - โ”‚ - โ–ผ - โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” - โ”‚ Admin Dashboard โ”‚ - โ”‚ (React SPA) โ”‚ + โ”‚ โ”‚ + โ–ผ โ”œโ”€ OpenAI Compatible + โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”œโ”€ OpenAI Responses API + โ”‚ Admin Dashboard โ”‚ โ”œโ”€ Anthropic + โ”‚ (React SPA) โ”‚ โ””โ”€ Google Gemini โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ ``` @@ -43,7 +43,7 @@ AI-powered code review assistant for Gitea. Automatically reviews Pull Requests - [Bun](https://bun.sh/) >= 1.2.5 - Gitea instance with API access -- OpenAI API key +- At least one LLM provider API key (OpenAI, Anthropic, Google Gemini, or any OpenAI-compatible endpoint) ### Installation @@ -63,10 +63,6 @@ Edit `.env` with your settings: GITEA_API_URL=https://your-gitea-instance.com/api/v1 GITEA_ACCESS_TOKEN=your_gitea_token -# OpenAI -OPENAI_API_KEY=your_openai_key -OPENAI_MODEL=gpt-4o-mini - # Security WEBHOOK_SECRET=your_webhook_secret # openssl rand -hex 32 @@ -74,6 +70,8 @@ WEBHOOK_SECRET=your_webhook_secret # openssl rand -hex 32 ADMIN_PASSWORD=your_admin_password ``` +> **Note**: LLM provider settings (API keys, models, endpoints) are configured through the Admin Dashboard Web UI, not environment variables. Access the dashboard at `http://your-server:3000` after starting the server. + See [Configuration Reference](#configuration-reference) for all options. ### Running @@ -108,12 +106,19 @@ In Gitea repository settings, add a webhook: | `GITEA_API_URL` | Gitea API endpoint | Required | | `GITEA_ACCESS_TOKEN` | Token for code review (read + comment permissions) | Required | | `GITEA_ADMIN_TOKEN` | Token for webhook management (optional) | - | -| `OPENAI_BASE_URL` | OpenAI API base URL | `https://api.openai.com/v1` | -| `OPENAI_API_KEY` | OpenAI API key | Required | -| `OPENAI_MODEL` | Model to use | `gpt-4o-mini` | | `PORT` | Server port | `3000` | | `WEBHOOK_SECRET` | Webhook signature secret | Required | +### LLM Provider Configuration + +LLM providers and models are configured exclusively through the **Admin Dashboard** Web UI: + +1. Access the dashboard at `http://your-server:3000` +2. Navigate to **LLM ้…็ฝฎ** (LLM Configuration) +3. Add your LLM providers (OpenAI Compatible, OpenAI Responses API, Anthropic, Google Gemini) +4. Assign models to review roles (legacy, planner, specialist, judge, embedding) + +> API keys are stored encrypted (AES-256-GCM) in a local SQLite database. ### Custom Prompts | Variable | Description | @@ -143,14 +148,10 @@ Enable with `REVIEW_ENGINE=agent` for advanced multi-agent reviews: |----------|-------------|---------| | `REVIEW_ENGINE` | Engine mode (`legacy` or `agent`) | `legacy` | | `REVIEW_WORKDIR` | Working directory for repo clones | `/tmp/gitea-assistant` | -| `REVIEW_MODEL_PLANNER` | Planner model | `gpt-4o-mini` | -| `REVIEW_MODEL_SPECIALIST` | Specialist model | `gpt-4o-mini` | -| `REVIEW_MODEL_JUDGE` | Judge model | `gpt-4o-mini` | | `REVIEW_MAX_PARALLEL_RUNS` | Max concurrent tasks | `2` | | `REVIEW_MAX_FILES_PER_RUN` | Max files per review | `200` | | `REVIEW_AUTO_PUBLISH_MIN_CONFIDENCE` | Min confidence for auto-publish | `0.8` | | `REVIEW_ENABLE_HUMAN_GATE` | Enable human approval | `true` | - ### Memory & Learning (Experimental) | Variable | Description | Default | @@ -185,7 +186,6 @@ Encode your credentials as base64 and update `k8s/gitea-assistant.yaml`: ```bash echo -n "your_gitea_token" | base64 -echo -n "your_openai_key" | base64 echo -n "your_webhook_secret" | base64 echo -n "your_admin_password" | base64 ``` @@ -195,8 +195,9 @@ echo -n "your_admin_password" | base64 Edit the ConfigMap in `k8s/gitea-assistant.yaml`: - Set `GITEA_API_URL` to your Gitea instance API endpoint -- Adjust model and review engine settings as needed +- Adjust review engine settings as needed +> **Note**: LLM provider configuration is done through the Admin Dashboard after deployment. Ensure persistent storage is configured for the `/app/data` directory to retain LLM settings and encrypted API keys. **3. Deploy** ```bash diff --git a/docs/README.zh-CN.md b/docs/README.zh-CN.md index 02d5423..b6cfb2b 100644 --- a/docs/README.zh-CN.md +++ b/docs/README.zh-CN.md @@ -2,31 +2,31 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -ๅŸบไบŽ AI ็š„ Gitea ไปฃ็ ๅฎกๆŸฅๅŠฉๆ‰‹ใ€‚่‡ชๅŠจๅฎกๆŸฅ Pull Request ๅ’Œๆไบค๏ผŒไฝฟ็”จ OpenAI ๆไพ›ๆ™บ่ƒฝไปฃ็ ่ดจ้‡ๅˆ†ๆž๏ผŒๆ”ฏๆŒๆ€ปไฝ“่ฏ„่ฎบๅ’Œ่กŒ็บงๅ้ฆˆใ€‚ +ๅŸบไบŽ AI ็š„ Gitea ไปฃ็ ๅฎกๆŸฅๅŠฉๆ‰‹ใ€‚่‡ชๅŠจๅฎกๆŸฅ Pull Request ๅ’Œๆไบค๏ผŒๆ”ฏๆŒๅคš็ง LLM ๆไพ›ๅ•†๏ผˆOpenAI ๅ…ผๅฎนใ€OpenAI Responses APIใ€Anthropicใ€Google Gemini๏ผ‰๏ผŒๆไพ›ๆ™บ่ƒฝไปฃ็ ่ดจ้‡ๅˆ†ๆž๏ผŒๆ”ฏๆŒๆ€ปไฝ“่ฏ„่ฎบๅ’Œ่กŒ็บงๅ้ฆˆใ€‚ **[English Documentation](../README.md)** ## ๅŠŸ่ƒฝ็‰น็‚น -- ๐Ÿค– **AI ไปฃ็ ๅฎกๆŸฅ** - ไฝฟ็”จ OpenAI ๆจกๅž‹่‡ชๅŠจๅฎกๆŸฅ PR ๅ’Œๆไบค +- ๐Ÿค– **AI ไปฃ็ ๅฎกๆŸฅ** - ไฝฟ็”จๅฏๆ’ๆ‹”็š„ LLM ๆไพ›ๅ•†่‡ชๅŠจๅฎกๆŸฅ PR ๅ’Œๆไบค - ๐Ÿ“ **่กŒ็บง่ฏ„่ฎบ** - ้’ˆๅฏนๅ…ทไฝ“ไปฃ็ ๅ˜ๆ›ด็š„็ฒพ็กฎๅ้ฆˆ - ๐Ÿ”„ **ๅŒๅผ•ๆ“Žๆจกๅผ** - Legacy๏ผˆ็ฎ€ๅ•๏ผ‰ๆˆ– Agent๏ผˆๅคšไปฃ็†๏ผ‰ๅฎกๆŸฅๆจกๅผ - ๐Ÿ”” **้ฃžไนฆ้€š็Ÿฅ** - PR ไบ‹ไปถ้€š็Ÿฅ้›†ๆˆ -- ๐ŸŽ›๏ธ **็ฎก็†ๅŽๅฐ** - ็”จไบŽ็ฎก็†ไป“ๅบ“ Webhook ๅ’Œ้…็ฝฎ็š„ Web ็•Œ้ข +- ๐ŸŽ›๏ธ **็ฎก็†ๅŽๅฐ** - ็”จไบŽ็ฎก็†ไป“ๅบ“ Webhook ๅ’Œ LLM ๆไพ›ๅ•†้…็ฝฎ็š„ Web ็•Œ้ข - ๐Ÿ” **ๅฎ‰ๅ…จ้ชŒ่ฏ** - HMAC-SHA256 ็ญพๅ้ชŒ่ฏ ## ๆžถๆž„่ฎพ่ฎก ``` โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” -โ”‚ Gitea ๆœๅŠกๅ™จ โ”‚โ”€โ”€โ”€โ”€โ–ถโ”‚ Gitea Assistant โ”‚โ”€โ”€โ”€โ”€โ–ถโ”‚ OpenAI API โ”‚ -โ”‚ (Webhooks) โ”‚ โ”‚ (Hono + Bun) โ”‚ โ”‚ โ”‚ +โ”‚ Gitea ๆœๅŠกๅ™จ โ”‚โ”€โ”€โ”€โ”€โ–ถโ”‚ Gitea Assistant โ”‚โ”€โ”€โ”€โ”€โ–ถโ”‚ LLM ็ฝ‘ๅ…ณ โ”‚ +โ”‚ (Webhooks) โ”‚ โ”‚ (Hono + Bun) โ”‚ โ”‚ (ๅคšๆไพ›ๅ•†) โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ - โ”‚ - โ–ผ - โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” - โ”‚ ็ฎก็†ๅŽๅฐ โ”‚ - โ”‚ (React SPA) โ”‚ + โ”‚ โ”‚ + โ–ผ โ”œโ”€ OpenAI ๅ…ผๅฎน + โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”œโ”€ OpenAI Responses API + โ”‚ ็ฎก็†ๅŽๅฐ โ”‚ โ”œโ”€ Anthropic + โ”‚ (React SPA) โ”‚ โ””โ”€ Google Gemini โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ ``` @@ -43,7 +43,7 @@ - [Bun](https://bun.sh/) >= 1.2.5 - ๅฏ่ฎฟ้—ฎ็š„ Gitea ๅฎžไพ‹ -- OpenAI API ๅฏ†้’ฅ +- ่‡ณๅฐ‘ไธ€ไธช LLM ๆไพ›ๅ•†็š„ API ๅฏ†้’ฅ๏ผˆOpenAIใ€Anthropicใ€Google Gemini ๆˆ–ไปปไฝ• OpenAI ๅ…ผๅฎน็ซฏ็‚น๏ผ‰ ### ๅฎ‰่ฃ…ๆญฅ้ชค @@ -63,10 +63,6 @@ cp .env.example .env GITEA_API_URL=https://your-gitea-instance.com/api/v1 GITEA_ACCESS_TOKEN=your_gitea_token -# OpenAI -OPENAI_API_KEY=your_openai_key -OPENAI_MODEL=gpt-4o-mini - # ๅฎ‰ๅ…จ WEBHOOK_SECRET=your_webhook_secret # openssl rand -hex 32 @@ -74,6 +70,8 @@ WEBHOOK_SECRET=your_webhook_secret # openssl rand -hex 32 ADMIN_PASSWORD=your_admin_password ``` +> **ๆณจๆ„**: LLM ๆไพ›ๅ•†่ฎพ็ฝฎ๏ผˆAPI ๅฏ†้’ฅใ€ๆจกๅž‹ใ€็ซฏ็‚น๏ผ‰้€š่ฟ‡็ฎก็†ๅŽๅฐ Web ็•Œ้ข้…็ฝฎ๏ผŒ่€Œ้ž็Žฏๅขƒๅ˜้‡ใ€‚ๅฏๅŠจๆœๅŠกๅŽ๏ผŒ่ฎฟ้—ฎ `http://your-server:3000` ่ฟ›่กŒ้…็ฝฎใ€‚ + ๅฎŒๆ•ด้…็ฝฎ้กน่ฏทๅ‚้˜… [้…็ฝฎๅ‚่€ƒ](#้…็ฝฎๅ‚่€ƒ)ใ€‚ ### ๅฏๅŠจๆœๅŠก @@ -108,12 +106,19 @@ bun run start # ็”Ÿไบงๆจกๅผ | `GITEA_API_URL` | Gitea API ๅœฐๅ€ | ๅฟ…ๅกซ | | `GITEA_ACCESS_TOKEN` | ไปฃ็ ๅฎกๆŸฅไปค็‰Œ๏ผˆ้œ€่ฆ่ฏปๅ–ๅ’Œ่ฏ„่ฎบๆƒ้™๏ผ‰ | ๅฟ…ๅกซ | | `GITEA_ADMIN_TOKEN` | Webhook ็ฎก็†ไปค็‰Œ๏ผˆๅฏ้€‰๏ผ‰ | - | -| `OPENAI_BASE_URL` | OpenAI API ๅŸบ็ก€ๅœฐๅ€ | `https://api.openai.com/v1` | -| `OPENAI_API_KEY` | OpenAI API ๅฏ†้’ฅ | ๅฟ…ๅกซ | -| `OPENAI_MODEL` | ไฝฟ็”จ็š„ๆจกๅž‹ | `gpt-4o-mini` | | `PORT` | ๆœๅŠก็ซฏๅฃ | `3000` | | `WEBHOOK_SECRET` | Webhook ็ญพๅ้ชŒ่ฏๅฏ†้’ฅ | ๅฟ…ๅกซ | +### LLM ๆไพ›ๅ•†้…็ฝฎ + +LLM ๆไพ›ๅ•†ๅ’Œๆจกๅž‹้€š่ฟ‡**็ฎก็†ๅŽๅฐ** Web ็•Œ้ข่ฟ›่กŒ้…็ฝฎ๏ผš + +1. ่ฎฟ้—ฎ็ฎก็†ๅŽๅฐ `http://your-server:3000` +2. ๅฏผ่ˆชๅˆฐ **LLM ้…็ฝฎ** ้กต้ข +3. ๆทปๅŠ  LLM ๆไพ›ๅ•†๏ผˆOpenAI ๅ…ผๅฎนใ€OpenAI Responses APIใ€Anthropicใ€Google Gemini๏ผ‰ +4. ไธบๅฎกๆŸฅ่ง’่‰ฒๅˆ†้…ๆจกๅž‹๏ผˆlegacyใ€plannerใ€specialistใ€judgeใ€embedding๏ผ‰ + +> API ๅฏ†้’ฅไฝฟ็”จ AES-256-GCM ๅŠ ๅฏ†ๅญ˜ๅ‚จๅœจๆœฌๅœฐ SQLite ๆ•ฐๆฎๅบ“ไธญใ€‚ ### ่‡ชๅฎšไน‰ๆ็คบ่ฏ | ๅ˜้‡ | ๆ่ฟฐ | @@ -143,14 +148,10 @@ bun run start # ็”Ÿไบงๆจกๅผ |------|------|--------| | `REVIEW_ENGINE` | ๅผ•ๆ“Žๆจกๅผ๏ผˆ`legacy` ๆˆ– `agent`๏ผ‰ | `legacy` | | `REVIEW_WORKDIR` | ไป“ๅบ“ๅ…‹้š†ๅทฅไฝœ็›ฎๅฝ• | `/tmp/gitea-assistant` | -| `REVIEW_MODEL_PLANNER` | ่ง„ๅˆ’ๆจกๅž‹ | `gpt-4o-mini` | -| `REVIEW_MODEL_SPECIALIST` | ไธ“ๅฎถๆจกๅž‹ | `gpt-4o-mini` | -| `REVIEW_MODEL_JUDGE` | ๅˆคๆ–ญๆจกๅž‹ | `gpt-4o-mini` | | `REVIEW_MAX_PARALLEL_RUNS` | ๆœ€ๅคงๅนถๅ‘ไปปๅŠกๆ•ฐ | `2` | | `REVIEW_MAX_FILES_PER_RUN` | ๅ•ๆฌกๅฎกๆŸฅๆœ€ๅคงๆ–‡ไปถๆ•ฐ | `200` | | `REVIEW_AUTO_PUBLISH_MIN_CONFIDENCE` | ่‡ชๅŠจๅ‘ๅธƒๆœ€ๅฐ็ฝฎไฟกๅบฆ | `0.8` | | `REVIEW_ENABLE_HUMAN_GATE` | ๅฏ็”จไบบๅทฅๅฎกๆ‰น | `true` | - ### ่ฎฐๅฟ†ไธŽๅญฆไน ๏ผˆๅฎž้ชŒๆ€ง๏ผ‰ | ๅ˜้‡ | ๆ่ฟฐ | ้ป˜่ฎคๅ€ผ | @@ -185,7 +186,6 @@ Kubernetes ้ƒจ็ฝฒๆธ…ๅ•ไฝไบŽ `k8s/` ็›ฎๅฝ•ใ€‚ ```bash echo -n "your_gitea_token" | base64 -echo -n "your_openai_key" | base64 echo -n "your_webhook_secret" | base64 echo -n "your_admin_password" | base64 ``` @@ -195,8 +195,9 @@ echo -n "your_admin_password" | base64 ็ผ–่พ‘ `k8s/gitea-assistant.yaml` ไธญ็š„ ConfigMap๏ผš - ๅฐ† `GITEA_API_URL` ่ฎพ็ฝฎไธบไฝ ็š„ Gitea ๅฎžไพ‹ API ๅœฐๅ€ -- ๆ นๆฎ้œ€่ฆ่ฐƒๆ•ดๆจกๅž‹ๅ’ŒๅฎกๆŸฅๅผ•ๆ“Ž้…็ฝฎ +- ๆ นๆฎ้œ€่ฆ่ฐƒๆ•ดๅฎกๆŸฅๅผ•ๆ“Ž้…็ฝฎ +> **ๆณจๆ„**: LLM ๆไพ›ๅ•†้…็ฝฎ้€š่ฟ‡้ƒจ็ฝฒๅŽ็š„็ฎก็†ๅŽๅฐ่ฟ›่กŒใ€‚่ฏท็กฎไฟไธบ `/app/data` ็›ฎๅฝ•้…็ฝฎๆŒไน…ๅŒ–ๅญ˜ๅ‚จ๏ผŒไปฅไฟ็•™ LLM ่ฎพ็ฝฎๅ’ŒๅŠ ๅฏ†็š„ API ๅฏ†้’ฅใ€‚ **3. ้ƒจ็ฝฒ** ```bash