Руководство по разработке расширений

10 реальных хуков Saba-chan и спецификация manifest.json, внедрение в слоты GUI и заметки о реализации встроенных расширений.

Руководство по разработке расширений

Расширение (плагин) — это дополнение, которое не привязано к конкретной игре, а глобально встраивается в жизненный цикл демона или внедряет компоненты в GUI. Демон Saba-chan передаёт управление включённым расширениям в следующих 10 точках (хуках). Сейчас в комплекте есть установка/обновление через SteamCMD (steamcmd) и парсер INI для UE4 (ue4-ini).

Содержание этого документа основано на реальных файлах manifest.json из репозитория saba-chan-extensions и на системе расширений на стороне демона (src/extension/mod.rs).


1. Структура файлов

%APPDATA%\saba-chan\extensions\<extension_id>\
  • manifest.jsonобязательно. Объявляет хуки, зависимости, поляобязательно. Объявляет хуки, зависимости, поля
  • __init__.pyпозволяет модулям импортировать расширение как extensions.<name>позволяет модулям импортировать расширение как extensions.<name>
  • <python_modules>.pyфайлы, на которые ссылается python_modules в manifest.jsonфайлы, на которые ссылается python_modules в manifest.json
  • icon.pngнеобязательнонеобязательно
  • gui/необязательно. Исходники и результат сборки пакета GUI (UMD)необязательно. Исходники и результат сборки пакета GUI (UMD)
  • i18n/необязательно. Задаётся через i18n_dir в манифесте (<locale>.json)необязательно. Задаётся через i18n_dir в манифесте (<locale>.json)
  • test_<name>.pyрекомендуется. Тесты pytestрекомендуется. Тесты pytest
  • Имя папки должно совпадать с id в манифесте. Допускается и id, в котором дефисы заменены подчёркиваниями (например, id ue4-ini → папка ue4_ini). Иначе демон не загружает расширение и перечисляет его в failed в ответе GET /api/extensions.
  • id может содержать только буквы, цифры, - и _.

2. Спецификация manifest.json

Реальный манифест расширения SteamCMD:

{
  "schema_version": 1,                    // при 1 неизвестные ключи и никогда не вызываемые хуки — ошибки
  "id": "steamcmd",                       // совпадает с именем папки
  "name": "SteamCMD",
  "version": "0.1.0",
  "description": "Installs and updates game servers with SteamCMD",
  "descriptions": { "ko": "SteamCMD를 사용한 게임 서버 설치 및 업데이트 자동화" },
  "author": "WareAoba",
  "min_app_version": "0.1.0",
  "dependencies": [],                     // зависимости от других расширений (массив или { "id": ">=x.y.z" })

  "python_modules": {
    "steamcmd": "steamcmd.py"             // логическое имя → путь к файлу
  },

  "hooks": {
    "server.check_update": {
      "module": "steamcmd",
      "function": "check_update",
      "condition": "instance.ext_data.install_method_steamcmd"
    }
  },

  "instance_fields": {
    "install_method_steamcmd": { "type": "boolean", "default": false },
    "steamcmd_app_id": { "type": "number", "optional": true },
    "steamcmd_anonymous": { "type": "boolean", "default": true },
    "steamcmd_beta": { "type": "string", "optional": true },
    "steamcmd_platform": { "type": "string", "optional": true }
  },
  "permissions": { "network": true, "spawn_process": true }
}

Сводка по полям:

  • schema_version: при 1 неизвестные ключи, имена хуков, отсутствующие в FIRED_HOOKS, и ссылки на несуществующие python_modules являются ошибками. Без него (0) это лишь предупреждения.
  • id, name, version: обязательны. version используется при сравнении для обновлений и зависимостей.
  • description / descriptions: описание на английском и описания по языкам. API списка выбирает то, что соответствует языку GUI.
  • min_app_version: расширение нельзя включить или установить в более старой версии Saba-chan.
  • dependencies: зависимости от других расширений (или от saba-core). Поддерживаются только требования версии вида >=. При включении проверяется, что зависимости включены; автоматически они не включаются.
  • python_modules: регистрирует по логическим именам Python-файлы, на которые ссылаются хуки и команды. Файлы, не зарегистрированные здесь, хуки вызвать не могут.
  • hooks.<имя хука>
    • module: логическое имя, объявленное в python_modules
    • function: имя функции в этом файле
    • condition (необязательно): поддерживается только форма instance.ext_data.<key>. Хук выполняется только для экземпляров, у которых это значение истинно, является ненулевым числом или непустой строкой.
  • instance_fields: значения для каждого экземпляра, которые использует расширение (extension_data). Если хотя бы у одного экземпляра значение задано, выключение или удаление расширения отклоняется (in_use).
  • config_fields: поля глобальных настроек расширения. Значения хранятся в extensions.settings.<id> в config.json.
  • gui: bundle (путь к UMD-пакету), styles (путь к CSS). См. раздел 5 ниже.
  • cli: объявления слотов CLI (cli.slots).
  • commands: команды, добавляемые в список команд экземпляра (name, label, risk, inputs, module, function, condition).
  • priority: порядок, когда у нескольких расширений один и тот же хук (меньшее значение выполняется раньше, по умолчанию 100).
  • i18n_dir: папка с файлами переводов.
  • permissions: объявляет рискованные возможности, которые использует код (та же таблица, что и [permissions] модуля).

У хуков нет поля async, а в манифесте нет manifest_url. Список расширений и обновления берутся только из подписанного манифеста релизов Saba-chan.


3. 10 реальных хуков

Функции хуков выполняются так же, как модули. Демон запускает python <файл>.py <имя функции>, записывает в stdin JSON контекста и читает JSON из stdout (целиком или последнюю строку) как результат. Код выхода должен быть 0. Список ниже совпадает с FIRED_HOOKS в коде демона.

Имя хукаКогда вызываетсяКак используется результатВыполнение
daemon.startupСразу после запуска демона / сразу после включения расширения (только для этого расширения)success/message попадают в состояние инициализации (/api/extensions/init-status)В фоне
daemon.shutdownНепосредственно перед завершением демонаТолько записывается в журналСинхронно
server.pre_startНепосредственно перед запуском сервераhandled: true заменяет стандартный запуск (если при этом success не истинно, запуск завершается ошибкой)Синхронно
server.stopНепосредственно перед остановкой сервераhandled: true берёт остановку на себяСинхронно
server.statusПри запросе состояния отдельного сервераhandled: true возвращает этот результат как естьСинхронно
server.list_enrichПри выводе списка экземпляровhandled: true заполняет status и extension_status. Тайм-аут 10 с, кеш с TTL 30 сСинхронно
server.post_createСразу после создания экземпляраРезультат не используетсяВ фоне
server.pre_deleteНепосредственно перед удалением экземпляраПри handled демон немного ждёт, чтобы освободились блокировки файловСинхронно
server.settings_changedПосле сохранения настроек экземпляраРезультат не используетсяСинхронно
server.check_updateПри запросе проверки обновленийОтветом становится первый успешный результатСинхронно

Таких имён, как server.pre_create, server.pre_install, server.post_install, server.post_start, module.parse_settings и module.write_settings, не существует; их использование в манифесте с schema_version = 1 приводит к ошибке загрузки.

3.1 Контекст и точка входа

Функция хука принимает один словарь контекста и возвращает словарь. В зависимости от хука контекст содержит instance_id, instance_name, module, instance_dir, extension_data и т. д., а каждый хук также получает глобальные настройки расширений как extension_config. Python-файл должен сам обрабатывать имя функции и stdin в __main__. Сокращённый пример структуры steamcmd.py:

import json, sys, traceback

def check_update(ctx: dict) -> dict:
    """
    пример ctx (server.check_update):
      {
        "instance_id": "…",
        "instance_name": "My Palworld",
        "module": "palworld",
        "instance_dir": "…",
        "install_dir": "…",
        "app_id": 2394010,
        "extension_data": {"install_method_steamcmd": true, ...},
        "extension_config": {...}
      }
    """
    ...
    return {"success": True, "update_available": False}

FUNCTIONS = {"check_update": check_update}

if __name__ == "__main__":
    name = sys.argv[1] if len(sys.argv) > 1 else ""
    try:
        raw = sys.stdin.read()
        ctx = json.loads(raw) if raw.strip() else {}
        result = FUNCTIONS[name](ctx) if name in FUNCTIONS else \
            {"success": False, "message": f"Unknown function: {name}"}
    except Exception as e:
        traceback.print_exc(file=sys.stderr)      # журналы — в stderr
        result = {"success": False, "message": str(e)}
    print(json.dumps(result, ensure_ascii=False))  # ошибки тоже — JSON + код выхода 0

3.2 handled и порядок выполнения

  • Расширения с одним и тем же хуком выполняются по одному, по порядку priority, затем по id.
  • Если результат содержит handled: true, оставшиеся расширения пропускаются. Не указывайте handled, если вы не заменяете стандартное поведение этого хука.
  • Если одно расширение завершилось ошибкой, ошибка записывается, и выполняется следующее расширение.
  • Лимит времени по умолчанию — 120 секунд. На пути хуков отображения прогресса (PROGRESS:) нет.

3.3 Кеш с TTL для server.list_enrich

Этот хук может вызываться друг за другом для каждого экземпляра с extension_data при каждом запросе списка экземпляров, поэтому демон кеширует успешные результаты на 30 секунд. Пока кеш действителен, демон повторно использует прежний результат, не запуская процесс Python. У каждого вызова тайм-аут 10 секунд, так что проектируйте хук так, чтобы он завершался быстро. status_line в результате — это короткое однострочное состояние, которое показывается в отображении состояния в Discord, поэтому не помещайте в него пути и секреты.


4. 3 встроенных расширения

steamcmd

  • id: steamcmd
  • Python: steamcmd.py (класс SteamCMD: портативная установка SteamCMD, установка/обновление игровых серверов, проверка обновлений)
  • Хук: только server.check_update (condition: instance.ext_data.install_method_steamcmd).
  • Саму установку выполняет install_server модуля напрямую через from extensions.steamcmd import SteamCMD.
  • instance_fields: install_method_steamcmd, steamcmd_app_id, steamcmd_anonymous, steamcmd_beta, steamcmd_platform. Демон заполняет их из секции [install] модуля по общему правилу (install_method_<method>, <method>_<field>).
  • GUI нет.

ue4-ini

  • id: ue4-ini (имя папки ue4_ini)
  • Python: ue4_ini.py (parse_option_settings, write_option_settings)
  • Назначение: предоставляет модулям утилиты для чтения и записи OptionSettings=(...) в INI игр на UE4, например Palworld.
  • Это чистая библиотека, не объявляющая хуков; модули импортируют её как extensions.ue4_ini.

xna

  • id: xna
  • Python: xna.py (install, present, XnaError)
  • Назначение: кладёт фиксированную версию Microsoft XNA Framework 4.0 Refresh рядом с папкой игрового сервера, не устанавливая её на ПК. Нужна Windows-серверу Terraria. Один раз загружает официальный MSI, сверяет его по зафиксированному SHA-256 и извлекает только нужные файлы.
  • Это чистая библиотека, не объявляющая хуков; модули используют её через from extensions.xna import install, present.

Модули не могут импортировать выключенные расширения. Защита импорта демона блокирует импорт любого extensions.<name>, которого нет в SABA_ENABLED_EXTENSIONS.


5. Пакет GUI (внедрение в слоты)

Если в manifest.json объявлен gui.bundle, GUI получает этот файл через GET /api/extensions/:id/gui и выполняет его (а если задан gui.styles, внедряет и CSS).

"gui": { "bundle": "gui/dist/index.umd.js", "styles": "gui/dist/style.css" }   // пути для примера
  • Пакет должен быть в формате UMD и создавать глобальный объект window.SabaExt<id в PascalCase>. Уберите из id - и _ и сделайте следующую за ними букву заглавной (например, steamcmd → window.SabaExtSteamcmd, ue4-ini → window.SabaExtUe4Ini).
  • Когда registerSlots() этого объекта возвращает { slotId: Component | Component[] }, GUI монтирует их в соответствующие слоты.
  • React подключается как внешняя зависимость из window.React хоста. Компоненты должны работать, используя только props, которые передаёт слот.
  • Переводы загружаются через GET /api/extensions/:id/i18n/:locale в пространство имён ext_<id>.
Id слотаГдеprops
ServerCard.badgeЗначок на карточке сервераserver
ServerCard.headerGaugeИндикатор в заголовке карточки сервераserver
ServerCard.provisionКарточка сервера во время подготовкиserver, provisionProgress, onDismiss, t
ServerCard.expandedStatsСтатистика развёрнутой карточки сервераserver, t
ServerSettings.tabВкладка настроек сервераserver, activeTab, setActiveTab, settings, onSettingsChange, t
AddServer.optionsПараметры добавления сервераt

server — это сведения о сервере из /api/servers; компоненты могут читать extension_data и extension_status[<extension_id>] (результат server.list_enrich).


6. Управление расширениями через REST API

GET    /api/extensions                   Список установленных (+ ошибки загрузки)
GET    /api/extensions/init-status       Результаты daemon.startup
POST   /api/extensions/rescan            Перечитать папку
GET    /api/extensions/manifest          Удалённый каталог (подписанный манифест релизов)
GET    /api/extensions/updates           Список обновлений
POST   /api/extensions/:id/install       Установить (из каталога, со сверкой sha256)
POST   /api/extensions/:id/enable        Включить → выполняет daemon.startup этого расширения
POST   /api/extensions/:id/disable       Выключить
POST   /api/extensions/:id/mount         Зарегистрировать в памяти
POST   /api/extensions/:id/unmount       Снять регистрацию в памяти
DELETE /api/extensions/:id               Удалить
GET    /api/extensions/:id/config        Значения config_fields
PUT    /api/extensions/:id/config        Обновить значения
GET    /api/extensions/:id/gui           Пакет GUI (JS)
GET    /api/extensions/:id/gui/styles    Стили GUI (CSS)
GET    /api/extensions/:id/icon          Значок
GET    /api/extensions/:id/audit         Сравнить возможности, используемые кодом, с permissions
GET    /api/extensions/:id/i18n/:locale  JSON локализации

Список включённых расширений хранится в extensions.enabled в config.json, а значения глобальных настроек — в extensions.settings.


7. Правила разработки

  • Расширения тоже не должны зависеть от кода демона. Используйте только контекст и переменные окружения, которые передаёт демон.
  • Собирайте пути через os.path.join; не прописывайте их жёстко.
  • Функции хуков тоже отвечают на ошибки JSON-ом (success: false с причиной) и кодом выхода 0, а журналы и трассировки отправляют в stderr.
  • Для condition используйте только форму instance.ext_data.<key>. Любая другая форма всегда даёт ложь.
  • Python-зависимости используют общее окружение демона. Отдельного объявления requirements для расширения нет.
  • Непроверенные расширения: расширения, загруженные не из подписанного каталога или изменённые после загрузки, работают в той же изолированной среде, что и модули (AppContainer в Windows, bubblewrap в Linux). Антивирусная проверка не выполняется. Далее описана Windows. Им недоступен loopback (например, API демона), они не получают SABA_TOKEN_PATH и могут только читать папки экземпляров. Данные, которые нужно записывать, кладите в выделенную папку, на которую указывает переменная окружения SABA_EXTENSION_DATA_DIR.
  • Тесты запускайте командой pytest из корня репозитория.