code-review-agent/cloud.md

План создания 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

- 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

- 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

- 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

- 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:

{
  "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

События:

{
  "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):

# 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):

VITE_API_URL=http://localhost:8000
VITE_WS_URL=ws://localhost:8000

9. Развертывание

Требования:

• Python 3.11+
• Node.js 18+
• Ollama установлен и запущен

Запуск Backend:

cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload

Запуск Frontend:

cd frontend
npm install
npm run dev

Настройка Ollama:

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
• Модульная архитектура для легкого добавления новых платформ