Справочник по конфигурации

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

✅ Узнаете все настраиваемые параметры и их назначение
✅ Сможете настроить поведение уведомлений под свои нужды
✅ Настроите тихие часы, чтобы избежать отвлечений в определённое время
✅ Поймёте, как различия платформ влияют на конфигурацию

С какими проблемами вы сталкиваетесь

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

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

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

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

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

Файл конфигурации позволяет настраивать поведение плагина без изменения кода — это как «меню настроек» для плагина. Файл конфигурации имеет формат JSON и располагается по пути ~/.config/opencode/kdco-notify.json.

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

Запуск плагина
    ↓
Чтение пользовательского файла конфигурации
    ↓
Объединение с конфигурацией по умолчанию (пользовательские настройки приоритетнее)
    ↓
Работа с объединённой конфигурацией

Путь к файлу конфигурации

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

📋 Описание параметров конфигурации

Полная структура конфигурации

json

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

Подробное описание параметров

notifyChildSessions

Параметр	Тип	По умолчанию	Описание
`notifyChildSessions`	boolean	`false`	Отправлять ли уведомления для дочерних сессий

Назначение: Управляет отправкой уведомлений для дочерних сессий (sub-session).

Что такое дочерняя сессия: При использовании функции мультисессий в OpenCode сессии делятся на родительские и дочерние. Дочерние сессии обычно представляют собой вспомогательные задачи, запущенные родительской сессией, например, чтение/запись файлов, сетевые запросы и т.д.

Поведение по умолчанию (false):

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

При включении (true):

Уведомления отправляются для всех сессий (родительских и дочерних)
Подходит для сценариев, когда нужно отслеживать прогресс всех подзадач

Рекомендуемая настройка

Оставьте значение по умолчанию false, если вам действительно не нужно отслеживать статус каждой подзадачи.

Определение фокуса (macOS)

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

Принцип работы:

Используется osascript в macOS для определения текущего активного приложения
Имя процесса активного приложения сравнивается с именем процесса вашего терминала
Если терминал на переднем плане, уведомление не отправляется
Исключение: уведомления с вопросами (для поддержки рабочего процесса в tmux)

Различия платформ

Функция определения фокуса работает только на macOS. Windows и Linux не поддерживают эту возможность.

sounds

Параметр	Тип	По умолчанию	Поддержка платформ	Описание
`sounds.idle`	string	`"Glass"`	✅ macOS	Звук завершения задачи
`sounds.error`	string	`"Basso"`	✅ macOS	Звук уведомления об ошибке
`sounds.permission`	string	`"Submarine"`	✅ macOS	Звук запроса разрешения
`sounds.question`	string	не задан	✅ macOS	Звук вопроса (опционально)

Назначение: Установка различных системных звуков для разных типов уведомлений (только macOS).

Список доступных звуков:

Название звука	Характеристика	Рекомендуемый сценарий
Glass	Лёгкий, чёткий	Завершение задачи (по умолчанию)
Basso	Низкий, предупреждающий	Уведомление об ошибке (по умолчанию)
Submarine	Напоминающий, мягкий	Запрос разрешения (по умолчанию)
Blow	Мощный	Важные события
Bottle	Чёткий	Завершение подзадачи
Frog	Расслабленный	Неформальные напоминания
Funk	Ритмичный	Завершение нескольких задач
Hero	Величественный	Достижение вехи
Morse	Азбука Морзе	Отладка
Ping	Чёткий	Лёгкие напоминания
Pop	Короткий	Быстрые задачи
Purr	Мягкий	Ненавязчивые напоминания
Sosumi	Уникальный	Особые события
Tink	Звонкий	Завершение небольших задач

Описание поля question: sounds.question — опциональное поле для уведомлений, когда ИИ задаёт вопрос. Если не задано, используется звук из permission.

Советы по настройке звуков

Используйте лёгкие звуки для успеха (idle)
Используйте низкие звуки для ошибок (error)
Используйте мягкие звуки для привлечения внимания (permission, question)
Разные комбинации звуков позволяют понять ситуацию, не глядя на уведомление

Различия платформ

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

quietHours

Параметр	Тип	По умолчанию	Описание
`quietHours.enabled`	boolean	`false`	Включить ли тихие часы
`quietHours.start`	string	`"22:00"`	Время начала тихих часов (формат HH:MM)
`quietHours.end`	string	`"08:00"`	Время окончания тихих часов (формат HH:MM)

Назначение: Подавление всех уведомлений в указанный период времени.

Поведение по умолчанию (enabled: false):

Тихие часы не включены
Уведомления могут приходить в любое время

При включении (enabled: true):

В период с start до end уведомления не отправляются
Поддерживается период, пересекающий полночь (например, 22:00-08:00)

Формат времени:

Используется 24-часовой формат HH:MM
Пример: "22:30" означает 22:30 вечера

Период через полночь:

Если start > end (например, 22:00-08:00), это означает период через полночь
С 22:00 вечера до 08:00 утра следующего дня — тихие часы

Приоритет тихих часов

Тихие часы имеют наивысший приоритет. Даже если все остальные условия выполнены, в период тихих часов уведомления не отправляются.

terminal

Параметр	Тип	По умолчанию	Описание
`terminal`	string	не задан	Ручное указание типа терминала (переопределяет автоопределение)

Назначение: Ручное указание типа используемого эмулятора терминала, переопределяющее автоматическое определение плагина.

Поведение по умолчанию (не задано):

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

При установке:

Плагин использует указанный тип терминала
Используется для определения фокуса и функции фокусировки по клику (macOS)

Распространённые значения для терминалов:

Приложение терминала	Значение конфигурации
Ghostty	`"ghostty"`
Kitty	`"kitty"`
iTerm2	`"iterm2"`
WezTerm	`"wezterm"`
Alacritty	`"alacritty"`
macOS Terminal	`"terminal"`
Hyper	`"hyper"`
Warp	`"warp"`
Встроенный терминал VS Code	`"vscode"`

Когда нужна ручная настройка

Автоопределение не работает, определение фокуса не функционирует
Вы используете несколько терминалов и хотите указать конкретный
Название вашего терминала отсутствует в списке распространённых

Сводка различий платформ

Разные платформы поддерживают параметры конфигурации в разной степени:

Параметр	macOS	Windows	Linux
`notifyChildSessions`	✅	✅	✅
Определение фокуса (встроено)	✅	❌	❌
`sounds.*`	✅	❌	❌
`quietHours.*`	✅	✅	✅
`terminal`	✅	✅	✅

Примечание для пользователей Windows/Linux

Конфигурация sounds и функция определения фокуса не работают на Windows и Linux.

Windows/Linux используют системный звук уведомлений по умолчанию
Windows/Linux не поддерживают определение фокуса (невозможно управлять через конфигурацию)

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

Базовая конфигурация (рекомендуется)

json

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

Эта конфигурация подходит большинству пользователей:

Уведомления только для родительской сессии, без шума от подзадач
На macOS уведомления автоматически подавляются, когда терминал на переднем плане (настройка не требуется)
Используется стандартная комбинация звуков
Тихие часы не включены

Включение тихих часов

json

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

Подходит для пользователей, которые не хотят отвлекаться ночью:

С 22:00 до 08:00 уведомления не отправляются
В остальное время уведомления работают нормально

Отслеживание всех подзадач

json

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

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

Уведомления для всех сессий (родительских и дочерних)
Отдельный звук для вопросов (Ping)

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

json

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

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

Ручное указание терминала Ghostty
Обеспечивает корректную работу определения фокуса и фокусировки по клику

Минимальная конфигурация для Windows/Linux

json

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

Подходит для пользователей Windows/Linux (упрощённая конфигурация):

Только параметры, поддерживаемые платформой
Конфигурация sounds и определение фокуса не работают на Windows/Linux, настраивать не нужно

Управление файлом конфигурации

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

macOS/Linux:

bash

# Создание директории конфигурации (если не существует)
mkdir -p ~/.config/opencode

# Создание файла конфигурации
nano ~/.config/opencode/kdco-notify.json

Windows (PowerShell):

powershell

# Создание директории конфигурации (если не существует)
New-Item -ItemType Directory -Path "$env:APPDATA\opencode" -Force

# Создание файла конфигурации
notepad "$env:APPDATA\opencode\kdco-notify.json"

Проверка файла конфигурации

Проверка существования файла:

bash

# macOS/Linux
cat ~/.config/opencode/kdco-notify.json

# Windows PowerShell
Get-Content "$env:APPDATA\opencode\kdco-notify.json"

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

Измените файл конфигурации
Перезапустите OpenCode (или инициируйте перезагрузку конфигурации)
Проверьте, соответствует ли поведение уведомлений ожиданиям

Обработка ошибок в файле конфигурации

Если формат файла конфигурации неверен:

Плагин игнорирует ошибочный файл конфигурации
Продолжает работу с конфигурацией по умолчанию
Выводит предупреждение в журнал OpenCode

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

Тип ошибки	Пример	Способ исправления
Отсутствует запятая	`"key1": "value1" "key2": "value2"`	Добавьте запятую: `"key1": "value1",`
Лишняя запятая	`"key1": "value1",}`	Удалите последнюю запятую: `"key1": "value1"}`
Незакрытые кавычки	`"key": value`	Добавьте кавычки: `"key": "value"`
Одинарные кавычки	`'key': 'value'`	Используйте двойные кавычки: `"key": "value"`
Ошибка синтаксиса комментария	`{"key": "value" /* comment */}`	JSON не поддерживает комментарии, удалите их

Используйте инструменты валидации JSON

Можно использовать онлайн-инструменты валидации JSON (например, jsonlint.com) для проверки корректности формата файла конфигурации.

Итоги урока

В этом уроке представлен полный справочник по конфигурации opencode-notify:

Основные параметры конфигурации:

Параметр	Назначение	По умолчанию	Поддержка платформ
`notifyChildSessions`	Переключатель уведомлений дочерних сессий	`false`	Все платформы
Определение фокуса	Подавление при фокусе терминала (встроено)	нет настройки	Только macOS
`sounds.*`	Пользовательские звуки	см. поля	Только macOS
`quietHours.*`	Настройка тихих часов	см. поля	Все платформы
`terminal`	Ручное указание терминала	не задан	Все платформы

Принципы конфигурации:

Большинство пользователей: используйте конфигурацию по умолчанию
Нужна тишина: включите quietHours
Нужно отслеживать подзадачи: включите notifyChildSessions
Пользователи macOS: можно настроить sounds, автоматическое определение фокуса работает
Пользователи Windows/Linux: меньше параметров, обратите внимание на notifyChildSessions и quietHours

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

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

В следующем уроке мы изучим Подробно о тихих часах.
Вы узнаете:
Детальный принцип работы тихих часов
Как настроить период через полночь
Приоритет тихих часов относительно других настроек
Распространённые проблемы и их решения

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

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

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

Функция	Путь к файлу	Строки
Определение интерфейса конфигурации	`src/notify.ts`	30-48
Конфигурация по умолчанию	`src/notify.ts`	56-68
Загрузка файла конфигурации	`src/notify.ts`	91-114
Проверка дочерней сессии	`src/notify.ts`	256-259
Проверка фокуса терминала	`src/notify.ts`	265
Проверка тихих часов	`src/notify.ts`	262
Использование конфигурации звуков	`src/notify.ts`	227-236
Пример конфигурации в README	`README.md`	68-79

Интерфейс конфигурации (NotifyConfig):

typescript

interface NotifyConfig {
  /** Уведомлять о событиях дочерних/подсессий (по умолчанию: false) */
  notifyChildSessions: boolean
  /** Конфигурация звуков по типу события */
  sounds: {
    idle: string
    error: string
    permission: string
    question?: string
  }
  /** Конфигурация тихих часов */
  quietHours: {
    enabled: boolean
    start: string // формат "HH:MM"
    end: string // формат "HH:MM"
  }
  /** Переопределение определения терминала (опционально) */
  terminal?: string
}

Примечание: В интерфейсе конфигурации нет поля suppressWhenFocused. Определение фокуса — это встроенное поведение платформы macOS, пользователь не может управлять им через файл конфигурации.

Конфигурация по умолчанию (DEFAULT_CONFIG):

typescript

const DEFAULT_CONFIG: NotifyConfig = {
  notifyChildSessions: false,
  sounds: {
    idle: "Glass",      // Звук завершения задачи
    error: "Basso",     // Звук ошибки
    permission: "Submarine",  // Звук запроса разрешения
  },
  quietHours: {
    enabled: false,     // Тихие часы по умолчанию отключены
    start: "22:00",    // 22:00 вечера
    end: "08:00",      // 08:00 утра
  },
}

Функция загрузки конфигурации (loadConfig):

Путь: ~/.config/opencode/kdco-notify.json
Использует fs.readFile() для чтения файла конфигурации
Объединяет с DEFAULT_CONFIG (пользовательская конфигурация приоритетнее)
Вложенные объекты (sounds, quietHours) также объединяются
При отсутствии файла конфигурации или ошибке формата используется конфигурация по умолчанию

Проверка дочерней сессии (isParentSession):

Проверяет, содержит ли sessionID символ / (идентификатор дочерней сессии)
Если notifyChildSessions равно false, уведомления дочерних сессий пропускаются
Уведомления о запросе разрешений (permission.updated) всегда отправляются, не подчиняются этому ограничению

Проверка фокуса терминала (isTerminalFocused):

Использует osascript для получения имени процесса текущего активного приложения
Сравнивает с processName терминала (без учёта регистра)
Работает только на платформе macOS, невозможно отключить через конфигурацию
Уведомления с вопросами (question) не проверяют фокус (для поддержки рабочего процесса в tmux)

Проверка тихих часов (isQuietHours):

Преобразует текущее время в минуты (от полуночи)
Сравнивает с настроенными start и end
Поддерживает период через полночь (например, 22:00-08:00)
Если start > end, это означает период через полночь

Использование конфигурации звуков (sendNotification):

Читает название звука для соответствующего события из конфигурации
Передаёт в опцию sound библиотеки node-notifier
Работает только на платформе macOS
Если для события question звук не настроен, используется звук из permission

Справочник по конфигурации ​

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

С какими проблемами вы сталкиваетесь ​

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

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

📋 Описание параметров конфигурации ​

Полная структура конфигурации ​

Подробное описание параметров ​

notifyChildSessions ​

Определение фокуса (macOS) ​

sounds ​

quietHours ​

terminal ​

Сводка различий платформ ​

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

Базовая конфигурация (рекомендуется) ​

Включение тихих часов ​

Отслеживание всех подзадач ​

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

Минимальная конфигурация для Windows/Linux ​

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

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

Проверка файла конфигурации ​

Обработка ошибок в файле конфигурации ​

Итоги урока ​

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

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

Справочник по конфигурации

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

С какими проблемами вы сталкиваетесь

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

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

📋 Описание параметров конфигурации

Полная структура конфигурации

Подробное описание параметров

notifyChildSessions

Определение фокуса (macOS)

sounds

quietHours

terminal

Сводка различий платформ

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

Базовая конфигурация (рекомендуется)

Включение тихих часов

Отслеживание всех подзадач

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

Минимальная конфигурация для Windows/Linux

Управление файлом конфигурации

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

Проверка файла конфигурации

Обработка ошибок в файле конфигурации

Итоги урока

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

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