Основные концепции адаптера
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"])
Процесс запуска:
- Отправка события
adapter.startжизненного цикла - Отправка события
adapter.status.change(starting) - Параллельный запуск адаптеров
- Если запуск не удался, автоматическая повторная попытка (экспоненциальная стратегия отката)
- После успешного запуска отправка события
adapter.status.change(started)
Стратегия повторных попыток:
- Первые 4 попытки: 60 секунд, 10 минут, 30 минут, 60 минут
- С пятой попытки и далее: фиксированный интервал 3 часа
Остановка адаптера
# Остановка всех адаптеров
await sdk.adapter.shutdown()
Процесс остановки:
- Отправка события
adapter.stopжизненного цикла - Вызов метода
shutdown()всех адаптеров - Остановка сервера маршрутизации
- Очистка обработчиков событий
- Отправка события
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):
- Обработка промежуточными обработчиками: сначала выполняются все промежуточные обработчики OneBot12
- Распределение стандартных событий: распределяются по соответствующим обработчикам стандартных событий
- Распределение оригинальных событий: если есть оригинальные данные, распределяются по обработчикам оригинальных событий
Правила сопоставления:
- Точное совпадение:
@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). Модули, которые нуждаются в расширении событий для других платформ, должны использовать старый APIregister_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):
- Ссылка на SDK: устанавливает
self.sdk,self.logger - Фабрика Send/Request: создает
self.Sendиself.Request - Шаблон конфигурации: если объявлен
ConfigClass, автоматически генерирует шаблон конфигурации (в первый раз) - Шаблон аккаунта: если объявлен
AccountConfigClass, автоматически генерирует шаблон аккаунта (в первый раз) - Регистрация 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 системы адаптеров - Управление состоянием бота。
Связанные документы
Глубокое понимание реализации
- Подробности SendDSL - изучение отправки сообщений
- Рекомендации по разработке адаптера - создание качественных адаптеров
Повторное изучение шагов старта
- Введение в разработку адаптера - создание первого адаптера