Руководство по реализации конвертера событий
Tip
Когда читать эту статью: обязательно при разработке адаптера (конвертер событий). Не нужно — пропустите, это не повлияет на использование других функций.
После получения платформой собственных событий конвертер (Converter) преобразует их в единый стандарт OneBot12 от ErisPulse — именно этот класс определяет, как события платформы попадают в фреймворк.
Ответственность Converter
Событие платформы ──→ Converter.convert() ──→ Событие стандарта OneBot12
Converter отвечает только за прямое преобразование (направление получения), то есть за преобразование данных собственных событий платформы в формат стандарта OneBot12. Обратное преобразование (направление отправки) обрабатывается методом Send.Raw_ob12().
Основные принципы
- Без потерь: исходные данные должны быть полностью сохранены в поле
{platform}_raw - Совместимость со стандартом: преобразованные события должны соответствовать формату стандарта OneBot12
- Платформенные расширения: платформенные специфичные данные хранятся в полях с префиксом
{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 должен поддерживать отправку изображений.
Лучшие практики
- Всегда сохраняйте исходные данные: поле
{platform}_rawне должно опускаться - Используйте стандартные сообщения: по возможности преобразуйте сообщения платформы в стандартные сообщения OneBot12
- Разумно устанавливайте detail_type: используйте стандартные типы (
private/group/channelи т.д.), не придумывайте свои - Обрабатывайте граничные случаи: исходное событие может содержать недостающие поля, используйте
.get()и разумные значения по умолчанию - Учитывайте производительность: метод
convert()вызывается для каждого события, избегайте длительных операций
Связанные документы
Продолжение разработки адаптера
- Основные концепции адаптера - общая архитектура адаптера
- Подробности SendDSL - обратное преобразование (направление отправки)
Следование официальным стандартам
- Стандарт преобразования событий - официальный стандарт преобразования событий
- Система типов сессий - правила отображения типов сессий