Устранение неполадок: уведомления не отображаются, фокус не определяется и другие проблемы

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

• Быстро определить причину отсутствия уведомлений
• Решить проблемы с разрешениями уведомлений macOS
• Диагностировать проблемы с определением фокуса
• Исправить ошибки формата файла конфигурации
• Понять различия функциональности на разных платформах

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

AI выполнил задачу, но вы не получили уведомление; или после нажатия на уведомление терминал не выводится на передний план. Вы не знаете, в чём проблема, и не знаете, с чего начать диагностику.

Когда использовать этот метод

• При первом использовании после установки плагина вы не получили никаких уведомлений
• После обновления плагина или системы уведомления перестали работать
• Вы хотите отключить определённые поведения уведомлений, но конфигурация, кажется, не применяется
• При переходе с macOS на Windows/Linux вы обнаружили, что некоторые функции недоступны

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

Рабочий процесс opencode-notify довольно прост, но включает множество этапов: OpenCode SDK → прослушивание событий → логика фильтрации → системные уведомления. Любая проблема на любом этапе может привести к тому, что уведомления не будут отображаться.

Ключ к диагностике — последовательно проверять каждый этап, начиная с наиболее вероятных причин. 80% проблем можно решить с помощью следующих 5 категорий:

1. Уведомления не отображаются — самая распространённая проблема
2. Определение фокуса не работает (только macOS)
3. Конфигурация не применяется — ошибки формата JSON или неправильный путь
4. Звук не воспроизводится (только macOS)
5. Различия платформ — некоторые функции не поддерживаются

---

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

Это самая распространённая проблема, возможные причины — 6. Проверьте по порядку:

1.1 Проверьте, правильно ли установлен плагин

Симптомы: OpenCode работает нормально, но вы никогда не получали никаких уведомлений.

Шаги диагностики:

# Проверьте, установлен ли плагин
ls ~/.opencode/plugin/kdco-notify

# Если не существует, переустановите
ocx add kdco/notify

Что вы должны увидеть: Существование каталога ~/.opencode/plugin/kdco-notify, содержащего файлы package.json и src/notify.ts и т. д.

Проверка при ручной установке

Если вы используете ручную установку, убедитесь:

1. Зависимости установлены: npm install node-notifier detect-terminal
2. Файлы плагина находятся в правильном месте: ~/.opencode/plugin/
3. OpenCode перезапущен (изменения плагина требуют перезапуска)

1.2 Проверьте разрешения уведомлений macOS

Симптомы: Только для пользователей macOS, плагин установлен, но вы никогда не получали уведомлений.

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

Шаги диагностики:

# 1. Откройте системные настройки
# macOS Ventura и выше: Системные настройки → Уведомления и режим фокуса
# macOS старые версии: Системные настройки → Уведомления

# 2. Найдите ваше терминальное приложение (например, Ghostty, iTerm2, Terminal.app)
# 3. Убедитесь, что "Разрешить уведомления" включено
# 4. Убедитесь, что "На экране блокировки" и "Показывать баннер на экране блокировки" включены

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

Распространённая ошибка

Сам OpenCode не появится в настройках уведомлений, вам нужно авторизовать терминальное приложение (Ghostty, iTerm2, Terminal.app и т. д.), а не OpenCode.

1.3 Проверьте настройки тихого режима

Симптомы: Нет уведомлений в определённое время, уведомления есть в другое время.

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

Шаги диагностики:

# Проверьте файл конфигурации
cat ~/.config/opencode/kdco-notify.json

Решение:

{
  "quietHours": {
    "enabled": false,  // Измените на false, чтобы отключить тихий режим
    "start": "22:00",
    "end": "08:00"
  }
}

Что вы должны увидеть: quietHours.enabled равно false, или текущее время не находится в тихом режиме.

Тихий режим через полночь

Тихий режим поддерживает переход через полночь (например, 22:00-08:00), это правильное поведение. Если текущее время между 22:00 и 08:00 следующего дня, уведомления будут подавлены.

1.4 Проверьте фокус окна терминала

Симптомы: Когда вы смотрите на терминал, вы не получаете уведомления.

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

Шаги диагностики:

Проверьте, сфокусирован ли терминал:

1. Переключитесь на другое приложение (например, браузер, VS Code)
2. Пусть AI выполнит задачу
3. Дождитесь завершения задачи

Что вы должны увидеть: В других приложениях уведомления отображаются нормально.

Описание определения фокуса

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

1.5 Проверьте фильтрацию дочерних сессий

Симптомы: AI выполнил несколько подзадач, но вы не получили уведомление для каждой подзадачи.

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

Шаги диагностики:

Понимание родительских и дочерних сессий:

• Родительская сессия: задача, которую вы напрямую попросили AI выполнить (например, "оптимизировать кодовую базу")
• Дочерняя сессия: подзадачи, которые AI разбил сам (например, "оптимизировать src/components", "оптимизировать src/utils")

Если вам действительно нужны уведомления о дочерних сессиях:

{
  "notifyChildSessions": true
}

Что вы должны увидеть: Вы получаете уведомление при завершении каждой дочерней сессии.

Рекомендуемый подход

Если вы не отслеживаете несколько параллельных задач, сохраните notifyChildSessions: false, получайте только уведомления о родительских сессиях.

1.6 Проверьте, не был ли удалён или переименован файл конфигурации

Симптомы: Ранее были уведомления, внезапно перестали отображаться.

Шаги диагностики:

# Проверьте, существует ли файл конфигурации
ls -la ~/.config/opencode/kdco-notify.json

Решение:

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

Удалите файл конфигурации, восстановите по умолчанию:

# Удалите файл конфигурации, используйте настройки по умолчанию
rm ~/.config/opencode/kdco-notify.json

Что вы должны увидеть: Плагин снова начинает отправлять уведомления (используя конфигурацию по умолчанию).

---

Проблема 2: Определение фокуса не работает (только macOS)

Симптомы: Когда вы смотрите на терминал, вы всё равно получаете уведомления, определение фокуса, кажется, не работает.

2.1 Проверьте, правильно ли определяется терминал

Причина: Плагин использует библиотеку detect-terminal для автоматического определения терминала, если определение не удаётся, определение фокуса не работает.

Шаги диагностики:

# Проверьте, нормально ли работает определение терминала
node -e "console.log(require('detect-terminal')())"

Что вы должны увидеть: Вывод названия вашего терминала (например, ghostty, iterm2 и т. д.).

Если вывод пуст, определение терминала не удалось.

2.2 Укажите тип терминала вручную

Если автоматическое определение не удалось, можно указать вручную:

{
  "terminal": "ghostty"  // Замените на название вашего терминала
}

Поддерживаемые названия терминалов (в нижнем регистре):

Терминал	Название	Терминал	Название
Ghostty	ghostty	Kitty	kitty
iTerm2	iterm2 или iterm	WezTerm	wezterm
Alacritty	alacritty	macOS Terminal	terminal или apple_terminal
Hyper	hyper	Warp	warp
Терминал VS Code	vscode	VS Code Insiders	vscode-insiders

Сопоставление имён процессов

Внутри плагина есть таблица сопоставления имён терминалов с именами процессов macOS. Если вы вручную указали terminal, убедитесь, что используете имя из таблицы сопоставления (строки 71-84).

---

Проблема 3: Конфигурация не применяется

Симптомы: Вы изменили файл конфигурации, но поведение плагина не изменилось.

3.1 Проверьте правильность формата JSON

Распространённые ошибки:

// ❌ Ошибка: отсутствуют кавычки
{
  notifyChildSessions: true
}

// ❌ Ошибка: завершающая запятая
{
  "notifyChildSessions": true,
}

// ❌ Ошибка: комментарии не поддерживаются
{
  "notifyChildSessions": true  // Это приведёт к ошибке разбора JSON
}

Правильный формат:

{
  "notifyChildSessions": false,
  "sounds": {
    "idle": "Glass",
    "error": "Basso",
    "permission": "Submarine"
  },
  "quietHours": {
    "enabled": false,
    "start": "22:00",
    "end": "08:00"
  }
}

Проверка формата JSON:

# Используйте jq для проверки формата JSON
cat ~/.config/opencode/kdco-notify.json | jq '.'

# Если выводится форматированный JSON, формат правильный
# Если ошибка, JSON имеет проблемы

3.2 Проверьте путь к файлу конфигурации

Симптомы: Файл конфигурации создан, но плагин, кажется, его не читает.

Правильный путь:

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

Шаги диагностики:

# Проверьте, существует ли файл конфигурации
ls -la ~/.config/opencode/kdco-notify.json

# Если не существует, создайте каталог и файл
mkdir -p ~/.config/opencode
cat > ~/.config/opencode/kdco-notify.json << 'EOF'
{
  "notifyChildSessions": false
}
EOF

3.3 Перезапустите OpenCode

Причина: Плагин загружает конфигурацию один раз при запуске, после изменения требуется перезапуск.

Шаги диагностики:

# Полностью перезапустите OpenCode
# 1. Выйдите из OpenCode
# 2. Снова запустите OpenCode

---

Проблема 4: Звук не воспроизводится (только macOS)

Симптомы: Уведомления отображаются нормально, но звук не воспроизводится.

4.1 Проверьте правильность названия звука

Поддерживаемые звуки macOS:

Название звука	Описание	Название звука	Описание
Basso	Бас	Blow	Звук дутья
Bottle	Звук бутылки	Frog	Звук лягушки
Funk	Фанк	Glass	Звук стекла (по умолчанию для завершения задачи)
Hero	Герой	Morse	Азбука Морзе
Ping	Звук "дзынь"	Pop	Звук пузырька
Purr	Мурлыканье	Sosumi	Sosumi
Submarine	Подводная лодка (по умолчанию для запроса разрешения)	Tink	Звук "дзынь-дзынь"

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

{
  "sounds": {
    "idle": "Glass",      // Звук завершения задачи
    "error": "Basso",    // Звук ошибки
    "permission": "Submarine",  // Звук запроса разрешения
    "question": "Ping"   // Звук вопроса (опционально)
  }
}

4.2 Проверьте настройки громкости системы

Шаги диагностики:

# Откройте Системные настройки → Звук → Громкость вывода
# Убедитесь, что звук не отключён, и громкость умеренная

4.3 Другие платформы не поддерживают пользовательские звуки

Симптомы: Пользователи Windows или Linux настроили звуки, но нет звука.

Причина: Пользовательские звуки — уникальная функция macOS, Windows и Linux не поддерживают.

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

Звуки на Windows/Linux

Звуки уведомлений на Windows и Linux контролируются системными настройками:

• Windows: Параметры → Система → Уведомления → Выберите звук уведомления
• Linux: Настройки среды рабочего стола → Уведомления → Звуки

---

Проблема 5: Нажатие на уведомление не фокусирует (только macOS)

Симптомы: После нажатия на уведомление окно терминала не выводится на передний план.

5.1 Проверьте, успешно ли получен Bundle ID

Причина: Функция фокусировки при нажатии на уведомление требует получения Bundle ID терминала (например, com.ghostty.Ghostty), если получение не удаётся, фокусировка невозможна.

Шаги диагностики:

Плагин автоматически определяет терминал и получает Bundle ID при запуске. Если не удаётся, функция фокусировки при нажатии на уведомление недоступна.

Распространённые причины:

1. Терминал не в таблице сопоставления (например, пользовательский терминал)
2. Выполнение osascript не удалось (проблема с разрешениями macOS)

Решение: Укажите тип терминала вручную (см. раздел 2.2).

5.2 Проверьте разрешения системной вспомогательной технологии

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

Шаги диагностики:

# Откройте Системные настройки → Конфиденциальность и безопасность → Вспомогательные технологии
# Убедитесь, что у терминального приложения есть разрешение вспомогательных технологий

Что вы должны увидеть: Ваше терминальное приложение (Ghostty, iTerm2 и т. д.) в списке вспомогательных технологий, и переключатель включён.

---

Проблема 6: Различия функциональности платформ

Симптомы: При переходе с macOS на Windows/Linux вы обнаружили, что некоторые функции недоступны.

6.1 Таблица сравнения функций

Функция	macOS	Windows	Linux
Нативные уведомления	✅	✅	✅
Пользовательские звуки	✅	❌	❌
Определение фокуса	✅	❌	❌
Фокус при нажатии на уведомление	✅	❌	❌
Определение терминала	✅	✅	✅
Тихий режим	✅	✅	✅
Уведомления дочерних сессий	✅	✅	✅

Описание:

• Windows/Linux: Поддерживаются только базовые функции уведомлений, расширенные функции (определение фокуса, фокус при нажатии, пользовательские звуки) недоступны
• macOS: Поддерживаются все функции

6.2 Кроссплатформенная совместимость файла конфигурации

Проблема: На macOS настроен sounds, после перехода на Windows звуки не применяются.

Причина: Конфигурация sounds действует только на macOS.

Решение: Файл конфигурации можно использовать на разных платформах, плагин автоматически игнорирует неподдерживаемые элементы конфигурации. Не нужно удалять поле sounds, Windows/Linux будут тихо игнорировать.

Рекомендуемая практика

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

---

Итоги урока

Диагностику неполадок opencode-notify можно свести к следующим 6 категориям проблем:

1. Уведомления не отображаются: Проверьте установку плагина, разрешения уведомлений macOS, тихий режим, фокус терминала, фильтрацию дочерних сессий, отключён ли плагин
2. Определение фокуса не работает (macOS): Проверьте, правильно ли определяется терминал, или укажите тип терминала вручную
3. Конфигурация не применяется: Проверьте формат JSON, путь к файлу конфигурации, перезапустите OpenCode
4. Звук не воспроизводится (macOS): Проверьте правильность названия звука, подтвердите, что звуки поддерживаются только на macOS
5. Нажатие на уведомление не фокусирует (macOS): Проверьте получение Bundle ID и разрешения вспомогательных технологий
6. Различия функциональности платформ: Windows/Linux поддерживают только базовые уведомления, расширенные функции доступны только на macOS

Быстрый контрольный список:

□ Плагин правильно установлен?
□ Разрешения уведомлений macOS авторизованы?
□ Тихий режим включён?
□ Терминал сфокусирован?
□ Фильтрация дочерних сессий включена?
□ Формат JSON файла конфигурации правильный?
□ Путь к файлу конфигурации правильный?
□ OpenCode перезапущен?
□ Название звука в списке поддерживаемых (только macOS)?
□ Bundle ID получен успешно (только macOS)?
□ Громкость системы нормальная?

---

Предпросмотр следующего урока

В следующем уроке мы изучим Часто задаваемые вопросы.

Вы узнаете:

• Увеличивает ли opencode-notify нагрузку на контекст диалога
• Получите ли вы много уведомлений (бомбардировка)
• Как временно отключить уведомления
• Влияние на производительность и вопросы безопасности конфиденциальности

---

Приложение: Ссылка на исходный код

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

Время обновления: 2026-01-27

Функция	Путь к файлу	Строки
Загрузка конфигурации и обработка ошибок	src/notify.ts	90-114
Определение терминала	src/notify.ts	145-164
Выполнение osascript macOS	src/notify.ts	120-133
Определение фокуса терминала	src/notify.ts	166-175
Проверка тихого режима	src/notify.ts	181-199
Определение родительской сессии	src/notify.ts	205-214
Отправка уведомления	src/notify.ts	227-243
Конфигурация по умолчанию	src/notify.ts	56-68
Сопоставление имён процессов терминала	src/notify.ts	71-84
Обработка завершения задачи	src/notify.ts	249-284
Обработка уведомления об ошибке	src/notify.ts	286-313
Обработка запроса разрешения	src/notify.ts	315-334
Обработка вопроса	src/notify.ts	336-351

Ключевые константы:

• DEFAULT_CONFIG: Конфигурация по умолчанию (строки 56-68)

  • notifyChildSessions: false: По умолчанию не уведомлять о дочерних сессиях
  • sounds.idle: "Glass": Звук завершения задачи
  • sounds.error: "Basso": Звук ошибки
  • sounds.permission: "Submarine": Звук запроса разрешения
  • quietHours.start: "22:00", quietHours.end: "08:00": Тихий режим по умолчанию

• TERMINAL_PROCESS_NAMES: Сопоставление имён терминалов с именами процессов macOS (строки 71-84)

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

• loadConfig(): Загружает и объединяет файл конфигурации с конфигурацией по умолчанию, использует значения по умолчанию, если файл конфигурации не существует или недействителен
• detectTerminalInfo(): Определяет информацию о терминале (имя, Bundle ID, имя процесса)
• isTerminalFocused(): Проверяет, является ли терминал текущим приложением переднего плана (macOS)
• isQuietHours(): Проверяет, находится ли текущее время в тихом режиме
• isParentSession(): Проверяет, является ли сессия родительской
• sendNotification(): Отправляет нативное уведомление, поддерживает фокус при нажатии на macOS
• runOsascript(): Выполняет AppleScript (macOS), возвращает null при неудаче
• getBundleId(): Получает Bundle ID приложения (macOS)

Бизнес-правила:

• BR-1-1: По умолчанию уведомлять только о родительских сессиях, не о дочерних (notify.ts:256-259)
• BR-1-2: Подавлять уведомления, когда терминал сфокусирован (notify.ts:265)
• BR-1-3: Не отправлять уведомления в тихом режиме (notify.ts:262)
• BR-1-4: Запросы разрешений всегда уведомляются, проверка родительской сессии не требуется (notify.ts:319)
• BR-1-5: Вопросы не проверяют фокус, поддерживают рабочий процесс tmux (notify.ts:340)
• BR-1-6: macOS поддерживает фокус терминала при нажатии на уведомление (notify.ts:238-240)

Обработка исключений:

• loadConfig(): При отсутствии файла конфигурации или ошибке разбора JSON использует конфигурацию по умолчанию (notify.ts:110-113)
• isParentSession(): При неудаче запроса сессии предполагает, что это родительская сессия (уведомить, а не пропустить) (notify.ts:210-212)
• runOsascript(): При неудаче выполнения osascript возвращает null (notify.ts:120-132)
• handleSessionIdle(): При неудаче получения информации о сессии использует заголовок по умолчанию (notify.ts:274-276)