docs(domain D): Assistant — спека + ревью-фиксы

- спека домена D: пайплайн (wake→VAD→STT→router→[локальные/LLM]→TTS, ONNX Runtime), функции (MVP/later), vehicle-context injection (killer), provider-agnostic LLM, интенты, память о водителе (.md), приватность - ревью: openWakeWord вместо проприетарного Porcupine (принцип #12); мягкая деградация при нестабильной сети до офлайн-фолбэка; креды LLM — свои у пользователя; + контекст-размер, офлайн-STT в шуме, function-calling, обучение wake-word Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-20 20:45:20 +03:00
parent 01119a4ccf
commit a8895ab99f
1 changed files with 142 additions and 0 deletions
@@ -0,0 +1,142 @@
+# Домен D — Голосовой ассистент
+
+> Русскоязычный со-пилот: слышит речь, **видит данные машины (через E)** и объясняет
+> их по-человечески. Интегрирован в UI лаконично (как Grok в Tesla). Вторая половина
+> killer-фичи. First-party ап на SDK (Rust + ONNX Runtime).
+
+Статус: **v1 (на ревью).**
+Связано с: домен E (Vehicle-Data) · [ipc.md](../contracts/ipc.md) (`Assistant`) · [plugin-sdk.md](../contracts/plugin-sdk.md) (интенты) · [security-privacy.md](../contracts/security-privacy.md) (mic, приватность) · [tech-stack.md](../tech-stack.md) · [principles.md](../principles.md) (#3,#6,#7,#8)
+
+---
+
+## 1. Назначение и границы
+
+- **Что делает:** голосовой и текстовый диалог по-русски; объясняет состояние машины;
+  выполняет интенты (свои + плагинов).
+- **Границы:** не трогает CAN напрямую (контекст берёт у E); **не даёт советов,
+  опасных для вождения** (констрейнт системного промпта); никаких safety-critical.
+
+## 2. Пайплайн
+
+```
+Mic-массив → Wake-word → VAD → STT(RU) → Intent router
+   → [локальные интенты]   (громче/домой/… — без LLM, низкая латентность)
+   → [LLM backend]         (свободный диалог + объяснения + контекст машины)
+   → TTS(RU) → Audio out
+```
+
+Компоненты: wake-word (**openWakeWord**, Apache-2.0, RU-фраза «Штурман»; Porcupine —
+коммерческий/проприетарный → конфликт с принципом #12, избегаем) · VAD (Silero) ·
+STT (Vosk/Silero, **офлайн**) · intent router · LLM backend (pluggable) · TTS (Silero, офлайн).
+Инференс — через ONNX Runtime (`ort`); см. [tech-stack.md](../tech-stack.md).
+
+## 3. Функции
+
+| функция | MVP/later | зависит от | фаза |
+|---------|-----------|------------|------|
+| Wake-word «Штурман» | **MVP** | mic, tech-stack | v1 |
+| VAD (Silero) | **MVP** | — | v1 |
+| STT RU офлайн (Vosk/Silero) | **MVP** | — | v1 |
+| TTS RU офлайн (Silero) | **MVP** | — | v1 |
+| Push-to-talk + текстовый лог диалога | **MVP** | Shell | v1 |
+| Intent router | **MVP** | — | v1 |
+| Локальные интенты (громче/домой/…) | **MVP** | — | v1 |
+| LLM online (GigaChat/YandexGPT) | **MVP** | Connectivity | v1 |
+| Multi-turn контекст | **MVP** | — | v1 |
+| **Vehicle-context injection** | **MVP (killer)** | E, data-model | v2 |
+| Provider auto-fallback | **MVP** | — | v1 |
+| Driver-distraction (приоритет голосу на скорости) | **MVP** | Shell, E(speed) | v1/v2 |
+| LLM offline fallback (локальная модель) | later | — | v3 |
+| Память о водителе (`.md`) | later | storage | v3 |
+| Plugin-интенты (dispatch в IntentHandler) | later | plugin-sdk | v3 |
+| Barge-in (прерывание TTS голосом) | later | — | later |
+
+## 4. Vehicle-context injection (killer-фича)
+
+Ассистент получает в системный промпт **live-снимок** данных машины (из E) и
+объясняет простым русским. Пример:
+
+```
+[SYSTEM] Ты — Штурман, голосовой со-пилот. Кратко, по-русски, для водителя в движении.
+Не давай советов, опасных для вождения.
+Данные машины (только чтение, могут быть неточны):
+  Скорость 64 км/ч · Обороты 2100 · Охлаждайка 92°C · Бортсеть 14.1В
+  Лампа Check: горит · Ошибки: P0420 (катализатор, банк 1 — низкая эффективность)
+[Память о водителе]: …
+[USER] Почему горит чек?
+[ASSISTANT] Из-за P0420 — система считает, что катализатор работает неэффективно.
+Часто это датчик кислорода или сам катализатор. Машина поедет, но на диагностику стоит заехать.
+```
+
+Снимок берётся из `VehicleData` (E); коды → стандартное описание из базы, человеческое
+объяснение — LLM.
+
+## 5. LLM backend (pluggable, provider-agnostic)
+
+- **Единый интерфейс бэкенда**, реализации сменные (принцип #8).
+- **Online:** GigaChat (OAuth2), YandexGPT (IAM) — HTTP, RU/152-ФЗ.
+- **Offline:** локальная квантованная модель через llama.cpp (фаза v3).
+- **Авто-fallback:** ошибка/нет сети → офлайн; восстановилась — обратно.
+- **Креды — свои у пользователя:** проект не шипит ключи; пользователь подключает
+  свой GigaChat/YandexGPT (токены в защищённом хранилище, refresh; облако — за его счёт).
+- **До офлайн-фолбэка (v1 online-only):** сеть в движении нестабильна → мягкая
+  деградация: «думаю…», таймаут → «нет сети», без зависаний. Офлайн-фолбэк (v3) и
+  делает ассистента по-настоящему надёжным.
+
+## 6. Интенты (routing)
+
+- **Локальные латентно-критичные** (громче, домой, отмена) — без LLM, мгновенно.
+- **Свободный диалог / объяснения** — LLM (с контекстом машины + памятью).
+- **Plugin-интенты** — dispatch в `IntentHandler` плагина; коллизии разрешаются по
+  политике [plugin-sdk](../contracts/plugin-sdk.md) §5; LLM-роутер — арбитр по контексту.
+
+## 7. Память о водителе (`.md`)
+
+- Хранит факты о водителе/привычках/машине в **локальных `.md`** (приватное
+  хранилище `/data/apps/assistant/`, как контекст-память у Claude/Cursor).
+- **Использование:** подмешивается в контекст (как и данные машины).
+- **Приватность:** локально; **не уходит в облако без явного согласия** (security-privacy §7);
+  пользователь может **смотреть/править/чистить**.
+- 🟡 *Осторожно:* что именно авто-запоминать — приватно-чувствительно; нужна
+  аккуратная политика (по умолчанию минимум, прозрачно).
+
+## 8. Приватность
+
+- Голос обрабатывается **локально** (STT) до отправки чего-либо; в облако — только
+  **текст запроса** при онлайн-LLM. Микрофон always-on для wake-word, но локально +
+  **видимый индикатор** прослушки. Контекст машины уходит провайдеру только онлайн и
+  по запросу (security-privacy §7).
+
+## 9. Зависимости
+
+- **Вниз/вбок:** E (контекст машины), Connectivity (online LLM), PipeWire (`audio_in`/`audio_out`),
+  Settings, Shell (UI-интеграция, driver-distraction), security-privacy (mic-индикатор),
+  tech-stack (ONNX Runtime, llama.cpp), data-model (коды/сигналы для контекста).
+
+## 10. Открытые вопросы
+
+- 🟡 **Память о водителе:** что авто-запоминать, схема, consent (приватность). → этот домен + security-privacy.
+- 🟡 **Выбор офлайн-модели** (YandexGPT Lite / T-lite / Qwen, квантизация) — по перфу/RAM RK3588. → отложено (бенч на железе).
+- ◻️ **Подход к матчингу интентов** (грамматика/ключевые слова для локальных vs LLM-роутер). → реализация.
+- ◻️ **Бюджет латентности** пайплайна (wake→ответ) — цель и измерение. → реализация.
+- ◻️ **STT:** Vosk (стриминг, легче) vs Silero (качество) — выбрать/поддержать оба. → реализация.
+- ◻️ **Barge-in** (прерывание TTS) — later.
+- ◻️ **Размер контекста:** машина + память + история → токены (особенно у офлайн-модели
+  с маленьким окном); нужна обрезка/суммаризация. → реализация.
+- ◻️ **Точность офлайн-STT в шуме:** приватность фиксирует офлайн-STT → критичен
+  **mic-массив** (beamforming/шумоподавление). → этот домен + [hardware.md](../contracts/hardware.md).
+- ◻️ **Plugin-интенты как function-calling** (tool-use LLM) vs фразы — зависит от
+  поддержки провайдером (у GigaChat/YandexGPT может быть ограничена). → реализация.
+- ◻️ **Обучение wake-word «Штурман»** (openWakeWord) — сбор данных/тренировка. → реализация.
+
+---
+
+## Журнал решений (домен D)
+
+| Решение | Выбор | Дата |
+|---------|-------|------|
+| Пайплайн | wake→VAD→STT→router→(локальные/LLM)→TTS; ONNX Runtime | 2026-06-16 |
+| LLM | provider-agnostic; online GigaChat/YandexGPT + offline llama.cpp; авто-fallback | 2026-06-16 |
+| Контекст машины | live-снимок из E в системный промпт (killer-фича) | 2026-06-16 |
+| Память о водителе | локальные `.md` в приватном хранилище; не в облако без согласия | 2026-06-16 |
+| Локальные интенты | латентно-критичные — без LLM | 2026-06-16 |