Особенности платформы Windows: нативные уведомления и определение терминала

Чему вы научитесь

• Узнаете, какие функции opencode-notify поддерживает на Windows
• Освоите механизм определения терминала в Windows
• Поймёте различия в функциональности между Windows и macOS
• Настроите подходящую стратегию уведомлений для Windows

Ваша текущая проблема

Вы используете OpenCode на Windows и замечаете, что некоторые функции работают не так интеллектуально, как на macOS. Уведомления появляются даже когда терминал в фокусе, а клик по уведомлению не переключает на окно терминала. Это нормально? Какие ограничения есть у платформы Windows?

Когда это пригодится

Изучите особенности платформы Windows в следующих случаях:

• Вы используете opencode-notify на Windows
• Вы обнаружили, что некоторые функции macOS недоступны на Windows
• Вы хотите максимально использовать доступные возможности Windows

Основная идея

opencode-notify предоставляет базовые возможности уведомлений на платформе Windows, но с некоторыми ограничениями по сравнению с macOS. Это обусловлено особенностями операционной системы, а не недостатками плагина.

Почему на macOS больше возможностей?

macOS предоставляет более мощные системные API:

• NSUserNotificationCenter поддерживает фокусировку по клику
• AppleScript позволяет определять активное приложение
• API системных звуков позволяет настраивать звуки

Windows и Linux имеют более базовые API системных уведомлений, поэтому opencode-notify на этих платформах использует node-notifier для вызова нативных уведомлений системы.

Обзор функций Windows

Функция	Windows	Описание
Нативные уведомления	✅ Поддерживается	Отправка уведомлений через Windows Toast
Определение терминала	✅ Поддерживается	Автоматическое распознавание 37+ эмуляторов терминала
Определение фокуса	❌ Не поддерживается	Невозможно определить, находится ли терминал на переднем плане
Фокусировка по клику	❌ Не поддерживается	Клик по уведомлению не переключает на терминал
Пользовательские звуки	❌ Не поддерживается	Используется стандартный звук уведомлений системы

Механизм уведомлений Windows

opencode-notify использует Windows Toast уведомления на Windows, вызывая нативный API системы через библиотеку node-notifier.

Когда срабатывают уведомления:

• При завершении задачи ИИ (session.idle)
• При ошибке выполнения ИИ (session.error)
• Когда ИИ запрашивает разрешение (permission.updated)
• Когда ИИ задаёт вопрос (tool.execute.before)

Особенности Windows Toast уведомлений

• Уведомления появляются в правом нижнем углу экрана
• Автоматически исчезают (примерно через 5 секунд)
• Используют стандартный звук уведомлений системы
• Клик по уведомлению открывает Центр уведомлений (не переключает на терминал)

Определение терминала

Автоматическое распознавание терминала

opencode-notify использует библиотеку detect-terminal для автоматического определения используемого эмулятора терминала.

Поддерживаемые терминалы Windows:

• Windows Terminal (рекомендуется)
• Git Bash
• ConEmu
• Cmder
• PowerShell
• Встроенный терминал VS Code

Принцип определения терминала

При запуске плагина detect-terminal() сканирует системные процессы для определения типа текущего терминала.

Расположение в исходном коде: src/notify.ts:145-147

async function detectTerminalInfo(config: NotifyConfig): Promise<TerminalInfo> {
	const terminalName = config.terminal || detectTerminal() || null
	
	if (!terminalName) {
		return { name: null, bundleId: null, processName: null }
	}
	
	return {
		name: terminalName,
		bundleId: null,  // Windows не требует bundleId
		processName: null,  // Windows не требует имени процесса
	}
}

Ручное указание терминала

Если автоматическое определение не работает, вы можете вручную указать тип терминала в файле конфигурации.

Пример конфигурации:

{
  "terminal": "Windows Terminal"
}

Доступные названия терминалов: см. список поддерживаемых терминалов detect-terminal.

Сравнение функций платформ

Функция	macOS	Windows	Linux
Нативные уведомления	✅ Notification Center	✅ Toast	✅ notify-send
Пользовательские звуки	✅ Список системных звуков	❌ Стандартный системный	❌ Стандартный системный
Определение фокуса	✅ AppleScript API	❌ Не поддерживается	❌ Не поддерживается
Фокусировка по клику	✅ activate bundleId	❌ Не поддерживается	❌ Не поддерживается
Определение терминала	✅ 37+ терминалов	✅ 37+ терминалов	✅ 37+ терминалов

Почему Windows не поддерживает определение фокуса?

В исходном коде функция isTerminalFocused() на Windows сразу возвращает false:

// src/notify.ts:166-168
async function isTerminalFocused(terminalInfo: TerminalInfo): Promise<boolean> {
	if (!terminalInfo.processName) return false
	if (process.platform !== "darwin") return false  // ← Windows/Linux сразу возвращает false
	// ... логика определения фокуса для macOS
}

Причины:

• Windows не предоставляет API для запроса активного приложения, аналогичный AppleScript в macOS
• Windows PowerShell может получить активное окно, но требует вызова COM-интерфейсов, что сложно в реализации
• Текущая версия приоритизирует стабильность, определение фокуса для Windows пока не реализовано

Почему Windows не поддерживает фокусировку по клику?

В исходном коде функция sendNotification() устанавливает опцию activate только на macOS:

// src/notify.ts:238-240
// macOS-specific: click notification to focus terminal
if (process.platform === "darwin" && terminalInfo.bundleId) {
	notifyOptions.activate = terminalInfo.bundleId
}

Причины:

• Windows Toast не поддерживает параметр activate
• Уведомления Windows могут быть связаны только через ID приложения, невозможно динамически указать целевое окно
• Клик по уведомлению открывает Центр уведомлений, а не фокусирует конкретное окно

Лучшие практики для Windows

Рекомендации по настройке

Поскольку Windows не поддерживает определение фокуса, рекомендуется настроить конфигурацию для уменьшения количества уведомлений.

Рекомендуемая конфигурация:

{
  "notifyChildSessions": false,
  "quietHours": {
    "enabled": true,
    "start": "22:00",
    "end": "08:00"
  }
}

Описание настроек:

• notifyChildSessions: false — уведомлять только о родительских сессиях, избегая шума от подзадач
• quietHours.enabled: true — включить тихие часы, чтобы не беспокоить ночью

Неподдерживаемые параметры конфигурации

Следующие параметры не работают на Windows:

Параметр	Эффект на macOS	Эффект на Windows
sounds.idle	Воспроизводит звук Glass	Используется стандартный системный звук
sounds.error	Воспроизводит звук Basso	Используется стандартный системный звук
sounds.permission	Воспроизводит звук Submarine	Используется стандартный системный звук

Полезные советы

Совет 1: Ручное отключение уведомлений

Если вы смотрите на терминал и не хотите отвлекаться:

1. Нажмите на значок «Центр уведомлений» на панели задач (Windows + A)
2. Отключите уведомления opencode-notify

Совет 2: Используйте тихие часы

Настройте рабочее и нерабочее время, чтобы не получать уведомления в нерабочее время:

{
  "quietHours": {
    "enabled": true,
    "start": "18:00",
    "end": "09:00"
  }
}

Совет 3: Временное отключение плагина

Если нужно полностью отключить уведомления, можно удалить файл конфигурации или установить тихие часы на весь день:

{
  "quietHours": {
    "enabled": true,
    "start": "00:00",
    "end": "23:59"
  }
}

Практическое задание

Проверка уведомлений Windows

Шаг 1: Вызовите тестовое уведомление

Введите простую задачу в OpenCode:

Пожалуйста, вычислите результат 1+1.

Ожидаемый результат:

• В правом нижнем углу появится Windows Toast уведомление
• Заголовок уведомления: "Ready for review"
• Воспроизведётся стандартный звук уведомления системы

Шаг 2: Проверка подавления при фокусе (подтверждение отсутствия поддержки)

Оставьте окно терминала на переднем плане и снова запустите задачу.

Ожидаемый результат:

• Уведомление всё равно появится (потому что Windows не поддерживает определение фокуса)

Шаг 3: Проверка клика по уведомлению

Нажмите на появившееся уведомление.

Ожидаемый результат:

• Откроется Центр уведомлений, а не переключится на окно терминала

Настройка тихих часов

Шаг 1: Создайте файл конфигурации

Отредактируйте файл конфигурации (PowerShell):

notepad $env:USERPROFILE\.config\opencode\kdco-notify.json

Шаг 2: Добавьте настройку тихих часов

{
  "quietHours": {
    "enabled": true,
    "start": "22:00",
    "end": "08:00"
  }
}

Шаг 3: Сохраните и протестируйте

Дождитесь, когда текущее время войдёт в период тихих часов, затем запустите задачу.

Ожидаемый результат:

• Уведомление не появится (тихие часы активны)

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

После выполнения вышеуказанных шагов убедитесь:

• [ ] Windows Toast уведомления отображаются корректно
• [ ] Уведомления показывают правильный заголовок задачи
• [ ] Настройка тихих часов работает
• [ ] Вы понимаете, какие функции не поддерживаются на Windows

Типичные проблемы

Проблема 1: Уведомления не отображаются

Причина: Не предоставлены разрешения на уведомления Windows

Решение:

1. Откройте «Параметры» → «Система» → «Уведомления»
2. Убедитесь, что включена опция «Получать уведомления от приложений и других отправителей»
3. Найдите OpenCode и убедитесь, что разрешения на уведомления включены

Проблема 2: Терминал не определяется

Причина: detect-terminal не может распознать ваш терминал

Решение:

Вручную укажите тип терминала в файле конфигурации:

{
  "terminal": "Windows Terminal"
}

Проблема 3: Пользовательские звуки не работают

Причина: Платформа Windows не поддерживает пользовательские звуки

Пояснение: Это нормальное поведение. Windows Toast уведомления используют стандартный системный звук, который нельзя изменить через файл конфигурации.

Проблема 4: Клик по уведомлению не фокусирует терминал

Причина: Windows Toast не поддерживает параметр activate

Пояснение: Это ограничение Windows API. Клик по уведомлению открывает Центр уведомлений, нужно вручную переключиться на окно терминала.

Итоги урока

В этом уроке мы узнали:

• ✅ Платформа Windows поддерживает нативные уведомления и определение терминала
• ✅ Windows не поддерживает определение фокуса и фокусировку по клику
• ✅ Windows не поддерживает пользовательские звуки
• ✅ Рекомендуемые настройки (тихие часы, уведомления только для родительских сессий)
• ✅ Решения типичных проблем

Ключевые выводы:

1. Функциональность платформы Windows относительно базовая, но основные возможности уведомлений полноценны
2. Определение фокуса и фокусировка по клику — эксклюзивные функции macOS
3. Настройка тихих часов помогает уменьшить количество уведомлений
4. Определение терминала поддерживает ручное указание для улучшения совместимости

Анонс следующего урока

В следующем уроке мы изучим Особенности платформы Linux.

Вы узнаете:

• Механизм уведомлений Linux (notify-send)
• Возможности определения терминала в Linux
• Сравнение функций с платформой Windows
• Проблемы совместимости дистрибутивов Linux

---

Приложение: Справочник по исходному коду

Нажмите, чтобы посмотреть расположение в исходном коде

Дата обновления: 2026-01-27

Функция	Путь к файлу	Строки
Проверка ограничений Windows (osascript)	src/notify.ts	121-133
Проверка ограничений Windows (определение фокуса)	src/notify.ts	166-175
Специфично для macOS: фокусировка по клику	src/notify.ts	238-240
Отправка уведомлений (кроссплатформенно)	src/notify.ts	227-243
Определение терминала (кроссплатформенно)	src/notify.ts	145-164
Загрузка конфигурации (кроссплатформенно)	src/notify.ts	90-114

Ключевые функции:

• runOsascript(): выполняется только на macOS, на Windows возвращает null
• isTerminalFocused(): на Windows сразу возвращает false
• sendNotification(): устанавливает параметр activate только на macOS
• detectTerminalInfo(): кроссплатформенное определение терминала

Определение платформы:

• process.platform === "darwin": macOS
• process.platform === "win32": Windows
• process.platform === "linux": Linux