Особенности платформы Linux: уведомления notify-send и обнаружение терминала

Что вы сможете делать после изучения

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

Ваша текущая ситуация

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

Когда использовать эту информацию

Узнайте об особенностях платформы Linux в следующих сценариях:

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

Основная концепция

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

Почему macOS имеет более богатый функционал?

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

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

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

Обзор функций платформы Linux

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

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

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

Моменты срабатывания уведомлений:

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

Особенности уведомлений notify-send

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

Обнаружение терминала

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

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

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

gnome-terminal (по умолчанию для GNOME)
konsole (для KDE)
xterm
lxterminal (для LXDE)
alacritty
kitty
terminator
guake
tilix
hyper
Встроенный терминал VS Code
И более 37 других эмуляторов терминала

Принцип обнаружения терминала

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

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

Функция detectTerminalInfo() выполняет следующее:

Читает поле terminal из конфигурации (если указано вручную)
Вызывает detectTerminal() для автоматического обнаружения типа терминала
Получает имя процесса (используется для обнаружения фокуса на macOS)
На macOS получает bundle ID (используется для клика для фокусировки)

На платформе Linux поля bundleId и processName будут null, поскольку Linux не требует этой информации.

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

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

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

json

{
  "terminal": "gnome-terminal"
}

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

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

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

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

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

typescript

// 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
}

Причины:

Разнообразие окружений рабочего стола Linux (GNOME, KDE, XFCE и др.), нет единого API для запроса активного приложения
Linux DBus может получать активное окно, но реализация сложна и зависит от окружения рабочего стола
В текущей версии приоритет отдается стабильности, обнаружение фокуса на Linux пока не реализовано

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

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

typescript

// src/notify.ts:238-240
// Только для macOS: клик по уведомлению для фокусировки терминала
if (process.platform === "darwin" && terminalInfo.bundleId) {
	notifyOptions.activate = terminalInfo.bundleId
}

Причины:

notify-send не поддерживает параметр activate
Уведомления Linux могут связываться только через ID приложения, нельзя динамически указать целевое окно
Клик по уведомлению открывает центр уведомлений, а не фокусирует конкретное окно

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

Принцип конфигурации звуков

На macOS функция sendNotification() передает параметр sound системному уведомлению:

typescript

// src/notify.ts:227-243
function sendNotification(options: NotificationOptions): void {
	const { title, message, sound, terminalInfo } = options
	
	const notifyOptions: Record<string, unknown> = {
		title,
		message,
		sound,  // ← macOS принимает этот параметр
	}
	
	// Только для macOS: клик по уведомлению для фокусировки терминала
	if (process.platform === "darwin" && terminalInfo.bundleId) {
		notifyOptions.activate = terminalInfo.bundleId
	}
	
	notifier.notify(notifyOptions)
}

Linux notify-send не поддерживает параметр пользовательского звука, поэтому конфигурация sounds на Linux не работает.

Лучшие практики для платформы Linux

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

Следующие параметры конфигурации не работают на Linux:

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

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

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

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

Кликните по иконке уведомлений в правом верхнем углу экрана
Отключите уведомления opencode-notify

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

Установите рабочее время и время отдыха, чтобы избежать отвлечений в нерабочее время:

json

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

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

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

Совет 4: Настройка системного звука уведомлений

Хотя opencode-notify не поддерживает пользовательские звуки, вы можете изменить звук уведомлений по умолчанию в настройках системы:

GNOME: Настройки → Звук → Системные звуки
KDE: Системные настройки → Уведомления → Звук по умолчанию
XFCE: Настройки → Оформление → Уведомления → Звук

Практическое руководство

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

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

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

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

Вы должны увидеть:

Всплывающее уведомление notify-send в правом верхнем углу экрана (GNOME/Ubuntu)
Заголовок уведомления "Ready for review"
Воспроизведение системного звука уведомлений по умолчанию

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

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

Вы должны увидеть:

Уведомление все равно появится (поскольку Linux не поддерживает обнаружение фокуса)

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

Кликните по появившемуся уведомлению.

Вы должны увидеть:

Раскрытие центра уведомлений, а не переключение на окно терминала

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

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

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

bash

nano ~/.config/opencode/kdco-notify.json

Шаг 2: Добавление конфигурации тихих часов

json

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

Шаг 3: Сохранение и тестирование

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

Вы должны увидеть:

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

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

После выполнения вышеуказанных шагов, пожалуйста, подтвердите:

[ ] Уведомления notify-send отображаются нормально
[ ] Уведомления показывают правильный заголовок задачи
[ ] Конфигурация тихих часов работает
[ ] Понимание неподдерживаемых функций на платформе Linux

Предупреждения о распространенных проблемах

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

Причина 1: notify-send не установлен

Решение:

bash

# Ubuntu/Debian
sudo apt install libnotify-bin

# Fedora/RHEL
sudo dnf install libnotify

# Arch Linux
sudo pacman -S libnotify

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

Решение:

Откройте системные настройки
Найдите "Уведомления" или "Конфиденциальность" → "Уведомления"
Убедитесь, что включено "Разрешить приложениям отправлять уведомления"
Найдите OpenCode и убедитесь, что разрешения на уведомления включены

Проблема 2: Ошибка обнаружения терминала

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

Решение:

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

json

{
  "terminal": "gnome-terminal"
}

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

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

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

Решение: Измените звук уведомлений по умолчанию в настройках системы.

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

Причина: notify-send не поддерживает параметр activate

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

Проблема 5: Различия в поведении уведомлений в разных окружениях рабочего стола

Проявление: В разных окружениях рабочего стола (GNOME, KDE, XFCE) положение и поведение уведомлений могут отличаться.

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

Решение: В зависимости от используемого окружения рабочего стола, настройте поведение уведомлений в системных настройках.

Резюме урока

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

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

Ключевые моменты:

Функциональность платформы Linux относительно базовая, но основные возможности уведомлений полные
Обнаружение фокуса и клик для фокусировки - уникальные функции macOS
Через конфигурацию тихих часов можно уменьшить шум от уведомлений
Обнаружение терминала поддерживает ручное указание для повышения совместимости
notify-send требует предварительной установки (некоторые дистрибутивы включают по умолчанию)

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

В следующем уроке мы изучим Поддерживаемые терминалы.
Вы узнаете:
Список из 37+ терминалов, поддерживаемых opencode-notify
Механизмы обнаружения различных терминалов
Методы настройки типа терминала
Советы по использованию встроенного терминала VS Code

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

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

Обновлено: 2026-01-27

Функция	Путь к файлу	Строки
Проверка ограничений платформы Linux (osascript)	`src/notify.ts`	121-133
Проверка ограничений платформы Linux (обнаружение фокуса)	`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, на Linux возвращает null
isTerminalFocused(): на Linux сразу возвращает false
sendNotification(): устанавливает параметр activate только на macOS
detectTerminalInfo(): кроссплатформенное обнаружение терминала

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

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

Зависимости уведомлений Linux:

Внешняя зависимость: node-notifier → команда notify-send
Системные требования: libnotify-bin или эквивалентный пакет

Особенности платформы Linux: уведомления notify-send и обнаружение терминала ​

Что вы сможете делать после изучения ​

Ваша текущая ситуация ​

Когда использовать эту информацию ​

Основная концепция ​

Обзор функций платформы Linux ​

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

Обнаружение терминала ​

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

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

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

Почему Linux не поддерживает обнаружение фокуса? ​

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

Почему Linux не поддерживает пользовательские звуки? ​

Лучшие практики для платформы Linux ​

Рекомендации по конфигурации ​

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

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

Практическое руководство ​

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

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

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

Предупреждения о распространенных проблемах ​

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

Проблема 2: Ошибка обнаружения терминала ​

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

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

Проблема 5: Различия в поведении уведомлений в разных окружениях рабочего стола ​

Резюме урока ​

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

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

Особенности платформы Linux: уведомления notify-send и обнаружение терминала

Что вы сможете делать после изучения

Ваша текущая ситуация

Когда использовать эту информацию

Основная концепция

Обзор функций платформы Linux

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

Обнаружение терминала

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

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

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

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

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

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

Лучшие практики для платформы Linux

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

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

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

Практическое руководство

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

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

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

Предупреждения о распространенных проблемах

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

Проблема 2: Ошибка обнаружения терминала

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

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

Проблема 5: Различия в поведении уведомлений в разных окружениях рабочего стола

Резюме урока

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

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