ADR-006: Версионирование агентов

Статус: принято Дата: 2026-05-10

Контекст

11 системных агентов VoIdea самообучаются — их код, промпты и capabilities изменяются автоматически через EvolutionAgent или вручную. Без контроля версий невозможно:

Отследить, когда и какой агент изменился
Понять, какие изменения были внесены
Откатить агента до предыдущей версии при проблемах
Синхронизировать версии агентов между окружениями (local → VPS)

Рассматривались:

Единая версия для всех — не отражает индивидуальных изменений
Только git — не покрывает runtime-эволюцию (изменение промптов без коммита)
A.B.C для каждого агента — точный контроль, авто-детект изменений

Решение

A.B.C (SemVer) для каждого агента, changelog в CHANGELOG/agents/<name>.md.

Правила бампа

Компонент	Когда меняется	Кто меняет
A (major)	Breaking change: сигнатура `run()` или публичные методы	EvolutionAgent (анализ кода)
B (minor)	Новая capability: новый метод, новый prompt, новая роль	EvolutionAgent (добавление capability)
C (patch)	Внутренние правки: багфикс, оптимизация, уточнение промпта	Сам агент (авто-сравнение checksum)

Механика

Каждый Agent.run()
  → compute_checksum() — SHA256 от __file__ агента
  → сравнивает с AgentConfig.checksum в БД
  → не совпал → bump_version("patch") → запись в changelog → обновление БД
  → совпал → ничего

EvolutionAgent
  → добавляет capability → bump_version("minor") → запись в changelog
  → обнаружил breaking change → bump_version("major") → запись в changelog

Хранение

CHANGELOG/agents/
├── doc_agent.md
├── audit_agent.md
├── security_agent.md
├── spec_agent.md
├── observer_agent.md
├── qa_tester_agent.md
├── fix_agent.md
├── ui_test_agent.md
├── rollout_agent.md
├── evolution_agent.md
└── backlog_agent.md

Формат changelog агента:

# audit_agent Changelog

## 1.0.2 (2026-05-10)
- Fixed: ruff output parsing for Windows paths

## 1.0.1 (2026-05-09)
- Fixed: missing error handling in health_check

## 1.0.0 (2026-05-08)
- Initial version

Разделение ответственности

Аспект	Владелец	Где хранится
Версия проекта	SpecAgent	`project.json`, `CHANGELOG/v*.md`
Версия агента	EvolutionAgent	`AgentConfig.version` (БД)
Changelog проекта	SpecAgent	`CHANGELOG/v*.md`
Changelog агента	EvolutionAgent	`CHANGELOG/agents/<name>.md`

Архитектура

Изменения в моделях БД

class AgentConfig(SQLBase, UUIDMixin, TimestampMixin):
    __tablename__ = "agent_configs"

    agent_name: str        # unique
    is_enabled: bool
    version: str           # "1.0.0" — новое поле
    checksum: str          # SHA256 — новое поле
    config: str | None     # JSON
    last_run_at: datetime  # DateTime вместо String

Изменения в BaseAgent

class BaseAgent(ABC):
    name: str
    version: str = "1.0.0"
    CHANGELOG_DIR = "CHANGELOG/agents/"

    def compute_checksum(self) -> str:
        """SHA256 от __file__ агента"""
        ...

    def bump_version(self, version_type: str = "patch") -> str:
        """Увеличить A/B/C, обновить self.version"""
        ...

    def write_changelog(self, version: str, entries: list[str]) -> None:
        """Дописать запись в CHANGELOG/agents/<name>.md"""
        ...

Последствия

Положительные

Полная traceability изменений каждого агента
Автоматическое версионирование без участия человека
Совместимо с git (checksum детектит и runtime-изменения)
Единый формат changelog для всех агентов

Отрицательные

Дополнительная нагрузка на БД (чтение/запись checksum при каждом run)
SHA256 файла не детектит изменения в импортируемых зависимостях
Patch-версия может расти быстро при частых правках

Ответственный

Decision maker: Owner Review date: При изменении архитектуры агентов

Создано: 2026-05-10

5.4 KiB Raw Blame History Unescape Escape