157 lines
5.4 KiB
Markdown
157 lines
5.4 KiB
Markdown
# 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 агента:
|
||
```markdown
|
||
# 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` |
|
||
|
||
---
|
||
|
||
## Архитектура
|
||
|
||
### Изменения в моделях БД
|
||
|
||
```python
|
||
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
|
||
|
||
```python
|
||
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*
|