first commit

2026-09-11 19:47:15 +03:00
commit 32754a1fe2
56 changed files with 3836 additions and 0 deletions
@@ -0,0 +1,76 @@
+# Модуль 5: горячие клавиши + машина состояний + память
+
+Сердце ассистента: сшивает STT (М1), brain (М4), TTS (М3), аудио (М2)
+в цельную программу с тремя способами управления.
+
+## Управление (три режима)
+
+| Режим | Как управлять | Где использовать |
+|---|---|---|
+| **Свободный** (`test_free.py`) | просто говори; пауза 2 с = фраза окончена (Silero-VAD) | целевой для отца |
+| **Клавиши-консоль** (`test_assistant.py`) | Enter/s/r/q (имитация) | разработка в Linux |
+| **Глобальные клавиши** (`--backend keys`) | space/esc/enter из любого окна | Windows-сборка |
+
+## Машина состояний
+
+```
+idle ─▶ listening ─▶ thinking ─▶ speaking ─▶ idle
+  ▲         │            │           │
+  └─────────┴────────────┴───────────┘  («Замолчи» из любого)
+```
+
+- Говорит, а отец начал говорить → речь мгновенно стихает, новая фраза обрабатывается.
+- «Замолчи» гасит речь/отменяет запись/отбрасывает «думание» (счётчик поколений:
+  устаревшие ответы никогда не прозвучат).
+- «Повтори» — последняя фраза (в idle).
+
+## Долговременная память (data/memory.md)
+
+- Слово прощания («до свидания», «прощай», «пока»…) → мгновенный прощальный ответ +
+  фоновым запросом модель формулирует конспект разговора → дописывается в файл.
+- При старте конспект вшивается в системный промпт — ассистент «помнит» прошлые разговоры.
+- Файл — обычный текст с датами, можно править руками; при переполнении (>8000 симв.)
+  старые записи сжимаются автоматически.
+- Память не критична к сбоям: ошибка сети при конспекте просто логируется.
+
+## Файлы
+
+| Файл | Назначение |
+|---|---|
+| `modules/hotkeys/` | бэкенды клавиш: `console.py` (Linux), `keyboard_hook.py` (Windows), общий контракт `KeyEvents` |
+| `modules/assistant/assistant.py` | машина состояний, конвейер STT→LLM→TTS, перебивание |
+| `modules/assistant/memory.py` | файл-конспект между сессиями |
+| `modules/assistant/farewell.py` | детект прощания + саммари диалога |
+| `modules/audio_io/handsfree.py` | свободный режим: Silero-VAD в потоке, конец фразы по паузе |
+| `test_assistant.py` | клавиши-консоль / глобальные клавиши |
+| `test_free.py` | свободный режим (говори без кнопок) |
+
+## Запуск
+
+```bash
+# свободный режим (целевой):
+.venv/bin/python modules/assistant/test_free.py
+.venv/bin/python modules/assistant/test_free.py --silence 2.5   # подольше пауза
+
+# клавишный режим (Linux-разработка):
+.venv/bin/python modules/assistant/test_assistant.py
+```
+
+Клавиши Windows-сборки настраиваются в .env: `HOTKEY_TALK/HOTKEY_STOP/HOTKEY_REPEAT`.
+
+## Критерии приёмки — статус
+
+1. ✅ Обычный цикл (живой тест юзером, 2026-09-11).
+2. ✅ Контекст диалога внутри сессии.
+3. ✅ «Замолчи» мгновенно; перебивание речи новым вопросом.
+4. ✅ «Повтори».
+5. ✅ Память между сессиями (мок-тест); живой тест двух запусков — на юзере.
+6. 🟡 Свободный режим VAD — код готов, живой тест после установки silero-vad (CPU-torch).
+
+## Известные детали
+
+- Silero-VAD требует torch; для разработки ставим CPU-вариант (~200 МБ):
+  `pip install --index-url https://download.pytorch.org/whl/cpu torch silero-vad`.
+  В Windows-сборке заменим на ONNX-детектор (2 МБ, без torch).
+- suppress-механизм: на время ответа микрофон глушится, чтобы не слышать саму себя;
+  при перебивании отцом suppress снимается мгновенно.