Руководство по стандартизации адаптеров (общий план)
Tip
Когда читать это: при разработке нового адаптера, добавлении новой функции для платформы, решении, следует ли добавлять в стандарт или использовать {platform}_ расширение, как назвать функцию, как обработать различия между платформами — сначала прочитайте эту статью. Если вы просто ищете конкретные спецификации для определенной области, можно сразу перейти к разделу §2, соответствующему стандартной карте.
Данный документ является общим планом стандартизации адаптеров ErisPulse: он устанавливает принципы кросс-платформенной стандартизации, стандартную карту, модели обработки различий, процесс внедрения новых возможностей в стандарт, а также дает полное определение стандартных компонентов интерфейса (кнопки/клавиатура, выпадающий список и т.д.) и обратных вызовов событий интерфейса. Любые разработчики адаптеров при реализации новых функций должны в первую очередь использовать стандартные определения, чтобы модули разработчиков могли использовать один и тот же код для получения последовательного опыта на любой платформе — с одинаковыми именами, параметрами и возвращаемыми значениями.
1. Принципы стандартизации
- Единообразное именование: одно и то же понятие на всех платформах должно использовать одно и то же имя (например, удаление сообщения —
delete_message, сегменты кнопок —keyboard), без различий из-за платформы - Единообразные параметры: структура параметров стандартных действий/сегментов/методов должна быть одинаковой на всех платформах; платформенные специфические параметры предоставляются в виде необязательных расширенных параметров или расширенных полей, не загрязняя стандартный сигнатуру
- Единообразные возвращаемые значения: все API/вызовы отправки возвращают стандартную структуру ответа (
status/retcode/data/message_id/message), стандартные поля вdata(например,user_id/user_name) имеют одинаковую семантику; платформенные исходные данные помещаются в{platform}_raw - Обоснованное расширение: платформенные специфические возможности должны иметь префикс
{platform}_(сегмент:yunhu_form; действие:yunhu.board; поля событий:qqbot_button_id), четко обозначая, что они не являются кросс-платформенными - Поглощение различий на уровне адаптера: модульный код должен программироваться с учетом стандарта, платформенные различия должны обрабатываться адаптером (сопоставление параметров, стандартизация полей, понижение возможностей), модулю не нужно писать платформенные ветви
- Безошибочное понижение возможностей: при отсутствии поддержки стандартной возможности платформой, она должна быть элегантно понижена (возвращается
retcode=10002, компоненты преобразуются в текст и помещаются вalt_message), без выбрасывания исключений, прерывающих логику модуля
2. Стандартная карта
| Область | Стандартный документ | Охватываемое содержание |
|---|---|---|
| Преобразование событий | Стандарт преобразования событий | Структура событий, стандартные сегменты сообщений (text/image/mention/reply/keyboard и т.д.), спецификации платформенных расширенных сегментов |
| Компоненты интерфейса | Документ §5 | Кнопки/клавиатура, выпадающий список, карточки, стандартные поля обратных вызовов событий интерфейса, соглашения о декораторах, отображение на платформах |
| API действия | Стандарт API действий | Единый интерфейс и ApiDSL для стандартных действий OneBot12 (управление пользователями/группами/каналами/сообщениями/мета-действиями) |
| Действия запроса | Спецификация действий запроса | Поля событий запроса (request_id), DSL запроса (approve/reject) и сохранение контекста типа запроса на неоднородных конечных точках |
| Методы отправки | Спецификация методов отправки | Названия, параметры, декораторы методов класса Send, обратное преобразование (OB12→платформа) |
| Типы сессий | Стандарт типов сессий | Определения и отображение типов сессий (user/group/channel/guild/dms) |
| API ответы | Стандарт API ответов | Стандартная структура ответа и соглашения о retcode |
3. Процесс стандартизации (как новые возможности входят в стандарт)
Платформенные специфические возможности (с префиксом {platform}_)
│ ≥2 платформы имеют подобные возможности
▼
Идентификация общих черт (извлечение общих концепций и подмножества параметров)
│
▼
Проект стандарта (название + параметры + возвращаемые значения + таблица отображения на платформы)
│ Обзор
▼
Внесение в этот общий план/документы по стандартам областей + реализация базового класса фреймворка/совместимый слой адаптера
│
▼
Стандартные сегменты/действия (без префикса) — модули могут использовать кросс-платформенно
Пример: Кнопки изначально реализовывались независимо на каждой платформе (telegram_inline_keyboard / кнопки Yunhu / клавиатура QQBot) → появляются на ≥3 платформах → извлекается общая структура (label/type/data + rows) → публикуется стандартный сегмент keyboard → реализуется совместимый слой на каждом адаптере (декоратор принимает общую структуру + преобразование стандартного сегмента + прямая передача оригинального сегмента).
3.1 Правила именования
| Объект | Правило | Пример |
|---|---|---|
| Стандартный сегмент сообщения | в нижнем регистре, общее понятие без префикса | keyboard, select, mention |
| Платформенный расширенный сегмент | с префиксом {platform}_ |
telegram_sticker, yunhu_form |
| Стандартное API действие | стандартное имя OB12 (snake_case) | get_group_info, delete_message |
| Платформенное расширенное действие | с префиксом {platform}. или общим именем протокола |
yunhu.board, send_poke (расширение OB11) |
| Декоратор | PascalCase, общие возможности в базовом классе фреймворка | .Keyboard(rows), .At(uid) |
| Стандартное поле события | общее понятие без префикса | interaction_id, button_data, request_id |
| Платформенное поле события | с префиксом {platform}_ |
qqbot_event_id, telegram_chat_id |
3.2 Правила параметров и возвращаемых значений
- Стандартные параметры на всех платформах имеют одинаковое имя и значение; единицы/форматы должны быть четко определены в стандарте (например, временная метка в секундах, строковый ID)
- Обязательные параметры — это общее подмножество возможностей всех платформ; расширенные возможности платформы — необязательные параметры
- Сильные ограничения платформы (например, в QQBot нельзя одновременно отправлять богатый медиа и event_id) должны обрабатываться адаптером автоматически/понижением, не отображаясь модулю
- Поля
dataв возвращаемых значениях стандартны на всех платформах; дополнительная платформенная информация помещается в платформенные поля внутриdataили в{platform}_raw
4. Модели обработки различий (на уровне адаптера)
| Модель | Описание | Пример |
|---|---|---|
| Сопоставление параметров | Стандартный параметр → платформенный оригинальный параметр | delete_message(message_id) → TG deleteMessage(chat_id, message_id) (заполнение chat_id по таблице) |
| Преобразование структуры | Стандартный сегмент → платформенная оригинальная структура | Сегмент keyboard → inline_keyboard / buttons / клавиатура QQBot |
| Сопоставление действий | Стандартное имя действия → платформенное имя действия | get_self_info → get_login_info (OB11) |
| Стандартизация полей | Платформенный ответ → стандартные поля | getMe() → {user_id, user_name, user_displayname} |
| Генерация идентификатора | При отсутствии оригинального идентификатора платформы генерируется определенный ID | TG join request без ID → tjr_{chat}_{user}_{date} |
| Понижение возможностей | При отсутствии поддержки возвращает 10002 | Kook без клавиатуры → текст в alt_message; get_friend_list → 10002 |
| Нормализация | Платформенные "грязные" данные → стандартный формат | @-метка QQBot openid → bot_id (имя нормализовано) |
| Двойная совместимость | Стандартная структура и платформенная оригинальная структура принимаются одновременно | .Keyboard() принимает общие rows или оригинальную структуру |
5. Стандартные компоненты интерфейса
5.1 Список компонентов и состояния
| Компонент | Стандартный тип сегмента | Состояние | Поддерживаемые платформы |
|---|---|---|---|
| Кнопки/клавиатура (keyboard) | keyboard |
✅ Стандартизирован | Telegram / Yunhu / QQBot |
| Выпадающий список (select) | select |
📋 Зарезервировано (структура см. §5.4) | Discord / Telegram(bot) |
| Карточка (card) | card |
📋 Зарезервировано (см. §5.5) | Kook / Yunhu(html) |
| Модальное окно (modal) | modal |
📋 Зарезервировано | Discord |
Соглашение о иерархии декораторов: декораторы отправки общих компонентов интерфейса реализуются в классе Send адаптера (базовый класс фреймворка не включает их), именование следует §5.2, параметры соответствуют стандартной структуре этого документа.
5.2 Кнопки/внутренняя клавиатура keyboard
Структура сегмента сообщения (направление отправки)
Стандартный сегмент keyboard = двумерный массив rows, каждый элемент кнопки —
{"label": "отображаемый текст", "type": "callback" | "link", "data": "данные обратного вызова или адрес перехода"}, также допускаются необязательные платформенные поля (адаптер отображает или игнорирует в зависимости от возможностей).
Официальное определение структуры: полная JSON-структура сегмента сообщения, таблица полей и семантика полей см. в стандарте преобразования событий §4.1.1 сегмент кнопки/внутренней клавиатуры, в этом разделе повторять не будем.
Отображение на платформы
| Платформа | Стандартный сегмент → оригинальная структура | Оригинальная структура |
|---|---|---|
| Telegram | reply_markup.inline_keyboard: [{text, callback_data | url}] |
callback→callback_data (≤64 байт), link→url |
| Yunhu | content.buttons: [{label, action_type}] |
callback→action_type:2 + action + value, link→action_type:1 + url |
| QQBot | keyboard.content.rows: [{label, type, data}] |
callback→type:2 + data, link→type:0 + data (сообщение должно быть типа markdown) |
| Kook | Модуль action-group карточки: [{type, text, value, click}] |
callback→click:return + value, link→click:link + url |
| Discord | components[].components: [{label, style, custom_id | url}] |
callback→style:1 + custom_id, link→style:5 + url |
Декораторы отправки (реализуются в классе Send каждого адаптера)
Общие декораторы реализуются в классе Send каждого адаптера (базовый класс фреймворка не изменяется):
.Keyboard(rows): стандартное имя, принимает структуруrowsиз §5.2, внутри генерирует стандартный сегментkeyboard(или напрямую преобразует в оригинальную структуру платформы), обрабатываетсяRaw_ob12.Buttons(rows): необязательный синоним семантики, поведение такое же- Обратная совместимость: при обнаружении оригинальной структуры платформы она передается напрямую (без ошибок, без преобразования)
- Платформенные расширенные сегменты (например,
telegram_inline_keyboard) продолжают передаваться напрямую, не затрагиваются
# Один и тот же код, любая платформа (каждый адаптер предоставляет декораторы и преобразование)
rows = [[{"label": "Лайк", "type": "callback", "data": "like:1"},
{"label": "Главная", "type": "link", "data": "https://example.com"}]]
await adapter.Send.To("group", gid).Keyboard(rows).Text("Выберите")
Список совместимых адаптеров: QQBot / Telegram / Yunhu реализованы (декораторы + преобразование стандартного сегмента); Новые адаптеры реализуются по этому документу (см. §7 Checklist).
5.3 Обратные вызовы событий интерфейса (после нажатия кнопки)
События, которые платформа отправляет после нажатия пользователем кнопки, должны содержать следующие стандартные поля (detail_type можно сохранить платформенное название):
| Стандартное поле | Тип | Обязательно | Описание |
|---|---|---|---|
interaction_id |
str | Да | ID текущей взаимодействия (может использоваться для ответа, например, для показа индикатора) |
button_data |
str | Да | Данные, возвращенные кнопкой (см. §5.2 data) |
button_label |
str | Нет | Отображаемый текст кнопки |
user_id |
str | Да | ID пользователя, нажавшего |
message_id |
str | Нет | ID сообщения, в котором находится кнопка |
group_id / channel_id |
str | Нет | ID источника сессии |
Соглашение о detail_type: сохраняются существующие названия платформ (например, qqbot_interaction, telegram_callback_query, yunhu_a2ui_button и т.д.), но стандартные поля должны быть полными — модули могут использовать event.get("button_data") для получения значений на кросс-платформенной основе.
Рекомендуемые методы расширения Event (предоставляются EventMixin адаптера):
def get_button_data(self) -> str: ... # button_data
def get_interaction_id(self) -> str: ... # interaction_id
Ответ на взаимодействие (в зависимости от возможностей платформы): adapter.reply_interaction(interaction_id, code=0) (QQBot) / answerCallbackQuery (Telegram) и т.д., именование следует семейству методов платформы, не обязательно унифицировать.
Отображение обратных вызовов событий на платформы
| Платформа | Оригинальное событие | detail_type | Источник interaction_id | Источник button_data |
|---|---|---|---|---|
| Telegram | callback_query |
telegram_callback_query (notice) |
callback_query.id |
callback_query.data |
| Yunhu | Событие нажатия кнопки | yunhu_button_click / yunhu_a2ui_button |
buttonId / sourceComponentId |
value / actionName |
| QQBot | INTERACTION_CREATE |
qqbot_interaction |
interaction.id |
data.resolved.button_data |
| Kook | Событие нажатия кнопки | kook_button_click |
msg_id+value |
value |
| Discord | INTERACTION_CREATE |
discord_interaction |
interaction.id |
data.custom_id |
5.4 Выпадающий список select (зарезервировано)
{
"type": "select",
"data": {
"placeholder": "Выберите",
"options": [
{"label": "Опция A", "data": "opt:A"},
{"label": "Опция B", "data": "opt:B"}
],
"min_values": 1,
"max_values": 1
}
}
Обратные вызовы событий используют поля из §5.3 (button_data = выбранное data, в случае множественного выбора — JSON-массив). Первые реализующие платформы: Discord (select menu), Telegram (переключение клавиатуры). Платформы, которые не реализуют, должны в alt_message преобразовать этот сегмент в текстовый список.
5.5 Карточка card (зарезервирована, отложена стандартизация)
Структура карточек сильно различается (модуль карточек Kook, html Yunhu, markdown+keyboard QQ), стандартизация пока не проводится. Рекомендуется:
- Использовать
text+keyboardдля выражения богатого текста карточек (для большинства сценариев достаточно) - Полнофункциональные карточки платформы продолжают использовать расширенный сегмент
{platform}_card(например,kook_card) - Стандартизация будет рассмотрена при появлении ≥2 платформ с одинаковыми возможностями карточек
6. Будущие кандидаты (Roadmap)
Следующие возможности уже появились на ≥2 платформах или ожидается их появление, и стандартизация проводится в порядке приоритетности:
| Кандидат | Платформы | Приоритет | Примечание |
|---|---|---|---|
| Выпадающий список select | Discord / Telegram | Высокий | Структурный черновик см. §5.4 |
| Реакции/эмоции (reactions) | QQBot / Telegram / Discord / Kook | Высокий | Стандартизация действий и событий с обеих сторон |
| Действия управления группой (запрет/выкидывание/одобрение) | QQBot / Yunhu / OB11 | Высокий | Большинство уже реализовано как платформенные действия, ожидается извлечение стандартной сигнатуры |
| Анонсы/доски | Yunhu / Telegram / Discord | Средний | Действия типа set_announcement |
| Модель ресурсов файлов (двухчастный file_id) | Все платформы | Низкий (отложено) | Прямая передача файлов SendDSL.File(file, filename) — уже стандартный путь (URL/путь/bytes напрямую, см. спецификацию методов отправки §2.1); file_id модель только при наличии в бэкенде, см. стандарт API действий §3.5 |
| Карточка card | Kook / Yunhu | Низкий | Структура сильно различается, см. §5.5 |
| Форма form | Yunhu | Низкий | Платформенный специфический, сохраняется префикс {platform}_ |
| Кодирование/размер медиа | Все платформы | Низкий | Реализуется внутри адаптера, не стандартизируется публично |
7. Список стандартов для новых разработчиков адаптеров
При разработке нового адаптера, сверяйтесь с этим списком (★ — обязательные, остальные рекомендуемые):
- ★ Преобразование событий в стандартную структуру OneBot12, наследование
BaseConverter - ★ Поддержка стандартных сегментов сообщений (text/image/mention/reply/keyboard и т.д.; сегменты медиа обрабатываются по иерархии и понижению, см. спецификацию методов отправки §2.1)
- ★ Реализация
Raw_ob12(включая преобразование стандартного сегмента → платформенная структура; обязательна реализация стандартного сегментаkeyboard) - ★ Возвращение стандартной структуры ответа (
make_response/make_error) - ★ Многоаккаунтность:
AccountConfigClass(BotAccountConfig)+ разбор аккаунта (сопоставление имени аккаунта /bot_id) - ★ Класс Send наследует
BaseAdapter.Send, использует_apply_modifiers/send_context - ☆ Api DSL: сопоставление стандартных действий с платформенными API (см. стандарт API действий)
- ☆ Request DSL: события запроса содержат
request_id+approve/reject(异构端点平台含请求类型上下文留存) - ☆ Компоненты интерфейса: преобразование сегмента
keyboard+ стандартные поля обратных вызовов + декораторы.Keyboard()/.Buttons() (реализуются в классе Send адаптера) - ☆ EventMixin:
get_raw_event()/get_button_data()и т.д. платформенные расширенные методы - ☆ Задачи жизненного цикла используют
runtime.spawn_background - ☆ Чтение конфигурации с помощью
self.cfg - ☆ Фреймворк без жесткой зависимости от ErisPulse + проверка версии во время выполнения
- ☆ i18n: конфигурационные поля и логи на нескольких языках
- ☆ platform-guide платформенная документация + файл platform-features.md в репозитории адаптера
8. Связанные документы
- Стандартные документы по областям см. в §2 Стандартной карте
- Встроенные адаптеры фреймворка могут служить примерами реализации: QQBot (полная реализация v5), OneBot11 (сопоставление Api DSL), Yunhu (BaseConverter + расширение Web API)