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,61 @@
+# Обзор системных агентов
+
+---
+
+## Что такое системный агент
+
+Системный агент — это программа, которая автоматизирует поддержку и развитие проекта.
+В отличие от AI-агента (который анализирует пользовательские данные), системный агент работает **над проектом**: пишет документацию, проверяет правила, версионирует код.
+
+---
+
+## Когда внедрять агентов
+
+**С первого коммита.** 4 ядерных агента создаются сразу.
+Остальные — по мере возникновения потребности.
+
+---
+
+## Отличие системного агента от AI-агента
+
+| Характеристика | Системный агент | AI-агент |
+|---------------|-----------------|-----------|
+| Что делает | Поддерживает проект | Анализирует данные пользователя |
+| Кто запускает | Триггеры (pre-commit, cron) | Пользователь (через UI) |
+| Результат | Чистый код, docs, версии | Анализ идеи, рекомендации |
+| Пример | DocAgent пишет docstrings | Координатор анализирует идею |
+| Версионируется | Да (A.B.C независимо) | Нет |
+
+---
+
+## Ядро (4 агента, обязательны)
+
+| # | Агент | Роль | Триггеры |
+|---|-------|------|----------|
+| 1 | **DocAgent** | Пишет документацию | pre-commit, manual |
+| 2 | **AuditAgent** | Проверяет правила | pre-commit, push, cron |
+| 3 | **EvolutionAgent** | Версионирует агентов | cron, event, manual |
+| 4 | **SupervisorAgent** | Следит за всеми агентами | cron, event, manual |
+
+---
+
+## Расширение (по необходимости)
+
+| # | Агент | Когда добавлять |
+|---|-------|----------------|
+| 5 | **QATesterAgent** | Появились тесты |
+| 6 | **FixAgent** | Пойман первый баг |
+| 7 | **BacklogAgent** | Появился техдолг |
+| 8 | **SecurityAgent** | Перед production |
+| 9 | **SpecAgent** | Перед релизом |
+| 10 | **RolloutAgent** | Перед деплоем |
+| 11 | **ObserverAgent** | После запуска |
+| 12 | **UITestAgent** | Есть UI |
+
+---
+
+## [ASK] Вопросы по агентам
+
+- Сколько агентов нужно сейчас? (рекомендация: 4 ядерных, потом по необходимости)
+- Есть ли ресурс на разработку агентов? (DocAgent ≈ 2 часа, AuditAgent ≈ 4 часа)
+- Кто будет поддерживать агентов? (те же разработчики)
@@ -0,0 +1,107 @@
+# Архитектура агентов
+
+---
+
+## BaseAgent
+
+Все агенты наследуются от `BaseAgent`:
+
+```python
+class BaseAgent(ABC):
+    name: str                           # Уникальное имя агента
+    version: str = "1.0.0"              # Текущая версия
+    description: str = ""               # Описание для registry
+    triggers: list[AgentTrigger]        # Когда запускается
+
+    async def run(self, context: dict | None = None) -> AgentResult:
+        """Выполнить задачу агента."""
+
+    async def health_check(self) -> bool:
+        """Проверить что агент работоспособен."""
+
+    def compute_checksum(self) -> str:
+        """SHA256 от __file__ агента."""
+
+    def bump_version(self, version_type: str = "patch") -> str:
+        """Увеличить версию (major/minor/patch)."""
+```
+
+---
+
+## Жизненный цикл
+
+```
+IDLE → RUNNING → [DONE | ERROR] → IDLE
+                ↘ OFFLINE
+```
+
+1. Агент запускается (триггер или вручную)
+2. Статус → RUNNING
+3. Выполняется `run(context)`
+4. Статус → IDLE (успех) или ERROR (ошибка)
+5. Результат сохраняется в AgentReport
+
+---
+
+## AgentResult
+
+```python
+class AgentResult:
+    success: bool                     # Успешно ли выполнен
+    message: str                      # Сообщение для лога
+    data: dict[str, Any]              # Произвольные данные результата
+    errors: list[str]                 # Список ошибок
+    duration_ms: int                  # Время выполнения
+    timestamp: datetime               # Когда выполнен
+```
+
+---
+
+## AgentRegistry
+
+Регистрация всех агентов в едином реестре:
+
+```python
+class AgentRegistry:
+    def register(self, agent: BaseAgent): ...
+    def get(self, name: str) -> BaseAgent | None: ...
+    def list_agents(self) -> list[dict]: ...
+    async def run_agent(self, name: str, context=None) -> AgentResult: ...
+    async def run_all(self, context=None) -> dict[str, AgentResult]: ...
+```
+
+---
+
+## Триггеры
+
+| Триггер | Когда | Пример |
+|---------|-------|--------|
+| `MANUAL` | Вручную из админки | Запуск DocAgent |
+| `PRE_COMMIT` | Перед git commit | AuditAgent проверяет правила |
+| `PUSH` | git push | SecurityAgent проверяет зависимости |
+| `TAG_CREATION` | git tag | SpecAgent обновляет CHANGELOG |
+| `CRON` | По расписанию | EvolutionAgent ежедневный анализ |
+| `API` | Через API-endpoint | Запуск из админ-панели |
+| `EVENT` | Событие в системе | FixAgent при ошибке |
+
+---
+
+## Хранение промптов
+
+Промпты агентов хранятся в `docs/agent_prompts.yaml` или в отдельных MD-файлах в `docs/specs/agents/`.
+
+Загрузка через `PromptLoader`:
+```python
+def get_prompt_config(role: str) -> dict | None:
+    # 1. Попробовать YAML (docs/agent_prompts.yaml)
+    # 2. Не найдено → загрузить из MD (docs/specs/agents/<role>.md)
+    # 3. Не найдено → None
+```
+
+---
+
+## [ASK] Вопросы по архитектуре
+
+- Нужен ли AgentRegistry? (да, обязателен для SupervisorAgent)
+- Хранить состояние агентов в БД или в памяти? (в БД для отказоустойчивости)
+- Как передавать контекст агенту? (через `context: dict` — гибко, но без типизации)
@@ -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 не совпал — не запускать)? (нет, только предупреждение)
@@ -0,0 +1,34 @@
+# Шаблон changelog агента
+
+Используйте для инициализации changelog нового агента.
+
+Формат файла: `CHANGELOG/agents/{agent_name}.md`
+
+```markdown
+# {agent_name} Changelog
+<!-- checksum: {sha256_hash} -->
+
+## 1.0.0 ({date})
+- Initial version
+```
+
+## Пример
+
+```markdown
+# doc_agent Changelog
+<!-- checksum: a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890 -->
+
+## 1.2.1 (2026-05-11)
+- Fixed: update README on file rename
+- Fixed: handle empty docstrings gracefully
+
+## 1.2.0 (2026-05-10)
+- Added: YAML prompt loading support
+- Added: cross-reference validation
+
+## 1.1.0 (2026-05-09)
+- Added: auto-generate README for new modules
+
+## 1.0.0 (2026-05-01)
+- Initial version
+```
@@ -0,0 +1,69 @@
+# Шаблон кода агента
+
+Используйте этот шаблон для создания нового системного агента.
+
+```python
+"""Agent: {name} — {description}."""
+
+from datetime import datetime, timezone
+from typing import Any
+
+from app.agents.base import BaseAgent, AgentResult, AgentTrigger
+
+
+class {Name}Agent(BaseAgent):
+    """{Description} agent.
+
+    Triggers: {triggers}
+    """
+
+    name = "{name}"
+    version = "1.0.0"
+    description = "{description}"
+    triggers = [AgentTrigger.MANUAL]
+
+    async def run(self, context: dict[str, Any] | None = None) -> AgentResult:
+        """Execute agent task.
+
+        Args:
+            context: Optional context with execution parameters
+
+        Returns:
+            AgentResult with execution outcome
+        """
+        start = datetime.now(timezone.utc)
+        errors: list[str] = []
+        data: dict[str, Any] = {}
+
+        try:
+            # === AGENT LOGIC HERE ===
+            # 1. Do the work
+            # 2. Collect results
+            # 3. Handle errors
+            pass
+
+        except Exception as e:
+            errors.append(str(e))
+
+        duration = int((datetime.now(timezone.utc) - start).total_seconds() * 1000)
+
+        result = AgentResult(
+            success=len(errors) == 0,
+            message=f"{self.name} completed with {len(errors)} errors",
+            data=data,
+            errors=errors,
+            duration_ms=duration,
+        )
+
+        # Auto-version check
+        new_version = await self._check_version()
+        if new_version:
+            result.data["version_bumped"] = True
+            result.data["new_version"] = new_version
+
+        return result
+
+    async def health_check(self) -> bool:
+        """Check if agent can execute."""
+        return True
+```