From a8895ab99f0edd51a416f65319b7119094577737 Mon Sep 17 00:00:00 2001 From: Alexander Date: Sat, 20 Jun 2026 20:45:20 +0300 Subject: [PATCH] =?UTF-8?q?docs(domain=20D):=20Assistant=20=E2=80=94=20?= =?UTF-8?q?=D1=81=D0=BF=D0=B5=D0=BA=D0=B0=20+=20=D1=80=D0=B5=D0=B2=D1=8C?= =?UTF-8?q?=D1=8E-=D1=84=D0=B8=D0=BA=D1=81=D1=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - спека домена 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) --- docs/domains/d-assistant.md | 142 ++++++++++++++++++++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 docs/domains/d-assistant.md diff --git a/docs/domains/d-assistant.md b/docs/domains/d-assistant.md new file mode 100644 index 0000000..873f6f4 --- /dev/null +++ b/docs/domains/d-assistant.md @@ -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 |