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,81 @@
+# Версионирование агентов
+
+---
+
+## Принцип
+
+Каждый агент версионируется **независимо** от проекта и от других агентов по A.B.C (SemVer).
+
+---
+
+## Правила бампа
+
+| Компонент | Когда | Кто |
+|-----------|-------|-----|
+| **A (major)** | Breaking change в публичном интерфейсе (сигнатура `run()`, публичные методы) | EvolutionAgent |
+| **B (minor)** | Новая capability (новый метод, новый prompt, новая роль) | EvolutionAgent |
+| **C (patch)** | Внутренние правки без изменения поведения | Сам агент (авто) |
+
+---
+
+## Механика
+
+```
+Каждый Agent.run()
+  → compute_checksum() — SHA256 от __file__ агента
+  → сравнивает с AgentConfig.checksum в БД
+  → не совпал → bump_version("patch") → запись в changelog → обновление БД
+  → совпал → ничего
+
+EvolutionAgent
+  → анализирует код агента
+  → нашёл новую capability → bump_version("minor")
+  → нашёл breaking change → bump_version("major")
+```
+
+---
+
+## Хранение checksum
+
+Checksum хранится в двух местах:
+1. **В БД** (`AgentConfig.checksum`) — для быстрого сравнения
+2. **В changelog файле** (`<!-- checksum: ... -->`) — для git history
+
+---
+
+## Changelog
+
+Файл: `CHANGELOG/agents/<agent_name>.md`
+
+```markdown
+# audit_agent Changelog
+<!-- checksum: a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890 -->
+
+## 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.yaml`, `CHANGELOG/v*.md` |
+| Версия агента | EvolutionAgent | `AgentConfig.version` (БД) |
+| Changelog проекта | SpecAgent / человек | `CHANGELOG/v*.md` |
+| Changelog агента | EvolutionAgent | `CHANGELOG/agents/<name>.md` |
+
+---
+
+## [ASK] Вопросы по версионированию
+
+- Версионировать агентов с первого коммита? (да — привычка, потом не внедрить)
+- Допустим ли ручной бамп версии? (да, EvolutionAgent — автоматизация, но человек может и вручную)
+- Нужна ли блокировка бампа (если checksum не совпал — не запускать)? (нет, только предупреждение)