Спецификация методов отправки ErisPulse
Tip
Когда стоит читать этот документ: когда вы реализуете класс Send в адаптере — сверяйтесь с этим документом при именовании методов, поддержке форм медиапараметров (URL/путь/bytes), обратном преобразовании Raw_ob12, возможностях объединённой пересылки. Если не нужно — пропустите.
Этот документ определяет соглашения об именовании методов отправки класса Send в адаптерах ErisPulse, спецификации параметров и требования к обратному преобразованию.
0. Соглашения о ключевых словах
Ключевые слова ОБЯЗАТЕЛЬНО (MUST), СЛЕДУЕТ (SHOULD), МОЖЕТ (MAY) в этом документе интерпретируются со следующей семантикой (в соответствии с RFC 2119):
| Ключевое слово | Семантика | Последствия нарушения |
|---|---|---|
| ОБЯЗАТЕЛЬНО | Обязательное требование; от него зависит поведение фреймворка/кроссплатформенная согласованность | Адаптер считается несоответствующим стандарту, код модулей может не работать |
| СЛЕДУЕТ | Настоятельная рекомендация; следовать, если нет веских причин поступить иначе | При отклонении необходимо указать причину и альтернативное поведение в документации адаптера |
| МОЖЕТ | Опционально; решается исходя из возможностей платформы | Отсутствуют |
1. Стандартное именование методов
Все методы отправки используют PascalCase, первая буква — заглавная.
1.1 Стандартные методы отправки
| Имя метода | Описание | Тип параметров | Требования к реализации |
|---|---|---|---|
Text |
Отправка текстового сообщения | str |
ОБЯЗАТЕЛЬНО |
Image |
Отправка изображения | str | bytes |
ОБЯЗАТЕЛЬНО (встроено в базовый класс, см. §6.4) |
Voice |
Отправка голосового сообщения | str | bytes |
ОБЯЗАТЕЛЬНО (встроено в базовый класс; если платформа не поддерживает голос — деградация по §2.1.5) |
Video |
Отправка видео | str | bytes |
ОБЯЗАТЕЛЬНО (встроено в базовый класс; если платформа не поддерживает видео — деградация по §2.1.5) |
File |
Отправка файла | str | bytes, filename: str | None = None |
ОБЯЗАТЕЛЬНО (встроено в базовый класс) |
Location |
Отправка сообщения о местоположении | float (latitude/longitude), title: str = "", content: str = "" |
ОБЯЗАТЕЛЬНО (встроено в базовый класс) |
At |
Упоминание пользователя/группы | str (user_id) |
Метод-модификатор, по необходимости |
Face |
Отправка эмодзи | str (emoji) |
МОЖЕТ |
Reply |
Ответ на сообщение | str (message_id) |
Метод-модификатор, по необходимости |
Forward |
Пересылка сообщения | str (message_id) |
МОЖЕТ |
Markdown |
Отправка Markdown-сообщения | str |
МОЖЕТ |
HTML |
Отправка HTML-сообщения | str |
МОЖЕТ |
Card |
Отправка карточки | dict |
МОЖЕТ |
Стандартные методы (
Text/Image/Voice/Video/File/Location) встроены в базовый классSendDSLи по умолчанию делегируютRaw_ob12; адаптер получает сигнатуры типов без повторной реализации. Переопределяйте отдельный метод только когда платформе требуется особая логика (см. §6.4).
1.2 Цепные методы-модификаторы
| Имя метода | Описание | Тип параметров |
|---|---|---|
At |
Упоминание пользователя (можно вызывать многократно) | str (user_id) |
AtAll |
Упоминание всех участников | нет |
Reply |
Ответ на сообщение | str (message_id) |
1.3 Протокольные методы
| Имя метода | Описание | Обязателен ли |
|---|---|---|
Raw_ob12 |
Отправка сегментов сообщений в формате OneBot12 | ОБЯЗАТЕЛЬНО |
Raw_ob12 — метод, который обязательно должен быть реализован. Это одна из ключевых обязанностей адаптера: принимать стандартные сегменты сообщений OneBot12 и преобразовывать их в вызовы нативного API платформы. Raw_ob12 — единая точка входа для обратного преобразования (OneBot12 → платформа), гарантирующая, что модули могут отправлять сообщения стандартными сегментами, не завися от платформенно-специфичных методов.
Поведение при не переопределённом Raw_ob12: реализация базового класса по умолчанию записывает журнал уровня error и возвращает стандартный формат ответа с ошибкой (status: "failed", retcode: 10002), указывая разработчику адаптера на необходимость реализовать этот метод.
1.4 Рекомендуемые соглашения об именовании расширений
Если адаптер должен поддерживать отправку сырых данных не в формате OneBot12 (например, JSON, XML конкретной платформы), рекомендуется использовать следующие соглашения об именовании:
| Рекомендуемое имя метода | Описание |
|---|---|
Raw_json |
Отправка произвольных JSON-данных |
Raw_xml |
Отправка произвольных XML-данных |
Примечание: эти методы не являются стандартными методами базового класса, и их реализация не обязательна. Они служат лишь соглашением об именовании; адаптер может определить их по мере необходимости. Если адаптер не поддерживает эти форматы, определять их не нужно.
MessageBuilder (конструктор сообщений): ErisPulse предоставляет утилитарный класс MessageBuilder для удобного построения списков сегментов сообщений OneBot12 в сочетании с Raw_ob12. Подробнее см. Подробно о MessageBuilder.
2. Подробная спецификация параметров
2.1 Протокол отправки мультимедийных сообщений (Image / Voice / Video / File)
Этот раздел — единый стандарт протокола отправки медиа: модули вызывают четыре медиаметода одним и тем же кодом, а адаптер отвечает за преобразование различных форм параметра file в нативные для платформы операции загрузки/отправки.
2.1.1 Допустимые формы параметра file
| Форма | Пример | Требование к адаптеру |
|---|---|---|
| HTTP(S) URL | https://example.com/image.jpg |
ОБЯЗАТЕЛЬНО принять |
| Локальный путь к файлу | /path/to/file.jpg, C:\path\to\file.jpg |
ОБЯЗАТЕЛЬНО принять |
| Бинарные данные | b"\x89PNG..." |
ОБЯЗАТЕЛЬНО принять |
URI file:// |
file:///path/to/file.jpg |
СЛЕДУЕТ принять (можно обработать как локальный путь) |
| Строка Base64 / Data URI | iVBORw0KGgo=..., data:image/png;base64,... |
СЛЕДУЕТ принять (совместимость с практикой экосистемы OneBot12) |
Адаптер ОБЯЗАН вести себя одинаково для трёх обязательных форм — что бы ни передал модуль (URL, путь или bytes), будет доставлено одно и то же сообщение. Если платформа не может использовать какую-то форму напрямую (например, API платформы не поддерживает ссылки на внешние URL), адаптер самостоятельно скачивает/читает и загружает данные; ЗАПРЕЩЕНО требовать от модуля повторной попытки в другой форме.
2.1.2 Порядок определения формы
При реализации обработки медиапараметров адаптер СЛЕДУЕТ определять форму в следующем порядке:
- Тип
bytes→ прямая загрузка - Строка начинается с
http:///https://→ обрабатывать как URL (прямая ссылка либо скачивание и загрузка, в зависимости от возможностей платформы) - Строка начинается с
file://→ отбросить префикс и обрабатывать как локальный путь - Остальные строки → обрабатывать как локальный путь (если существует — прочитать и загрузить; если нет — вернуть стандартный формат ответа с ошибкой)
def _resolve_media(self, file: "str | bytes") -> bytes:
"""Определение формы и нормализация (пример)"""
if isinstance(file, (bytes, bytearray)):
return bytes(file)
if file.startswith(("http://", "https://")):
return self._download(file) # скачать, если платформа не может ссылаться на URL
if file.startswith("file://"):
file = file[len("file://"):]
with open(file, "rb") as f: # локальный путь
return f.read()
2.1.3 Семантика имени файла у File
Сигнатура метода File: File(file, filename=None) (filename — необязательный параметр, встроен в базовый класс).
Порядок вывода имени файла (адаптер генерирует его по этой схеме, когда filename не задан явно):
- Явный параметр
filename(наивысший приоритет) - basename URL (например,
https://host/a/b/report.pdf→report.pdf, необходимо отбросить query string) - basename локального пути (например,
/tmp/data/backup.zip→backup.zip) - Генерация по умолчанию платформы (например,
file_{timestamp}; СЛЕДУЕТ сохранять реальное расширение — расширение влияет на распознавание типа и поведение предпросмотра на стороне платформы)
Image/Voice/Videoтакже МОГУТ приниматьfilename(передаётся черезdata.filenameсегмента сообщения), но кроссплатформенная семантическая гарантия имени файла есть только уFile.
2.1.4 Обязанность декларировать ограничения платформы
Платформы различаются по ограничениям на размер медиа, форматы (MIME), длительность (аудио/видео) и т.д. Адаптер СЛЕДУЕТ:
- Задекларировать в документации адаптера поддерживаемые типы медиа и пределы ограничений
- При превышении лимитов или неподдерживаемом вводе возвращать стандартный ответ с ошибкой (
status: "failed";retcode—10002или семантический код ошибки платформы,messageс объяснением причины); ЗАПРЕЩЕНО выбрасывать исключения, прерывая логику модуля
2.1.5 Лестница деградации возможностей
Когда платформа не поддерживает какой-либо тип медиа, деградация выполняется по следующей лестнице (следуя принципу главного документа «деградация возможностей без ошибок»):
| Сценарий | Поведение при деградации |
|---|---|
Voice: голосовые сообщения не поддерживаются |
СЛЕДУЕТ отправлять как File (или близкую форму платформы); если невозможно выразить — вернуть retcode=10002 |
Video: видео не поддерживается |
Аналогично |
| Тип медиа полностью не поддерживается (нет файловых возможностей) | Вернуть retcode=10002, в message указать неподдерживаемый тип данных |
| Форма не поддерживается (например, нельзя обработать base64) | Вернуть retcode=10002; МОЖНО в message подсказать модулю использовать URL/bytes |
ЗАПРЕЩЕНО поведение: молчаливое отбрасывание (без возврата), выбрасывание исключений, требование к модулю писать платформенно-зависимые ветвления.
2.2 Спецификация параметра @пользователя
Метод: At (метод-модификатор)
Параметр: user_id (str)
Требования:
user_idдолжен быть строковым идентификатором пользователя- Формат
user_idможет отличаться на разных платформах (числа, UUID, строки и т.д.) - Адаптер отвечает за преобразование
user_idв формат, специфичный для платформы - Обратите внимание: реальный вызов метода отправки должен стоять на последнем месте
Пример:
# Одиночное упоминание пользователя
Send.To("group", "g123").At("123456").Text("Привет")
# Несколько упоминаний (цепной вызов)
send.To("group", "g123").At("123456").At("789012").Text("Всем привет")
2.3 Спецификация параметра ответа на сообщение
Метод: Reply (метод-модификатор)
Параметр: message_id (str)
Требования:
message_idдолжен быть строковым идентификатором сообщения- Должен быть ID ранее полученного сообщения
- Некоторые платформы могут не поддерживать функцию ответа; адаптер должен корректно деградировать
Пример:
send.To("group", "g123").Reply("msg_123456").Text("Получено")
2.4 Возможность объединённой пересылки (MergeForward, опционально)
MergeForward(nodes) — опциональный метод возможностей: упаковывает несколько фрагментов контента в форму «объединённая пересылка / свёрнутый rich text» и отправляет; адаптер выбирает наилучшее представление по возможностям платформы. По семантике это отличается от Forward(from_chat_id, message_id) из §1.1 (пересылка уже существующего сообщения); оба сосуществуют.
Контекст стандарта: ядро стандарта OneBot12 не содержит сегмента node и API объединённой пересылки — «узлы сообщений» являются концепцией уровня реализации экосистемы OneBot v11 (расширение go-cqhttp); в v12 такие платформенно-специфичные возможности отданы механизму расширений. ErisPulse реализует это как эквивалент механизма расширений: не добавляя стандартные сегменты сообщений, а через опциональные методы возможностей + обнаружение во время выполнения
list_sends— адаптеры, реализовавшиеMergeForward, автоматически получают возможность; вызывающие без неё автоматически откатываются к обычному тексту; модули не требуют изменений.
Сигнатура метода:
def MergeForward(self, nodes: List[Dict]) -> asyncio.Task:
"""
Отправка сообщения в виде объединённой пересылки / свёрнутого rich text
:param nodes: массив узлов объединённой пересылки (формат узлов OneBot v11 из расширения go-cqhttp):
[
{
"type": "node",
"data": {
"user_id": "10000", # id отправителя для отображения
"nickname": "MyBot", # ник отправителя для отображения
"content": [ # массив сегментов сообщения, сейчас сегменты text
{"type": "text", "data": {"text": "[1/3] Заголовок\nТекст…"}}
],
},
},
]
:return: asyncio.Task, после await возвращает стандартный формат ответа
"""
Требования к реализации:
- Платформа имеет нативную объединённую пересылку (серия OneBot11): ОБЯЗАТЕЛЬНО вызывать специализированные эндпоинты протокола
(
send_group_forward_msg/send_private_forward_msg) — реализации вроде NapCat отклоняют node-сегменты, переданные черезsend_msg(retcode 1400); при сбое специализированного эндпоинта МОЖНО откатиться к прямой отправке node-сегментов черезsend_msg - Платформа не имеет нативной пересылки, но поддерживает rich text (Yunhu / Telegram / Kook / Discord / Matrix и др.):
СЛЕДУЕТ отобразить узлы в свёрнутой rich-text-форме платформы (свёрнутая HTML-карточка / Card / Embed / список blockquote);
справочные стили и список задач по каждому адаптеру см. в
SDK/Adapter/ADAPTER_FORWARD_GUIDE.md - Нет ни того, ни другого: ЗАПРЕЩЕНО реализовывать этот метод (тем более возвращать успех, отправив node-словари как простой текст) —
когда метод не реализован,
list_sendsне содержитMergeForward, и вызывающий автоматически откатывается к обычному тексту - Семантика отказа: допустимо вернуть стандартный формат ответа с ошибкой (
status: "failed") или выбросить исключение; вызывающий откатится к простой отправке текста, контент не теряется - ЗАПРЕЩЕНО внутри
MergeForwardснова вызыватьRaw_ob12для отправки тех же nodes (вRaw_ob12OneBot11 уже встроена автоматическая маршрутизация чистых node-сегментов, возникнет цикл) - Парсинг исходящих node-сегментов (соглашение для всех адаптеров): в распределении сегментов
Raw_ob12каждого адаптера должен быть зарегистрирован сегментnode— чистый список node автоматически маршрутизируется к представлению объединённой пересылки данного адаптера (на платформах сMergeForwardэквивалентно прямому вызову; на платформах без этого метода текст каждого узла извлекается и выводится как есть построчно в формате «ник: текст»); в смешанном списке текст node-сегментов включается в основной текст. Любой адаптер, получив node-сегмент, не должен молча его отбрасывать.
Формы реализации на платформах (подробнее в SDK/Adapter/ADAPTER_FORWARD_GUIDE.md):
- Нативные эндпоинты: OneBot11, SnowLuma (трёхуровневый откат: специализированный эндпоинт
send_group/private_forward_msg→upload_forward_msgс получением resid и отправкой forward-сегмента → прямая отправка node-сегментов; API SnowLuma полностью согласован с NapCat, адаптер может подключаться напрямую к бэкенду NapCat) - Свёрнутая HTML-карточка
<details>: Yunhu (протокол bot/пользователя), Email, Sandbox, Allons(Ideaura) - HTML по белому списку / цитатные блоки: Telegram (
<b>+<blockquote>), Matrix (вариант blockquote, белый список с удалением details/встроенных стилей) - Карточки платформы: Kook (Card header+section), Discord (Embed fields)
- Официальный Markdown-список цитат: QQBot (в официальном md нет синтаксиса свёртывания, серверная валидация отклоняет недопустимые теги 40034011)
- Не реализуется (деградация — вывод node-сегментов как есть): OneBot12 (в стандарте нет node-сегментов), WeCom, Terminal, Webhook, WechatMp
Пример обнаружения на стороне вызывающего:
sends = adapter.list_sends(platform)
if "MergeForward" in sends:
await adapter.Send.To("group", "123").MergeForward(nodes)
else:
await adapter.Send.To("group", "123").Text(plain_text)
Референсная реализация:
ErisPulse-OneBot11Adapter(специализированный эндпоинт → откат кsend_msg); шаблоны рендеринга и список задач по каждому адаптеру см.SDK/Adapter/ADAPTER_FORWARD_GUIDE.md.
3. Именование платформенно-специфичных методов
НЕ рекомендуется добавлять в класс Send методы с префиксом платформы напрямую. Рекомендуется использовать общие имена методов или методы вида Raw_{протокол}.
Не рекомендуется:
def YunhuForm(self, form_id: str): # ❌ не рекомендуется
pass
def TelegramSticker(self, sticker_id: str): # ❌ не рекомендуется
pass
Рекомендуется:
def Form(self, form_id: str): # ✅ общее имя метода
pass
def Sticker(self, sticker_id: str): # ✅ общее имя метода
pass
def Raw_ob12(self, message): # ✅ отправка в формате OneBot12
pass
Требования к расширенным методам:
- Имя метода в PascalCase, без префикса платформы
- Должен возвращать объект
asyncio.Task - Должны быть полные аннотации типов и docstring
- Дизайн параметров должен максимально соответствовать стилю стандартных методов
4. Соглашения об именовании параметров
| Имя параметра | Описание | Тип |
|---|---|---|
text |
Текстовое содержимое | str |
file |
Медиа-контент (URL / путь / бинарные данные, см. §2.1.1) | str / bytes |
filename |
Имя файла (опционально для File, см. §2.1.3) |
str / None |
user_id |
ID пользователя | str / int |
group_id |
ID группы | str / int |
message_id |
ID сообщения | str |
data |
Объект данных (например, данные карточки) | dict |
5. Спецификация возвращаемых значений
- Методы отправки (например,
Text,Image): должны возвращать объектasyncio.Task - Методы-модификаторы (например,
At,Reply,AtAll): должны возвращатьselfдля поддержки цепных вызовов
6. Спецификация обратного преобразования (OneBot12 → платформа)
Адаптер должен не только преобразовывать нативные события платформы в формат OneBot12 (прямое преобразование), но и ОБЯЗАН предоставлять возможность преобразования сегментов сообщений OneBot12 обратно в вызовы нативного API платформы (обратное преобразование). Единая точка входа для обратного преобразования — метод Raw_ob12.
6.1 Модель преобразования
Прямое преобразование (направление приёма) Обратное преобразование (направление отправки)
───────────────── ─────────────────
Нативное событие платформы Список сегментов сообщений OneBot12
│ │
▼ ▼
Converter.convert() Send.Raw_ob12()
│ │
▼ ▼
Стандартное событие OneBot12 Вызов нативного API платформы
(включая {platform}_raw) (возвращает стандартный формат ответа)
Ключевая симметрия: прямое преобразование сохраняет исходные данные в {platform}_raw; обратное преобразование принимает стандартный формат OneBot12 и восстанавливает его в вызов платформы.
6.2 Спецификация реализации Raw_ob12
Raw_ob12 принимает стандартный список сегментов сообщений OneBot12 и должен преобразовать его в вызовы нативного API платформы.
Сигнатура метода:
def Raw_ob12(self, message_segments: List[Dict]) -> asyncio.Task:
"""
Отправка стандартных сегментов сообщений OneBot12
:param message_segments: список сегментов сообщений OneBot12
[
{"type": "text", "data": {"text": "Hello"}},
{"type": "image", "data": {"file": "https://..."}},
{"type": "mention", "data": {"user_id": "123"}},
]
:return: asyncio.Task, после await возвращает стандартный формат ответа
"""
Требования к реализации:
- Должны обрабатываться все стандартные типы сегментов сообщений: как минимум поддерживаться
text,image,audio,video,file,mention,reply - Должны обрабатываться расширенные сегменты платформы: сегменты типа
{platform}_xxxпреобразовывать в соответствующие нативные вызовы платформы - Должен возвращаться стандартный формат ответа: следовать стандарту API-ответов
- Неподдерживаемые сегменты следует пропускать с записью предупреждения; не выбрасывать исключения, приводящие к сбою отправки всего сообщения
6.3 Правила преобразования сегментов сообщений
6.3.1 Преобразование стандартных сегментов
Адаптер обязан реализовать преобразование следующих стандартных сегментов:
| Сегмент OneBot12 | Требования к преобразованию |
|---|---|
text |
Использовать data.text напрямую |
image |
data.file обрабатывать по медиапротоколу §2.1 (три обязательные формы + порядок определения) |
audio |
Логика обработки как у image |
video |
Логика обработки как у image |
file |
Логика обработки как у image; имя файла обрабатывается по порядку вывода §2.1.3 через data.filename |
mention |
Преобразовать в механизм упоминаний платформы (например, entities Telegram, at_uid Yunhu) |
reply |
Преобразовать в механизм цитирования ответов платформы |
face |
Преобразовать в механизм отправки эмодзи платформы; если не поддерживается — пропустить |
location |
Преобразовать в механизм отправки местоположения платформы; если не поддерживается — пропустить |
6.3.2 Преобразование расширенных сегментов платформы
Для сегментов с префиксом платформы адаптер должен распознавать и преобразовывать их:
def _convert_ob12_segments(self, segments: List[Dict]) -> Any:
"""Преобразование сегментов OneBot12 в нативный формат платформы"""
platform_prefix = f"{self._platform_name}_"
for segment in segments:
seg_type = segment["type"]
seg_data = segment["data"]
if seg_type.startswith(platform_prefix):
# Расширенный сегмент платформы → нативный вызов платформы
self._handle_platform_segment(seg_type, seg_data)
elif seg_type in self._standard_segment_handlers:
# Стандартный сегмент → эквивалентная операция платформы
self._standard_segment_handlers[seg_type](seg_data)
else:
# Неизвестный сегмент → записать предупреждение и пропустить
logger.warning(f"Неподдерживаемый тип сегмента сообщения: {seg_type}")
6.3.3 Обработка составных сегментов сообщений
Одно сообщение может содержать несколько сегментов; адаптер должен корректно обрабатывать составные сообщения:
# Модуль отправляет сообщение, содержащее текст + изображение + упоминание пользователя
await send.Raw_ob12([
{"type": "mention", "data": {"user_id": "123"}},
{"type": "text", "data": {"text": "Привет"}},
{"type": "image", "data": {"file": "https://example.com/img.jpg"}}
])
Стратегии обработки:
- Приоритет объединению: если платформа поддерживает текст, изображения, упоминания и т.д. в одном сообщении, следует отправлять объединённо
- В противном случае — разделение: если платформа не поддерживает объединение, разделить по порядку на несколько сообщений
- Сохранение порядка: порядок отправки сегментов должен соответствовать порядку списка
6.4 Связь Raw_ob12 со стандартными методами
Стандартные методы отправки адаптера (Text, Image и т.д.) уже встроены в базовый класс SendDSL и по умолчанию делегируют Raw_ob12; подклассу адаптера не нужно реализовывать их повторно:
class Send(SendDSL):
def Raw_ob12(self, message_segments: List[Dict]) -> asyncio.Task:
"""Ключевая реализация: сегменты OneBot12 → API платформы (обязательно к реализации)"""
return asyncio.create_task(self._send_ob12(message_segments))
# Text/Image/Voice/Video/File/Location унаследованы от базового класса и автоматически делегируют Raw_ob12
# При необходимости платформенной логики можно переопределить отдельный метод:
# def Text(self, text: str) -> asyncio.Task:
# return self.Raw_ob12([{"type": "text", "data": {"text": text}}])
Преимущества:
- Логика преобразования сосредоточена в одном месте —
Raw_ob12, что сокращает дублирование кода - Поведение стандартных методов и
Raw_ob12полностью совпадает - Модуль получает одинаковый результат независимо от использования
Text()илиRaw_ob12() - Базовый класс предоставляет сигнатуры типов; IDE может дополнять стандартные методы
6.5 Пример реализации
class YunhuSend(SendDSL):
"""Реализация Send платформы Yunhu"""
def Raw_ob12(self, message_segments: list) -> asyncio.Task:
"""Сегменты OneBot12 → вызовы API Yunhu"""
return asyncio.create_task(self._do_send(message_segments))
async def _do_send(self, segments: list) -> dict:
"""Фактическая логика отправки"""
# 1. Парсинг состояния модификаторов
at_users = self._at_users or []
reply_to = self._reply_to
at_all = self._at_all
# 2. Преобразование сегментов
yunhu_elements = []
for seg in segments:
seg_type = seg["type"]
seg_data = seg["data"]
if seg_type == "text":
yunhu_elements.append({"type": "text", "content": seg_data["text"]})
elif seg_type == "image":
yunhu_elements.append({"type": "image", "url": seg_data["file"]})
elif seg_type == "mention":
at_users.append(seg_data["user_id"])
elif seg_type == "reply":
reply_to = seg_data["message_id"]
elif seg_type == "yunhu_form":
# Расширенный сегмент платформы
yunhu_elements.append({"type": "form", "form_id": seg_data["form_id"]})
else:
logger.warning(f"Сегмент, не поддерживаемый Yunhu: {seg_type}")
# 3. Вызов API Yunhu
response = await self._call_yunhu_api(yunhu_elements, at_users, reply_to, at_all)
# 4. Возврат стандартного формата ответа
return {
"status": "ok" if response["code"] == 0 else "failed",
"retcode": response["code"],
"data": {"message_id": response.get("msg_id", ""), "time": int(time.time())},
"message_id": response.get("msg_id", ""),
"message": "",
"yunhu_raw": response
}
7. Обнаружение методов
Разработчики модулей могут через API запрашивать методы отправки, поддерживаемые адаптером (НЕ следует хардкодить список методов конкретной платформы в модуле — расширенные методы каждого адаптера эволюционируют с версиями; ориентируйтесь на обнаружение во время выполнения):
from ErisPulse import adapter
# Список всех методов отправки
methods = adapter.list_sends("myplatform")
# ["Batch", "Form", "Image", "Recall", "Sticker", "Text", ...]
# Просмотр деталей метода
info = adapter.send_info("myplatform", "Form")
# {
# "name": "Form",
# "parameters": [{"name": "form_id", "type": "str", ...}],
# "return_type": "Awaitable[Any]",
# "docstring": "Отправка формы Yunhu"
# }
9. Примечания по разработке адаптера
О том, как правильно переопределять __init__ в BaseAdapter, Send, Request, см. Начало разработки адаптеров - примечания по __init__.
10. Чек-лист реализации адаптера
Методы отправки
- Стандартные методы (
Text,Imageи т.д.) реализованы - Все возвращаемые значения —
asyncio.Task - Методы-модификаторы (
At,Reply,AtAll) возвращаютself - Расширенные методы платформы используют PascalCase, без префикса платформы
- Все методы имеют полные аннотации типов и docstring
Протокол отправки медиа
- Параметр
fileподдерживает все обязательные формы: HTTP(S) URL / локальный путь /bytes(см. §2.1.1) - Порядок определения формы соответствует §2.1.2 (bytes → URL →
file://→ путь) - Порядок вывода имени файла
Fileсоответствует §2.1.3 (явныйfilename> basename URL > basename пути > платформа по умолчанию) - Ограничения платформы по медиа (размер / MIME / длительность) задекларированы в документации адаптера (§2.1.4)
- Неподдерживаемые типы медиа обрабатываются по лестнице деградации §2.1.5: деградация к близкому типу или возврат
retcode=10002, без исключений, без молчаливого отбрасывания
Объединённая пересылка (опционально, см. §2.4)
- Если платформа имеет нативную объединённую пересылку,
MergeForwardиспользует специализированный эндпоинт протокола, при сбое — откат кsend_msg(серия OneBot11) - Если платформа не имеет нативной пересылки, но поддерживает rich text,
MergeForwardотображается в свёрнутой форме платформы (HTML-карточка / Card / Embed / blockquote) - Если нет ни того, ни другого,
MergeForwardне реализуется; не возвращать успех, отправив node-словари как простой текст - Внутри
MergeForwardне вызывать сноваRaw_ob12для пересылки тех же nodes
Обратное преобразование
-
Raw_ob12реализован (обязательно, пропускать нельзя) -
Raw_ob12обрабатывает все стандартные сегменты (text,image,audio,video,file,mention,reply) -
Raw_ob12обрабатывает расширенные сегменты платформы (тип{platform}_xxx) - Стандартные методы отправки (
Text,Imageи т.д.) внутри делегируютRaw_ob12, а не реализуют логику преобразования независимо - Неподдерживаемые сегменты пропускаются с записью предупреждения, без выбрасывания исключений
- Составные сегменты обрабатываются корректно (объединение или разделение по порядку)
11. Конструктор сообщений (MessageBuilder) — что нужно знать на стороне адаптера
MessageBuilder — предоставляемый ErisPulse инструмент построения сегментов сообщений OneBot12 для стороны модулей:
цепные вызовы (или статическое быстрое построение) в итоге создают стандартный список сегментов [{"type": ..., "data": ...}],
который вызывающий передаёт напрямую в Raw_ob12.
На стороне адаптера достаточно знать одно: то, что получает Raw_ob12, — это и есть этот продукт — полностью изоморфный рукописному списку сегментов сообщений; достаточно обработать его по логике распределения сегментов из §6.2, не нужно определять, поступил ли он из MessageBuilder или был записан как литерал.
Полное использование (механизм двух режимов, все методы сегментов, утилитарные методы
copy()/clear()и примеры) см. в Подробно о MessageBuilder; в этой статье повторяться не будем.
12. Связанные документы
Сопутствующий справочник при реализации возвращаемых значений отправки:
- Стандарт API-ответов - стандарт формата API-ответов адаптера
Другие стороны того же адаптера:
- Стандарт преобразования событий - полная спецификация преобразования событий, именование расширений и стандарт сегментов сообщений
- Стандарт типов сессий - определения типов сессий и соответствия
- Спецификация операций запроса - требования к полям событий запроса, Request DSL (approve/reject) и требования к реализации адаптера