Initial commit: VoIdeaAI - voice-first AI idea assistant

2026-05-13 12:51:42 +03:00
commit 688d043dad
421 changed files with 47915 additions and 0 deletions
@@ -0,0 +1,156 @@
+# 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*