ErisPulse ErisPulse
Открыть интерактивную версию →
Разделы страницы
Архитектура адаптера Компоненты и связи AdapterManager (менеджер адаптеров) Основные функции Основное использование Запуск и остановка Управление конфигурацией Слушатели событий Промежуточные обработчики Получение экземпляра адаптера BaseAdapter (базовый класс адаптера) Основная структура Управление конфигурацией Декларативные ключи перевода (v2.7.0+) Декларативные методы расширения событий (v2.7.0+) Процесс инициализации DSL для отправки сообщений Send Наследование Доступные атрибуты Вспомогательные методы фреймворка Основные методы Методы цепочки модификаторов Конвертер событий Процесс преобразования Обязательные поля Повторное получение событий для нескольких учетных записей (внедрение фреймворком) Пример конвертера Управление подключениями Два правильных способа реализации start() Базовые классы для режимов подключения WebSocket-подключение WebHook-подключение Стандартный формат ответа API Успешный ответ Ручное создание ответа (старый способ по-прежнему совместим) Поддержка нескольких аккаунтов Декларативная конфигурация (рекомендуется) Файл конфигурации аккаунта Отправка с указанием аккаунта Связь идентификатора аккаунта в событии и Using Обработка ошибок Повторные попытки подключения Обработка ошибок API Управление состоянием бота Автоматическая обнаружение Типы мета-событий Отправка мета-событий адаптером Расширение поля self Запрос состояния бота Отслеживание жизненного цикла бота Связанные документы Глубокое понимание реализации Повторное изучение шагов старта
Статическое зеркало — интерактивная версия является основной Открыть интерактивную версию →

Основные концепции адаптера

Tip

Когда читать эту статью: Обязательно при разработке адаптера (полное описание основных механизмов: BaseAdapter, SendDSL, жизненного цикла и т.д.). Для быстрого старта можно сначала прочитать Введение в разработку адаптера, а при возникновении вопросов "почему так" — обратиться к этой статье.

В этой статье объясняется механизм работы адаптера: как AdapterManager регистрирует и распределяет события, что делает BaseAdapter при инициализации, как объявляются конфигурации и многоаккаунтность — всё, что вызывает вопрос "почему так пишется", можно найти здесь.

Архитектура адаптера

Компоненты и связи

Прямое преобразование (направление получения)                           Обратное преобразование (направление отправки)
─────────────────                           ─────────────────
                                             
┌──────────────────┐                        ┌──────────────────┐
│ Платформа: оригинальные события │                        │ Модуль: построение сообщений │
└────────┬─────────┘                        └────────┬─────────┘
         │                                           │
         ↓                                           ↓
┌──────────────────┐   ┌──────────────────┐   ┌──────────────────┐
│                  │   │  Адаптер (MyAdapter) │   │                  │
│  Converter       │   │ ┌──────────────┐ │   │ Send.Raw_ob12()  │
│  (конвертер событий)    │──→│ │              │ │   │ (точка входа в обратное преобразование)   │
│                  │   │ │              │ │   │                  │
└──────────────────┘   │ └──────────────┘ │   └────────┬─────────┘
                       └──────────────────┘            │
                                │                      ↓
                                ↓              ┌──────────────────┐
                       ┌──────────────────┐    │ Платформа: вызов API    │
                       │ OneBot12: стандартные события │    └────────┬─────────┘
                       └────────┬─────────┘             │
                                │                      ↓
                                ↓              ┌──────────────────┐
                       ┌──────────────────┐    │ Стандартный формат ответа    │
                       │ Система событий         │    └──────────────────┘
                       └────────┬─────────┘
                                │
                                ↓
                       ┌──────────────────┐
                       │ Модуль: обработка событий  │
                       └──────────────────┘

Основная симметрия:

  • Прямое преобразование (Converter): платформа → OneBot12, оригинальные данные сохраняются в {platform}_raw
  • Обратное преобразование (Raw_ob12): OneBot12 → платформа, возвращает стандартный формат ответа

AdapterManager (менеджер адаптеров)

AdapterManager — основной компонент системы адаптеров ErisPulse, отвечающий за управление всеми платформенными адаптерами: регистрацию, запуск, остановку и распределение событий.

Основные функции

  • Регистрация адаптеров: управление несколькими платформенными адаптерами
  • Управление жизненным циклом: запуск и остановка адаптеров
  • Распределение событий: распределение стандартных событий OneBot12 и оригинальных событий платформы
  • Управление конфигурацией: управление статусом включения/отключения адаптеров
  • Поддержка промежуточных обработчиков: поддержка промежуточных обработчиков событий OneBot12

Основное использование

from ErisPulse import sdk

# Регистрация адаптера (обычно автоматически делается Loader)
sdk.adapter.register("myplatform", MyPlatformAdapter)

# Запуск всех адаптеров
await sdk.adapter.startup()

# Запуск указанного адаптера
await sdk.adapter.startup(["myplatform"])
# Запуск всех адаптеров
await sdk.adapter.startup()

# Получение экземпляра адаптера
my_adapter = sdk.adapter.get("myplatform")
# Или через атрибут
my_adapter = sdk.adapter.myplatform

# Остановка всех адаптеров
await sdk.adapter.shutdown()

Запуск и остановка

Запуск адаптера

# Запуск всех зарегистрированных адаптеров
await sdk.adapter.startup()

# Запуск указанной платформы
await sdk.adapter.startup(["platform1", "platform2"])

Процесс запуска:

  1. Отправка события adapter.start жизненного цикла
  2. Отправка события adapter.status.change (starting)
  3. Параллельный запуск адаптеров
  4. Если запуск не удался, автоматическая повторная попытка (экспоненциальная стратегия отката)
  5. После успешного запуска отправка события adapter.status.change (started)

Стратегия повторных попыток:

  • Первые 4 попытки: 60 секунд, 10 минут, 30 минут, 60 минут
  • С пятой попытки и далее: фиксированный интервал 3 часа

Остановка адаптера

# Остановка всех адаптеров
await sdk.adapter.shutdown()

Процесс остановки:

  1. Отправка события adapter.stop жизненного цикла
  2. Вызов метода shutdown() всех адаптеров
  3. Остановка сервера маршрутизации
  4. Очистка обработчиков событий
  5. Отправка события adapter.stopped жизненного цикла

Управление конфигурацией

Проверка статуса платформы

# Проверка, зарегистрирована ли платформа
exists = sdk.adapter.exists("myplatform")

# Проверка, включена ли платформа
enabled = sdk.adapter.is_enabled("myplatform")

# Использование оператора in
if "myplatform" in sdk.adapter:
    print("Платформа существует и включена")

Список платформ

# Список всех зарегистрированных платформ
platforms = sdk.adapter.list_registered()

# Список всех платформ и их статусов
status_dict = sdk.adapter.list_items()
# Возвращает: {"platform1": true, "platform2": false, ...}

# Получение списка включенных платформ
enabled_platforms = [p for p, enabled in status_dict.items() if enabled]

Слушатели событий

Стандартные события OneBot12

from ErisPulse import sdk

# Слушать все стандартные события сообщений
@sdk.adapter.on("message")
async def handle_message(data):
    print(f"Получено OneBot12 сообщение: {data}")

# Слушать стандартные события сообщений определенной платформы
@sdk.adapter.on("message", platform="myplatform")
async def handle_platform_message(data):
    print(f"Получено сообщение myplatform: {data}")

# Слушать все события
@sdk.adapter.on("*")
async def handle_any_event(data):
    print(f"Получено событие: {data.get('type')}")

Оригинальные события платформы

# Слушать оригинальные события определенной платформы
@sdk.adapter.on("raw_event_type", raw=True, platform="myplatform")
async def handle_raw_event(data):
    print(f"Получено оригинальное событие: {data}")

# Слушать оригинальные события всех платформ (шаблон)
@sdk.adapter.on("*", raw=True)
async def handle_all_raw_events(data):
    print(f"Получено оригинальное событие: {data}")

Механизм распределения событий

При вызове adapter.emit(event_data):

  1. Обработка промежуточными обработчиками: сначала выполняются все промежуточные обработчики OneBot12
  2. Распределение стандартных событий: распределяются по соответствующим обработчикам стандартных событий
  3. Распределение оригинальных событий: если есть оригинальные данные, распределяются по обработчикам оригинальных событий

Правила сопоставления:

  • Точное совпадение: @sdk.adapter.on("message") только для события message
  • Шаблон: @sdk.adapter.on("*") для всех событий
  • Фильтрация по платформе: platform="myplatform" только для событий указанной платформы

Промежуточные обработчики

Добавление промежуточного обработчика

@sdk.adapter.middleware
async def logging_middleware(data):
    """Промежуточный обработчик для логирования"""
    print(f"Обработка события: {data.get('type')}")
    return data  # Должен вернуть данные

@sdk.adapter.middleware
async def filter_middleware(data):
    """Промежуточный обработчик для фильтрации"""
    # Фильтрация ненужных событий
    if data.get("type") == "notice":
        return None  # Возвращение None игнорирует результат, сохраняя исходные данные
    return data  # Должен вернуть данные для продолжения передачи

Возвращаемое значение промежуточного обработчика

Возвращаемое значение Поведение
dict Изменяет данные события (последующие обработчики получают измененные события)
None Пропуск, данные остаются неизменными (выводит предупреждение — рекомендуется явно return data)
False Отклонение: событие отбрасывается, не передается ни одному обработчику, без побочных эффектов

Отклонение подходит для сценариев "отбрасывания на уровне событий" (например, брандмауэр, ограничение скорости, черный список). При отклонении фреймворк выводит трассировку и запускает хук жизненного цикла adapter.event.blocked (с именем промежуточного обработчика, полным событием, platform / event_type / detail_type), что помогает отслеживать "почему событие не ответило":

@sdk.adapter.middleware
async def rate_limit_middleware(data):
    """Промежуточный обработчик для ограничения скорости"""
    if _is_rate_limited(data):
        return False  # Отклонение: событие отбрасывается
    data["rate_marked"] = True
    return data

@sdk.lifecycle.on("adapter.event.blocked")
async def on_event_blocked(data):
    print(f"Событие отклонено {data['middleware']}: {data['event_type']}")

Порядок выполнения промежуточных обработчиков

Промежуточные обработчики выполняются в порядке регистрации, последний зарегистрированный обработчик выполняется первым.

Внимание: если промежуточный обработчик возвращает None (например, забыл return data), фреймворк игнорирует этот результат, сохраняет исходные данные и выводит предупреждение уровня warning. Это гарантирует, что ошибка одного промежуточного обработчика не приведет к прерыванию всей цепочки событий.

# Регистрация в порядке
sdk.adapter.middleware(middleware1)  # Выполняется последним
sdk.adapter.middleware(middleware2)  # Выполняется посередине
sdk.adapter.middleware(middleware3)  # Выполняется первым

# Порядок выполнения: middleware3 -> middleware2 -> middleware1

Получение экземпляра адаптера

Метод get()

adapter = sdk.adapter.get("myplatform")
if adapter:
    await adapter.Send.To("user", "123").Text("Hello")

Атрибутный доступ

# Через имя атрибута (без учета регистра)
adapter = sdk.adapter.myplatform
await adapter.Send.To("user", "123").Text("Hello")

BaseAdapter (базовый класс адаптера)

Основная структура

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

@dataclass
class MyConfig(BaseConfig):
    """Конфигурация адаптера (объявляется, фреймворк автоматически управляет)"""
    token: str = field(
        default="",
        metadata={
            "description": {"i18n": "my_adapter.token", "default": "Токен бота"},
            "required": True,
            "secret": True,
            "ui": {"widget": "password", "group": "basic", "order": 1},
        },
    )

class MyAdapter(BaseAdapter):
    ConfigClass = MyConfig  # Объявление класса конфигурации
    
    # Не нужно переопределять __init__, фреймворк автоматически обрабатывает:
    # - self.sdk, self.logger
    # - self.cfg (типоверная конфигурация, считывается в реальном времени)
    # - self.Send, self.Request
    
    async def start(self):
        """Запуск адаптера (обязательно реализовать)"""
        cfg = self.cfg  # Автоматически загруженная типоверная конфигурация
        pass
    
    async def shutdown(self):
        """Остановка адаптера (обязательно реализовать)"""
        pass
    
    async def call_api(self, endpoint: str, **params):
        """Вызов платформенного API (обязательно реализовать)"""
        pass

Управление конфигурацией

Фреймворк предоставляет декларативное управление конфигурацией, определяя структуру конфигурации с помощью dataclass, фреймворк автоматически обрабатывает загрузку, проверку и генерацию шаблонов.

Конфигурация одного аккаунта

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

@dataclass
class TelegramConfig(BaseConfig):
    token: str = field(default="", metadata={
        "description": {"i18n": "telegram.token", "default": "Токен бота"},
        "required": True,
        "secret": True,
        "ui": {"widget": "password", "group": "basic", "order": 1},
    })
    proxy: str = field(default="", metadata={
        "description": {"i18n": "telegram.proxy", "default": "Адрес прокси"},
        "ui": {"widget": "text", "group": "advanced", "order": 10},
    })

class TelegramAdapter(BaseAdapter):
    ConfigClass = TelegramConfig
    
    async def start(self):
        cfg = self.cfg  # Типоверная, считывается в реальном времени
        if not cfg.token:
            raise ValueError("Не настроен токен")
        await self._connect(cfg.token, proxy=cfg.proxy)

Конфигурация нескольких аккаунтов

Базовый класс BotAccountConfig предоставляет поля enabled и name. Большинство адаптеров могут автоматически получать bot_id из протокола платформы или ответа на вход, в процессе преобразования событий вставляется в конфигурацию аккаунта.:

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

# Большинство адаптеров: bot_id получается во время выполнения, не нужно конфигурировать
@dataclass
class MyBotConfig(BotAccountConfig):
    token: str = field(default="", metadata={
        "description": {"i18n": "my_adapter.bot_token", "default": "Токен"},
        "required": True,
    })

# Если при входе невозможно получить bot_id, можно позволить пользователю ввести в конфигурации
@dataclass
class YunhuBotConfig(BotAccountConfig):
    bot_id: str = field(default="", metadata={
        "description": {"i18n": "yunhu.bot_id", "default": "ID бота"},
        "required": True,
    })
    token: str = field(default="", metadata={
        "description": {"i18n": "yunhu.token", "default": "Токен"},
        "required": True,
    })

class MyAdapter(BaseAdapter):
    AccountConfigClass = MyBotConfig
    
    async def start(self):
        for name, account in self.enabled_accounts.items():
            user_id = await self._login(name, account)
            await self.emit_meta("connect", user_id)

Соглашение о metadata

Поле metadata служит для генерации комментариев TOML и рендеринга веб-интерфейса формы:

metadata = {
    "description": str | dict,  # Описание поля (поддержка i18n)
    "required": bool,         # Обязательно ли поле (проверка + метка обязательного поля в веб-интерфейсе)
    "secret": bool,           # Является ли поле секретным (отображается как *** в веб-интерфейсе, маскируется в логах)
    "example": bool,          # Не сохраняется в файле: не записывается в config.toml (исключается из значений по умолчанию и шаблонов),
                              # только рендерится в config.full.example; schema с меткой "example": true,
                              # конфигурационный помощник командной строки по умолчанию пропускает; после ручного установки пользователем сохраняется нормально
    "min": number, "max": number,  # Проверка диапазона значений
    "ui": {                   # Конфигурация элемента управления веб-интерфейсом (старое имя "webui" по-прежнему поддерживается)
        "widget": str,        # Тип элемента управления: "text" | "switch" | "select" | "number" | "password"
        "group": str,         # Группа: "basic" | "advanced" | "connection" и т.д.
        "order": int,         # Приоритет сортировки (чем меньше, тем выше)
        "options": list,      # Доступные опции для элемента select [{label, value}], label поддерживает i18n
        "placeholder": str | dict,  # Подсказка в поле ввода (поддержка i18n)
    },
    "extra": dict,            # Дополнительные расширенные поля (прозрачно передаются в schema)
}

Все пользовательские текстовые поля поддерживают i18n, используя единый формат {"i18n": "key", "default": "text"}, чистые строки прозрачно передаются (обратная совместимость). Поддерживаемые поля i18n:

Поле Позиция Описание
description metadata поля Описание поля
options[].label ui.options Метка опции элемента select
placeholder ui.placeholder Подсказка в поле ввода
group_labels _schema_meta Название отображения группы (заголовок раздела панели)

При использовании i18n необходимо заранее зарегистрировать ключи перевода в системе i18n (см. документацию по i18n).

Примеры description / placeholder / options label:

token: str = field(
    default="",
    metadata={
        "description": {"i18n": "my_adapter.token", "default": "Токен бота"},
        "ui": {
            "widget": "text",
            "placeholder": {"i18n": "my_adapter.token.ph", "default": "Введите токен"},
        },
    },
)
mode: str = field(
    default="a",
    metadata={
        "description": {"i18n": "my_adapter.mode", "default": "Режим"},
        "ui": {
            "widget": "select",
            "options": [
                {"label": {"i18n": "my_adapter.mode.a", "default": "Опция A"}, "value": "a"},
                {"label": "Чистая строка метки", "value": "b"},  # Чистые строки прозрачно передаются
            ],
        },
    },
)

Пример group_labels (объявляется после определения класса конфигурации):

MyConfig._schema_meta = {
    "group_labels": {
        "basic": {"i18n": "my_adapter.group.basic", "default": "Основные настройки"},
        "advanced": {"i18n": "my_adapter.group.advanced", "default": "Дополнительные настройки"},
    }
}

Фреймворк resolve_config_schema() автоматически разрешает все эти поля i18n в зависимости от текущего языка; get_config_schema() прозрачно передает словарь i18n, и фронтенд сам разрешает его.

Автоматическое создание описания полей из docstring (v2.8.0+)

Если поле не объявлено в metadata description, фреймворк автоматически извлекает описание поля из docstring класса конфигурации в качестве резервного варианта, поддерживая два общих стиля (можно смешивать):

@dataclass
class MyConfig(BaseConfig):
    """
    Конфигурация MyAdapter

    :ivar endpoint: Адрес API платформы        # Стиль reST
    :ivar timeout: Время ожидания в секундах
    """

    endpoint: str = "https://api.example.com"   # Без metadata description → описание из docstring
    timeout: int = 30

    # Также поддерживается стиль Google (раздел Attributes):
    # Attributes:
    #     endpoint: Адрес API платформы

Приоритет: metadata description > описание поля из docstring > пусто. i18n-словари в description не затрагиваются (всегда имеют приоритет).

Вложенные конфигурации (v2.8.0+)

Если тип поля — вложенный dataclass, фреймворк рекурсивно обрабатывает: schema с "type": "table" + "fields" поддерево (веб-интерфейс рендерит вложенные группы, которые можно свернуть), TOML шаблон рендерится в виде [подтаблица] секций, значения по умолчанию, заполнение, проверка, разрешение i18n также применяются рекурсивно.

@dataclass
class RetryConfig(BaseConfig):
    """Стратегия повтора

    :ivar max_retries: Максимальное количество повторов
    """
    max_retries: int = 3
    backoff: float = 0.5

@dataclass
class MyConfig(BaseConfig):
    """Конфигурация MyAdapter"""
    endpoint: str = "https://api.example.com"
    retry: RetryConfig = field(default_factory=RetryConfig)   # Вложенный раздел конфигурации

Сгенерированный TOML шаблон:

endpoint = "https://api.example.com"

[retry]
# Максимальное количество повторов
max_retries = 3
backoff = 0.5

Рекомендуется использовать прямые типы для вложенных типов; строковые аннотации (для отложенного вычисления) должны гарантировать, что тип можно разрешить по имени из модуля конфигурации, внешнего пространства имен класса или атрибута класса.

Поля, не сохраняемые в config (v2.8.0+)

gc_interval: int = field(default=300, metadata={"example": True})

Поля с example: True:

  • Не записываются в config.toml (шаблон конфигурации адаптера/модуля и значения по умолчанию исключают их, используют значения по умолчанию из кода)
  • Отображаются только в config.full.example (для справки пользователя, по желанию копируются в config.toml)
  • Маркируются в schema как "example": true (панель может решить, как отображать), конфигурационный помощник командной строки по умолчанию пропускает
  • После ручной установки пользователем сохраняются нормально, нормально обновляются (предпочтение отдается явному намерению пользователя)

Подходит для "сложных, но редко используемых" настроек, сохраняя config.toml пользователя минимальным.

⚠️ _schema_meta — это метаданные класса (не поле конфигурации). Если объявить внутри тела dataclass, необходимо добавить аннотацию ClassVar (_schema_meta: ClassVar[dict] = {...}), иначе dataclass будет рассматривать это как обычное поле. Фреймворк защитно исключает поля с подчеркиванием в начале (не входят в schema / шаблон / значения по умолчанию / проверку), но рекомендуется соблюдать нормальное объявление.

Декларативные ключи перевода (v2.7.0+)

Адаптер может объявить ключи перевода, как и ConfigClass, с помощью вложенного класса I18nClass, объединяя объявление ключей перевода. Фреймворк автоматически зарегистрирует все объявленные ключи перевода в __init__ (до генерации шаблона конфигурации), гарантируя, что ключи перевода, используемые в описании конфигурации, доступны при генерации шаблона.

from ErisPulse.Core.Bases import BaseAdapter, BaseI18n, I18nKey

class MyAdapter(BaseAdapter):
    class I18nClass(BaseI18n):
        endpoint: I18nKey = I18nKey(
            default="API Endpoint",
            zh_CN="API адрес",
            zh_TW="API 位址",
            en="API Endpoint",
            ja="APIアドレス",
            ru="API адрес",
        )
        token: I18nKey = I18nKey(
            default="Platform Token",
            zh_CN="平台 Token",
            zh_TW="平台權杖",
            en="Platform Token",
            ja="プラットフォームトークン",
            ru="Токен платформы",
        )

I18nKey.default — это языкобезразличный резервный текст, не регистрируется ни в каком языке. Чтобы перевод был активен, необходимо явно передать хотя бы один параметр языка.

Подробное использование (правила путей ключей, явный параметр key и т.д.) см. в документации по i18n.

Декларативные методы расширения событий (v2.7.0+)

Адаптер может декларативно объявить методы расширения событий платформы через EventMixin, фреймворк автоматически регистрирует их для текущей платформы.

from ErisPulse.Core import BaseAdapter

class MyAdapter(BaseAdapter):
    class EventMixin:
        def get_chat_name(self):
            """Получить название чата"""
            return self.get("myplatform_raw", {}).get("chat", {}).get("name", "")

        def is_official_message(self):
            """Определить, является ли сообщение официальным"""
            raw = self.get("myplatform_raw", {})
            return raw.get("sender", {}).get("is_official", False)

После регистрации, методы расширения событий доступны в объекте события:

@message.on_group_message()
async def handler(event):
    if event.is_official_message():
        chat_name = event.get_chat_name()
        await event.reply(f"[{chat_name}] Получено официальное сообщение")

Методы расширения событий адаптера регистрируются для его собственной платформы (self._platform). Модули, которые нуждаются в расширении событий для других платформ, должны использовать старый API register_event_mixin().

Разрешение аккаунта

При реализации call_api адаптеру необходимо преобразовать идентификатор аккаунта в конкретную конфигурацию аккаунта. Фреймворк передает идентификатор аккаунта (в виде стандартного поля account_id), полученного в результате привязки (Using() или результата автоматической привязки в цепочке событий), в call_api, и фреймворк автоматически адаптирует его по фактическому потреблению адаптера — три формы потребления можно выбрать, фреймворк определяет по имени параметра сигнатуры и константам в теле функции, независимо от позиции параметров:

# Форма 1 (рекомендуемая): сигнатура объявляет стандартное имя
async def call_api(self, endpoint: str, account_id: str | None = None, **params):
    name, account = self._resolve_account(account_id)
    # name: имя аккаунта, account: экземпляр конфигурации

# Форма 2 (совместимость с существующим кодом): старое имя _account_id, фреймворк автоматически перенаправляет account_id в старое имя
async def call_api(self, endpoint: str, _account_id: str | None = None, **params):
    name, account = self._resolve_account(_account_id)

# Форма 3: значение из params (обнаруживается константами в теле функции)
async def call_api(self, endpoint: str, **params):
    account_id = params.pop("account_id", None)
    name, account = self._resolve_account(account_id)

Если адаптер не потребляет поле аккаунта, фреймворк удаляет это поле (чтобы не передавать в параметры платформы) и выводит предупреждение один раз; адаптеры с одним аккаунтом могут не потреблять (разрешение возвращается к первому включенному аккаунту).

Стратегия разрешения: сопоставление имени аккаунта → сопоставление поля bot_id → сопоставление других строковых полей → первый включенный аккаунт.

Разрешение и сохранение в режиме выполнения (2.12+): адаптер вызывает self.update_bot_id(account_name, bot_id) при установлении соединения / при поступлении события — фреймворк поддерживает таблицу регистрации bot_id → аккаунт (первый приоритет в разрешении цепочки), и при изменении значения записывает accounts.<имя аккаунта>.bot_id в хранилище конфигурации: после перезапуска воссоздаются экземпляры аккаунтов с bot_id, и разрешение второй учетной записи и т.д. не зависит от активного возвращения (устраняет окно перезапуска).

Горячая перезагрузка конфигурации

Подкласс может переопределить on_config_update() для реакции на изменения конфигурации:

class MyAdapter(BaseAdapter):
    ConfigClass = MyConfig
    
    def on_config_update(self, old_config, new_config):
        if old_config.token != new_config.token:
            self.logger.info("Токен обновлен, будет повторное подключение")

Процесс инициализации

Фреймворк автоматически выполняет следующие действия в BaseAdapter.__init__(self, sdk=None):

  1. Ссылка на SDK: устанавливает self.sdk, self.logger
  2. Фабрика Send/Request: создает self.Send и self.Request
  3. Шаблон конфигурации: если объявлен ConfigClass, автоматически генерирует шаблон конфигурации (в первый раз)
  4. Шаблон аккаунта: если объявлен AccountConfigClass, автоматически генерирует шаблон аккаунта (в первый раз)
  5. Регистрация EventMixin: если объявлен EventMixin, автоматически регистрируется после присвоения имени платформы в AdapterManager

Конфигурация доступна через self.cfg / self.accounts в реальном времени (каждый раз при обращении читается из хранилища конфигурации). self.config как совместимый псевдоним self.cfg по-прежнему доступен.

Большинству адаптеров не нужно переопределять __init__. Если требуется кастомная инициализация:

class MyAdapter(BaseAdapter):
    ConfigClass = MyConfig
    
    def __init__(self, sdk=None):
        super().__init__(sdk)  # Передать sdk
        self.converter = self._setup_converter()
        self.convert = self.converter.convert

DSL для отправки сообщений Send

Наследование

class MyAdapter(BaseAdapter):
    class Send(BaseAdapter.Send):
        """Вложенный класс Send, наследующий BaseAdapter.Send"""
        pass

Доступные атрибуты

Send класс автоматически устанавливает следующие атрибуты при вызове:

Атрибут Описание Способ установки
_target_id Идентификатор цели To(id) или To(type, id)
_target_type Тип цели To(type, id)
_target_to Упрощенный идентификатор цели To(id)
_account_id Идентификатор отправляющего аккаунта Using(account_id)
_adapter Экземпляр адаптера Автоматическая установка
_at_user_ids Список @ пользователей At(user_id)
_reply_message_id Идентификатор сообщения для ответа Reply(message_id)
_at_all Отправлять @ всех AtAll()

Рекомендуется: использовать self.send_context для получения target_type, target_id, account_id за один раз, это яснее, чем прямое обращение к экземплярным переменным.

Вспомогательные методы фреймворка

Метод/Атрибут Описание
self._apply_modifiers(message) Объединяет модификаторы At/AtAll/Reply в список сегментов сообщения
self.send_context Возвращает словарь {target_type, target_id, account_id}; если account_id не указан явно, используется аккаунт, вызвавший событие

Основные методы

Адаптеру нужно реализовать только Raw_ob12, стандартные методы (Text/Image/Voice/Video/File) уже унаследованы от базового класса SendDSL и по умолчанию делегированы ему:

class Send(BaseAdapter.Send):
    def Raw_ob12(self, message, **kwargs):
        """Обязательно реализовать: OneBot12 сегменты сообщений → вызов платформенного API"""
        async def _do_send():
            segments = self._apply_modifiers(message)
            return await self._adapter.call_api(
                endpoint="/send_message",
                message=segments,
                **self.send_context,
                **kwargs
            )
        return asyncio.create_task(_do_send())

    # Text/Image/Voice/Video/File уже унаследованы от базового класса, автоматически делегируют Raw_ob12, не нужно повторно реализовывать
    # Если нужна платформенно-специфическая логика, можно переопределить отдельный метод:
    # def Text(self, text: str):
    #     return self.Raw_ob12([{"type": "text", "data": {"text": text}}])

Методы цепочки модификаторов

class Send(BaseAdapter.Send):

    def __init__(self, adapter, target_type=None, target_id=None, account_id=None):
        super().__init__(adapter, target_type, target_id, account_id)
        self.buttons = []

    def Button(self, content: list) -> 'Send':
        self.buttons.append(content)
        return self

Конвертер событий

Процесс преобразования

Оригинальное событие платформы
    ↓
Converter.convert()
    ↓
OneBot12: стандартное событие

Обязательные поля

Все преобразованные события должны содержать:

{
    "id": "уникальный идентификатор события",          # Для одного аккаунта повторная отправка одного и того же события должна быть одинаковой (фреймворк использует это для удаления дубликатов)
    "time": 1234567890,           # 10-значный Unix-время
    "type": "message/notice/request/meta",
    "detail_type": "подробный тип события",
    "platform": "название платформы",
    "message_id": "идентификатор сообщения",        # Должен быть для событий сообщений
    "self": {
        "platform": "название платформы",
        "user_id": "идентификатор бота"     # Должен совпадать с bot_id
    },
    "{platform}_raw": {...},       # Оригинальные данные (должны быть)
    "{platform}_raw_type": "..."    # Тип оригинального события (должен быть)
}

Идентификатор события должен содержать учетную запись: для одного аккаунта повторная отправка одного и того же события должна иметь одинаковый id, для разных аккаунтов, получивших одно и то же сообщение в одной группе, id должен быть разным (например, f"{self.user_id}:{post_type}:{message_id}").

Повторное получение событий для нескольких учетных записей (внедрение фреймворком)

Для нескольких учетных записей адаптера, когда несколько учетных записей получают одно и то же физическое сообщение в одной группе/сессии, одно и то же физическое сообщение будет поступать последовательно через каждую учетную запись. Фреймворк автоматически выполняет контент-уровневое сопоставление (та же платформа + та же сессия + тот же отправитель + та же alt_message в коротком окне), если ErisPulse.framework.cross_account_policy != "off", адаптеру не нужно участвовать:

  • mark: последующие копии получают дополнительное поле верхнего уровня "multi_receipt": {"event_id": id первого события, "self_id": self_id первого аккаунта}, затем продолжают распределяться, модули читают это поле для принятия решений
  • drop: последующие копии отбрасываются на входе распределения

multi_receipt — это необязательное поле, внедренное фреймворком, адаптер не производит и не потребляет; политика по умолчанию off, структура события полностью соответствует существующему контракту.

Три уровня механизма удаления дубликатов

Механизм Конфигурация Что блокирует Основание для определения
Дедупликация幂等 ErisPulse.framework.event_dedupe (по умолчанию включено) Повторная отправка одного и того же события с одним и тем же подключением Идентификатор события id
Фильтрация эхо-событий ErisPulse.event.message.ignore_self (по умолчанию включено) Сообщения, отправленные самим аккаунтом (отправитель == аккаунт) self.user_id против user_id
Повторное получение между аккаунтами ErisPulse.framework.cross_account_policy (по умолчанию off, drop включено) Одно и то же физическое сообщение, полученное другими аккаунтами — когда бот A отправляет сообщение, бот B в той же группе также получает его, дублирующий модуль видит одно и то же содержимое дважды. Контент-уровневое сопоставление (та же платформа + та же сессия + тот же отправитель + то же содержимое, короткое окно), ключ не содержит self_id

Типичный сценарий — дублирование сообщений с несколькими аккаунтами: бот A отправляет сообщение, и в той же группе другие аккаунты (бот B) также получают его, дублирующий модуль видит одно и то же сообщение дважды. При включении cross_account_policy = "drop" последующие копии отбрасываются на входе распределения, и любой модуль видит его ровно один раз.

Семантика ignore_self ортогональна, и их комбинация определяет количество видимых сообщений:

Комбинация Количество раз, сколько модуль видит сообщение от бота A
drop + ignore_self = true (по умолчанию) 0 или 1 раз (если первая копия была от бота A, она отфильтрована ignore_self) — никогда не 2 раза
drop + ignore_self = false Всегда ровно 1 раз

Не рекомендуется расширять семантику ignore_self до "исключения всех аккаунтов": это зависит от self.user_id события (связь может быть недоступна в окне установки), а сопоставление между аккаунтами — это сопоставление на уровне контента, не зависит от информации self; и "получение по каждому аккаунту" — это существующая зависимость от логов и синхронизирующих модулей, сужение семантики является скрытым нарушением. Удаление дубликатов между аккаунтами делается с помощью cross_account_policy.

Пример конвертера

class MyPlatformConverter:
    def convert(self, raw_event):
        """Преобразование оригинального события платформы в стандартный формат OneBot12"""
        if not isinstance(raw_event, dict):
            return None
        
        # Генерация идентификатора события
        event_id = raw_event.get("event_id") or str(uuid.uuid4())
        
        # Преобразование временной метки
        timestamp = raw_event.get("timestamp")
        if timestamp and timestamp > 10**12:
            timestamp = int(timestamp / 1000)
        else:
            timestamp = int(timestamp) if timestamp else int(time.time())
        
        # Преобразование типа события
        event_type = self._convert_type(raw_event.get("type"))
        detail_type = self._convert_detail_type(raw_event)
        
        # Построение стандартного события
        onebot_event = {
            "id": str(event_id),
            "time": timestamp,
            "type": event_type,
            "detail_type": detail_type,
            "platform": "myplatform",
            "self": {
                "platform": "myplatform",
                "user_id": str(raw_event.get("bot_id", ""))
            },
            "myplatform_raw": raw_event,
            "myplatform_raw_type": raw_event.get("type", "")
        }
        
        return onebot_event

Управление подключениями

Два правильных способа реализации start()

Адаптеры с клиентским режимом (WebSocket-клиент, HTTP-опрос и т.д.) должны в start() запускать цикл постоянного подключения. Фреймворк поддерживает два способа, оба правильны, но нужно выбрать один:

Способ 1: spawn-возвращающий (рекомендуется) — с помощью spawn_client_loop() цикл распределяется как фоновая задача, принадлежащая текущей платформе, start() немедленно возвращает:

class MyAdapter(BaseAdapter):
    async def start(self):
        # Задача цикла принадлежит self._platform: фреймворк автоматически отменяет при shutdown
        self.spawn_client_loop(self._connect_loop())
        # start() здесь завершается — "запуск успешен", ошибка подключения обрабатывается внутри цикла

    async def _connect_loop(self):
        while True:
            try:
                await self._connect_and_receive()   # При разрыве вызывается исключение → ниже задержка
            except asyncio.CancelledError:
                raise
            except Exception:
                await asyncio.sleep(5)              # Внутри цикла собственная задержка повторного подключения

Способ 2: постоянный режим — start() непосредственно await цикл подключения, никогда не возвращает:

class MyAdapter(BaseAdapter):
    async def start(self):
        await self._connect_loop()   # Постоянный режим, не возвращает; ошибка цикла = ошибка start

Различия и общие черты двух способов:

spawn-возвращающий Постоянный режим
Время возврата start() Немедленно после запуска цикла После выхода из цикла подключения/сбоя (фреймворк по стратегии задержки повторяет)
Обработка ошибок подключения Внутри цикла обрабатывается и задерживается Исключение всплывает, передается в цепочку повтора фреймворка
Область применения Требуется быстрый возврат подтверждения запуска (множественные подключения, регистрация маршрутов, затем запуск других задач) "Подключение = запуск" семантика простой реализации

spawn_client_loop(coro, *, name="client_loop") — это входная точка для способа 1: задача регистрируется по принадлежности self._platform, при shutdown() фреймворк автоматически отменяет по принадлежности, без необходимости управлять дескриптором задачи; исключения, не обработанные внутри цикла, автоматически оставляются для отслеживания (ожидаемые разрывы и повторные подключения следует обрабатывать внутри цикла).

Единственный неправильный способ — смешивание: запуск spawn и затем await того же цикла — это приведет к тому, что start() потеряет семантику немедленного возврата, и путь отмены задачи станет непредсказуемым.

Базовые классы для режимов подключения

Наряду с двумя способами в предыдущем разделе, наиболее распространенные режимы подключения фреймворк предоставляет наполовину готовые базовые классы (в ErisPulse.Core.Bases.adapter_patterns, корневой пакет можно импортировать напрямую): start / shutdown жизненный цикл полностью управляется базовым классом, подкласс реализует только обработчики событий.

PollingAdapter (режим HTTP-опроса)

Подходит для платформ, где клиент периодически запрашивает события (типа Telegram getUpdates). Базовый класс с помощью spawn-возвращающего способа запускает постоянный цикл опроса, ошибка запроса автоматически регистрируется и экспоненциально задерживается (база 1 секунда, максимум 60 секунд, при успешном сбросе к нулю; константы POLLING_ADAPTER_BACKOFF_BASE_SECS / POLLING_ADAPTER_BACKOFF_MAX_SECS можно настроить в Core/constants.py):

from ErisPulse import PollingAdapter

class MyAdapter(PollingAdapter):
    # Интервал опроса по умолчанию 5 секунд; если в ConfigClass объявлено поле poll_interval, используется значение конфигурации (горячее обновление生效)
    poll_interval = 5.0

    async def fetch_events(self):
        """Получить пакет оригинальных событий платформы (ошибки обрабатываются базовым классом с задержкой, не нужно try/except)"""
        resp = await self.sdk.client.get(f"{self.cfg.endpoint}/getUpdates")
        data = await resp.json()
        return data.get("result", [])

    def convert_one(self, raw):
        """Преобразовать одно оригинальное событие в OneBot12; возвращает None для пропуска"""
        return self.converter.convert(raw)

    async def call_api(self, endpoint: str, **params):
        ...  # Как и обычный адаптер

Минимальный интерфейс: fetch_events / convert_one / call_api. start() запускает цикл и немедленно возвращает; shutdown() не требует обработки подклассом (цикл опроса автоматически отменяется по принадлежности).

WebhookAdapter (режим HTTP-вебхука)

Подходит для платформ, где платформа активно отправляет обратные вызовы. Базовый класс start() регистрирует маршрут приема в маршрутизаторе фреймворка (окончательный путь /{имя платформы}/webhook, метод POST), регистрация происходит в owner_scope — адаптер при выгрузке автоматически удаляет маршрут, не нужно вручную удалять:

from ErisPulse import WebhookAdapter

class MyAdapter(WebhookAdapter):
    def verify_request(self, request) -> bool:
        """Необязательный хук: проверка обратного вызова (по умолчанию разрешает; возвращает False, чтобы базовый класс ответил 403)"""
        cfg = self.cfg
        if not cfg.token:
            return True
        auth = request.headers.get("authorization", "")
        return auth == f"Bearer {cfg.token}"

    def convert(self, payload):
        """Преобразовать нагрузку обратного вызова в OneBot12; возвращает None для пропуска"""
        return self.converter.convert(payload)

    async def call_api(self, endpoint: str, **params):
        ...  # Как и обычный адаптер

Минимальный интерфейс: convert / call_api (необязательно verify_request). Адрес обратного вызова можно получить через sdk.adapter.get_connection_info(platform) и заполнить в настройках платформы; запросы с неудачной проверкой возвращают 403, с неудачным анализом нагрузки — 400, нормальные — {"status": "ok"}.

Как выбрать три режима

Протокол платформы Наследование Скрипт
Платформа подключается (WebSocket-сервер) BaseAdapter epsdk create adapter (по умолчанию ws-server)
Мы подключаемся (HTTP-опрос) PollingAdapter epsdk create adapter --template polling
Платформа отправляет (HTTP-вебхук) WebhookAdapter epsdk create adapter --template webhook

Полные рабочие примеры см. в репозитории examples/example-adapter/ (ws-server), examples/example-adapter-polling/, examples/example-adapter-webhook/.

WebSocket-подключение

class MyAdapter(BaseAdapter):
    async def start(self):
        """Регистрация маршрута WebSocket"""
        router.register_websocket(
            module_name="myplatform",
            path="/ws",
            handler=self._ws_handler,
            auth_handler=self._auth_handler
        )
    
    async def _ws_handler(self, websocket):
        """Обработчик подключения WebSocket"""
        self.connection = websocket
        
        try:
            while True:
                data = await websocket.receive_text()
                onebot_event = self.convert(data)
                if onebot_event:
                    await self.adapter.emit(onebot_event)
        except WebSocketDisconnect:
            self.logger.info("Соединение разорвано")
        finally:
            self.connection = None
    
    async def _auth_handler(self, websocket) -> bool:
        """Аутентификация WebSocket"""
        token = websocket.query_params.get("token")
        return token == "valid_token"

WebHook-подключение

class MyAdapter(BaseAdapter):
    async def start(self):
        """Регистрация маршрута WebHook"""
        router.register_http_route(
            module_name="myplatform",
            path="/webhook",
            handler=self._webhook_handler,
            methods=["POST"]
        )
    
    async def _webhook_handler(self, request):
        """Обработчик запроса WebHook"""
        data = await request.json()
        onebot_event = self.convert(data)
        if onebot_event:
            await self.adapter.emit(onebot_event)
        return {"status": "ok"}

Для чисто обратных платформ не нужно вручную писать эту регистрацию/проверку/очистку — просто унаследуйтесь от WebhookAdapter наполовину готового базового класса, реализуйте convert (по желанию перезапишите verify_request).

Информация о маршруте: маршруты, зарегистрированные адаптером (HTTP, WebSocket, SSE), можно получить с помощью sdk.adapter.get_connection_info(platform) и sdk.router.get_module_urls(module_name), чтобы узнать полный адрес соединения (включая base_url + путь). Подробнее см. Введение в разработку адаптера - Информация о соединении и обнаружение маршрутов и Поддержка SSE。

Стандартный формат ответа API

Фреймворк предоставляет методы make_response() и make_error() для создания стандартизированных ответов, без необходимости вручную создавать словарь ответа.

Успешный ответ

async def call_api(self, endpoint: str, **params):
    try:
        raw_response = await self._platform_api_call(endpoint, **params)
        
        return self.make_response(
            data=raw_response.get("data"),
            message_id=raw_response.get("data", {}).get("message_id", ""),
            raw=raw_response,
        )
    except Exception as e:
        return self.make_error(message=str(e), raw=None)

Ручное создание ответа (старый способ по-прежнему совместим)

async def call_api(self, endpoint: str, **params):
    return {
        "status": "ok",
        "retcode": 0,
        "data": {...},
        "message_id": "msg_id",
        "message": "",
        "myplatform_raw": raw_response
    }

Поддержка нескольких аккаунтов

Декларативная конфигурация (рекомендуется)

Используя AccountConfigClass для объявления класса конфигурации, фреймворк автоматически управляет загрузкой, проверкой и генерацией шаблонов для нескольких аккаунтов:

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

@dataclass
class MyBotConfig(BotAccountConfig):
    bot_id: str = field(default="", metadata={"description": "ID бота", "required": True})
    token: str = field(default="", metadata={"description": "Токен", "required": True, "secret": True})

class MyAdapter(BaseAdapter):
    AccountConfigClass = MyBotConfig
    
    async def start(self):
        for name, account in self.enabled_accounts.items():
            self.logger.info(f"Запуск аккаунта {name}: {account.bot_id}")
            await self._connect(name, account)
    
    async def call_api(self, endpoint: str, account_id: str | None = None, **params):
        name, account = self._resolve_account(account_id)
        # Использовать account.token, account.bot_id и т.д.

Файл конфигурации аккаунта

[MyAdapter.accounts.account1]
bot_id = "bot_001"
token = "token1"
enabled = true

[MyAdapter.accounts.account2]
bot_id = "bot_002"
token = "token2"
enabled = true

Отправка с указанием аккаунта

# Использовать метод Using для указания аккаунта
my_adapter = adapter.get("myplatform")

# Через self.user_id из события (рекомендуется, наиболее универсально)
await my_adapter.Send.Using(event["self"]["user_id"]).To("user", "123").Text("Hello")

# Через имя аккаунта
await my_adapter.Send.Using("account1").To("user", "123").Text("Hello")

Связь идентификатора аккаунта в событии и Using

Система ответа на события фреймворка автоматически извлекает идентификатор аккаунта из поля self события (в первую очередь account_id, в качестве резерва user_id), вставляя его в Using. Разработчику адаптера необходимо убедиться, что Converter правильно устанавливает идентификатор аккаунта (имя аккаунта или поля bot_id и т.д.), чтобы фреймворк смог разрешить его в правильный аккаунт. Идентификаторы, пустые, фреймворк не вставляет Using, в этом случае отправка происходит без указания аккаунта — возвращается к первому включенному аккаунту.

Поведение фреймворка при вставке идентификатора:

# Логика фреймворка извлечения идентификатора аккаунта (account_id приоритетнее, user_id в качестве резерва)
account = self.get("self", {}).get("account_id", "") or self.get("self", {}).get("user_id", "")

# Вставлять Using только если идентификатор не пуст
if account:
    send_chain = send_chain.Using(account)

Ключевой момент: даже если адаптер использует только одну конфигурацию бота, если Converter правильно установил идентификатор аккаунта, фреймворк вставит его в Using. Адаптер должен убедиться, что этот идентификатор соответствует имени аккаунта или полям bot_id и т.д. в AccountConfigClass, чтобы правильно разрешить аккаунт. Если идентификатор пуст, фреймворк не вставляет Using, в этом случае отправка обрабатывается без указания аккаунта — возвращается к первому включенному аккаунту.

Если явно переданный account_id не может быть разрешен, фреймворк записывает предупреждение и возвращает к первому включенному аккаунту; в предупреждении platform / account_id / account можно использовать для определения источника события, не принадлежащего аккаунту.

Автоматическая привязка в цепочке событий: при вызове методов отправки в процессе обработки события не нужно явно использовать Using() — фреймворк на входе распределения событий вставляет идентификатор аккаунта, вызвавшего событие, в контекст вызова, Send / Api / Request цепочка без явного указания аккаунта использует это для привязки по умолчанию (явный Using() всегда имеет приоритет; в сценариях таймера / запуска задач без контекста события сохраняется семантика аккаунта по умолчанию). Автоматическая привязка в цепочке событий требует ErisPulse 2.12+.

Соглашение о выводе self.user_id / self.account_id и его замене см. в стандарте преобразования событий; это соглашение о наличии всегда присутствующего поля является предпосылкой для семантики возврата при разрешении аккаунта — если поле отсутствует, возврат к первому включенному аккаунту, при нескольких аккаунтах — "отправка от аккаунта по умолчанию".

Обработка ошибок

Повторные попытки подключения

import asyncio

class MyAdapter(BaseAdapter):
    async def start(self):
        retry_count = 0
        max_retries = 5
        
        while retry_count < max_retries:
            try:
                await self._connect_to_platform()
                break
            except Exception as e:
                retry_count += 1
                if retry_count < max_retries:
                    wait_time = min(60 * (2 ** retry_count), 600)
                    self.logger.warning(f"Подключение не удалось, повтор через {wait_time} секунд")
                    await asyncio.sleep(wait_time)
                else:
                    raise

Обработка ошибок API

async def call_api(self, endpoint: str, **params):
    try:
        # Рекомендуется использовать встроенный клиент SDK
        from ErisPulse.Core import client
        from ErisPulse.Core.Bases.errors import ClientError, ClientTimeoutError
        resp = await client.post(
            f"https://api.platform.com/{endpoint}",
            json=params,
            max_retries=2,
        )
        response = await resp.json()
        return self._standardize_response(response)
    except ClientTimeoutError:
        self.logger.error(f"Тайм-аут запроса: {endpoint}")
        return self._error_response("Тайм-аут запроса", 32000)
    except ClientError as e:
        self.logger.error(f"Ошибка сети: {e}")
        return self._error_response("Ошибка сети", 33000)
    except Exception as e:
        self.logger.error(f"Неизвестная ошибка: {e}")
        return self._error_response(str(e), 34000)

Обратная совместимость: код старых адаптеров, использующих aiohttp.ClientSession, не пострадает, по-прежнему можно обрабатывать aiohttp.ClientError. Оба способа могут сосуществовать. Рекомендуется использовать sdk.client и систему исключений ErisPulse в новом коде.

Управление состоянием бота

AdapterManager встроил систему отслеживания состояния ботов, автоматически отслеживая онлайн-статус, время активности и метаданные всех зарегистрированных ботов.

Автоматическая обнаружение

Когда адаптер отправляет событие с помощью adapter.emit(), фреймворк автоматически проверяет поле self события:

  • Мета-события: в зависимости от detail_type выполняются соответствующие действия (connect — регистрация, disconnect — отмечает как оффлайн, heartbeat — обновляет время активности)
  • Обычные события (message/notice/request): автоматически обнаруживает бота и обновляет время активности
# Все события с полем self будут запускать автоматическое обнаружение
await self.adapter.emit({
    "type": "message",
    "platform": "myplatform",
    "self": {"platform": "myplatform", "user_id": "bot123"},
    # ...
})
# Бот "bot123" будет автоматически зарегистрирован (если впервые) и обновит время активности

Типы мета-событий

detail_type Описание Поведение фреймворка
connect Бот подключился Регистрация бота и запуск события adapter.bot.online
disconnect Бот отключился Отмечает бота как оффлайн и запуск события adapter.bot.offline
heartbeat Бот посылает heartbeat Обновляет время активности и метаданные бота

Отправка мета-событий адаптером

Способы отправки (однострочная emit_meta() и формат события heartbeat) см. в Рекомендациях по разработке адаптера - Управление состоянием бота и мета-события。

Расширение поля self

Поле self помимо обязательных platform и user_id поддерживает следующие необязательные поля:

Поле Описание
user_name Имя пользователя бота
nickname Никнейм бота
avatar URL аватара бота
account_id Идентификатор аккаунта

Запрос состояния бота

API запроса (get_bot_info() / list_bots() / is_bot_online() / get_status_summary()) см. в API системы адаптеров - Управление состоянием бота。

Отслеживание жизненного цикла бота

События жизненного цикла adapter.bot.online / adapter.bot.offline и примеры их прослушивания см. в API системы адаптеров - Управление состоянием бота。

Связанные документы

Глубокое понимание реализации

Повторное изучение шагов старта