mirror of
https://github.com/jeffusion/gitea-ai-assistant.git
synced 2026-03-27 10:05:50 +00:00
docs: rewrite README following open source standards with i18n
- Create English README.md as primary documentation - Create Chinese docs/README.zh-CN.md with language link - Focus on core functionality: features, quick start, configuration, deployment - Remove CI badge, GitHub Actions, Contributing, Acknowledgments sections - Remove verbose API Reference and Development sections - Condense configuration examples for clarity - Delete obsolete docs/ADMIN_UI_DESIGN.md
This commit is contained in:
jeffusion
@@ -1,93 +0,0 @@
|
||||
# Gitea AI Assistant 后台管理页面设计方案
|
||||
|
||||
## 1. 总体目标
|
||||
|
||||
构建一个简单、安全的后台管理界面，允许管理员浏览 Gitea 上的代码仓库，并为选定的仓库一键“开启”或“关闭” AI 代码审查的 Webhook。此功能旨在替代当前繁琐的手动配置过程，简化新项目的接入流程。
|
||||
|
||||
## 2. 技术选型
|
||||
|
||||
- **后端增强**: 继续使用 **Hono** 框架，在现有应用中开辟一组新的 API 路由。
|
||||
- **前端框架**: **React (Vite + TypeScript)**，用于快速构建现代化交互界面。
|
||||
- **UI 组件库**: **shadcn/ui** 配合 **Tailwind CSS**，以实现专业且美观的界面。
|
||||
- **状态管理**: **React Query (TanStack Query)**，用于高效管理服务器状态和数据缓存。
|
||||
- **认证机制**: **JSON Web Tokens (JWT)**，实现安全无状态的登录认证。
|
||||
|
||||
## 3. 架构设计
|
||||
|
||||
采用前后端分离的架构。
|
||||
|
||||
- **后端 (Backend)**:
|
||||
- 在 Hono 应用中新增路由组 `/admin/api`，提供 RESTful API。
|
||||
- 通过一个新的管理员级别 Gitea Token 与 Gitea API 交互，该 Token 需具备读写仓库和 Webhook 的权限。
|
||||
- 所有 `/admin/api` 路由都将受到 JWT 中间件的保护。
|
||||
|
||||
- **前端 (Frontend)**:
|
||||
- 在项目根目录创建新的 `frontend` 文件夹，存放所有前端代码。
|
||||
- 前端为单页面应用 (SPA)，负责登录、展示仓库列表和提供 Webhook 管理操作。
|
||||
|
||||
- **部署 (Deployment)**:
|
||||
- 采用多阶段 `Dockerfile` 进行构建。
|
||||
- 第一阶段构建前端静态文件。
|
||||
- 第二阶段构建后端服务。
|
||||
- 最终镜像将前端静态文件集成到后端服务中，由 Hono 统一提供服务，实现单容器部署。
|
||||
- 相应更新 `kubernetes.yaml.template` 文件。
|
||||
|
||||
## 4. 核心功能模块设计
|
||||
|
||||
### A. 认证流程
|
||||
|
||||
1. **访问**: 用户访问管理页面，若无本地有效 JWT，则跳转至登录页。
|
||||
2. **登录**: 用户输入在环境变量中配置的 `ADMIN_PASSWORD`。
|
||||
3. **验证**: 前端调用 `POST /admin/api/login`，后端验证密码。
|
||||
4. **Token 生成**: 验证成功后，后端使用 `JWT_SECRET` 生成一个有时效性的 JWT 并返回给前端。
|
||||
5. **存储**: 前端将 JWT 存储在 `localStorage` 中。
|
||||
6. **请求**: 后续所有对 `/admin/api` 的请求均在 `Authorization` 请求头中携带 `Bearer <token>`。
|
||||
|
||||
### B. 后端 API 设计 (`/admin/api`)
|
||||
|
||||
- **`POST /admin/api/login`** (公开)
|
||||
- **功能**: 用户登录。
|
||||
- **请求体**: `{ password: "..." }`
|
||||
- **响应**: `{ token: "jwt_token" }` 或认证失败错误。
|
||||
|
||||
- **`GET /admin/api/repositories`** (需认证)
|
||||
- **功能**: 获取 Gitea 实例上管理员可见的所有仓库列表，并附带其 Webhook 状态。
|
||||
- **逻辑**: 调用 Gitea API 获取仓库列表，并对每个仓库检查是否存在由本应用创建的 Webhook。
|
||||
- **返回**: `[{ name: "owner/repo", webhook_status: "active" | "inactive" }]`
|
||||
|
||||
- **`POST /admin/api/repositories/{owner}/{repo}/webhook`** (需认证)
|
||||
- **功能**: 为指定仓库创建 AI Review 的 Webhook。
|
||||
- **逻辑**: 调用 Gitea API 创建 Webhook，目标 URL 指向本服务的 `/api/webhook`。
|
||||
- **返回**: `{ success: true }`
|
||||
|
||||
- **`DELETE /admin/api/repositories/{owner}/{repo}/webhook`** (需认证)
|
||||
- **功能**: 删除为 AI Review 创建的 Webhook。
|
||||
- **逻辑**: 调用 Gitea API 查找并删除与本服务相关的 Webhook。
|
||||
- **返回**: `{ success: true }`
|
||||
|
||||
### C. 前端页面设计
|
||||
|
||||
- **登录页**: 一个居中的表单，包含密码输入框和“登录”按钮。
|
||||
- **管理主页 (Dashboard)**:
|
||||
- 顶部标题和刷新按钮。
|
||||
- 仓库列表，支持按名称搜索/筛选。
|
||||
- 列表项包括：
|
||||
- 仓库名称 (`owner/repo`)。
|
||||
- Webhook 状态标识 (例如，彩色的图标和文字)。
|
||||
- 操作按钮 (例如，“启用”或“停用”)。
|
||||
|
||||
## 5. 环境变量配置
|
||||
|
||||
需要新增以下环境变量：
|
||||
|
||||
- `ADMIN_PASSWORD`: 后台管理页面的登录密码。
|
||||
- `JWT_SECRET`: 用于签发和验证 JWT 的密钥。
|
||||
- `GITEA_ADMIN_TOKEN`: 一个拥有 Gitea 管理权限的 Token，用于 API 调用。
|
||||
|
||||
## 6. 实施步骤规划
|
||||
|
||||
1. **项目初始化**: 创建 `frontend` 目录并初始化 Vite (React+TS) 项目，配置 UI 库。
|
||||
2. **后端开发**: 实现 `/admin/api` 路由组，包括登录、JWT 中间件和 Webhook 管理逻辑。
|
||||
3. **前端开发**: 创建登录页和管理主页，实现与后端 API 的交互。
|
||||
4. **容器化**: 更新 `Dockerfile` 为多阶段构建，并调整 `kubernetes.yaml.template`。
|
||||
5. **文档更新**: 在 `README.md` 中说明新功能的使用和配置方法。
|
||||
180
docs/README.zh-CN.md
Normal file
180
docs/README.zh-CN.md
Normal file
@@ -0,0 +1,180 @@
|
||||
# Gitea AI Assistant
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
|
||||
基于 AI 的 Gitea 代码审查助手。自动审查 Pull Request 和提交，使用 OpenAI 提供智能代码质量分析，支持总体评论和行级反馈。
|
||||
|
||||
**[English Documentation](../README.md)**
|
||||
|
||||
## 功能特点
|
||||
|
||||
- 🤖 **AI 代码审查** - 使用 OpenAI 模型自动审查 PR 和提交
|
||||
- 📝 **行级评论** - 针对具体代码变更的精确反馈
|
||||
- 🔄 **双引擎模式** - Legacy（简单）或 Agent（多代理）审查模式
|
||||
- 🔔 **飞书通知** - PR 事件通知集成
|
||||
- 🎛️ **管理后台** - 用于管理仓库 Webhook 和配置的 Web 界面
|
||||
- 🔐 **安全验证** - HMAC-SHA256 签名验证
|
||||
|
||||
## 架构设计
|
||||
|
||||
```
|
||||
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
||||
│ Gitea 服务器 │────▶│ Gitea Assistant │────▶│ OpenAI API │
|
||||
│ (Webhooks) │ │ (Hono + Bun) │ │ │
|
||||
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────┐
|
||||
│ 管理后台 │
|
||||
│ (React SPA) │
|
||||
└──────────────────┘
|
||||
```
|
||||
|
||||
### 审查引擎对比
|
||||
|
||||
| 引擎 | 描述 | 适用场景 |
|
||||
|------|------|----------|
|
||||
| `legacy` | 单次 AI 审查，生成总结和行级评论 | 简单、快速的审查 |
|
||||
| `agent` | 多代理编排，支持专家、反思和辩论 | 深度、全面的分析 |
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 环境要求
|
||||
|
||||
- [Bun](https://bun.sh/) >= 1.2.5
|
||||
- 可访问的 Gitea 实例
|
||||
- OpenAI API 密钥
|
||||
|
||||
### 安装步骤
|
||||
|
||||
```bash
|
||||
git clone https://github.com/user/gitea-ai-assistant.git
|
||||
cd gitea-ai-assistant
|
||||
bun install
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
### 配置说明
|
||||
|
||||
编辑 `.env` 文件：
|
||||
|
||||
```bash
|
||||
# Gitea
|
||||
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
|
||||
|
||||
# 管理后台
|
||||
ADMIN_PASSWORD=your_admin_password
|
||||
```
|
||||
|
||||
完整配置项请参阅 [配置参考](#配置参考)。
|
||||
|
||||
### 启动服务
|
||||
|
||||
```bash
|
||||
bun run dev # 开发模式
|
||||
bun run start # 生产模式
|
||||
```
|
||||
|
||||
### 配置 Webhook
|
||||
|
||||
**方式一：管理后台（推荐）**
|
||||
|
||||
1. 在浏览器中访问 `http://your-server:3000`
|
||||
2. 使用 `ADMIN_PASSWORD` 登录
|
||||
3. 点击仓库对应的「启用」按钮自动配置 Webhook
|
||||
|
||||
**方式二：手动配置**
|
||||
|
||||
在 Gitea 仓库设置中添加 Webhook：
|
||||
- **URL**: `http://your-server:3000/webhook/gitea`
|
||||
- **内容类型**: `application/json`
|
||||
- **密钥**: 与 `WEBHOOK_SECRET` 相同
|
||||
- **触发事件**: 「Pull Request」和「Status」
|
||||
|
||||
## 配置参考
|
||||
|
||||
### 核心配置
|
||||
|
||||
| 变量 | 描述 | 默认值 |
|
||||
|------|------|--------|
|
||||
| `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 签名验证密钥 | 必填 |
|
||||
|
||||
### 自定义提示词
|
||||
|
||||
| 变量 | 描述 |
|
||||
|------|------|
|
||||
| `CUSTOM_SUMMARY_PROMPT` | 自定义总结审查提示词 |
|
||||
| `CUSTOM_LINE_COMMENT_PROMPT` | 自定义行级评论提示词 |
|
||||
|
||||
### 管理后台
|
||||
|
||||
| 变量 | 描述 | 默认值 |
|
||||
|------|------|--------|
|
||||
| `ADMIN_PASSWORD` | 后台登录密码 | `password` |
|
||||
| `JWT_SECRET` | JWT 签名密钥 | 自动生成 |
|
||||
|
||||
### 飞书集成
|
||||
|
||||
| 变量 | 描述 |
|
||||
|------|------|
|
||||
| `FEISHU_WEBHOOK_URL` | 飞书机器人 Webhook 地址 |
|
||||
| `FEISHU_WEBHOOK_SECRET` | 飞书 Webhook 密钥（可选） |
|
||||
|
||||
### Agent 审查引擎
|
||||
|
||||
设置 `REVIEW_ENGINE=agent` 启用多代理审查：
|
||||
|
||||
| 变量 | 描述 | 默认值 |
|
||||
|------|------|--------|
|
||||
| `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` |
|
||||
|
||||
### 记忆与学习（实验性）
|
||||
|
||||
| 变量 | 描述 | 默认值 |
|
||||
|------|------|--------|
|
||||
| `QDRANT_URL` | Qdrant 向量数据库地址 | - |
|
||||
| `ENABLE_MEMORY` | 启用记忆系统 | `false` |
|
||||
| `ENABLE_REFLECTION` | 启用自我批评 | `false` |
|
||||
| `ENABLE_DEBATE` | 启用多代理辩论 | `false` |
|
||||
|
||||
## 部署指南
|
||||
|
||||
### Docker
|
||||
|
||||
```bash
|
||||
docker build -t gitea-assistant .
|
||||
docker run -d -p 3000:3000 --env-file .env gitea-assistant
|
||||
```
|
||||
|
||||
### Docker Compose
|
||||
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
## 许可证
|
||||
|
||||
MIT 许可证
|
||||
Reference in New Issue
Block a user