shturman/docs/domains/d-assistant.md

# Домен 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 |