ErisPulse ErisPulse
Открыть интерактивную версию →
Разделы страницы
1. Основные принципы 2. Требования к стандартным полям 2.1 Обязательные поля 2.2 Поля событий сообщений 2.3 Поля событий уведомлений 2.4 Поля событий запросов 3. Примеры форматов событий 3.1 Событие сообщения (message) 3.2 Событие уведомления (notice) 3.3 Событие запроса (request) 4. Стандарт сегментов сообщений 4.1 Стандартные сегменты сообщений 4.1.1 Сегмент keyboard — кнопки/инлайн-клавиатура (кроссплатформенный) 4.2 Сегменты расширенных сообщений платформы 5. Обработка неизвестных событий 6. Правила именования расширений 6.1 Именование полей 6.2 Именование типов сегментов сообщений 6.3 Именование полей исходных данных 6.4 Примеры платформенно-специфичных полей 6.5 Вложенные поля расширений 6.6 Расширение поля self 7. Расширение типов сессий 8. Руководство для разработчиков модулей 8.1 Доступ к полям расширений 8.2 Обработка сегментов расширенных сообщений 8.3 Лучшие практики 8.4 Обработка событий запросов 9. Определение типа сессии для событий notice / request 9.1 Контекст проблемы 9.2 Правила определения 9.3 Определение цели event.reply() 9.4 Рекомендации по разработке адаптеров 10. Связанные документы
Статическое зеркало — интерактивная версия является основной Открыть интерактивную версию →

Спецификация стандартизированной конвертации адаптеров

Tip

Когда следует читать этот документ: когда вы конвертируете нативные события платформы в стандартные события OneBot12 внутри адаптера — сверяйтесь с этим документом при проверке обязательных полей, структуры сегментов сообщений, правил именования расширений (префикс {platform}_) и определения типа сессии. Если это не требуется — пропустите.

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

  1. Строгая совместимость: все стандартные поля должны полностью соответствовать спецификации OneBot12
  2. Явные расширения: специфичные для платформы функции должны добавляться с префиксом {platform}_ (например, yunhu_form)
  3. Полнота данных: исходные данные события должны сохраняться в поле {platform}_raw, а исходный тип события — в поле {platform}_raw_type
  4. Единый формат времени: все метки времени должны быть преобразованы в 10-значные метки времени Unix (с точностью до секунды)
  5. Единообразие платформ: имя элемента platform должно совпадать с именем/псевдонимом, зарегистрированным вами в ErisPulse

2. Требования к стандартным полям

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

Поле Тип Описание
id string Уникальный идентификатор события
time integer Метка времени Unix (с точностью до секунды)
type string Тип события
detail_type string Подробный тип события (подробнее см. Стандарт типов сессий)
sub_type string Подтип события
platform string Название платформы
self object Информация о самом боте
self.platform string Название платформы
self.user_id string ID пользователя бота

Базовая линия OneBot12: self.platform / self.user_id и message_id событий сообщений являются полями, определёнными базовой линией OneBot12; фреймворк принимает определения базовой линии напрямую и не вводит собственные ключи расширений (self.account_id — ограниченный ключ расширения, служащий замещающим идентификатором только до момента получения user_id динамической учётной записью, см. §6).

Спецификация detail_type:

  • Необходимо использовать стандартные типы сессий ErisPulse (подробнее см. Стандарт типов сессий)
  • Поддерживаемые типы: private, group, user, channel, guild, thread
  • Адаптер отвечает за отображение нативных типов платформы на стандартные типы

2.2 Поля событий сообщений

Поле Тип Описание
message_id string ID сообщения (обязательное поле базовой линии OneBot12; адаптер должен выдавать его на верхнем уровне события)
message array Массив сегментов сообщения
alt_message string Резервный текст сегментов сообщения
user_id string ID пользователя
user_nickname string Ник пользователя (необязательно)

2.3 Поля событий уведомлений

Поле Тип Описание
user_id string ID пользователя
user_nickname string Ник пользователя (необязательно)
operator_id string ID оператора (необязательно)

2.4 Поля событий запросов

Поле Тип Описание
user_id string ID пользователя
user_nickname string Ник пользователя (необязательно)
comment string Сопроводительное сообщение к запросу (необязательно)
request_id string Идентификатор запроса (настоятельно рекомендуется, используется для операций принятия/отклонения запроса)

Описание поля request_id:

  • request_id — уникальный операционный идентификатор события запроса, используемый для выполнения операций принятия/отклонения через Request DSL
  • При конвертации события запроса адаптер должен отображать нативный идентификатор запроса платформы в это поле
  • Если платформа не имеет собственного ID запроса, адаптер должен сгенерировать уникальный идентификатор (например, хэш на основе метки времени + ID пользователя)
  • При отсутствии request_id методы event.approve() / event.reject() выбросят ValueError

3. Примеры форматов событий

3.1 Событие сообщения (message)

{
  "id": "1234567890",
  "time": 1752241223,
  "type": "message",
  "detail_type": "group",
  "platform": "yunhu",
  "self": {
    "platform": "yunhu",
    "user_id": "bot_123"
  },
  "message": [
    {
      "type": "text",
      "data": {
        "text": "розыгрыш суперприз"
      }
    }
  ],
  "alt_message": "розыгрыш суперприз",
  "user_id": "user_456",
  "user_nickname": "YingXinche",
  "group_id": "group_789",
  "yunhu_raw": {...},
  "yunhu_raw_type": "message.receive.normal",
  "yunhu_command": {
    "name": "розыгрыш",
    "args": "суперприз"
  }
}

3.2 Событие уведомления (notice)

{
  "id": "1234567891",
  "time": 1752241224,
  "type": "notice",
  "detail_type": "group_member_increase",
  "platform": "yunhu",
  "self": {
    "platform": "yunhu",
    "user_id": "bot_123"
  },
  "user_id": "user_456",
  "user_nickname": "YingXinche",
  "group_id": "group_789",
  "operator_id": "",
  "yunhu_raw": {...},
  "yunhu_raw_type": "bot.followed"
}

3.3 Событие запроса (request)

{
  "id": "1234567892",
  "time": 1752241225,
  "type": "request",
  "detail_type": "friend",
  "platform": "onebot11",
  "self": {
    "platform": "onebot11",
    "user_id": "bot_123"
  },
  "user_id": "user_456",
  "user_nickname": "YingXinche",
  "comment": "Пожалуйста, добавьте в друзья",
  "request_id": "req_abc123",
  "onebot11_raw": {...},
  "onebot11_raw_type": "request"
}

4. Стандарт сегментов сообщений

4.1 Стандартные сегменты сообщений

Стандартные сегменты сообщений не требуют префикса платформы.

Тип Описание Поле data
text Обычный текст text: str
image Изображение file, url: str
voice Голосовое сообщение (звук, записанный на месте, в отличие от audio) file, url: str
audio Аудио (музыкальный файл, воспроизводимый напрямую, в отличие от voice) file, url: str
video Видео file, url: str
file Файл file, url: str, filename: str
mention Упоминание пользователя user_id: str, user_name: str
mention_all Упоминание всех участников нет поля data
reply Ответ message_id: str, user_id: str (отправитель исходного сообщения, на которое даётся ответ; в направлении приёма заполняется адаптером по возможности)
location Местоположение latitude: float, longitude: float, title: str (необязательно), content: str (необязательно)
face Эмодзи (кроссплатформенный сегмент расширения ErisPulse) id: str
keyboard Кнопки/инлайн-клавиатура (кроссплатформенный сегмент расширения ErisPulse) rows: list[list[button]] (см. 4.1.1)

Сопоставление полей с базовой линией OneBot12: медиасегменты (image / voice / audio / video / file) в базовой линии OneBot12 представлены как file_id: str; file данного стандарта (надмножество форматов отправки: URL / локальный путь / bytes) и url (обратная ссылка при приёме) двунаправленно отображаются адаптером на ресурс file_id платформы. face / keyboard являются сегментами расширения вне базовой линии OneBot12.

Формат поля file медиасегментов (направление отправки; общее для image / audio / video / file):

Формат Пример Требование к адаптеру
HTTP(S) URL https://example.com/a.png обязан принимать
Локальный путь к файлу /tmp/a.png, C:\tmp\a.png обязан принимать
Двоичные данные bytes обязан принимать
URI file:// / Base64 / Data URI file:///tmp/a.png, data:image/png;base64,... следует принимать

Полный протокол отправки медиа (порядок определения формата, вывод имени файла, лестница деградации возможностей) см. в Спецификации методов отправки §2.1.

Семантика направления полей:

  • file: источник содержимого в направлении отправки (форматы, указанные выше); в направлении приёма адаптер заполняет формат, доступный для получения с платформы (обычно URL для скачивания или идентификатор ресурса, пригодный для действий типа get_file)
  • url: обратная ссылка платформы в направлении приёма (адаптер заполняет по возможности при конвертации событий платформы, чтобы модули могли использовать её напрямую); в направлении отправки может не заполняться
  • filename: имя файла сегмента file (необязательно в направлении отправки; при отсутствии адаптер генерирует его согласно порядку вывода из Спецификации методов отправки §2.1.3; в направлении приёма следует указывать исходное имя файла платформы)
{
  "type": "text",
  "data": {
    "text": "Hello World"
  }
}

4.1.1 Сегмент keyboard — кнопки/инлайн-клавиатура (кроссплатформенный)

Кнопки/инлайн-клавиатура имеют соответствующие возможности на нескольких платформах (Telegram / Yunhu / QQBot / Kook / Discord и др.) и относятся к кроссплатформенным универсальным концепциям, поэтому являются стандартным сегментом сообщения (без префикса платформы). Адаптер должен преобразовывать стандартный сегмент в нативную структуру платформы; нативные сегменты расширения платформы (например, telegram_inline_keyboard) по-прежнему передаются в прозрачном режиме.

{
  "type": "keyboard",
  "data": {
    "rows": [
      [
        {"label": "Вариант A", "type": "callback", "data": "vote:A"},
        {"label": "Официальный сайт",   "type": "link",     "data": "https://example.com"}
      ]
    ]
  }
}

Описание полей:

Поле Тип Обязательное Описание
rows Двумерный массив Да Каждый подмассив — ряд кнопок
rows[][].label str Да Отображаемый текст кнопки
rows[][].type str Да callback (возврат данных при нажатии) / link (переход по URL)
rows[][].data str Да Данные обратного вызова (type=callback) или адрес перехода (type=link)
rows[][].* Any Нет Необязательные поля, специфичные для платформы (например, web_app, menus); адаптер отображает их по своим возможностям или игнорирует

Справочник по конвертации для адаптеров (полное сопоставление и стандарт событий интерактивного обратного вызова см. в Стандарте кроссплатформенных интерактивных компонентов):

Платформа Стандартный сегмент → Нативный формат платформы
Telegram inline_keyboard: [{text, callback_data | url}]
Yunhu buttons: [{label, action_type: 2=обратный вызов | 1=переход, ...}]
QQBot keyboard.content.rows: [{label, type: 2=обратный вызов | 0=переход, data}] (требуется сообщение типа markdown)
Kook Модуль action-group карточки
Discord components: action_row + buttons (custom_id/url)

4.2 Сегменты расширенных сообщений платформы

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

// Yunhu — форма
{"type": "yunhu_form", "data": {"form_id": "123456", "form_name": "Форма регистрации"}}

// Telegram — стикер
{"type": "telegram_sticker", "data": {"file_id": "CAACAgIAAxkBAA...", "emoji": "😂"}}

Требования к сегментам расширенных сообщений:

  1. Поля внутри data — без префикса: {"type": "yunhu_form", "data": {"form_id": "..."}}, а не {"type": "yunhu_form", "data": {"yunhu_form_id": "..."}}
  2. Обеспечить резервный вариант: модуль может не распознать сегмент расширенного сообщения, поэтому адаптер должен предоставить текстовую альтернативу в alt_message
  3. Полнота документации: каждый сегмент расширенного сообщения должен быть описан в документации адаптера с указанием type, структуры data и сценариев использования

5. Обработка неизвестных событий

Для нераспознанных типов событий следует генерировать событие с предупреждением:

{
  "id": "1234567893",
  "time": 1752241223,
  "type": "unknown",
  "platform": "yunhu",
  "yunhu_raw": {...},
  "yunhu_raw_type": "unknown",
  "warning": "Unsupported event type: special_event",
  "alt_message": "This event type is not supported by this system."
}

6. Правила именования расширений

6.1 Именование полей

Правило: {platform}_{field_name}

Префикс      Имя поля          Полное имя поля
────────     ────────          ────────────────
yunhu        command           yunhu_command
telegram     sticker_file_id   telegram_sticker_file_id
onebot11     anonymous         onebot11_anonymous
email        subject           email_subject

Требования:

  • platform должен полностью совпадать с именем платформы, указанным при регистрации адаптера (с учётом регистра)
  • field_name использует именование snake_case
  • Запрещено начинать с двойного подчёркивания __ (зарезервировано Python)
  • Запрещено совпадение с именами стандартных полей (например, type, time, message и т.д.)

6.2 Именование типов сегментов сообщений

Правило: {platform}_{segment_type}

Стандартные типы сегментов сообщений (text, image, audio, video, mention, reply и др.) не должны получать префикс платформы. Префикс требуется только для типов сегментов сообщений, специфичных для платформы.

6.3 Именование полей исходных данных

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

Зарезервированное поле Тип Описание
{platform}_raw any Полная копия исходных данных события платформы
{platform}_raw_type string Идентификатор исходного типа события платформы

Требования:

  • {platform}_raw должен быть глубокой копией исходных данных, а не ссылкой
  • {platform}_raw_type должен быть строкой; даже если платформа использует числовой тип, его необходимо преобразовать в строку
  • Эти два поля обязаны присутствовать во всех событиях (при невозможности получения — null и пустая строка "")

6.4 Примеры платформенно-специфичных полей

{
  "yunhu_command": {
    "name": "розыгрыш",
    "args": "суперприз"
  },
  "yunhu_form": {
    "form_id": "123456"
  },
  "telegram_sticker": {
    "file_id": "CAACAgIAAxkBAA..."
  }
}

6.5 Вложенные поля расширений

Поля расширений могут быть простыми значениями или вложенными объектами:

{
  "telegram_chat": {
    "id": 123456,
    "type": "supergroup",
    "title": "My Group"
  },
  "telegram_forward_from": {
    "user_id": "789",
    "user_name": "ForwardUser"
  }
}

Требования к вложенным полям:

  • Ключи верхнего уровня должны иметь префикс платформы
  • Вложенные внутренние поля не получают префикс платформы
  • Рекомендуемая глубина вложенности — не более 3 уровней

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

Стандартные обязательные поля объекта self (platform, user_id) приведены в §2.1; ниже перечислены необязательные поля расширения ErisPulse:

Поле Тип Описание
self.user_name string Ник бота
self.avatar string URL аватара бота
self.account_id string Ограниченный ключ расширения (замещение именем учётной записи): если динамически внедрённая учётная запись ещё не получила user_id бота, поле заполняется замещающим значением — именем учётной записи / идентификатором учётной записи, что гарантирует возможность атрибуции события; после того как self.user_id станет доступен, он должен заполняться в приоритетном порядке. Фреймворк поддерживает оба варианта по логике account_id or user_id — при замещении именем учётной записи привязка reply() через сопоставление имени учётной записи разрешается обратно в правильную учётную запись

Граница времени выполнения: событие всегда должно нести self.user_id (включая окно, когда привязка ещё не установлена). События, полученные уровнем подключения до обратного заполнения таблицы привязок и прихода connect meta, также должны получать инъекцию известных идентификаторов: если user_id бота ещё не получен, self.account_id заполняется именем учётной записи в качестве замещения (фреймворк разрешает по логике account_id or user_id, имя учётной записи может быть маршрутизировано обратно в правильную учётную запись через сопоставление по имени учётной записи); если получен — приоритетно заполняется self.user_id — фреймворку на любом этапе обработки события необходимо уметь определять, «из какой учётной записи пришло это событие». Последствия отсутствия определённы: event.reply() не внедряет учётную запись, отправка без указанной учётной записи откатывается к первой включённой учётной записи, и мультиаккаунтный адаптер проявляется как «отправка от учётной записи по умолчанию».

Отслеживание состояния бота: адаптер сообщает фреймворку о состоянии подключения бота, отправляя события type: "meta". Поддерживаемые detail_type: connect (в сети), heartbeat (пульс), disconnect (не в сети). Система автоматически извлекает метаданные бота из поля self для отслеживания состояния. Кроме того, бот автоматически обнаруживается и по полю self в обычных событиях. Подробнее см. API системы адаптеров — Управление состоянием бота.


7. Расширение типов сессий

ErisPulse расширяет набор типов сессий стандарта OneBot12 (private, group) следующими типами:

Тип Стандарт OneBot12 Расширение ErisPulse Описание
private ✅ — Личный чат один на один
group ✅ — Групповой чат
user — ✅ Тип пользователя (Telegram и др.)
channel — ✅ Канал (широковещательный)
guild — ✅ Сервер/сообщество
thread — ✅ Тема/подканал

Расширение пользовательскими типами для адаптеров:

from ErisPulse.Core.Event.session_type import register_custom_type

# Регистрация при запуске адаптера
register_custom_type(
    receive_type="email",      # detail_type в принимаемых событиях
    send_type="email",         # целевой тип при отправке
    id_field="email_id",       # имя соответствующего поля ID
    platform="email"           # идентификатор платформы
)

Требования к пользовательским типам:

  • Должны регистрироваться при вызове start() адаптера и отменяться при shutdown()
  • receive_type не должен совпадать по имени со стандартными типами
  • id_field должен следовать шаблону именования {target}_id

Полные определения типов сессий и соответствия между ними см. в Стандарте типов сессий.


8. Руководство для разработчиков модулей

8.1 Доступ к полям расширений

from ErisPulse.Core.Event import message

@message()
async def handle_message(event):
    # Доступ к стандартным полям
    text = event.get_text()
    user_id = event.get_user_id()

    # Доступ к полям расширений платформы — способ 1: прямой get
    yunhu_command = event.get("yunhu_command")

    # Доступ к полям расширений платформы — способ 2: доступ через точку (класс-обёртка Event)
    # event.yunhu_command

    # Доступ к исходным данным
    raw_data = event.get("yunhu_raw")
    raw_type = event.get_raw_type()

    # Определение платформы
    platform = event.get_platform()
    if platform == "yunhu":
        pass
    elif platform == "telegram":
        pass

8.2 Обработка сегментов расширенных сообщений

@message()
async def handle_message(event):
    message_segments = event.get("message", [])

    for segment in message_segments:
        seg_type = segment.get("type")
        seg_data = segment.get("data", {})

        if seg_type == "text":
            text = seg_data["text"]
        elif seg_type.startswith("yunhu_"):
            if seg_type == "yunhu_form":
                form_id = seg_data["form_id"]
        elif seg_type.startswith("telegram_"):
            if seg_type == "telegram_sticker":
                file_id = seg_data["file_id"]

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

  1. Приоритет стандартных полей: не предполагайте, что поля расширений обязательно существуют
  2. Определение платформы: определяйте платформу через event.get_platform(), а не путём вывода из наличия полей расширений
  3. Плавная деградация: если сегмент расширенного сообщения не может быть обработан, используйте alt_message в качестве запасного варианта
  4. Не хардкодить префикс: используйте динамическую конкатенацию с переменной platform
# ✅ Рекомендуется
platform = event.get_platform()
raw_data = event.get(f"{platform}_raw")

# ❌ Не рекомендуется
raw_data = event.get("yunhu_raw")

8.4 Обработка событий запросов

Разработчики модулей могут выполнять операции над событиями запросов с помощью event.approve() и event.reject():

from ErisPulse.Core.Event import request

# Запрос в друзья: автоматическое принятие
@request.on_friend_request()
async def handle_friend_request(event):
    user_name = event.get_user_nickname() or event.get_user_id()
    comment = event.get_comment()
    
    # Принять запрос
    result = await event.approve()
    if result.get("status") == "ok":
        print(f"Запрос в друзья от {user_name} принят")
    else:
        print(f"Не удалось принять запрос в друзья: {result.get('message')}")

# Приглашение в группу: решение в зависимости от условий
@request.on_group_request()
async def handle_group_request(event):
    comment = event.get_comment()
    
    # Отклонить запрос
    result = await event.reject(comment="Пока не присоединяюсь к новым группам")

Прямые операции через адаптер (применимо вне обработчиков событий):

from ErisPulse import adapter

# Прямая операция через request_id
await adapter.myplatform.Request("req_abc123").accept()
await adapter.myplatform.Request("req_abc123").reject()

# Операция с указанием аккаунта бота
await adapter.myplatform.Request("req_abc123").Using("bot1").accept()

# С сопроводительной записью
await adapter.myplatform.Request("req_abc123").accept(comment="Добро пожаловать")

9. Определение типа сессии для событий notice / request

9.1 Контекст проблемы

detail_type событий notice и request является семантическим подтипом (например, group_member_increase, friend_increase), а не типом сессии (например, group, private).

type        detail_type              Значение                  Тип сессии
────        ───────────              ────────                  ──────────
message     group                    Групповое сообщение       group (detail_type и есть тип сессии)
message     private                  Личное сообщение          private (detail_type и есть тип сессии)
notice      group_member_increase    Прирост участников группы group (выводится из group_id)
notice      friend_increase          Добавление в друзья       private (выводится из user_id)
request     friend                   Запрос в друзья           private (выводится из user_id)
request     group                    Групповой запрос          group (detail_type и есть тип сессии)

9.2 Правила определения

Порядок определения в infer_receive_type():

  1. Если detail_type является известным типом сессии (private/group/channel/guild/thread/user), используется напрямую
  2. Если detail_type является пользовательским типом сессии, используется напрямую
  3. Иначе (семантические подтипы notice/request) определение выполняется по полям ID:
    • есть group_id → "group"
    • есть channel_id → "channel"
    • есть guild_id → "guild"
    • есть thread_id → "thread"
    • есть user_id → "private"

9.3 Определение цели event.reply()

Цель отправки event.reply() в событиях notice/request определяется выводом типа сессии:

  • События групповых уведомлений (содержат group_id) → ответ отправляется в группу
  • События уведомлений о друзьях (содержат только user_id) → ответ отправляется в личный чат пользователя
from ErisPulse.Core.Event import notice

@notice.on_group_increase()
async def handle_welcome(event):
    group_id = event.get("group_id")    # "group_789"
    user_id = event.get("user_id")      # "user_456"

    # event.reply() отправляет в группу (group/group_789)
    await event.reply("Добро пожаловать в группу!")

    # Чтобы уведомить администратора (в личный чат), явно укажите цель:
    await adapter.Send.To("user", "admin_id").Text(f"Новый участник {user_id} присоединился к {group_id}")

9.4 Рекомендации по разработке адаптеров

Убедитесь, что события notice/request содержат правильные поля ID:

detail_type Обязательные поля ID Определяемый тип сессии
group_member_increase group_id + user_id group
group_member_decrease group_id + user_id group
friend_increase user_id private
friend_decrease user_id private
friend (запрос) user_id private
group (запрос) group_id group

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

Для сопоставления при реализации конвертера:

Отправляющая сторона того же адаптера:

Известные события расширений и сегменты сообщений платформ: