# 🤖 AGENTS.md — Справочник для AI-агентов и разработчиков

Документ содержит всю ключевую архитектурную, инфраструктурную и техническую информацию о проекте **Decky Loader (Russian Community Edition / deckyloader.ru)**.

---

## 📌 1. О проекте и назначение

* **Название:** Decky Loader (Каталог плагинов от Steam Deck Россия)
* **Основной домен:** `https://deckyloader.ru/`
* **Репозиторий GitFlic:** `https://gitflic.ru/project/rosakodu/decky-loader`
* **Команда разработчиков:**
  * `rosakodu` (https://gitflic.ru/user/rosakodu) — Архитектура, инфраструктура и серверный каталог.
  * `viktorkoval1997` (https://gitflic.ru/user/viktorkoval1997) — Разработка, тестирование и интеграция плагинов.
* **Цель:** Полностью автономная, быстрая и независимая от внешних блокировок CDN инфраструктура загрузчика плагинов для пользователей SteamOS / Steam Deck в РФ и СНГ.

---

## ⚖️ 2. Важнейшие правила и комплаенс (ВАЖНО!)

> **Требование законодательства РФ:** В каталоге плагинов, на сайте и в репозитории **строго запрещено** размещать или рекламировать плагины, связанные с VPN, прокси, VLESS, WARP, Zapret, Clash, Tailscale и обходом блокировок. Каталог фокусируется на кастомизации (SteamGridDB, CSS Loader), эмуляции, производительности (LSFG, Framegen), звуке и системных утилитах.

---

## 🏗️ 3. Архитектура проекта

### Основные компоненты:
1. **Frontend (`frontend/`):**
   * React / TypeScript бандл интерфейса Decky (внутриигровое меню QAM).
   * Каталог магазина плагинов (`frontend/src/components/store/Store.tsx`, `frontend/src/store.tsx`).
   * Направлен на `https://deckyloader.ru/store/plugins`.
   * Содержит регистронезависимое и форматное сопоставление установленных плагинов (показывает «Переустановить» вместо повторной кнопки «Установить»).
2. **Backend (`backend/decky_loader/`):**
   * Python-демон (сборка через PyInstaller в один бинарный файл `PluginLoader`).
   * `browser.py`: логика скачивания, распаковки и импорта плагинов.
   * `helpers.py`: надежный HTTP-клиент для загрузки бинарных зависимостей (`remote_binary`) с поддержкой `User-Agent`, авторедиректов и таймаутов.
3. **Web-сервер и Витрина (`/opt/remnawave/decky/` на VPS):**
   * `index.html`: Веб-витрина каталога плагинов (поиск, категории, фильтры, рекомендуемые плагины, кнопка копирования команды установки).
   * `/store/plugins`: статический JSON со списком всех плагинов.
   * `/store/images/`: кэш превью и миниатюр плагинов.
   * `/store/plugins/.../increment`: эндпоинт счётчика установок (возвращает `{"success": true}`).
   * `/PluginLoader` и `/PluginLoader-prerelease`: исполняемые бинарные файлы загрузчика для SteamOS.
   * `/install.sh`: интерактивный скрипт установки с выбором ветки (`Release` / `Pre-release`) и поддержкой графического интерфейса KDE Plasma (`kdialog`/`zenity`).
   * `decky_installer.desktop`: ярлык установки в один клик для рабочего стола Steam Deck.

---

## 🌐 4. Инфраструктура и адреса

* **Домен:** `https://deckyloader.ru` (DNS через Cloudflare, SSL: Let's Encrypt).
* **Сервер VPS (Основной в РФ):** `37.46.135.5` (`rosakodu.fvds.ru`, Дата-центр IXcellerate Москва, FirstVDS)
  * Путь к файлам Decky: `/var/www/deckyloader/`
  * Путь к изображениям: `/var/www/deckyloader/images/`
  * Конфиг Nginx: `/etc/nginx/sites-available/deckyloader`
  * SSL-сертификаты: `/var/www/deckyloader/ssl/` (Let's Encrypt для `deckyloader.ru`)
* **Старый сервер (зеркало):** `89.125.168.144`

---

## 🛠️ 5. Сборка и развёртывание

### ⚠️ Строгий порядок сборки:
> **КРИТИЧНО:** Статический бандл фронтенда `backend/decky_loader/static/` находится в `.gitignore` и упаковывается PyInstaller'ом прямо внутрь бинарника `PluginLoader`. **Сборка фронтенда ВСЕГДА должна предшествовать сборке бэкенда!** Несоблюдение порядка приведёт к зашиванию устаревшего кэша JS-бандла.

### Сборка фронтенда (Обязательный шаг 1):
```bash
cd frontend
mise exec node@25.1.0 -- npx rollup -c
```

### Сборка бинарника `PluginLoader` (Шаг 2):
```bash
cd backend
python3 -m venv /tmp/decky_build_env
/tmp/decky_build_env/bin/pip install -e .
/tmp/decky_build_env/bin/pyinstaller pyinstaller.spec
# Итоговый файл: backend/dist/PluginLoader
```

### Перезапуск службы загрузчика на Steam Deck:
```bash
sudo systemctl restart plugin_loader
# Логи службы:
journalctl -u plugin_loader -f
```

### Синхронизация изменений с сервером deckyloader.ru:
```bash
# Обновление index.html:
scp index.html decky-new:/var/www/deckyloader/index.html

# Обновление install.sh:
scp scripts/install_release.sh decky-new:/var/www/deckyloader/install.sh

# Перезагрузка Nginx:
ssh decky-new "nginx -t && systemctl reload nginx"
```

---

## 📋 6. Рекомендованные плагины на витрине

На сайте `https://deckyloader.ru/` в блок **⭐ Рекомендуемые** и на верхние позиции каталога вынесены:
1. `SteamGridDB` — Кастомизация обложек библиотеки.
2. `Decky LSFG-VK` — Генератор промежуточных кадров (Lossless Scaling).
3. `Decky-Framegen` — Генерация кадров FSR 3 / OptiScaler.
4. `Decky DoT DNS` — Быстрый безопасный DNS over TLS.
5. `KDE Connect` — Синхронизация со смартфоном/ПК.
6. `MagicPods` — Интеграция наушников AirPods / Beats.

---

## 🔄 7. Обязательные правила синхронизации и обновлений (КРИТИЧНО!)

AI-агент и разработчики **всегда** должны контролировать актуальность проекта по двум ключевым направлениям:

### 1. Синхронизация ядра Decky Loader с апстримом:
* **Апстрим-репозиторий:** `https://github.com/steamdeckhomebrew/decky-loader`
* **Обязанность:** Проактивно проверять свежие коммиты, теги и релизы в апстриме `SteamDeckHomebrew/decky-loader`. Не ждать напоминаний пользователя — проверять всегда!
* **⚡ Проактивный протокол перед началом любых работ:**
  Перед выполнением любых задач по коду, сборкам или деплою AI-агент первым делом запускает проверку:
  ```bash
  git fetch upstream
  git log HEAD..upstream/main --oneline
  ```
  Если обнаружены свежие коммиты:
  1. Смерджить их в рабочую ветку (`git merge upstream/main`).
  2. Проверить сохранение нашей русификации, логотипов и конфигурации.
  3. Пересобрать бандл/бинарник и обновить GitFlic и рабочий сервер `deckyloader.ru`.

### 2. Актуализация каталога плагинов (База плагинов):
* **Апстрим-база одобренных плагинов:** `https://github.com/SteamDeckHomebrew/decky-plugin-database/pulls`
* **Обязанность:** Постоянно и проактивно отслеживать Pull Requests (как принятые/мерджи, так и новые/отклонённые) в репозитории базы плагинов Decky. Обо всех изменениях (одобрение новых плагинов, обновления версий, отклонение/закрытие PR ботом или мейнтейнерами) **всегда оперативно сообщать пользователю**!
* **Правила добавления/обновления:**
  1. **Комплаенс (Строго!):** Проверять плагин на соответствие разделу 2 (никаких VPN, прокси, Zapret, Clash, обходов блокировок).
  2. **Актуализация версий:** Для разрешённых плагинов скачивать последние релизные ZIP-архивы, обновлять хеши, иконки и метаданные в `/store/plugins.json` на сервере и в `index.html`. Поле `created` **всегда** выставлять на текущее время UTC в момент добавления/обновления плагина в каталоге, чтобы плагин гарантированно попадал в раздел «Обновления за сегодня» (фильтр `updated-24h`) ровно на сутки!
  3. **Сохранение работоспособности:** Тестировать совместимость версий со SteamOS и библиотеками Decky.
  4. **Уведомление разработчика:** При обнаружении одобренных или перспективных отклоненных/дорабатываемых плагинов сразу формировать сводку с описанием изменений, номером PR и рекомендацией по добавлению в наш каталог.

---

## 🛑 8. Обязательный протокол верификации на физическом Steam Deck (ЖЕСТКОЕ ПРАВИЛО!)

> **КРИТИЧЕСКИ ВАЖНО:** Любая сборка `PluginLoader` / `PluginLoader-prerelease` **КАТЕГОРИЧЕСКИ ЗАПРЕЩЕНА** к выгрузке на боевой сервер `deckyloader.ru` без предварительной сборки и успешной верификации на физическом Steam Deck пользователя!

### Причина правила:
Хостовая машина разработки использует новейшие библиотеки (например, `GLIBC 2.44`, Python 3.14), тогда как на SteamOS установлена стабильная системная `GLIBC 2.41` (Python 3.13). Сборка на хосте приводит к крашу `ImportError: GLIBC version not found` на устройствах пользователей.

### Порядок действий перед любым релизом бинарников:
1. **Шаг 0: Обязательная предварительная пересборка фронтенда и проверка версии в pyproject.toml:**
   * Проверить соответствие версии в `backend/pyproject.toml` целевому релизу (например `version = "3.2.10"` для Stable или `version = "3.3.0a1"` для Pre-release).
   * Перед копированием папки `backend/` на Steam Deck **всегда** пересобирать бандл фронтенда:
     ```bash
     cd frontend && mise exec node@25.1.0 -- npx rollup -c
     ```
   * *Причина:* Папка `backend/decky_loader/static/` находится в `.gitignore` и вшивается PyInstaller'ом в бинарник `PluginLoader`. Если пропустить этот шаг, на Steam Deck будет отправлен устаревший статический бандл с хоста!
2. **Сборка нативного бинарника на Steam Deck:**
   * Исходники `backend/` синхронизируются на Steam Deck (`192.168.0.104` / `192.168.0.103`, пользователь: `deck`, пароль: `0451`):
     ```bash
     sshpass -p '0451' rsync -avz --delete --exclude 'dist' --exclude 'build' --exclude '__pycache__' --exclude '*.pyc' backend/ deck@192.168.0.104:/tmp/decky_build/backend/
     ```
   * Сборка PyInstaller запускается нативно на SteamOS:
     ```bash
     python3 -m venv /tmp/decky_build/env
     /tmp/decky_build/env/bin/pip install -e /tmp/decky_build/backend
     /tmp/decky_build/env/bin/pip install pyinstaller
     cd /tmp/decky_build/backend && /tmp/decky_build/env/bin/pyinstaller pyinstaller.spec
     ```
   * **Обязательная проверка вшитых метаданных бинарника:**
     Перед установкой обязательно проверить запакованную версию:
     ```bash
     strings /tmp/decky_build/backend/dist/PluginLoader | grep -E 'xdecky_loader-.*\.dist-info'
     ```
     Версия в метаданных обязана строго совпадать с целевой! Если там зашит устаревший `dist-info`, загрузчик будет отдавать старую версию, и в настройках останется вечная кнопка «Установить обновление».
3. **Живая проверка на Steam Deck:**
   * Служба останавливается: `echo 0451 | sudo -S systemctl stop plugin_loader`.
   * Бинарник устанавливается: `echo 0451 | sudo -S cp /tmp/decky_build/backend/dist/PluginLoader /home/deck/homebrew/services/PluginLoader && echo 0451 | sudo -S chmod 777 /home/deck/homebrew/services/PluginLoader`.
   * Файл версии актуализируется: `echo 0451 | sudo -S bash -c "echo 'v<версия>' > /home/deck/homebrew/services/.loader.version"`.
   * Служба запускается: `echo 0451 | sudo -S systemctl start plugin_loader`.
   * Обязательная проверка журнала:
     ```bash
     systemctl status plugin_loader --no-pager
     journalctl -u plugin_loader -n 25 --no-pager
     ```
   * В логах **обязательно** должны присутствовать:
     * `[main][INFO]: Starting Decky version v<target>` — версия в логе **ОБЯЗАНА** совпадать с целевой!
     * `[main][INFO]: Loading Decky frontend!`
   * Локальный порт `http://127.0.0.1:1337` должен отвечать `403 Forbidden`.
   * При проверке через CDP (`updater/get_version_info`) поле `"current"` обязано совпадать с целевой версией.
4. **Выгрузка на рабочий сервер `deckyloader.ru` и синхронизация размера:**
   * Только после подтверждения на Steam Deck проверенный бинарник загружается на сервер:
     ```bash
     scp PluginLoader decky-new:/var/www/deckyloader/PluginLoader
     scp PluginLoader-prerelease decky-new:/var/www/deckyloader/PluginLoader-prerelease
     ```
   * **Обязательная синхронизация размера в байтах в `/api/releases.json`:**
     Точный размер загруженного файла (`stat -c %s /var/www/deckyloader/PluginLoader...`) **ОБЯЗАН** быть прописан в поле `"size"` соответствующего релиза в `/var/www/deckyloader/api/releases.json`. Без этого прогресс загрузки и валидация апдейтера завершаются с ошибкой.
5. **Синхронизация скрипта установки (`install.sh`) и репозитория GitFlic:**
   * **Актуализация версий в `scripts/install_release.sh`:**
     При изменении целевых версий веток (`release` / `prerelease`) файл `scripts/install_release.sh` обязан содержать точные номера версий в блоке записи `.loader.version`:
     ```bash
     if [ "$SELECTED_BRANCH" = "prerelease" ]; then
         echo "v<целевая_prerelease>" > "${HOMEBREW_FOLDER}/services/.loader.version"
     else
         echo "v<целевая_release>" > "${HOMEBREW_FOLDER}/services/.loader.version"
     fi
     ```
   * **Выгрузка `install.sh` на боевой сервер:**
     ```bash
     scp scripts/install_release.sh decky-new:/var/www/deckyloader/install.sh
     ```
   * **Синхронизация бинарников в GitFlic (ОБЯЗАТЕЛЬНО В ОБЕ ВЕТКИ main И master):**
     Скрипт `install.sh` в первую очередь скачивает бинарники `PluginLoader` и `PluginLoader-prerelease` напрямую из репозитория GitFlic (`https://gitflic.ru/project/rosakodu/decky-loader/blob/raw?...`).
     ⚠️ **КРИТИЧЕСКИ ВАЖНО:** На GitFlic дефолтной веткой репозитория является `master`, а рабочей — `main`. Если запушить только в `main`, GitFlic CDN может отдавать устаревший кэш бинарника из `master` (например, старую версию 3.2.8 вместо 3.2.10, что приводит к черному экрану Steam Deck и ложным уведомлениям об обновлении!).
     Поэтому коммиты и бинарники **ОБЯЗАНЫ** отправляться одновременно в обе ветки:
     ```bash
     git add scripts/install_release.sh PluginLoader PluginLoader-prerelease
     git commit -m "fix(installer): sync verified binaries and loader version"
     git push origin main
     git push origin main:master
     ```
   * **Обязательная проверка прямой отдачи бинарника с GitFlic CDN:**
     Сразу после пуша необходимо выполнить проверку размера и метаданных прямо с URL загрузчика:
     ```bash
     curl -sI "https://gitflic.ru/project/rosakodu/decky-loader/blob/raw?branch=main&file=PluginLoader" | grep -i content-length
     ```
     Размер в заголовке `content-length` обязан строго совпадать с целевым размером бинарника в байтах!
6. **Подключение к Steam Deck:**
   * Взаимодействие со Steam Deck (скриншоты, проверка интерфейса, клики) осуществляется **напрямую** по SSH и через CDP Chrome DevTools Protocol (`http://127.0.0.1:8080/json` -> WebSocket `Page.captureScreenshot`).
   * Скрипт `open_projacktor.sh` использовать строго запрещено.

---

## 🖼️ 9. Обязательный фикс для плагина SteamGridDB (ЖЕСТКОЕ ПРАВИЛО!)

> **КРИТИЧЕСКИ ВАЖНО:** При любых обновлениях, сборках или изменениях плагина **SteamGridDB** (`https://gitflic.ru/project/rosakodu/steamgriddb`), агент **ОБЯЗАН** сохранять и внедрять наш инфраструктурный фикс обхода блокировок и авто-авторизации:

### 1. Архитектура фикса SteamGridDB:
* Сервис SteamGridDB заблокировал дефолтный ключ `deckyloader42069`, а его CDN (`cdn2.steamgriddb.com`) заблокирован многими провайдерами в РФ.
* На сервере `deckyloader.ru` настроен кэширующий обратный прокси:
  * `/sgdb-api/` ➔ проксирует запросы к `www.steamgriddb.com/api/v2/` и **на лету внедряет валидный API-ключ** (`proxy_set_header Authorization "Bearer <KEY>"`).
  * `/sgdb-cdn/` ➔ кэширует обложки и картинки с `cdn2.steamgriddb.com` на SSD на 30 дней.

### 2. Обязательные изменения в коде плагина (`steamgriddb.zip`):
1. **Фронтенд (`dist/index.js`):**
   * Подменять `const SGDB_API_BASE = 'https://www.steamgriddb.com/api/v2'` на `https://deckyloader.ru/sgdb-api`.
   * При получении результатов поиска заменять все вхождения `https://cdn2.steamgriddb.com/` на `https://deckyloader.ru/sgdb-cdn/`.
2. **Бэкенд (`main.py`):**
   * В функциях скачивания картинок (`download_file`, `download_as_base64`, `set_shortcut_icon_from_url`, `set_steam_icon_from_url`) перенаправлять все URL с `cdn2.steamgriddb.com` на `https://deckyloader.ru/sgdb-cdn/`.
3. **Публикация:**
   * Упаковывать обновлённый архив `steamgriddb.zip`.
   * Отправлять в репозиторий GitFlic: `git push origin main` в `rosakodu/steamgriddb`.
   * Обновлять SHA256-хеш версии в `/var/www/deckyloader/store/plugins.json` на рабочем сервере.

---

## 🎖️ 10. Обязательный фикс для плагина ProtonDB Badges (ЖЕСТКОЕ ПРАВИЛО!)

> **КРИТИЧЕСКИ ВАЖНО:** При любых обновлениях или сборках плагина **ProtonDB Badges** (`https://gitflic.ru/project/rosakodu/protondb-badges`), агент **ОБЯЗАН** сохранять наш фикс проксирования и расширенного таймаута:

### 1. Архитектура фикса ProtonDB Badges:
* Оригинальный сервис ProtonDB хостится на серверах Netlify/AWS, а в коде плагина зашит жесткий таймаут в 2000 мс (`FETCH_TIMEOUT_MS = 2000`).
* Из-за задержек DPI/ТСПУ и блокировок подсетей Netlify в РФ запросы отваливаются по таймауту, и значки совместимости не загружаются (NO REPORT).
* На сервере `deckyloader.ru` настроен кэширующий обратный прокси:
  * `/protondb/` ➔ проксирует запросы к `https://www.protondb.com/api/v1/reports/summaries/` с дисковым кэшированием на 7 дней (`proxy_cache sgdb_cache`).

### 2. Обязательные изменения в коде плагина (`protondb-badges.zip`):
1. **Фронтенд (`dist/index.js`):**
   * Заменять `https://www.protondb.com/api/v1/reports/summaries/` на `https://deckyloader.ru/protondb/`.
   * Увеличивать таймаут `FETCH_TIMEOUT_MS` и `FETCH_TIMEOUT_MS$1` с `2000` до `6000` (6 секунд).
2. **Публикация:**
    * Упаковывать обновлённый архив `protondb-badges.zip`.
    * Отправлять в репозиторий GitFlic: `git push origin main` в `rosakodu/protondb-badges`.
    * Обновлять SHA256-хеш версии в `/var/www/deckyloader/store/plugins.json` на рабочем сервере.

---

## ⚡ 11. Обязательный мониторинг и синхронизация стороннего плагина MAKO (ЖЕСТКОЕ ПРАВИЛО!)

> **КРИТИЧЕСКИ ВАЖНО:** Плагин **MAKO (Motion-Adaptive Kernel Orchestration)** является ключевым сторонним решением нового поколения для генерации промежуточных кадров (Lossless Scaling) и пространственного масштабирования (продолжение проектов `Decky LSFG-VK Experimental` и `LSFG-VK Experimental`). Агент **ОБЯЗАН** проактивно отслеживать новые релизы MAKO и оперативно обновлять его в каталоге!

### 1. Источники и репозитории:
* **Апстрим-репозиторий:** `https://github.com/eugeniosegala/MAKO/releases`
* **Репозиторий GitFlic (Автономное зеркало):** `https://gitflic.ru/project/rosakodu/mako`
* **Целевой архив:** релизный ассет `MAKO-Decky-vX.Y.Z.zip` (тег `plugin-vX.Y.Z`), заливается как `mako.zip`.

### 2. Структура плагина:
* Релизный архив `MAKO-Decky` (`mako.zip`) уже включает в себя встроенный **MAKO Renderer** (все Vulkan-слои, Flatpak-адаптеры и CLI-утилиты находятся внутри папки `Mako/bin/` и автоматически регистрируются плагином при старте).
* В каталоге плагинов `deckyloader.ru` представлена единая позиция **`MAKO - Frame Generation`** (ID 139), так как плагин самостоятельно настраивает весь рендерер без ручных манипуляций пользователя.

### 3. Протокол обновления MAKO при выходе новой версии:
1. **Проверка релизов:** Проверять GitHub API `https://api.github.com/repos/eugeniosegala/MAKO/releases`.
2. **Скачивание и валидация:** При появлении нового релиза с префиксом `plugin-v*`:
   * Скачивать архив `MAKO-Decky-v*.zip`.
   * Рассчитывать актуальный SHA256-хеш архива (`sha256sum`).
3. **Публикация на GitFlic:**
   * Заливать обновлённый архив `mako.zip` в репозиторий `rosakodu/mako` на GitFlic в ветки `main` и `master`.
4. **Обновление каталога:**
   * Обновлять номер версии, SHA256-хеш и дату (`created` **всегда** выставляется на текущее время UTC в момент релиза в нашем каталоге, чтобы плагин автоматически попадал в раздел «Обновления за сегодня» на 24 часа) в `/var/www/deckyloader/store/plugins.json` на рабочем сервере `deckyloader.ru`.
   * Синхронизировать метаданные в `index.html` и перевыгружать сайт.

---

## ⚡ 12. Обязательное сохранение версии 0.12.8 для плагина Decky LSFG-VK (ЖЕСТКОЕ ПРАВИЛО!)

> **КРИТИЧЕСКИ ВАЖНО:** Для плагина **Decky LSFG-VK** (ID `113`, `https://github.com/xXJSONDeruloXx/decky-lsfg-vk`) в каталоге `deckyloader.ru` **ВСЕГДА ДОЛЖНА ПРИСУТСТВОВАТЬ ВЕРСИЯ 0.12.8** как постоянная точка отката!
> 
> * **Причина:** Версия `0.12.8` является эталонной стабильной сборкой для многих пользователей. Для неё нами подготовлена и вшита полная русская локализация (`ru.json` + бандл `dist/index.js`).
> * **Правило обновления:** При выходе новых версий плагина (например, замена `0.14.4` на `0.15.0` и выше) обновляется **только первая (актуальная) версия** в массиве `versions`. Версия `0.12.8` **НИКОГДА НЕ УДАЛЯЕТСЯ** из массива `versions` в `/var/www/deckyloader/store/plugins.json` и `index.html`.
> * **Параметры версии 0.12.8 в манифесте:**
>   ```json
>   {
>     "name": "0.12.8",
>     "hash": "cfb6c0d60a510633721f11e0f7008c889f83263ba2e8bf37fcfe2da95583dffb",
>     "artifact": "https://deckyloader.ru/store/plugins/decky-lsfg-vk-v0.12.8.zip",
>     "created": "2026-09-08T18:00:00Z",
>     "downloads": 1420,
>     "updates": 0
>   }
>   ```

---

## 🎨 13. Обязательный фикс для плагина CSS Loader (ЖЕСТКОЕ ПРАВИЛО!)

> **КРИТИЧЕСКИ ВАЖНО:** При любых обновлениях, сборках или изменениях плагина **CSS Loader** (`https://gitflic.ru/project/rosakodu/css-loader`), агент **ОБЯЗАН** сохранять и внедрять наш инфраструктурный фикс загрузки тем, превью и сопоставлений без VPN:

### 1. Архитектура фикса CSS Loader:
* Сервис DeckThemes (`api.deckthemes.com`) и его хостинг подвержены блокировкам/замедлениям ТСПУ/DPI в РФ, из-за чего пользователи не могут открывать магазин тем, загружать CSS-маппинги и скачивать темы без VPN.
* На сервере `deckyloader.ru` настроен кэширующий обратный прокси:
  * `/deckthemes/(.*)` ➔ проксирует запросы к `https://api.deckthemes.com/$1` с дисковым кэшированием ответов на 7 дней (`proxy_cache sgdb_cache`, `proxy_cache_valid 200 7d;`).
  * Обеспечивает мгновенную отдачу тяжелых JSON-файлов сопоставлений (`stable.json`, ~2.5 МБ) и ZIP-архивов тем (`/deckthemes/blobs/...`).
  * Для плейсхолдера карточек используется локальный кэш: `https://deckyloader.ru/store/images/cssplaceholder.png`.

### 2. Обязательные изменения в коде плагина (`css-loader.zip`):
1. **Фронтенд (`dist/index.js`):**
   * Заменять базовый URL: `this.apiUrl = "https://api.deckthemes.com";` ➔ `this.apiUrl = "https://deckyloader.ru/deckthemes";`
   * Заменять пути карусели и картинок:
     * `https://api.deckthemes.com/blobs/${...}` ➔ `https://deckyloader.ru/deckthemes/blobs/${...}`
     * `https://share.deckthemes.com/cssplaceholder.png` ➔ `https://deckyloader.ru/store/images/cssplaceholder.png`
   * Заменять эндпоинт патронов: `https://api.deckthemes.com/patrons` ➔ `https://deckyloader.ru/deckthemes/patrons`
2. **Бэкенд (`main.py`):**
   * В функции загрузки CSS-трансляций:
     * `css_translations_url = "https://api.deckthemes.com/beta.json"` ➔ `"https://deckyloader.ru/deckthemes/beta.json"`
     * `css_translations_url = "https://api.deckthemes.com/stable.json"` ➔ `"https://deckyloader.ru/deckthemes/stable.json"`
3. **Версионирование (`package.json`):**
   * При сборке патча повышать версию (например `2.1.3`), чтобы у всех существующих пользователей со старой версией `2.1.2` в интерфейсе Decky Loader автоматически появилась кнопка «Обновить».
4. **Публикация:**
   * Упаковывать архив `css-loader.zip` с корневой папкой `SDH-CssLoader/`.
   * Отправлять в репозиторий GitFlic: `git push origin main` и `master` в `rosakodu/css-loader`.
   * Обновлять версию, хеш и дату в `/var/www/deckyloader/store/plugins.json` на рабочем сервере и в `index.html`.

---

## 📦 14. Обязательная структура корневой папки в ZIP-архивах плагинов (ЖЕСТКОЕ ПРАВИЛО!)

> **КРИТИЧЕСКИ ВАЖНО:** Все без исключения ZIP-архивы плагинов в каталоге (`/var/www/deckyloader/store/plugins/`), на сервере и в релизах GitFlic/GitHub **ОБЯЗАНЫ** содержать корневую директорию плагина (например, `lampa-deck/`, `SDH-CssLoader/`, `decky-steamgriddb/`). Архивы без корневой папки («плоские» архивы) **КАТЕГОРИЧЕСКИ ЗАПРЕЩЕНЫ**!

### 1. Архитектура распаковщика Decky Loader (`backend/decky_loader/browser.py`):
* В методе `_unzip_to_plugin_dir` загрузчик выполняет:
  `ZipFile(zip).extractall(self.plugin_path)` непосредственно в общую директорию плагинов пользователя (`/home/deck/homebrew/plugins`).
* Сразу после этого вызывается проверка:
  ```python
  plugin_folder = self.find_plugin_folder(name)
  assert plugin_folder is not None
  ```
* Метод `find_plugin_folder(name)` сканирует только дочерние папки:
  `for folder in listdir(self.plugin_path): if path.exists(path.join(self.plugin_path, folder, 'plugin.json')) ...`
* **Что происходит при упаковке без корневой папки:**
  Если запаковать файлы изнутри директории (плоский архив), `plugin.json` и остальные файлы выпадут прямо в корень `/home/deck/homebrew/plugins/`. В результате `find_plugin_folder()` возвращает `None`, падает `AssertionError`, установка через интерфейс Game Mode завершается ошибкой, а директория плагинов замусоривается разрозненными файлами.

### 2. Правильный способ упаковки плагинов:
Упаковывать архив необходимо **ТОЛЬКО** из родительской директории, включая саму папку плагина:
```bash
# ПРАВИЛЬНО (создает архив с корневой папкой plugin-name/):
cd /path/to/parent_dir
zip -r /path/to/output/plugin-name.zip plugin-name/ -x "plugin-name/.git*" "plugin-name/node_modules*"

# НЕПРАВИЛЬНО (КАТЕГОРИЧЕСКИ ЗАПРЕЩЕНО — плоский архив):
cd /path/to/parent_dir/plugin-name
zip -r plugin-name.zip ./*
```

### 3. Проверка архива перед публикацией:
Перед выгрузкой любого плагина на сервер `deckyloader.ru` или в релиз, агент **ОБЯЗАН** проверить структуру архива:
```bash
unzip -l plugin.zip | head -n 10
```
Первая колонка путей **всегда** должна начинаться с имени подпапки (например, `lampa-deck/plugin.json`, а не просто `plugin.json`).

---

## 🎬 14. Обязательный фикс для плагина Animation Changer (ЖЕСТКОЕ ПРАВИЛО!)

> **КРИТИЧЕСКИ ВАЖНО:** При любых обновлениях, сборках или изменениях плагина **Animation Changer** (`https://gitflic.ru/project/rosakodu/animation-changer`), агент **ОБЯЗАН** сохранять и внедрять наш инфраструктурный фикс загрузки заставок и видео без VPN:

### 1. Архитектура фикса Animation Changer:
* Сервис SteamDeckRepo (`steamdeckrepo.com`) отдаёт огромный JSON-каталог (`api/posts/all`, ~7.5 МБ) и жестко лимитирует запросы (Cloudflare rate limit 60 req/min).
* Картинки и превью-видео хостятся на `cdn.steamdeckrepo.com`, который блокируется или замедляется многими провайдерами в РФ.
* Ссылка скачивания `steamdeckrepo.com/post/download/<id>` возвращает HTTP 302 редирект на Backblaze B2 S3 storage (`steamdeckrepo.s3.us-west-004.backblazeb2.com`), который заблокирован в РФ и падает с ошибкой на клиентах SteamOS.
* При этом файл видео на CDN (`cdn.steamdeckrepo.com/videos/<hash>.webm`) байт-в-байт идентичен файлу из Backblaze B2. Прямое скачивание с CDN полностью обходит блокировку Backblaze!
* На сервере `deckyloader.ru` настроены кэширующие обратные прокси:
  * `/sdr-api/(.*)` ➔ проксирует запросы к `https://steamdeckrepo.com/api/$1` с дисковым кэшированием каталога на 1 час (`proxy_cache sgdb_cache; proxy_cache_valid 200 1h;`).
  * `/sdr-cdn/(.*)` ➔ кэширует превью и полноразмерные webm-видео с `cdn.steamdeckrepo.com` на 30 дней с поддержкой Range-запросов (`proxy_force_ranges on; proxy_cache_valid 200 206 30d;`).

### 2. Обязательные изменения в коде плагина (`animation-changer.zip`):
1. **Бэкенд (`main.py`):**
   * Вспомогательная функция `mirror_sdr_url(url)` для замены `https://cdn.steamdeckrepo.com` на `https://deckyloader.ru/sdr-cdn`.
   * В функции `get_steamdeckrepo()`: сначала опрашивать `https://deckyloader.ru/sdr-api/posts/all`, при неудаче делать фоллбэк на оригинал. Все URL картинок и видео заменять через `mirror_sdr_url`. Поле `download_url` направлять напрямую на `mirror_sdr_url(entry['video'])` во избежание редиректа на Backblaze B2.
   * В методе `downloadAnimation()`: поддержать зеркалирование `download_url` и автозамену старых ссылок `post/download` на прямой CDN-URL видео (`anim['preview_video']`).
2. **Версионирование (`package.json`):**
   * Повышать версию (например `1.3.3`), чтобы у существующих пользователей появилась кнопка «Обновить».
3. **Публикация:**
   * Упаковывать архив `animation-changer.zip` с корневой папкой `SDH-AnimationChanger/`.
   * Отправлять в репозиторий GitFlic: `git push origin main` и `master` в `rosakodu/animation-changer`.
   * Обновлять версию, хеш и дату в `/var/www/deckyloader/store/plugins.json` на рабочем сервере и в `index.html`.

---

## 🎬 15. Зеркала TMDB API и CDN для плагина Projacktor (Медиа-каталог)

> **Назначение:** Полный обход DNS-отравления и блокировок сервиса The Movie Database (TMDB) в РФ для плагина **Projacktor** (`/home/rosakodu/Projects/projacktor`).

### 1. Архитектура зеркала TMDB:
* Домены `api.themoviedb.org` и `image.tmdb.org` в РФ подвергаются DNS-спуфингу (подменяются на `127.0.0.1`), блокировкам DoH и замедлению.
* На сервере `deckyloader.ru` (IXcellerate Москва) настроены upstream-пулы прямых IP-адресов CloudFront и BunnyCDN, полностью исключающие зависимость от отравленного DNS:
  * `upstream tmdb_api_backend` (IP CloudFront) с SNI `api.themoviedb.org`
  * `upstream tmdb_image_backend` (IP BunnyCDN) с SNI `image.tmdb.org`
* **Эндпоинты Nginx на `deckyloader.ru`:**
  * **`/tmdb-api/(.*)`** ➔ проксирует запросы к `https://api.themoviedb.org/$1` с дисковым кэшированием метаданных на 2 часа (`proxy_cache sgdb_cache; proxy_cache_valid 200 2h;`).
  * **`/tmdb-image/(.*)`** и **`/tmdb-cdn/(.*)`** ➔ кэширует постеры, фоны и превью на SSD на 30 дней (`proxy_cache_valid 200 30d;`).

### 2. Маршрутизация в плагине Projacktor:
* Метаданные фильмов и сериалов: `https://deckyloader.ru/tmdb-api/3/...` (с авто-фоллбэком на оригинал).
* Изображения: `https://deckyloader.ru/tmdb-image/t/p/...` (с авто-фоллбэком на оригинал).

---

## 🛠️ 16. Справочник для разработки плагинов сторонними разработчиками

* **Файл руководства:** [`docs/AGENTS_PLUGIN_DEV.md`](file:///home/rosakodu/Projects/Decky%20Loader/docs/AGENTS_PLUGIN_DEV.md)
* **Назначение:** Полный архитектурный и программный справочник для разработчиков и AI-агентов (Cursor, Windsurf, Claude, Copilot, Antigravity) по созданию новых плагинов для Steam Deck (файловая структура, `@decky/ui`, Python `main.py`, фиксы SteamOS 3.6+, упаковка и комплаенс).

---

## 🪐 17. Обязательный мониторинг и синхронизация плагина GyroParallax

> **КРИТИЧЕСКИ ВАЖНО:** Плагин **GyroParallax** от разработчика `nikita201294` добавляет на страницу с описанием игры в Steam Deck эффект 3D-параллакса с управлением гироскопом. Агент **ОБЯЗАН** проактивно отслеживать новые коммиты и релизы GyroParallax и синхронизировать их в каталоге!

### 1. Источники и репозитории:
* **Апстрим-репозиторий:** `https://github.com/kuchazefira-hub/GyroParallax-Decky-plugin`
* **Репозиторий GitFlic (Автономное публичное зеркало):** `https://gitflic.ru/project/rosakodu/gyroparallax`
* **Boosty автора (донаты):** `https://boosty.to/nikita201294/donate`
* **VK автора:** `https://vk.ru/nikita201294`
* **Целевой архив:** `gyroparallax.zip` в `/var/www/deckyloader/store/plugins/gyroparallax.zip`.
* **Текущий статус в каталоге:** Раздел тестирования (`/var/www/deckyloader/store/testing.json`, ID 146).

### 2. Протокол мониторинга и обновления:
1. **Проверка обновлений:** Проверять GitHub API `https://api.github.com/repos/kuchazefira-hub/GyroParallax-Decky-plugin/releases` и коммиты `commits`.
2. **Синхронизация кода в GitFlic:**
   * При появлении новых коммитов синхронизировать их в репозиторий `rosakodu/gyroparallax` на GitFlic в ветки `main` и `master`.
3. **Валидация и упаковка архива:**
   * Скачивать/собирать архив `gyroparallax.zip`.
   * **Обязательно** проверять правило 13: внутри архива должна быть корневая папка `GyroParallax/` (не плоский архив!).
   * Рассчитывать актуальный SHA256-хеш архива (`sha256sum`).
4. **Обновление каталога:**
   * Загружать `gyroparallax.zip` на сервер `deckyloader.ru` в `/var/www/deckyloader/store/plugins/gyroparallax.zip`.
   * Обновлять версию, хеш и дату (`created` выставлять на текущее время UTC) в `/var/www/deckyloader/store/testing.json` (а при переносе в основной каталог — в `plugins.json`).
   * Синхронизировать начальные данные в `index.html` и перевыгружать на сервер.

---

## 🛡️ 18. Обязательный фикс модального окна истории версий и запрет Carousel (ЖЕСТКОЕ ПРАВИЛО!)

> **КРИТИЧЕСКИ ВАЖНО:** В официальном апстриме `SteamDeckHomebrew/decky-loader` окно патчноутов и истории версий (`PatchNotesModal` в `frontend/src/components/settings/pages/general/Updater.tsx`) написано через компонент `Carousel` (`<Carousel ... />`). Этот компонент в Game Mode SteamOS фатально сломан и приводит к полному зависанию интерфейса!

### 1. Суть бага апстримного `Carousel`:
* **Симптомы:** При открытии патчноута отображается слайдер с точками `1 • 2 • 3`, правым боковым слайдом и полупрозрачным фоном. Кнопка «Закрыть» отсутствует, кнопки геймпада `(A)` и `(B)` не закрывают окно, а фокус ввода проваливается сквозь модалку на системные слои SteamOS (например, на экран ввода ПИН-кода блокировки). Пользователь оказывается заблокирован.
* **Причина:** В Game Mode SteamOS компонент `Carousel` внутри `showModal` перехватывает ввод, ломает дерево навигации GamepadNavigationTrees и не имеет обработчиков для событий геймпада `onCancel` / `onGamepadCancel`.

### 2. Жесткие требования реализации (Архитектурный стандарт):
1. **Категорический запрет на `Carousel`:** Использование компонента `Carousel` в диалоговых и модальных окнах **КАТЕГОРИЧЕСКИ ЗАПРЕЩЕНО**.
2. **Использование нативного `ConfirmModal`:** Компонент `PatchNotesModal` в `frontend/src/components/settings/pages/general/Updater.tsx` **ОБЯЗАН** строиться исключительно на нативном диалоге `<ConfirmModal>` из `@decky/ui`:
   * Флаг `bAlertDialog={true}` (режим системного диалога-оповещения).
   * Текст кнопки подтверждения: `strOKButtonText={t('General.close', 'Закрыть')}` (на этой кнопке гарантированно стоит фокус ввода по умолчанию).
   * Полная обвязка закрытия:
     ```tsx
     closeModal={handleClose}
     onOK={handleClose}
     onCancel={handleClose}
     onEscKeypress={handleClose}
     {...({ onGamepadCancel: handleClose } as any)}
     ```
   * Переключение версий: через безопасные системные кнопки `<DialogButton>` («← Предыдущая» и «Следующая →»).

### 3. Контроль при апстримных мерджах (`git merge upstream/main`):
* При любых синхронизациях с апстримом агент **ОБЯЗАН** проверять `frontend/src/components/settings/pages/general/Updater.tsx`. Если апстрим вернул компонент `Carousel`, эти правки **немедленно отменяются**, а наша реализация с `ConfirmModal` сохраняется!

### 4. Обязательная сборка фронтенда:
* Перед любой сборкой бинарников (на физическом Deck или хосте) агент **ОБЯЗАН** запускать `cd frontend && mise exec node@25.1.0 -- npx rollup -c`, так как `backend/decky_loader/static/` находится в `.gitignore` и зашивается в PyInstaller!

---

## 📦 19. Архитектура раздела «Программы» (Apps Manager) и сохранение совместимости с апстримом (ЖЕСТКОЕ ПРАВИЛО!)

> **КРИТИЧЕСКИ ВАЖНО:** В Decky Loader (Россия) интегрирован автономный раздел **«Программы»** для скачивания, обновления и управления независимыми AppImage-приложениями (Bloodborne PC port, PortProtonQt, PineconeMC, DeckyWolf, LocalSend, серия Craft-утилит). Раздел спроектирован так, чтобы гарантировать сохранность данных пользователя и максимальную легкость синхронизации с апстримом `SteamDeckHomebrew/decky-loader`.

### 1. Архитектурная изоляция (Модульный принцип):
Все компоненты раздела «Программы» изолированы от базового ядра Decky Loader:
* **Бэкенд:**
  * `backend/decky_loader/apps_manager.py` — автономный менеджер AppImage (скачивание, отмена, прогресс, desktop-файлы, права доступа `deck:deck`).
  * `backend/decky_loader/vdf_shortcuts.py` — безопасный парсер и инъектор `shortcuts.vdf` (без перезапуска клиента Steam).
  * Минимальная точка интеграции: `backend/decky_loader/wsrouter.py` регистрирует роуты `apps/*` и связывает WebSocket с фронтендом.
* **Фронтенд:**
  * `frontend/src/apps.ts` — типизированный клиент вызовов `apps/*`.
  * `frontend/src/components/store/AppsTab.tsx` — отдельный экран каталога программ с фильтрацией по категориям (Лаунчеры, Браузеры, Утилиты, Творчество) и поиском.
  * `frontend/src/components/store/AppCard.tsx` — карточка программы со строгим flex-распределением кнопок (`appActionBtnContainer`), индикатором прогресса загрузки и кнопкой отмены (`FaTimes`).
  * Минимальная точка интеграции: `frontend/src/components/store/Store.tsx` (вкладка «ПРОГРАММЫ» в таб-баре магазина).

### 2. Гарантия сохранности данных и конфигураций пользователей (Soft Push):
* **Принцип AppImage:** Файл AppImage является Read-Only образом SquashFS.
* **Пользовательские данные (Конфиги, сейвы, сессии):**
  * Все приложения сохраняют конфиги строго в `~/.config/<app>/` и `~/.local/share/<app>/`.
  * При обновлении программы (`AppsManager.install_app`) файл скачивается во временный `~/Applications/<exe>.AppImage.part`, после чего атомарно заменяет старый бинарник. **Папки `~/.config/`, префиксы Wine/эмуляторов и домашние файлы пользователя НЕ удаляются и НЕ перезаписываются!**
  * Путь в Steam (`shortcuts.vdf`) остается неизменным (`~/Applications/<exe>.AppImage`), поэтому пользовательские настройки геймпада и наигранное время сохраняются.
* **При удалении программы (`AppsManager.uninstall_app`):**
  * Удаляется **только** бинарник в `~/Applications/`, иконки и ярлыки рабочего стола/меню.
  * Каталоги сохранений и настроек в `~/.config/` **намеренно не стираются**, предотвращая потерю прогресса пользователя.

### 3. Регламент синхронизации с апстримом Decky Loader:
* При получении обновлений из апстрима (`git fetch upstream && git merge upstream/main`):
  1. Основные файлы Decky Loader мерджатся автоматически без конфликтов.
  2. Если конфликт возникает в `Store.tsx` — **всегда сохранять** наш таб-бар с вкладкой `AppsTab`.
  3. Если конфликт возникает в `wsrouter.py` — **всегда сохранять** вызов `AppsManager`.
  4. После мерджа всегда запускать полный цикл: `cd frontend && npm run build` ➔ нативная сборка `PluginLoader` на Steam Deck ➔ тестирование на консоли ➔ деплой на `deckyloader.ru`.

### 4. Серверная инфраструктура каталога программ:
* Каталог: `https://deckyloader.ru/store/apps.json` (и алиас `/store/apps`).
* Бинарные пакеты AppImage: `/var/www/deckyloader/store/apps/` (раздача напрямую с московского VPS РФ на максимальной скорости без блокировок зарубежных CDN).
* Изображения и иконки: `/var/www/deckyloader/store/images/apps/`.
* Обложки игрового режима (Steam Grid): `/var/www/deckyloader/store/grids/<app_id>/`.

### 5. Политика жесткой экономии диска на сервере: Ротация «N и N-1» (ЖЕСТКОЕ ПРАВИЛО!):
* **Ограничение инфраструктуры:** На основном VPS (`37.46.135.5`) объём диска составляет 15 ГБ, из которых свободно ~4.3 ГБ.
* **Правило ротации:** Для каждого пакета (как AppImage-программ, так и ZIP-плагинов) на сервере разрешено хранить **строго две версии**:
  1. **Текущий последний релиз ($N$)** — активная версия для чистой установки и обновлений.
  2. **Предпоследний релиз ($N-1$)** — резервная копия для функции быстрого отката («Downgrade») при несовместимости свежей версии.
* **Очистка устаревших релизов:** Все файлы более ранних версий ($N-2$, $N-3$ и т.д.) **обязательно удаляются** из файловой системы (`/var/www/deckyloader/store/apps/` и `/var/www/deckyloader/store/plugins/`), а их записи исключаются из истории версий каталога.
* Регулярный скрипт очистки: `scripts/cleanup_old_releases.py`. Общий объём хранилища на VPS удерживается в пределах ~2–2.5 ГБ.

### 6. Регламент выкатки (Pre-release ➔ Release):
* **Бета-тестирование:** Все новые фичи раздела «Программы» выкатываются исключительно в ветку **Pre-release** (`PluginLoader-prerelease`).
* **Стабильный релиз:** Ветка **Release** (`PluginLoader`) сохраняет стабильную апстрим-версию до полного тестирования на реальных устройствах.
* **Продвижение:** Перевод сборки с программами в статус стабильного релиза осуществляется только после подтверждения стабильности сообществом.

---

## 🏆 20. Обязательные требования к плагину SAM (Steam Achievement Manager) (ЖЕСТКОЕ ПРАВИЛО!)

> **КРИТИЧЕСКИ ВАЖНО:** При любых обновлениях, сборках или изменениях плагина **SAM (Steam Achievement Manager)** (`https://github.com/Kowalski-coder/SAM-for-Decky-Loader` | `https://gitflic.ru/project/viktorkoval1997/sam-for-decky-loader`), агент **ОБЯЗАН** строго следовать правилам:

### 1. Точное соответствие имени плагина (`name`):
* В файле `plugin.json` автора плагин зарегистрирован как `"name": "SAM"`.
* В каталоге и базах данных магазина (`plugins.json`, `testing.json`, `index.html`) имя плагина **ОБЯЗАНО** строго совпадать с полем в `plugin.json` — **`"name": "SAM"`**.
* *Причина:* Загрузчик Decky Loader при установке проверяет `plugin['name'] == name` (`browser.py:115`) и ищет директорию плагина `SAM/`. Если в каталоге указать другое имя (например `Steam Achievement Manager`), поиск завершается падением `AssertionError`, а интерфейс магазина зависает на 90% установки.

### 2. Мониторинг релизов через бота:
* Репозиторий `Kowalski-coder/SAM-for-Decky-Loader` подключен к автоматическому Telegram-боту мониторинга апстрима (`/var/www/deckyloader/check_upstream.py`).
* При публикации нового релиза бот отправляет уведомление в группу разработчиков. Агент обязан оперативно скачивать архив, проверять структуру и обновлять версию на сервере.

---

## 🚀 21. Обязательные требования к плагину Station (ЖЕСТКОЕ ПРАВИЛО!)

> **КРИТИЧЕСКИ ВАЖНО:** Плагин **Station** от разработчика `kntn-popov` (`https://gitflic.ru/project/kntn-popov/station`) позволяет устанавливать portable-игры, автоматически настраивать Wine-префиксы и поднимать SMB-шары в игровом режиме.

### 1. Наличие бандла фронтенда (`dist/index.js`):
* Релизы плагина на GitFlic содержат два вида архивов: архив исходного кода (`Station.zip`) и собранный релиз (`Station-vX.X.X.zip`).
* В каталог `deckyloader.ru` разрешено выгружать **только** архив со скомпилированным бандлом `Station/dist/index.js`! Без директории `dist/` плагин запускается в фоне, но вкладка и интерфейс в меню быстрого доступа QAM не отображаются.

### 2. Корневая директория архива:
* Архив обязан быть упакован с корневой папкой `Station/` (содержащей `main.py`, `plugin.json`, `dist/index.js` и `py_modules/`).

### 3. Мониторинг релизов на GitFlic через бота:
* Репозиторий `kntn-popov/station` отслеживается ботом `/var/www/deckyloader/check_upstream.py` напрямую через GitFlic парсер релизов. При выходе свежей версии бот уведомляет команду в Telegram.