Initial commit: VoIdeaAI - voice-first AI idea assistant
This commit is contained in:
@@ -0,0 +1,397 @@
|
||||
# ADR-002: Архитектура системных агентов
|
||||
|
||||
**Статус:** принято
|
||||
**Дата:** 2026-05-10
|
||||
|
||||
---
|
||||
|
||||
## Контекст
|
||||
|
||||
Проект VoIdea требует автоматизации через AI-агентов. Необходимо определить:
|
||||
- Количество агентов
|
||||
- Их обязанности
|
||||
- Взаимодействие между агентами
|
||||
- Стек реализации
|
||||
|
||||
Рассматривались:
|
||||
- **Один суперагент** — всё в одном, сложно масштабировать
|
||||
- **Ручное управление** — человек выполняет всё
|
||||
- **11 отдельных агентов** — модульность, специализация
|
||||
|
||||
---
|
||||
|
||||
## Решение
|
||||
|
||||
**11 системных агентов**, каждый со своей ответственностью.
|
||||
|
||||
### Список агентов
|
||||
|
||||
| Агент | Ответственность | Триггеры |
|
||||
|-------|-----------------|----------|
|
||||
| DocAgent | Документация, комментарии | pre-commit, push, manual |
|
||||
| AuditAgent | Соблюдение правил, прогресс | pre-commit, daily, manual |
|
||||
| SecurityAgent | Безопасность, уязвимости | pre-commit, weekly, manual |
|
||||
| SpecAgent | Спецификации, версионирование | tag creation, push |
|
||||
| ObserverAgent | Наблюдение за пользователями | continuous, daily report |
|
||||
| QATesterAgent | Функциональное тестирование | pre-commit, daily, manual |
|
||||
| FixAgent | Исправление багов | QATesterAgent results |
|
||||
| UITestAgent | Визуальное тестирование | weekly, manual |
|
||||
| RolloutAgent | Постепенное развёртывание | after tests, manual |
|
||||
| EvolutionAgent | Саморазвитие агентов | daily, learning |
|
||||
| BacklogAgent | Управление задачами | continuous |
|
||||
|
||||
---
|
||||
|
||||
## Архитектура
|
||||
|
||||
### Структура файлов
|
||||
|
||||
```
|
||||
app/agents/
|
||||
├── __init__.py # Публичный API
|
||||
├── base.py # Базовый класс Agent
|
||||
├── doc_agent.py # DocAgent
|
||||
├── audit_agent.py # AuditAgent
|
||||
├── security_agent.py # SecurityAgent
|
||||
├── spec_agent.py # SpecAgent
|
||||
├── observer_agent.py # ObserverAgent
|
||||
├── qa_tester_agent.py # QATesterAgent
|
||||
├── fix_agent.py # FixAgent
|
||||
├── ui_test_agent.py # UITestAgent
|
||||
├── rollout_agent.py # RolloutAgent
|
||||
├── evolution_agent.py # EvolutionAgent
|
||||
└── backlog_agent.py # BacklogAgent
|
||||
```
|
||||
|
||||
### Базовый класс
|
||||
|
||||
```python
|
||||
from abc import ABC, abstractmethod
|
||||
from typing import Any, Optional
|
||||
|
||||
class BaseAgent(ABC):
|
||||
name: str
|
||||
version: str
|
||||
|
||||
@abstractmethod
|
||||
async def run(self, context: dict) -> AgentResult:
|
||||
"""Основной метод выполнения"""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
async def health_check(self) -> bool:
|
||||
"""Проверка работоспособности"""
|
||||
pass
|
||||
|
||||
async def get_status(self) -> AgentStatus:
|
||||
"""Текущий статус агента"""
|
||||
pass
|
||||
|
||||
async def get_metrics(self) -> AgentMetrics:
|
||||
"""Метрики работы агента"""
|
||||
pass
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Меж-агентское взаимодействие
|
||||
|
||||
### Делегирование
|
||||
|
||||
```python
|
||||
class AgentA:
|
||||
async def process(self, task):
|
||||
if task.requires_agent_b:
|
||||
result = await delegate_to(
|
||||
target=AgentB,
|
||||
task=task,
|
||||
timeout=30
|
||||
)
|
||||
# continue processing
|
||||
```
|
||||
|
||||
### Event-driven
|
||||
|
||||
```python
|
||||
class EventBus:
|
||||
async def publish(self, event: AgentEvent):
|
||||
await self._handlers[event.type].handle(event)
|
||||
|
||||
class AgentB:
|
||||
@event_handler(AgentEventTypes.TASK_DELEGATED)
|
||||
async def handle_delegated_task(self, event):
|
||||
# process task
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Описание поведения каждого агента
|
||||
|
||||
### DocAgent
|
||||
|
||||
**Цель:** Поддержание документации в актуальном состоянии.
|
||||
|
||||
**Обязанности:**
|
||||
- Создание README.md для новых модулей
|
||||
- Обновление docs при изменении кода
|
||||
- Генерация docstrings
|
||||
- Ведение Runbook
|
||||
|
||||
**Триггеры:**
|
||||
- Создание нового файла
|
||||
- Изменение существующего > 50 строк
|
||||
- Создание новой папки
|
||||
- Push в main/develop
|
||||
|
||||
**Взаимодействие:**
|
||||
- SpecAgent → обновление спецификаций
|
||||
- AuditAgent → проверка актуальности docs
|
||||
|
||||
---
|
||||
|
||||
### AuditAgent
|
||||
|
||||
**Цель:** Контроль соблюдения правил проекта.
|
||||
|
||||
**Обязанности:**
|
||||
- Проверка code style (ruff)
|
||||
- Проверка типизации (mypy)
|
||||
- Контроль прогресса по плану
|
||||
- Фиксация отклонений
|
||||
|
||||
**Триггеры:**
|
||||
- pre-commit hook
|
||||
- Ежедневно 09:00
|
||||
- По запросу администратора
|
||||
|
||||
**Взаимодействие:**
|
||||
- SecurityAgent → проверка безопасности
|
||||
- DocAgent → обновление отчётов
|
||||
|
||||
---
|
||||
|
||||
### SecurityAgent
|
||||
|
||||
**Цель:** Обеспечение безопасности проекта.
|
||||
|
||||
**Обязанности:**
|
||||
- Сканирование уязвимостей
|
||||
- Проверка input валидации
|
||||
- Контроль зависимостей (safety)
|
||||
- Соответствие 152-ФЗ
|
||||
|
||||
**Триггеры:**
|
||||
- pre-commit hook
|
||||
- Еженедельно (полное сканирование)
|
||||
- При добавлении зависимости
|
||||
|
||||
**Взаимодействие:**
|
||||
- FixAgent → исправление уязвимостей
|
||||
- RolloutAgent → блокировка при критических уязвимостях
|
||||
|
||||
---
|
||||
|
||||
### SpecAgent
|
||||
|
||||
**Цель:** Управление спецификациями и версионированием.
|
||||
|
||||
**Обязанности:**
|
||||
- Генерация CHANGELOG
|
||||
- Обновление project.json
|
||||
- Управление ADR
|
||||
- Версионирование кода
|
||||
|
||||
**Триггеры:**
|
||||
- Создание git tag
|
||||
- Push в main
|
||||
- Изменение спецификаций
|
||||
|
||||
**Взаимодействие:**
|
||||
- DocAgent → обновление docs
|
||||
- EvolutionAgent → фиксация изменений
|
||||
|
||||
---
|
||||
|
||||
### ObserverAgent
|
||||
|
||||
**Цель:** Сбор и анализ данных о пользователях.
|
||||
|
||||
**Обязанности:**
|
||||
- Сбор метрик использования
|
||||
- Генерация идей для развития
|
||||
- Выявление паттернов поведения
|
||||
- Отчёты для EvolutionAgent
|
||||
|
||||
**Триггеры:**
|
||||
- Непрерывный сбор данных
|
||||
- Ежедневный отчёт
|
||||
- По запросу EvolutionAgent
|
||||
|
||||
**Метрики (MVP):**
|
||||
- page_views
|
||||
- session_duration
|
||||
- feature_usage_frequency
|
||||
- conversion_rate
|
||||
|
||||
**Взаимодействие:**
|
||||
- EvolutionAgent → данные для анализа
|
||||
- RolloutAgent → метрики для решения
|
||||
|
||||
---
|
||||
|
||||
### QATesterAgent
|
||||
|
||||
**Цель:** Функциональное тестирование.
|
||||
|
||||
**Обязанности:**
|
||||
- Создание временных аккаунтов
|
||||
- Выполнение тестов
|
||||
- Очистка временных данных
|
||||
- Генерация отчётов
|
||||
|
||||
**Триггеры:**
|
||||
- pre-commit hook
|
||||
- Ежедневно в 06:00
|
||||
- Вручную через админ-панель
|
||||
- После FixAgent исправления
|
||||
|
||||
**Взаимодействие:**
|
||||
- FixAgent → исправление найденных багов
|
||||
- UITestAgent → визуальное тестирование
|
||||
- RolloutAgent → результаты для решения
|
||||
|
||||
---
|
||||
|
||||
### FixAgent
|
||||
|
||||
**Цель:** Автоматическое исправление багов.
|
||||
|
||||
**Обязанности:**
|
||||
- Анализ багов из QATesterAgent
|
||||
- Генерация исправлений
|
||||
- Создание PR
|
||||
- Валидация исправлений
|
||||
|
||||
**Триггеры:**
|
||||
- Результаты QATesterAgent
|
||||
- Критические ошибки в логах
|
||||
- По запросу человека
|
||||
|
||||
**Взаимодействие:**
|
||||
- QATesterAgent → повторное тестирование
|
||||
- DocAgent → обновление документации
|
||||
- Git → создание PR
|
||||
|
||||
---
|
||||
|
||||
### UITestAgent
|
||||
|
||||
**Цель:** Визуальное тестирование интерфейса.
|
||||
|
||||
**Обязанности:**
|
||||
- Скриншот-тестирование
|
||||
- Проверка layout
|
||||
- Accessibility testing
|
||||
- Кросс-браузерное тестирование
|
||||
|
||||
**Триггеры:**
|
||||
- Еженедельно
|
||||
- После изменений в UI
|
||||
- Вручную через админ-панель
|
||||
|
||||
**Взаимодействие:**
|
||||
- QATesterAgent → результаты
|
||||
- FixAgent → исправление визуальных багов
|
||||
|
||||
---
|
||||
|
||||
### RolloutAgent
|
||||
|
||||
**Цель:** Управление развёртыванием.
|
||||
|
||||
**Обязанности:**
|
||||
- Контроль этапов rollout (3→1%→5%→15%→100%)
|
||||
- Мониторинг метрик
|
||||
- Принятие решения о переходе
|
||||
- Откат при проблемах
|
||||
|
||||
**Триггеры:**
|
||||
- После успешных тестов
|
||||
- Ежедневный мониторинг
|
||||
- По решению человека
|
||||
|
||||
**Взаимодействие:**
|
||||
- ObserverAgent → метрики
|
||||
- FixAgent → исправление проблем
|
||||
- BacklogAgent → создание задач
|
||||
|
||||
---
|
||||
|
||||
### EvolutionAgent
|
||||
|
||||
**Цель:** Саморазвитие агентов.
|
||||
|
||||
**Обязанности:**
|
||||
- Анализ эффективности агентов
|
||||
- Генерация предложений по улучшению
|
||||
- Обновление capabilities
|
||||
- Обучение на данных
|
||||
|
||||
**Триггеры:**
|
||||
- Ежедневно
|
||||
- При обнаружении новых паттернов
|
||||
- По запросу BacklogAgent
|
||||
|
||||
**Взаимодействие:**
|
||||
- ObserverAgent → данные о пользователях
|
||||
- Все агенты → улучшение работы
|
||||
|
||||
---
|
||||
|
||||
### BacklogAgent
|
||||
|
||||
**Цель:** Управление отложенными задачами.
|
||||
|
||||
**Обязанности:**
|
||||
- Создание задач из предложений
|
||||
- Приоритизация
|
||||
- Отслеживание статуса
|
||||
- Напоминания
|
||||
|
||||
**Триггеры:**
|
||||
- Непрерывный мониторинг
|
||||
- По предложению других агентов
|
||||
- Вручную через админ-панель
|
||||
|
||||
**Взаимодействие:**
|
||||
- Все агенты → создание задач
|
||||
- RolloutAgent → задачи для реализации
|
||||
|
||||
---
|
||||
|
||||
## Последствия
|
||||
|
||||
### Положительные
|
||||
|
||||
- Модульность — легко добавлять новых агентов
|
||||
- Специализация — каждый делает своё
|
||||
- Тестируемость — можно тестировать отдельно
|
||||
- Масштабируемость — агенты работают параллельно
|
||||
|
||||
### Отрицательные
|
||||
|
||||
- Сложность координации
|
||||
- Возможные конфликты агентов
|
||||
- Overhead на коммуникацию
|
||||
|
||||
---
|
||||
|
||||
## Ответственный
|
||||
|
||||
**Decision maker:** Owner
|
||||
**Review date:** При добавлении новых агентов
|
||||
|
||||
---
|
||||
|
||||
*Создано: 2026-05-10*
|
||||
*Обновлено при изменениях EvolutionAgent*
|
||||
Reference in New Issue
Block a user