BugPilot

AI-агент для анализа дефектов в инженерии на основе ИИ

Основная архитектура: BugPilot работает на чистом, сквозном декомпозированном конвейере: React / Vite → FastAPI Backend → ReAct Orchestrator → Специализированные агенты → MCP Client → MCP Server → 10 инструментов только для чтения → SQLite база данных (синтетические данные Jira).

1. Архитектура системы

┌─────────────────────────────────────────────────────────────────────────────┐
│                       React / Vite Frontend (TypeScript)                     │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                        │ HTTP REST API (JWT + RBAC + Tenant Isolation)
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                          FastAPI Backend (Port 8000)                         │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                        ReAct Orchestrator Agent                              │
│         Dynamic reasoning loop: Goal → LLM Decision → Tool Call →            │
│                    Observation → Next Decision → FINISH                     │
│               [Groq Primary API + Local Ollama Fallback]                    │
└───────────┬──────────────────────────┼──────────────────────────┬───────────┘
            │                          │                          │
            ▼                          ▼                          ▼
┌──────────────────────┐   ┌──────────────────────┐   ┌──────────────────────┐
│  Bug Analyst Agent   │   │ Trend Analyst Agent  │   │ Risk Analyst Agent   │
└───────────┬──────────┘   └──────────┬───────────┘   └──────────┬───────────┘
            │                          │                          │
            └──────────────────────────┼──────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                                 MCP Client                                   │
│                 Dynamic tool discovery, timeout & sandboxing                 │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                        │ stdio JSON-RPC Transport
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                          MCP Server (mcp_server)                            │
│                  Exposes 10 Strict READ-ONLY Tools                          │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              AnalyticsService                                │
│              Deterministic metric calculation & statistical trends          │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                 DataProvider Interface (SQLDataProvider / SQLite)            │
│                 Multi-tenant tenant isolation (`organization_id`)           │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                    SQLite Database (`sqlite:///./bugpilot.db`)              │
│       Realistic Jira-style Defect Catalog, Sprints, Users & Audit Trails    │
└─────────────────────────────────────────────────────────────────────────────┘

Строгий контракт доступа к данным

✅ Agent → MCP Client → MCP Server → AnalyticsService → DataProvider → SQLite Data
❌ Agent → Direct Database Access (FORBIDDEN)
❌ Agent → Direct Data File Reading (FORBIDDEN)
❌ External Vector Database / RAG dependencies (FORBIDDEN)

Агенты взаимодействуют исключительно через динамически обнаруживаемые MCP-инструменты, что обеспечивает изоляцию и полную тестируемость.

Related MCP server: mcp-sqlite-manager

2. Справочник по 10 MCP-инструментам

Все 10 инструментов являются строго только для чтения, ограничены по арендатору (org_id) и динамически обнаруживаются через протокол MCP:

3. Динамическая оркестрация ReAct и сравнительный анализ

Агент-оркестратор работает на основе подлинного цикла Рассуждение + Действие (ReAct):

1. Намерение и защита от выхода за пределы домена — Ранние проверки отфильтровывают неинженерные запросы без лишних затрат LLM/инструментов.

2. Динамический выбор инструментов — LLM решает каждое действие (CALL_TOOL, DELEGATE или FINISH) на основе запроса, динамически обнаруженных инструментов и накопленных наблюдений.

3. Итеративная проверка нескольких кандидатов — Для сравнительных запросов и запросов ранжирования ("проанализируйте дефекты аутентификации и определите задачу с самым высоким риском") search_bugs находит кандидатов, а Оркестратор итеративно вызывает get_bug для каждого кандидата-дефекта, прежде чем разрешить FINISH, обеспечивая сбор полных технических данных (первопричина, радиус поражения, шаги воспроизведения).

4. Дифференцированная оценка риска на основе данных — Оценивает серьезность, приоритет, статус, производственную среду, влияние на безопасность (например, SOC2/угон сессии) и технические первопричины (например, состояние гонки, сбой). Генерирует ненасыщаемые оценки (0.0–99.5), чтобы избежать искусственных совпадений 100/100.

5. Оценка качества агентом рефлексии — Проверяет сгенерированные отчеты на соответствие эталонным данным MCP для предотвращения галлюцинаций и подтверждения точности отчетности.

4. Мультиарендность и безопасность RBAC

• Изоляция арендаторов — Каждая запись в базе данных (issues, sprints, users, audit_logs) строго ограничена organization_id (например, org-acme). Доступ к данным между организациями блокируется на уровне репозитория и MCP.

• Управление доступом на основе ролей (RBAC):

  • Администратор — Полный доступ, управление пользователями и администрирование задач.

  • Инженер / Разработчик — Создание, обновление, переход и анализ задач.

  • Наблюдатель — Доступ только для чтения к задачам, аналитике и отчетам.

• Управление секретами — Никакие секретные ключи или учетные данные не захардкожены. Секреты JWT, ключи API и переменные окружения строго загружаются из .env и исключены из системы контроля версий.

5. Технологический стек

6. Руководство по настройке и запуску

Предварительные требования

• Python 3.12+

• Node.js 18+ (для фронтенда)

• Ключ API Groq (необязательно — приложение работает и без него, переходя на локальный Ollama или детерминированный режим)

1. Настройка бэкенда

# Clone and enter project
git clone <repo-url> bugpilot
cd bugpilot

# Create and activate virtual environment
python -m venv .venv
# Windows: .\.venv\Scripts\activate | macOS/Linux: source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure environment (defaults to SQLite with zero setup)
cp .env.example .env
# Optional: add your GROQ_API_KEY to .env for live LLM responses

2. Запуск автономного MCP-сервера

# Windows
.\.venv\Scripts\python -m mcp_server.server

# macOS / Linux
.venv/bin/python -m mcp_server.server

3. Запуск FastAPI бэкенда

uvicorn backend.main:app --host 127.0.0.1 --port 8000 --reload

База данных создается и заполняется автоматически при первом запуске — шаг миграции не требуется. Проверьте работоспособность по адресам http://127.0.0.1:8000/api/v1/health и http://127.0.0.1:8000/docs.

4. Сборка и запуск фронтенда

cd frontend
npm install
npm run dev

Dev-сервер Vite проксирует запросы /api на бэкенд FastAPI на порту 8000 (см. vite.config.ts), поэтому оба сервиса должны работать одновременно.

5. Запуск набора тестов

# Run all unit and integration tests (329 tests)
pytest tests/unit tests/integration -q

Вызовы LLM имитируются во время тестов (см. tests/conftest.py), поэтому набор выполняется детерминированно без подключения к Groq/Ollama. Поскольку несколько тестов запускают новый подпроцесс MCP-сервера, полный набор выполняется несколько минут — это ожидаемо, а не зависание.

7. Результаты оценки и качества

BugPilot поставляется с автоматизированной средой оценки (evaluation/), которая оценивает агента по золотому набору из 23 запросов по 11 измерениям — точность намерения, выбор инструментов, обоснованность, уровень галлюцинаций, валидность траектории, следование инструкциям, безопасность и задержка — без необходимости ручной оценки. Запустите сами с помощью:

python -m evaluation.run_eval

Последние зафиксированные результаты (evaluation_report.json):

Два непройденных запроса были пограничными случаями маршрутизации намерений (например, запрос классифицирован как COMPONENT_ANALYSIS вместо METRIC), а не галлюцинациями или сбоями — агент ни разу не сфабриковал информацию ни в одном из 23 тестовых случаев.

Тест на параллельность/нагрузку (1–50 одновременных пользователей) также включен через evaluation/load_tester.py. При до 25 одновременных пользователях система удерживает 0% ошибок; при 50 одновременных пользователях уровень ошибок возрастает до ~66%, что указывает на то, что текущая однопроцессная установка еще не настроена для высоконагруженного производственного трафика. См. Известные ограничения ниже.

Примечание о цифрах стоимости/токенов: значения estimated_total_cost_usd и average_tokens_per_query в evaluation_report.json являются оценками на основе подсчета слов, а не реальными данными об использовании API Groq. Относитесь к ним как к приблизительным индикаторам, а не к счетам.

8. Известные ограничения

В интересах прозрачности для рецензентов:

• Потолок параллельности — нагрузочное тестирование показывает резкий рост уровня ошибок при 50 одновременных пользователях (см. выше). Подходит для демо/использования в небольших командах в текущем виде; потребуется пул соединений / асинхронная настройка для более крупного производственного трафика.

• Оценка (не измерение) токенов/стоимости — цифры стоимости в отчете оценки являются эвристическими оценками на основе подсчета слов, а не реальным учетом использования API.

• Небольшой золотой набор для оценки — автоматическая оценка охватывает 23 репрезентативных запроса; более широкое покрытие (больше состязательных/инъекционных случаев, больше пограничных случаев) еще больше укрепило бы доверие.

• generate_pdf.py — это автономная утилита экспорта документации с путем вывода по умолчанию, специфичным для Windows; передайте явный аргумент имени файла в macOS/Linux.

---.