Polynya

Активная разработка

Меню документации

Сборка и участие в разработке

Спасибо за интерес к разработке Polynya! В этом файле описано, как развернуть окружение, собрать ядро и модули, прогнать тесты и предложить свои изменения.

1. Инструменты и зависимости

Проект написан на чистом Rust без внешних UI-фреймворков (используются только крейты windows 0.62, serde / serde_json, toml и embed-resource на этапе сборки).

Для сборки понадобятся:

  • Windows 11 (x64 или ARM64);
  • Rust — версия закреплена в rust-toolchain.toml, rustup поставит ее сам. Подходит и GNU toolchain с MinGW-w64, и MSVC (полный Windows SDK для обычной компиляции не требуется); релизы собираются на MSVC.
  • Inno Setup 6.5+ — только для сборки установщика (winget install JRSoftware.InnoSetup).

2. Сборка проекта

Весь проект организован как единый Cargo workspace (ядро polynya, крейт протокола proto и 4 встроенных модуля в modules/{agents,notify,picker,start}).

Собрать всё разом в релизном профиле:

cargo build --release --workspace

После сборки в target/release/ появятся:

  • polynya.exe — ядро острова и CLI-клиент;
  • polynya-agents.exe, polynya-notify.exe, polynya-picker.exe — бинарники встроенных модулей;
  • polynya-start.exe — модуль своего "Пуска". Он лежит в репозитории (modules/start), как и modules/devtools на Node.js, но в релизы оба пока не входят.

Примечание про версионирование: скрипт build.rs автоматически вычисляет версию из git (на теге vX.Y.Z ставит X.Y.Z, между тегами — X.Y.Z+коммитов.хэш, до первого тега — 1.0.0-dev.N+хэш) и вшивает её в VERSIONINFO исполняемого файла.

3. Локальный деплой для отладки

При запуске polynya.exe работает со своей рабочей директорией в %LOCALAPPDATA%\Polynya\. Чтобы протестировать свежую сборку локально:

  1. Остановите работающий остров командой polynya quit (резидентные модули завершатся вместе с ним).
  2. Скопируйте собранный polynya.exe в %LOCALAPPDATA%\Polynya\, а бинарники модулей (вместе с их module.toml) — по папкам %LOCALAPPDATA%\Polynya\modules\<id>\.
  3. Важно: запускайте polynya.exe через explorer.exe или из обычного (не повышенного!) терминала. Если ваша IDE или терминал запущены от имени администратора, дочерний процесс острова унаследует повышенный токен, что сломает общение с Everything через UIPI.

Логирование при отладке

Общий лог ядра и всех модулей пишется в %LOCALAPPDATA%\Polynya\logs\polynya.log. Чтобы включить подробный вывод (тайминги обхода каталога, решения по баннерам, параметры снимка панели), добавьте в %APPDATA%\Polynya\config.ini строку:

log = debug

4. Тестирование

В проекте 85 автоматических тестов, покрывающих логику очереди и серий уведомлений, парсинг манифестов, сериализацию протокола proto, математику цвета APCA/OKLCH, слияние конфигов ИИ-агентов, парсер калькулятора и CLI.

Запуск всех модульных тестов:

cargo test --release --workspace

Для проверки интеграции с реальным окружением Windows (получение миниатюр медиасессий GSMTC, системная геолокация и т.д.) есть набор изолированных тестов:

cargo test --release --workspace -- --ignored

Перед отправкой Pull Request убедитесь, что все тесты в --workspace проходят без ошибок.

Стиль кода

  • Форматирование: cargo fmt --all (настройки в rustfmt.toml). Комментарии rustfmt не переносит - держите их в пределах ~100 символов вручную.
  • Комментарии: на английском; объясняют почему, а не пересказывают код. Модуль начинается с //!, публичные элементы описываются через ///.
  • unsafe: у каждого блока - комментарий // SAFETY: с настоящим обоснованием (кто владеет хэндлом, сколько живет буфер). Линт clippy::undocumented_unsafe_blocks включен на весь workspace: cargo clippy --workspace не должен выдавать новых предупреждений.
  • Шапка файла: каждый исходник начинается с двух строк Copyright и SPDX-License-Identifier (GPL-3.0-or-later, у крейта proto - MIT).

5. Вспомогательные скрипты (tools/)

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

  • tools/package.ps1 — пересобирает неподписанный sparse-пакет .msix для модуля notify (сам скачивает легковесный makeappx из NuGet-пакета Microsoft.Windows.SDK.BuildTools). Важно: при любом изменении манифеста пакета обязательно поднимите номер версии и в самом манифесте, и в константе VERSION внутри src/package.rs, чтобы ядро увидело обновление при старте.
  • tools/release.ps1 — собирает файлы релиза для одной архитектуры в target/dist: установщик (installer/polynya.iss через installer/build.ps1, который скачивает установщик Everything и сверяет его SHA-256), портативный архив и архив модулей к нему. Workflow Release запускает его для обеих архитектур по тегу vX.Y.Z и создает черновик релиза.
  • tools/logo.py и tools/ascii.py — генерируют .ico, растровые и векторные варианты логотипа с зерном, а также цветную ASCII-разметку assets/logo/mark-ascii.json из исходника assets/logo/mark.svg.

6. Правила локализации и текста (i18n)

Интерфейс поддерживает 4 языка: русский (ru), английский (en), китайский (zh) и японский (ja). Строки ядра живут в src/i18n.rs, строки модулей — в их коде и файлах module.toml. При добавлении новых строк придерживайтесь общих правил проекта:

  1. Регистр: самостоятельные заголовки и названия параметров пишутся с заглавной буквы; составные статусы вида "объект + состояние" — со строчной (например: "Caps Lock включен", "#ff0000 скопирован").
  2. Многоточие: у длящихся процессов и плейсхолдеров ввода ставится единый символ … ("Думает…", "Введите город…"); в предметных строках действий агентов многоточие не ставится ("Редактирует main.rs").
  3. Тон и терминология: строго нейтральная форма без местоимения "ты" и без первого лица. Для системных команд используются точные формулировки самой ОС Windows на соответствующем языке ("Завершение работы" / "Shut down" / "关机" / "シャットダウン"). Строки подтверждения (confirm) формулируются только как короткий вопрос.

Документация ведется на тех же четырех языках: основная версия - английская (README.md, docs/*.md), переводы лежат в README.<язык>.md и docs/<язык>/. Юридические тексты (LICENSE, TRADEMARKS.md) существуют только на английском.

7. Лицензионное соглашение для контрибьюторов

Отправляя Pull Request в этот репозиторий, вы соглашаетесь с тем, что ваш код:

  • в составе ядра и встроенных модулей распространяется на условиях LICENSE (GNU GPLv3 + дополнительные условия Раздела 7);
  • в составе крейта proto и документации протокола распространяется на условиях proto/LICENSE (MIT License).