366 lines
11 KiB
Markdown
366 lines
11 KiB
Markdown
# План создания AI агента-ревьювера
|
||
|
||
## Обзор проекта
|
||
|
||
AI агент-ревьювер для автоматического анализа Pull Request с поддержкой Gitea, GitHub и Bitbucket. Работает на LangChain/LangGraph с Ollama.
|
||
|
||
## Архитектура
|
||
|
||
```
|
||
platform/review/
|
||
├── backend/
|
||
│ ├── app/
|
||
│ │ ├── __init__.py
|
||
│ │ ├── main.py # FastAPI приложение
|
||
│ │ ├── config.py # Конфигурация
|
||
│ │ ├── database.py # Database setup
|
||
│ │ ├── models/ # SQLAlchemy модели
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── repository.py
|
||
│ │ │ ├── pull_request.py
|
||
│ │ │ ├── review.py
|
||
│ │ │ └── comment.py
|
||
│ │ ├── schemas/ # Pydantic схемы
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── repository.py
|
||
│ │ │ ├── review.py
|
||
│ │ │ └── webhook.py
|
||
│ │ ├── agents/ # LangGraph агенты
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── reviewer.py # Основной агент-ревьювер
|
||
│ │ │ ├── tools.py # Инструменты агента
|
||
│ │ │ └── prompts.py # Промпты для агента
|
||
│ │ ├── services/ # Сервисы интеграций
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── base.py # Базовый класс
|
||
│ │ │ ├── gitea.py # Gitea API
|
||
│ │ │ ├── github.py # GitHub API
|
||
│ │ │ └── bitbucket.py # Bitbucket API
|
||
│ │ ├── webhooks/ # Webhook обработчики
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── gitea.py
|
||
│ │ │ ├── github.py
|
||
│ │ │ └── bitbucket.py
|
||
│ │ └── api/ # API endpoints
|
||
│ │ ├── __init__.py
|
||
│ │ ├── repositories.py
|
||
│ │ ├── reviews.py
|
||
│ │ └── webhooks.py
|
||
│ ├── requirements.txt
|
||
│ └── .env.example
|
||
├── frontend/
|
||
│ ├── src/
|
||
│ │ ├── App.tsx
|
||
│ │ ├── main.tsx
|
||
│ │ ├── api/
|
||
│ │ │ ├── client.ts
|
||
│ │ │ └── websocket.ts
|
||
│ │ ├── components/
|
||
│ │ │ ├── RepositoryForm.tsx
|
||
│ │ │ ├── RepositoryList.tsx
|
||
│ │ │ ├── ReviewProgress.tsx
|
||
│ │ │ ├── ReviewList.tsx
|
||
│ │ │ ├── CommentsList.tsx
|
||
│ │ │ └── WebSocketStatus.tsx
|
||
│ │ ├── pages/
|
||
│ │ │ ├── Dashboard.tsx
|
||
│ │ │ ├── Repositories.tsx
|
||
│ │ │ ├── Reviews.tsx
|
||
│ │ │ └── ReviewDetail.tsx
|
||
│ │ └── types/
|
||
│ │ └── index.ts
|
||
│ ├── package.json
|
||
│ ├── vite.config.ts
|
||
│ ├── tsconfig.json
|
||
│ └── index.html
|
||
├── cloud.md # Этот файл
|
||
└── README.md
|
||
```
|
||
|
||
## Технологический стек
|
||
|
||
### Backend
|
||
- **FastAPI** - веб-фреймворк
|
||
- **LangChain/LangGraph** - фреймворк для AI агента
|
||
- **Ollama** - локальная LLM (модель codellama)
|
||
- **SQLAlchemy** - ORM
|
||
- **SQLite** - база данных
|
||
- **WebSockets** - real-time обновления
|
||
- **httpx** - HTTP клиент для API запросов
|
||
|
||
### Frontend
|
||
- **React 18** - UI библиотека
|
||
- **TypeScript** - типизация
|
||
- **Vite** - сборщик
|
||
- **TanStack Query** - управление состоянием сервера
|
||
- **WebSocket API** - real-time обновления
|
||
- **Tailwind CSS** - стилизация
|
||
|
||
## Детальный план реализации
|
||
|
||
### 1. Backend: Модели данных (SQLAlchemy)
|
||
|
||
**Repository**
|
||
```python
|
||
- id: int (PK)
|
||
- name: str
|
||
- platform: enum (gitea, github, bitbucket)
|
||
- url: str
|
||
- api_token: str (encrypted)
|
||
- webhook_secret: str
|
||
- config: JSON (настройки ревью)
|
||
- is_active: bool
|
||
- created_at: datetime
|
||
```
|
||
|
||
**PullRequest**
|
||
```python
|
||
- id: int (PK)
|
||
- repository_id: int (FK)
|
||
- pr_number: int
|
||
- title: str
|
||
- author: str
|
||
- source_branch: str
|
||
- target_branch: str
|
||
- status: enum (open, reviewing, reviewed, closed)
|
||
- url: str
|
||
- created_at: datetime
|
||
- updated_at: datetime
|
||
```
|
||
|
||
**Review**
|
||
```python
|
||
- id: int (PK)
|
||
- pull_request_id: int (FK)
|
||
- status: enum (pending, analyzing, commenting, completed, failed)
|
||
- started_at: datetime
|
||
- completed_at: datetime
|
||
- files_analyzed: int
|
||
- comments_generated: int
|
||
- error_message: str (nullable)
|
||
```
|
||
|
||
**Comment**
|
||
```python
|
||
- id: int (PK)
|
||
- review_id: int (FK)
|
||
- file_path: str
|
||
- line_number: int
|
||
- content: str
|
||
- severity: enum (info, warning, error)
|
||
- posted: bool
|
||
- posted_at: datetime (nullable)
|
||
```
|
||
|
||
### 2. LangGraph агент-ревьювер
|
||
|
||
**Граф состояний:**
|
||
```
|
||
START → fetch_pr_info → fetch_changed_files → analyze_files → generate_comments → post_comments → END
|
||
↓
|
||
(параллельный анализ файлов)
|
||
```
|
||
|
||
**Узлы графа:**
|
||
1. **fetch_pr_info** - получение информации о PR
|
||
2. **fetch_changed_files** - получение списка измененных файлов
|
||
3. **analyze_files** - анализ каждого файла через Ollama
|
||
4. **generate_comments** - генерация комментариев
|
||
5. **post_comments** - отправка комментариев в PR
|
||
|
||
**Промпты для Ollama:**
|
||
```
|
||
Системный промпт: "Ты опытный code reviewer. Анализируй код на:
|
||
- Потенциальные баги
|
||
- Проблемы безопасности
|
||
- Нарушения best practices
|
||
- Проблемы производительности
|
||
- Читаемость кода"
|
||
```
|
||
|
||
### 3. API интеграции (приоритет - Gitea)
|
||
|
||
**Gitea API endpoints:**
|
||
- `GET /repos/{owner}/{repo}/pulls/{index}` - информация о PR
|
||
- `GET /repos/{owner}/{repo}/pulls/{index}/files` - измененные файлы
|
||
- `GET /repos/{owner}/{repo}/pulls/{index}/commits` - коммиты
|
||
- `POST /repos/{owner}/{repo}/pulls/{index}/reviews` - создание ревью
|
||
- `POST /repos/{owner}/{repo}/pulls/comments` - добавление комментария
|
||
|
||
**GitHub API** - аналогичные endpoints через REST API v3
|
||
**Bitbucket API** - через REST API 2.0
|
||
|
||
### 4. Webhook обработчики
|
||
|
||
**Gitea webhook payload:**
|
||
```json
|
||
{
|
||
"action": "opened" | "synchronized",
|
||
"pull_request": {
|
||
"id": 123,
|
||
"number": 42,
|
||
"title": "Fix bug",
|
||
...
|
||
}
|
||
}
|
||
```
|
||
|
||
**Обработка:**
|
||
1. Валидация webhook secret
|
||
2. Проверка, что репозиторий отслеживается
|
||
3. Запуск LangGraph агента асинхронно
|
||
4. Отправка WebSocket уведомлений
|
||
|
||
### 5. REST API endpoints
|
||
|
||
**Repositories:**
|
||
- `GET /api/repositories` - список репозиториев
|
||
- `POST /api/repositories` - добавить репозиторий
|
||
- `PUT /api/repositories/{id}` - обновить репозиторий
|
||
- `DELETE /api/repositories/{id}` - удалить репозиторий
|
||
- `GET /api/repositories/{id}/webhook-url` - получить webhook URL
|
||
|
||
**Reviews:**
|
||
- `GET /api/reviews` - список ревью (с фильтрами)
|
||
- `GET /api/reviews/{id}` - детали ревью
|
||
- `GET /api/reviews/{id}/comments` - комментарии ревью
|
||
- `POST /api/reviews/{id}/retry` - повторить ревью
|
||
|
||
**Stats:**
|
||
- `GET /api/stats/dashboard` - статистика для дашборда
|
||
|
||
### 6. WebSocket
|
||
|
||
**Endpoint:** `ws://localhost:8000/ws/reviews`
|
||
|
||
**События:**
|
||
```json
|
||
{
|
||
"type": "review_started",
|
||
"review_id": 123,
|
||
"pr_id": 42
|
||
}
|
||
|
||
{
|
||
"type": "review_progress",
|
||
"review_id": 123,
|
||
"status": "analyzing",
|
||
"files_processed": 3,
|
||
"total_files": 10
|
||
}
|
||
|
||
{
|
||
"type": "review_completed",
|
||
"review_id": 123,
|
||
"comments_count": 5
|
||
}
|
||
```
|
||
|
||
### 7. Frontend: Страницы
|
||
|
||
**Dashboard** (`/`)
|
||
- Статистика: всего ревью, активных PR, комментариев
|
||
- График активности
|
||
- Последние ревью
|
||
|
||
**Repositories** (`/repositories`)
|
||
- Таблица репозиториев
|
||
- Кнопка "Add Repository"
|
||
- Webhook URL для каждого
|
||
- Статус (active/inactive)
|
||
|
||
**Reviews** (`/reviews`)
|
||
- Таблица всех ревью
|
||
- Фильтры: по репозиторию, статусу, дате
|
||
- Ссылки на детали
|
||
|
||
**Review Detail** (`/reviews/:id`)
|
||
- Информация о PR
|
||
- Прогресс бар
|
||
- Список сгенерированных комментариев
|
||
- Real-time обновления
|
||
|
||
### 8. Конфигурация
|
||
|
||
**Backend (.env):**
|
||
```env
|
||
# Ollama
|
||
OLLAMA_BASE_URL=http://localhost:11434
|
||
OLLAMA_MODEL=codellama
|
||
|
||
# Database
|
||
DATABASE_URL=sqlite:///./review.db
|
||
|
||
# Security
|
||
SECRET_KEY=your-secret-key-here
|
||
WEBHOOK_SECRET=your-webhook-secret
|
||
|
||
# Server
|
||
HOST=0.0.0.0
|
||
PORT=8000
|
||
```
|
||
|
||
**Frontend (.env):**
|
||
```env
|
||
VITE_API_URL=http://localhost:8000
|
||
VITE_WS_URL=ws://localhost:8000
|
||
```
|
||
|
||
### 9. Развертывание
|
||
|
||
**Требования:**
|
||
- Python 3.11+
|
||
- Node.js 18+
|
||
- Ollama установлен и запущен
|
||
|
||
**Запуск Backend:**
|
||
```bash
|
||
cd backend
|
||
pip install -r requirements.txt
|
||
uvicorn app.main:app --reload
|
||
```
|
||
|
||
**Запуск Frontend:**
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
**Настройка Ollama:**
|
||
```bash
|
||
ollama pull codellama
|
||
ollama serve
|
||
```
|
||
|
||
### 10. Безопасность
|
||
|
||
- API токены храним зашифрованными (Fernet)
|
||
- Webhook secret для валидации запросов
|
||
- CORS настроен только для frontend домена
|
||
- Rate limiting на webhook endpoints
|
||
- Валидация всех входных данных
|
||
|
||
## Этапы разработки
|
||
|
||
1. ✅ Создание структуры проекта
|
||
2. ⏳ Backend: Модели и база данных
|
||
3. ⏳ Backend: LangGraph агент
|
||
4. ⏳ Backend: Интеграции с Git платформами
|
||
5. ⏳ Backend: Webhook обработчики
|
||
6. ⏳ Backend: REST API
|
||
7. ⏳ Backend: WebSocket
|
||
8. ⏳ Frontend: Базовая структура
|
||
9. ⏳ Frontend: Компоненты и страницы
|
||
10. ⏳ Frontend: Интеграция с Backend
|
||
11. ⏳ Тестирование
|
||
12. ⏳ Документация
|
||
|
||
## Примечания
|
||
|
||
- Gitea имеет приоритет в разработке
|
||
- Агент работает в одном экземпляре (можно масштабировать через очереди позже)
|
||
- Real-time обновления через WebSocket для UX
|
||
- Модульная архитектура для легкого добавления новых платформ
|
||
|