macOS companion app

Голосовой оверлей

Аудитория: разработчики macOS приложения. Цель: обеспечить предсказуемость голосового оверлея при пересечении wake-word и push-to-talk.

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

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

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

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

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

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

Чеклист для отладки

  • Потоковое логирование при воспроизведении зависшего оверлея:

    Копировать

    sudo log stream --predicate 'subsystem == "ai.openclaw" 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 к издателю; удалите прямые вызовы из runtime/PTT.
  5. Добавьте интеграционные тесты для принятия сессии, перерыва и скрытия при пустом тексте.

Voice WakeWebChat