​

Жизненный цикл голосового оверлея (macOS)

​

Текущий замысел

• Если оверлей уже виден из‑за ключевого слова активации и пользователь нажимает горячую клавишу, сеанс по горячей клавише подхватывает существующий текст вместо его сброса. Оверлей остаётся на экране, пока удерживается горячая клавиша. Когда пользователь отпускает её: отправить, если есть обрезанный текст, иначе закрыть.
• Ключевое слово активации само по себе по‑прежнему автоматически отправляет по тишине; push-to-talk отправляет сразу при отпускании.

​

Реализовано (9 декабря 2025)

• Сеансы оверлея теперь несут токен на каждый захват (ключевое слово активации или push-to-talk). Обновления partial/final/send/dismiss/level отбрасываются, если токен не совпадает, что предотвращает устаревшие колбэки.
• Push-to-talk подхватывает любой видимый текст оверлея как префикс (поэтому нажатие горячей клавиши, когда оверлей от ключевого слова уже открыт, сохраняет текст и добавляет новую речь). Он ждёт до 1,5 с финальной транскрипции, прежде чем откатиться к текущему тексту.
• Логирование звукового сигнала/оверлея выводится под info в категориях voicewake.overlay, voicewake.ptt и voicewake.chime (начало сеанса, partial, final, send, dismiss, причина звукового сигнала).

​

Следующие шаги

1. VoiceSessionCoordinator (actor)
   • Владеет ровно одним VoiceSession в каждый момент времени.
   • API (на основе токенов): beginWakeCapture, beginPushToTalk, updatePartial, endCapture, cancel, applyCooldown.
   • Отбрасывает колбэки со старыми токенами (предотвращает повторное открытие оверлея старыми распознавателями).
2. VoiceSession (model)
   • Поля: token, source (wakeWord|pushToTalk), зафиксированный/временный текст, флаги звуковых сигналов, таймеры (автоотправка, простой), overlayMode (display|editing|sending), дедлайн кулдауна.
3. Привязка оверлея
   • VoiceSessionPublisher (ObservableObject) зеркалирует активный сеанс в SwiftUI.
   • VoiceWakeOverlayView рендерит только через publisher; он никогда напрямую не мутирует глобальные синглтоны.
   • Действия пользователя в оверлее (sendNow, dismiss, edit) вызывают координатор обратно с токеном сеанса.
4. Единый путь отправки
   • При endCapture: если обрезанный текст пуст → закрыть; иначе performSend(session:) (проигрывает звуковой сигнал отправки один раз, пересылает, закрывает).
   • Push-to-talk: без задержки; ключевое слово активации: опциональная задержка для автоотправки.
   • Применить короткий кулдаун к рантайму ключевого слова активации после завершения push-to-talk, чтобы ключевое слово не срабатывало сразу же повторно.
5. Логирование
   • Координатор выводит логи .info в подсистеме bot.molt, категориях voicewake.overlay и voicewake.chime.
   • Ключевые события: session_started, adopted_by_push_to_talk, partial, finalized, send, dismiss, cancel, cooldown.

​

Контрольный список отладки

• Стримьте логи при воспроизведении «залипшего» оверлея:
  sudo log stream --predicate 'subsystem == "bot.molt" AND category CONTAINS "voicewake"' --level info --style compact
  
• Убедитесь, что активен только один токен сеанса; устаревшие колбэки должны отбрасываться координатором.
• Убедитесь, что отпускание push-to-talk всегда вызывает endCapture с активным токеном; если текст пуст, ожидайте dismiss без звукового сигнала и отправки.

​

Шаги миграции (рекомендуется)

1. Добавить VoiceSessionCoordinator, VoiceSession и VoiceSessionPublisher.
2. Рефакторить VoiceWakeRuntime, чтобы создавать/обновлять/завершать сеансы вместо прямого обращения к VoiceWakeOverlayController.
3. Рефакторить VoicePushToTalk, чтобы подхватывать существующие сеансы и вызывать endCapture при отпускании; применить кулдаун рантайма.
4. Подключить VoiceWakeOverlayController к publisher; убрать прямые вызовы из рантайма/PTT.
5. Добавить интеграционные тесты для подхвата сеанса, кулдауна и закрытия при пустом тексте.