Спецификация стандартизированной конвертации адаптеров
Tip
Когда следует читать этот документ: когда вы конвертируете нативные события платформы в стандартные события OneBot12 внутри адаптера — сверяйтесь с этим документом при проверке обязательных полей, структуры сегментов сообщений, правил именования расширений (префикс {platform}_) и определения типа сессии. Если это не требуется — пропустите.
1. Основные принципы
- Строгая совместимость: все стандартные поля должны полностью соответствовать спецификации OneBot12
- Явные расширения: специфичные для платформы функции должны добавляться с префиксом {platform}_ (например, yunhu_form)
- Полнота данных: исходные данные события должны сохраняться в поле {platform}_raw, а исходный тип события — в поле {platform}_raw_type
- Единый формат времени: все метки времени должны быть преобразованы в 10-значные метки времени Unix (с точностью до секунды)
- Единообразие платформ: имя элемента 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— уникальный операционный идентификатор события запроса, используемый для выполнения операций принятия/отклонения черезRequestDSL- При конвертации события запроса адаптер должен отображать нативный идентификатор запроса платформы в это поле
- Если платформа не имеет собственного 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": "😂"}}
Требования к сегментам расширенных сообщений:
- Поля внутри data — без префикса:
{"type": "yunhu_form", "data": {"form_id": "..."}}, а не{"type": "yunhu_form", "data": {"yunhu_form_id": "..."}} - Обеспечить резервный вариант: модуль может не распознать сегмент расширенного сообщения, поэтому адаптер должен предоставить текстовую альтернативу в
alt_message - Полнота документации: каждый сегмент расширенного сообщения должен быть описан в документации адаптера с указанием
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 Лучшие практики
- Приоритет стандартных полей: не предполагайте, что поля расширений обязательно существуют
- Определение платформы: определяйте платформу через
event.get_platform(), а не путём вывода из наличия полей расширений - Плавная деградация: если сегмент расширенного сообщения не может быть обработан, используйте
alt_messageв качестве запасного варианта - Не хардкодить префикс: используйте динамическую конкатенацию с переменной
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():
- Если
detail_typeявляется известным типом сессии (private/group/channel/guild/thread/user), используется напрямую - Если
detail_typeявляется пользовательским типом сессии, используется напрямую - Иначе (семантические подтипы 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. Связанные документы
Для сопоставления при реализации конвертера:
- Стандарт типов сессий — определения типов сессий и соответствия между ними
- Стандарт ответов API — стандарт формата ответов API адаптера
Отправляющая сторона того же адаптера:
- Спецификация методов отправки — именование методов класса Send, спецификация параметров и требования к обратной конвертации
- Стандарт API-действий — унифицированный интерфейс стандартных API-действий OneBot12
Известные события расширений и сегменты сообщений платформ:
- Документация по особенностям платформ — обратитесь к этому документу, чтобы узнать об особенностях каждой платформы, известных событиях расширений, сегментах сообщений и т.д.