Конфигурация и метаданные пользовательского интерфейса

Область применения: все объявления конфигурации, наследующие BaseConfig / BotAccountConfig (глобальные настройки адаптера, настройки аккаунта, настройки модуля).

Система конфигурации ErisPulse является декларативной: разработчики описывают параметры конфигурации с помощью полей dataclass и метаданных, а фреймворк get_config_schema() преобразует их в JSON Schema, который может быть использован любым потребителем (панель управления, сторонняя панель, CLI-модуль и т.д.) для отображения. В этой статье приведено нормативное определение этих метаданных — семантика виджетов, форма значений, условия отображения и обязательства по совместимости определяются исключительно здесь; конкретная реализация за потребителями, но семантика должна соответствовать этой статье.

Структура объявления

from dataclasses import dataclass, field
from ErisPulse.Core.Bases import BaseConfig, BotAccountConfig

@dataclass
class MyAdapterConfig(BaseConfig):
    """Глобальная конфигурация адаптера"""

@dataclass
class MyAccountConfig(BotAccountConfig):
    """Конфигурация аккаунта (адаптер с несколькими аккаунтами)"""
    token: str = field(
        default="",
        metadata={
            "description": "Токен доступа",
            "required": True,
            "secret": True,
            "ui": {
                "widget": "password",
                "group": "basic",
                "order": 1,
                "placeholder": "Вставьте токен платформы",
            },
        },
    )

Основные метаданные (ключи верхнего уровня metadata)

UI-метаданные (подтаблица metadata["ui"])

Ключ ui является стандартным; webui — это старое алиас (эквивалентно, потребители должны поддерживать оба).

Общие ключи

Условное отображение/отключение (взаимосвязь полей)

Объект условия: {"field": <имя поля или полный ключ конфигурации в том же диапазоне>, "op": <оператор>, "value": <сравниваемое значение>}. Набор операторов:

Если op не указан, по умолчанию используется eq. Разбор поля: сначала по короткому имени в том же диапазоне конфигурации, затем по полному ключу (например, accounts.default.mode).

Формат значения (value_type, используется для multiselect)

Обязанности потребителя: Если value_type не указан, необходимо определять по типу поля (если int и цифровые опции → mask; если list → array; в остальных случаях → json), чтобы при объявлении только widget: multiselect можно было корректно записывать значения нужного типа.

Справочник виджетов

Потребитель должен реализовать следующую семантику; неизвестные виджеты должны возвращаться к однорядному тексту, без ошибок.

Контракт совместимости (должен соблюдаться потребителями)

1. Игнорировать неизвестные ключи: при появлении в метаданных ключей, не описанных в спецификации (включая будущие добавления), игнорировать их без ошибки.
2. Вернуться к text для неизвестного widget: обеспечить, чтобы новые объявления оставались редактируемыми на старых потребителях.
3. Условие не выполнено ≠ удаление значения: значения полей, скрытых через show_if, сохраняются без изменений.
4. Типизация по умолчанию: при отсутствии расширенных ключей, таких как value_type, корректно определять форму хранения на основе типа поля.

Полный пример

@dataclass
class OneBotAccountDemo(BotAccountConfig):
    mode: str = field(
        default="server",
        metadata={
            "description": "Режим подключения",
            "ui": {
                "widget": "select",
                "group": "connection",
                "order": 1,
                "options": [
                    {"label": "Server (пассивный)", "value": "server"},
                    {"label": "Client (активный)", "value": "client"},
                ],
            },
        },
    )
    url: str = field(
        default="ws://127.0.0.1:3001",
        metadata={
            "description": "Адрес WebSocket",
            "ui": {
                "widget": "text",
                "group": "connection",
                "order": 2,
                "show_if": {"field": "mode", "op": "eq", "value": "client"},
            },
        },
    )
    intents: int = field(
        default=33281,
        metadata={
            "description": "Маска битов (поле типа int, автоматически хранится по маске)",
            "ui": {
                "widget": "multiselect",
                "group": "advanced",
                "order": 3,
                "options": [
                    {"label": "Основа каналов", "value": 0},
                    {"label": "Сообщения каналов", "value": 9},
                    {"label": "Содержание сообщений (привилегии)", "value": 15},
                ],
            },
        },
    )

Схема вывода

ErisPulse.Core.Bases.config_schema.get_config_schema(cls) выводит JSON-схему (поля/группы/account_based/метаданные), и прозрачно передает все ключи подтаблицы ui, определённые в настоящем документе, для прямого использования потребителями.