ErisPulse ErisPulse
Открыть интерактивную версию →
Разделы страницы
Статическое зеркало — интерактивная версия является основной Открыть интерактивную версию →

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

Tip

Когда читать эту статью: обязательно при разработке адаптера (конвертер событий). Не нужно — пропустите, это не повлияет на использование других функций.

После получения платформой собственных событий конвертер (Converter) преобразует их в единый стандарт OneBot12 от ErisPulse — именно этот класс определяет, как события платформы попадают в фреймворк.

Ответственность Converter

Событие платформы ──→ Converter.convert() ──→ Событие стандарта OneBot12

Converter отвечает только за прямое преобразование (направление получения), то есть за преобразование данных собственных событий платформы в формат стандарта OneBot12. Обратное преобразование (направление отправки) обрабатывается методом Send.Raw_ob12().

Основные принципы

  1. Без потерь: исходные данные должны быть полностью сохранены в поле {platform}_raw
  2. Совместимость со стандартом: преобразованные события должны соответствовать формату стандарта OneBot12
  3. Платформенные расширения: платформенные специфичные данные хранятся в полях с префиксом {platform}_

Базовый класс BaseConverter (рекомендуется)

Начиная с версии 2.7.0, фреймворк предоставляет базовый класс BaseConverter (ErisPulse.Core.Bases), который封装ует общие поля событий OneBot12 и вспомогательные методы для сообщений, позволяя конвертеру сосредоточиться на отображении типов:

from ErisPulse.Core.Bases import BaseConverter


class MyConverter(BaseConverter):
    def __init__(self):
        super().__init__(platform="myplatform")

    def convert(self, raw_event: dict) -> dict | None:
        if not isinstance(raw_event, dict):
            return None
        event_type = raw_event.get("type", "")
        base = self.build_base_event(raw_event, event_type)  # id/time/platform/self/raw
        if event_type == "message":
            base["type"] = "message"
            base["detail_type"] = "group" if raw_event.get("group_id") else "private"
            base["user_id"] = str(raw_event.get("sender_id", ""))
            base["message"] = [self.text(raw_event.get("content", ""))]
            base["alt_message"] = raw_event.get("content", "")
            return base
        return None

build_base_event() заполняет следующие общие поля:

Поле Источник
id raw_event["event_id"], генерируется UUID по умолчанию
time raw_event["timestamp"], по умолчанию текущее время
platform переданное при создании platform
self {"platform": ..., "user_id": raw_event["bot_id"]}
{platform}_raw исходное событие (соответствует принципу "без потерь")
{platform}_raw_type тип исходного события

Общие вспомогательные методы для сообщений (все статические методы, можно использовать напрямую):

converter.text("hi")          # {"type": "text", "data": {"text": "hi"}}
converter.at("123456")        # {"type": "at", "data": {"user_id": "123456"}}
converter.image("file.png")   # {"type": "image", "data": {"file": "file.png"}}

При ручной реализации конструктор общих полей в build_base_event является обязательным шаблоном, использование BaseConverter позволяет избежать этой части и автоматически обеспечивает "без потерь" (исходное событие всегда попадает в {platform}_raw).

Метод convert()

Подпись метода

def convert(self, raw_event: dict) -> dict:
    """
    Преобразует собственное событие платформы в формат стандарта OneBot12

    :param raw_event: данные собственного события платформы
    :return: словарь события в формате стандарта OneBot12
    """
    pass

Структура возвращаемого значения

Словарь преобразованного события должен содержать следующие стандартные поля:

{
    "id": "уникальный идентификатор события",
    "time": 1234567890,           # Unix timestamp (секунды)
    "type": "message",             # Тип события
    "detail_type": "private",      # Подтип
    "platform": "myplatform",      # Название платформы
    "self": {
        "platform": "myplatform",
        "user_id": "bot_user_id"
    },

    # Поля сообщения
    "user_id": "sender_id",
    "message": [...],              # Список сообщений стандарта OneBot12
    "alt_message": "чистый текст",

    # Должны быть сохранены исходные данные
    "myplatform_raw": { ... },     # Полные данные исходного события
    "myplatform_raw_type": "имя типа исходного события",
}

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

Общие поля (для всех типов событий)

Поле OB12 Тип Описание
id str Уникальный идентификатор события
time int Unix timestamp (секунды)
type str Тип события: message / notice / request / meta
detail_type str Подтип: private / group / friend и т.д.
platform str Название платформы, совпадает с именем зарегистрированного адаптера
self dict Информация о боте: {"platform": "...", "user_id": "..."}

Дополнительные поля для события сообщения

Поле OB12 Тип Описание
user_id str ID отправителя
message list[dict] Список сообщений стандарта OneBot12
alt_message str Резервный текст

Дополнительные поля для события уведомления

Поле OB12 Тип Описание
user_id str ID связанного пользователя
operator_id str ID оператора (например, при изменении участников группы)

Преобразование сообщений

Стандарт OneBot12 определяет следующие типы сообщений:

# Текст
{"type": "text", "data": {"text": "Hello"}}

# Изображение
{"type": "image", "data": {"file": "https://example.com/img.jpg"}}

# Аудио
{"type": "audio", "data": {"file": "https://example.com/audio.mp3"}}

# Видео
{"type": "video", "data": {"file": "https://example.com/video.mp4"}}

# Файл
{"type": "file", "data": {"file": "https://example.com/doc.pdf"}}

# Упоминание
{"type": "mention", "data": {"user_id": "123"}}

# Упоминание всех
{"type": "mention_all", "data": {}}

# Ответ
{"type": "reply", "data": {"message_id": "msg_123"}}

Если платформа не поддерживает определённый тип сообщения, его можно опустить или преобразовать в наиболее близкий стандартный тип.

Правила рендеринга alt_message

alt_message — это резервный текст сообщения, используемый для архивации логов, extract_text и командного распределения. При генерации alt_message адаптеры должны следовать следующим правилам (особенно важно для упоминаний):

  • Упоминание сначала рендерится как @имя; если платформа не предоставляет имя, используется @{user_id}; если user_id — all (упоминание всех), рендерится как @всех участников
  • Если отсутствуют и имя, и user_id, этот элемент опускается, не выводится пустой "@" — например, "@ помощь" загрязнит текстовое сопоставление и командный анализ
  • Обратите внимание на ловушку data.get("user_name", fallback): если при создании сообщения user_name по умолчанию содержит пустую строку, ключ будет существовать, и fallback никогда не сработает; следует использовать data.get("user_name") or data.get("user_id")
  • Стиль рендеринга остальных сообщений (например, [изображение], [аудио]) и способ соединения между элементами ("" или " ") следует соблюдать согласно существующему стилю адаптера, без принудительного унифицирования
# Пример рендеринга упоминания
data = seg.get("data") or {}
user_id = str(data.get("user_id") or "").strip()
user_name = str(data.get("user_name") or "").strip()
if user_id == "all":
    parts.append("@всех участников")
elif user_name:
    parts.append(f"@{user_name}")
elif user_id:
    parts.append(f"@{user_id}")

Платформенные расширения

Платформенные специфичные данные следует хранить с префиксом {platform}_, чтобы избежать конфликта с стандартными полями:

{
    # Стандартные поля
    "type": "message",
    "detail_type": "group",
    # ...

    # Платформенные расширения
    "myplatform_raw": { ... },          # Исходные данные события (обязательно)
    "myplatform_raw_type": "chat",      # Тип исходного события (обязательно)

    # Другие платформенные поля
    "myplatform_group_name": "Название группы",
    "myplatform_sender_role": "администратор",
}

Важно: поле {platform}_raw обязательно, система событий ErisPulse и модули могут зависеть от него для доступа к платформенным исходным данным.

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

Ниже приведена полная реализация конвертера:

class MyConverter:
    def __init__(self, platform: str):
        self.platform = platform

    def convert(self, raw_event: dict) -> dict:
        event_type = raw_event.get("type", "")

        base_event = {
            "id": raw_event.get("id", ""),
            "time": raw_event.get("timestamp", 0),
            "platform": self.platform,
            "self": {
                "platform": self.platform,
                "user_id": raw_event.get("self_id", ""),
            },
            "myplatform_raw": raw_event,
            "myplatform_raw_type": event_type,
        }

        if event_type == "chat":
            return self._convert_message(raw_event, base_event)
        elif event_type == "notification":
            return self._convert_notice(raw_event, base_event)
        elif event_type == "request":
            return self._convert_request(raw_event, base_event)

        return base_event

    def _convert_message(self, raw: dict, base: dict) -> dict:
        base["type"] = "message"
        base["detail_type"] = "group" if raw.get("group_id") else "private"
        base["user_id"] = raw.get("sender_id", "")
        base["message"] = self._convert_message_segments(raw.get("content", ""))
        base["alt_message"] = raw.get("content", "")

        if raw.get("group_id"):
            base["group_id"] = raw["group_id"]

        return base

    def _convert_message_segments(self, content: str) -> list:
        segments = []
        if content:
            segments.append({"type": "text", "data": {"text": content}})
        return segments

    def _convert_notice(self, raw: dict, base: dict) -> dict:
        base["type"] = "notice"
        notification_type = raw.get("notification_type", "")

        if notification_type == "member_join":
            base["detail_type"] = "group_member_increase"
            base["user_id"] = raw.get("user_id", "")
            base["group_id"] = raw.get("group_id", "")
            base["operator_id"] = raw.get("operator_id", "")
        elif notification_type == "friend_add":
            base["detail_type"] = "friend_increase"
            base["user_id"] = raw.get("user_id", "")

        return base

    def _convert_request(self, raw: dict, base: dict) -> dict:
        base["type"] = "request"
        request_type = raw.get("request_type", "")

        if request_type == "friend":
            base["detail_type"] = "friend"
            base["user_id"] = raw.get("user_id", "")
            base["comment"] = raw.get("message", "")
        elif request_type == "group_invite":
            base["detail_type"] = "group"
            base["group_id"] = raw.get("group_id", "")
            base["user_id"] = raw.get("inviter_id", "")

        return base

Пример преобразования сообщений с мультимедиа

На практике сообщения платформы обычно содержат изображения, упоминания, ответы и другие мультимедийные элементы. Ниже приведён пример обработки _convert_message_segments для различных типов сообщений:

def _convert_message_segments(self, raw_content: list) -> list:
    """Преобразует список сообщений платформы в стандартный список OneBot12"""
    segments = []

    for item in raw_content:
        item_type = item.get("type", "")

        if item_type == "text":
            segments.append({
                "type": "text",
                "data": {"text": item.get("content", "")}
            })

        elif item_type == "image":
            file_url = item.get("url") or item.get("file_id", "")
            segments.append({
                "type": "image",
                "data": {"file": file_url}
            })

        elif item_type == "at":
            segments.append({
                "type": "mention",
                "data": {"user_id": item.get("target_id", "")}
            })

        elif item_type == "reply":
            segments.append({
                "type": "reply",
                "data": {"message_id": item.get("reply_to_id", "")}
            })

        elif item_type == "at_all":
            segments.append({"type": "mention_all", "data": {}})

        else:
            segments.append({
                "type": "text",
                "data": {"text": f"[не поддерживаемый тип сообщения: {item_type}]"}
            })

    return segments

Распространённые ошибки

1. Отсутствие поля {platform}_raw

Это самая распространённая ошибка. Отсутствие поля с исходными данными приведёт к тому, что модули не смогут получить платформенные специфичные данные.

base_event["myplatform_raw"] = raw_event        # Обязательно!
base_event["myplatform_raw_type"] = event_type   # Обязательно!

2. Неправильный формат временной метки

Стандарт OneBot12 требует, чтобы поле time было Unix timestamp в секундах (целое число). Если платформа возвращает миллисекунды или ISO-строку, необходимо преобразовать:

import time

# Миллисекунды → секунды
"time": raw_event.get("timestamp", 0) // 1000

# ISO-строка → секунды
"time": int(time.mktime(time.strptime(raw_event["created_at"], "%Y-%m-%dT%H:%M:%S")))

3. Отсутствие поля self

Поле self содержит информацию о боте, user_id — это ID бота. В сценариях с несколькими ботами это поле крайне важно:

"self": {
    "platform": self.platform,
    "user_id": raw_event.get("bot_id", ""),   # ID самого бота
}

4. Использование недопустимых значений detail_type

detail_type должен содержать значения, определённые в стандарте OneBot12, такие как private, group, friend_increase, group_member_increase и т.д. Не используйте платформенные названия.

5. Согласованность направлений

Убедитесь, что сообщения, созданные конвертером, соответствуют типам, поддерживаемым методами отправки. Например, если конвертер преобразует изображения платформы в {"type": "image", ...}, то метод Image() в Send должен поддерживать отправку изображений.

Лучшие практики

  1. Всегда сохраняйте исходные данные: поле {platform}_raw не должно опускаться
  2. Используйте стандартные сообщения: по возможности преобразуйте сообщения платформы в стандартные сообщения OneBot12
  3. Разумно устанавливайте detail_type: используйте стандартные типы (private/group/channel и т.д.), не придумывайте свои
  4. Обрабатывайте граничные случаи: исходное событие может содержать недостающие поля, используйте .get() и разумные значения по умолчанию
  5. Учитывайте производительность: метод convert() вызывается для каждого события, избегайте длительных операций

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

Продолжение разработки адаптера

Следование официальным стандартам