Руководство пользователя

В этом документе собрано все про повседневное использование Polynya: как устроена компоновка в панели задач, что умеет поиск-лаунчер, как настраиваются плеер и погода, как установить, обновить и удалить программу, где лежат файлы и какие ключи есть в config.ini и командной строке.

1. Как остров живет в панели задач

Кликабельность трея и иконок. Окно утилиты растянуто на всю ширину панели задач основного монитора, но перехватывает мышь только там, где что-то нарисовано (блоки острова, чипы уведомлений, открытая выпадашка). Все остальное пространство прозрачно для кликов - системный трей и иконки запущенных программ работают как обычно.
Расположение иконок Windows (TaskbarAl). Если в Windows 11 иконки панели задач стоят по центру, остров автоматически встает в свободную левую часть панели (до кнопки "Пуск") и растет вправо. Если иконки выровнены по левому краю - остров встает строго по центру панели задач.
Панель снизу или сверху. Поддерживаются оба варианта. Если панель задач внизу, выпадашки растут из нее вверх (зеркальной формой). При вертикальной панели (сбоку экрана) остров прячется.
Несколько мониторов. Остров живет на мониторе основной панели задач и автоматически переезжает вместе с ней, если поменять главный дисплей или разрешение.
Полноэкранный режим. Когда на мониторе открыта полноэкранная игра, видео или презентация, остров прячется и полностью перестает считать кадры и анализировать звук. При этом вызов поиска по Alt+Space все равно сработает поверх полноэкранного окна.

Компоновка блоков

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

Остров по центру (когда иконки Windows выровнены по левому краю):
1. Плеер и визуализатор (растет влево);
2. Время и погода (стоит строго по центру на подложке);
3. Кнопка поиска (лупа на подложке, растет вправо);
4. Правая зона уведомлений (чипы и стопка "+N", растут вправо). При наведении сегмент раздается вправо, не сдвигая центральный блок времени.
Остров слева (когда иконки Windows стоят по центру панели задач): Остров занимает свободную левую часть до кнопки "Пуск" и весь растет слева направо:
1. Время и погода (на подложке);
2. Кнопка поиска (на подложке);
3. Плеер и визуализатор;
4. Зона уведомлений (чипы и стопка "+N").

2. Время и погода

Часы

Показывают текущее время и дату; при смене минуты меняющиеся цифры плавно прокручиваются.
Наведение: показывает время рассвета и заката.
Клик: открывает стандартный системный центр уведомлений и календарь Windows.

Погода

Данные берутся из Open-Meteo (бесплатно и без API-ключей).
Определение города: по умолчанию работает через системную геолокацию Windows (Geolocator) с обратным геокодингом через Nominatim (OpenStreetMap) - в этом режиме рядом с названием города горит значок навигации. Либо можно выключить автоопределение в настройках и вписать любой город вручную (меняется на лету, без перезапуска).
Наведение: показывает температуру "Ощущается как", скорость ветра и влажность.
Клик: раскрывает выпадашку с почасовым прогнозом на ближайшее время и прогнозом на 3 дня вперед.

3. Плеер и визуализатор

Поддержка плееров: подхватывает любое приложение, которое транслирует медиасессию в Windows (GSMTC) - Spotify, браузеры (YouTube, Яндекс Музыка, SoundCloud и т.д.), Telegram, классические плееры. Если открыто несколько плееров сразу, приоритет отдается тому, который играет прямо сейчас.
Бегущая строка: длинные названия треков плавно прокручиваются силами системного композитора DWM (почти не нагружая процессор).
Наведение и клик: при наведении появляются кнопки управления (назад / пауза / вперед), полоса прогресса и тайминг. По клику открывается выпадашка с крупной обложкой на фоне ее размытой копии и перемоткой трека по клику на полосу.
Изолированный визуализатор: 5 полос спектра слушают аудиопоток конкретного процесса плеера (включая дочерние процессы браузеров) через WASAPI process loopback. Звуки игры или уведомления мессенджеров на эквалайзер не влияют. Полосы показывают не сухую громкость, а динамику (превышение над средним фоном за последние 1,5 секунды).

4. Поиск-лаунчер (`Alt+Space` или клик по лупе)

Лаунчер закрывает запуск софта, вызов внутренних команд, поиск файлов и быстрые вычисления. Каталог программ прогревается в фоне через 10 секунд после старта системы, поэтому поиск открывается мгновенно.

Что можно искать и делать

Приложения и команды модулей. Ищет по всем классическим и магазинным программам (shell:AppsFolder) с поддержкой нечеткого ввода (например, vsc найдет Visual Studio Code). Встроенные команды ("Настройки", "Пипетка" и команды сторонних модулей) ищутся по названию и ключевым словам сразу на всех поддерживаемых языках.
Недавние. На пустом запросе показывает список недавно запущенных программ и команд вперемешку. При вводе текста частые позиции получают небольшую прибавку к весу (при равной оценке команда модуля всегда выше обычной программы).
Поиск файлов (через Everything). Если в системе установлен и запущен Everything, при вводе от нескольких символов в выдаче сразу появляются файлы и папки. Если Everything не установлен - внизу предлагается строка "Искать в Windows".
Калькулятор. Считает прямо по мере ввода:
- Арифметика, скобки, константы (pi), корни (√16), тригонометрия в градусах (sin(30));
- Сравнения с допуском погрешности чисел с плавающей точкой (0.1 + 0.2 == 0.3 -> true);
- Операции со строками ("ха" * 3 -> хахаха).
- Нажатие Enter копирует ответ в буфер обмена. Последний расчет помнится 10 минут после закрытия окна - можно снова открыть поиск и сразу дописать + 15.
Конвертер валют. Понимает запросы на естественном языке и коды валют: 100$, 100 usd в eur, 10 долларов в рубли. Если целевая валюта не указана (100$), переводит в домашнюю валюту вашего региона Windows. Курсы берутся с open.er-api.com, дата обновления курса пишется в подсказке справа.

Контекстное меню и ввод

Меню действий по ПКМ: клик правой кнопкой мыши по строке в результатах плавно раскрывает подменю прямо внутри выпадашки: Открыть, Запустить от администратора, Показать в проводнике, Скопировать путь, Убрать из недавних, Удалить программу (повторный ПКМ сворачивает меню).
Полноценное поле ввода: работают выделение мышью и с клавиатуры, Ctrl+A/C/X/V, многоуровневый откат Ctrl+Z, прыжки и удаление по словам (Ctrl+Стрелки, Ctrl+Backspace), а также азиатские методы ввода (IME) с сохранением раскладки окна, из которого вы вызвали поиск.

5. Модули

Все, что сверх лаунчера, времени с погодой, плеера и стека уведомлений, делают модули. Они включаются и выключаются в настройках (раздел 6), а как написать свой - описано в API модулей.

ИИ-агенты (модуль `agents`)

Показывает в стеке уведомлений статус Claude Code, Codex, Cursor и Kimi Code: агент думает, редактирует файл, ждет ввода или закончил. Хуки прописываются в конфиги агентов при включении модуля и убираются при выключении. Подробности - в документе Уведомления, ИИ-агенты и терминал.

Пипетка (модуль `picker`)

Вызывается командой "Пипетка" (Color picker) из лаунчера.

Открывает живую экранную лупу без заморозки изображения на мониторе (может брать цвет даже с самого острова).
По клику копирует HEX-код цвета в буфер обмена и выводит в панель задач чип.
Если кликнуть по чипу пипетки, раскроется палитра из 11 оттенков этого цвета в пространстве OKLCH (по принципу шкалы Tailwind, где ваш исходный цвет встает на ближайшую ступень без искажений). Клик по любому квадратику копирует его HEX.

Уведомления Windows (модуль `notify`, экспериментальный)

По умолчанию выключен. Показывает системные уведомления Windows в острове вместо стандартных баннеров. При включении один раз запрашивает UAC, чтобы зарегистрировать пакет модуля. Подробности и ограничения - в документе Уведомления, ИИ-агенты и терминал.

Девтулз (модуль `devtools`)

В разработке: в текущем релизе пока не поставляется, появится в одном из следующих.

Небольшие инструменты для веб-разработки. Модуль работает на Node.js: он должен быть установлен и доступен в PATH.

Преобразование выделенного (Ctrl+Alt+D). Выделите значение в любой программе (или скопируйте его) и нажмите сочетание. Появится список вариантов; Enter копирует выбранный, показывает чип и возвращает фокус в программу, так что Ctrl+V вставит результат на место. Значения внутри строки CSS меняются на месте: padding: 16px 24px превращается в padding: 1rem 1.5rem.
- Размеры: px, rem, em, pt; из двух размеров (16px 24px) получается еще и резиновый clamp().
- Цвета: HEX, RGB, HSL, OKLCH.
- Unix-время (секунды и миллисекунды) и даты ISO 8601.
- JSON (с отступами и в одну строку), JWT (заголовок и данные), Base64, URL-кодировка, регистр имен (camelCase, snake_case, kebab-case и другие).
Команда Девтулз в поиске открывает список инструментов: конвертер, резиновый размер с проверкой на трех ширинах экрана, генерация ID (UUID, nanoid, hex), текущее время, хеши (SHA-256, SHA-1, MD5) и текст-рыба.
Настройки (в том же списке): корневой размер шрифта для rem, диапазон ширины экрана для clamp() и число знаков после запятой.
Сочетание можно поменять или выключить в config.ini: hotkey.devtools.convert = Ctrl+Shift+Q.

Свой "Пуск" (модуль `start`)

В разработке: в текущем релизе пока не поставляется, появится в одном из следующих.

Заменяет громоздкое стандартное меню по одиночному нажатию клавиши Win, Ctrl+Esc или левому клику на кнопку "Пуск" (работает только при горизонтальной панели задач).

Все системные хоткеи (Win+E, Win+D, Win+Shift+S, Win+L и т.д.), диспетчер по Ctrl+Shift+Esc и техническое меню по ПКМ на кнопку "Пуск" (Win+X) работают штатно.
Внутри: О системе, Параметры, Диспетчер задач, Спящий режим, Перезагрузка, Завершение работы, Заблокировать, Выйти из системы.
Защита от случайного нажатия: пункты перезагрузки, выключения и выхода требуют подтверждения вторым кликом в течение 3 секунд (появляется вопрос с убывающей полоской, без всплывающих системных окон).
Экран "О системе": показывает цветной ASCII-знак Polynya, версию Windows, модель процессора, объем ОЗУ, видеокарты, свободное место на диске и аптайм системы.

6. Настройки, трей и обновление цвета

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

Тема и город погоды применяются мгновенно на лету.
Язык интерфейса, включение/отключение модулей и режим баннеров уведомлений применяются по кнопке "Применить" (остров сам мягко перезапустится с флагом --relaunch). Если вы поменяли эти пункты и случайно закрыли окно, появится экран защиты от потери несохраненных изменений.
Обновить вид (polynya refresh): остров сам переснимает цвета панели задач при смене темы, обоев, акцента или перезапуске проводника. Но если вы используете сторонние твикеры вроде Windhawk, которые перекрашивают таскбар в обход системных событий Windows, нажмите в трее "Обновить вид" (или выполните polynya refresh).

7. Конфигурационный файл (`config.ini`)

Настройки хранятся в файле %APPDATA%\Polynya\config.ini, в портативной версии - в data\config.ini рядом с polynya.exe (создается при первом запуске с комментариями). Формат: ключ = значение, комментарии начинаются с #. Быстро открыть файл можно кнопкой "Открыть config.ini" внизу настроек.

Ключ	Допустимые значения	По умолчанию	Описание
`taskbar_height`	число в DIP (пикселях при масштабе 100%) / пусто	из системы	Ручное переопределение высоты панели задач (обычно определяется автоматически).
`city`	название города / пусто	по геолокации	Город для прогноза погоды (если пусто - берется по местоположению Windows).
`language`	`ru`, `en`, `zh`, `ja` / пусто	язык Windows	Язык интерфейса и встроенных модулей.
`terminal_notify`	секунды (`0` - выкл.)	`10`	Порог времени для уведомлений о долгих командах в терминале.
`modules_off`	`id` через пробел	пусто	Список выключенных обычных модулей (например, `agents picker`).
`modules_on`	`id` через пробел	пусто	Список включенных экспериментальных модулей (например, `notify`).
`notify_banners`	`ours` / `system`	`ours`	Кто рисует всплывающие баннеры при включенном модуле `notify`: `ours` (выпадашка острова) или `system` (оставить баннеры Windows, в острове только чипы).
`theme`	`os`, `dark`, `light`	`os`	Управляет только цветом текста и иконок (фон и плашки всегда подстраиваются под реальный цвет панели задач).
`font`	имя семейства / пусто	`Inter` (вшит)	Кастомный шрифт интерфейса (если установлен в системе; иначе берется вшитый Inter, а если и он не загрузился - Segoe UI Variable Text или Segoe UI).
`hotkey.<модуль>.<команда>`	сочетание вроде `Ctrl+Alt+D` / пусто	из модуля	Переназначает сочетание команды модуля; пустое значение выключает его (например, `hotkey.translator.translate`).
`log`	`debug` / пусто	обычный	Включает подробное логирование (включая названия треков, тайминги обхода каталога и детали снимка панели).

8. Справочник командной строки (CLI)

Все команды выполняются через основной бинарник polynya:

polynya
    Запустить остров в панели задач.

polynya push <заголовок> [подробности] [--key K] [--ttl СЕК] [--icon ИКОНКА] [--meta ТЕКСТ]
    Отправить уведомление (чип) в стек острова.
    Параметры:
      --key K       Ключ уведомления. Повторный вызов с тем же ключом обновит существующий чип.
      --ttl СЕК     Время жизни в секундах (по умолчанию 10). Значение 0 - висит, пока не закроют.
      --icon ИКОНКА Иконка чипа: ok | fail | info | key | claude | agent | color:#rrggbb
      --meta ТЕКСТ  Мелкая подпись источника/времени внизу раскрытой выпадашки.
    (Подробности в CLI обрезаются до первой строки и 160 символов).

polynya dismiss <K>
    Убрать из стека уведомление с ключом K.

polynya refresh
    Принудительно переснять цвета, кромку и шум панели задач.

polynya notify-setup
    Установить системный пакет для экспериментального модуля уведомлений Windows (запросит UAC)
    и сразу запустить модуль.

polynya modules reload
    Перезапустить процессы модулей, например после правки кода модуля.

polynya modules enable|disable <id>...
    Включить или выключить модули; применится при следующем запуске острова.

polynya language ru|en|zh|ja
    Задать язык интерфейса; применится при следующем запуске острова.

polynya quit
    Закрыть остров.

polynya uninstall [--purge]
    Закрыть остров и снять то, что он прописал в систему: автозапуск, хуки ИИ-агентов и пакет
    уведомлений. С --purge удаляются еще настройки и логи. Это вызывает деинсталлятор,
    сами файлы программы команда не трогает.

polynya help
    Вывести в консоль цветной ASCII-знак Polynya, точную версию сборки и справку по командам.

9. Установка, обновление и удаление

Установщик. Ставит для текущего пользователя в %LOCALAPPDATA%\Polynya, без прав администратора. Модули выбираются галочками: ИИ-агенты и пипетка отмечены, уведомления Windows нет (экспериментальный модуль). Если Everything еще не установлен, установщик может поставить его для поиска файлов, на этом шаге запросится UAC. Автозапуск при входе в Windows - тоже галочка.
Обновление. Запустите установщик новой версии: он закроет остров, заменит файлы и запустит его заново. Настройки, включенные и выключенные модули и автозапуск останутся как были. Уже установленные модули обновятся, а те, что не ставились раньше, можно добавить.
Удаление. Параметры → Приложения → Установленные приложения → Polynya. Деинсталлятор снимает автозапуск, хуки ИИ-агентов и пакет уведомлений и спрашивает, удалить ли заодно настройки и логи. Everything остается: это отдельная программа.
Портативная версия. В …-portable.zip лежат polynya.exe, файл-метка portable и лицензия. Распакуйте куда угодно: остров работает прямо из этой папки и все хранит рядом (data\, logs\, modules\). Модули лежат отдельно в …-modules.zip, их нужно распаковать в ту же папку. Автозапуск выключен, пока вы не включите его в трее. Хуки ИИ-агентов указывают на тот остров, который включал их последним: портативный или установленный.
SmartScreen. Сборки пока не подписаны, поэтому при первом запуске новой версии Windows может показать "Система Windows защитила ваш компьютер": нажмите Подробнее → Выполнить в любом случае.

10. Где что лежит (файлы, логи и реестр)

В портативной версии вместо %LOCALAPPDATA%\Polynya и %APPDATA%\Polynya используется папка с polynya.exe: рядом с ним лежат modules\ и logs\, а файлы из %APPDATA%\Polynya попадают в data\.

Путь / ветка	Что там хранится
`%LOCALAPPDATA%\Polynya\polynya.exe`	Исполняемый файл ядра.
`%LOCALAPPDATA%\Polynya\modules\<id>\`	Папки модулей (`module.toml` + `.exe` модуля).
`%LOCALAPPDATA%\Polynya\logs\polynya.log`	Единый лог ядра и модулей (ротация при 1 МБ в `polynya.old.log`, хранится не более двух файлов).
`%APPDATA%\Polynya\config.ini`	Настройки пользователя.
`%APPDATA%\Polynya\recent.txt`	История и частота запусков в лаунчере (`запусков\tвремя\tid`).
`%APPDATA%\Polynya\banners*.{txt,reg}`	Точечный бэкап настроек системных баннеров для модуля `notify`.
`HKCU\Software\Microsoft\Windows\CurrentVersion\Run`	Запись автозапуска при входе в систему.
`HKCU\Software\Microsoft\Windows\CurrentVersion\RunOnce\PolynyaBanners`	Страховочный откат системных баннеров через `reg import`, если процесс был убит аварийно.