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,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` — гибко, но без типизации)