shturman/docs/domains/d-assistant.md

Домен D — Голосовой ассистент

Русскоязычный со-пилот: слышит речь, видит данные машины (через E) и объясняет их по-человечески. Интегрирован в UI лаконично (как Grok в Tesla). Вторая половина killer-фичи. First-party ап на SDK (Rust + ONNX Runtime).

Статус: v1 (на ревью). Связано с: домен E (Vehicle-Data) · ipc.md (Assistant) · plugin-sdk.md (интенты) · security-privacy.md (mic, приватность) · tech-stack.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.

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 §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.
• ◻️ 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