ErisPulse ErisPulse
Открыть интерактивную версию →
Разделы страницы
0. Соглашения о ключевых словах 1. Стандартное именование методов 1.1 Стандартные методы отправки 1.2 Цепные методы-модификаторы 1.3 Протокольные методы 1.4 Рекомендуемые соглашения об именовании расширений 2. Подробная спецификация параметров 2.1 Протокол отправки мультимедийных сообщений (Image / Voice / Video / File) 2.2 Спецификация параметра @пользователя 2.3 Спецификация параметра ответа на сообщение 2.4 Возможность объединённой пересылки (MergeForward, опционально) 3. Именование платформенно-специфичных методов 4. Соглашения об именовании параметров 5. Спецификация возвращаемых значений 6. Спецификация обратного преобразования (OneBot12 → платформа) 6.1 Модель преобразования 6.2 Спецификация реализации Raw_ob12 6.3 Правила преобразования сегментов сообщений 6.4 Связь Raw_ob12 со стандартными методами 6.5 Пример реализации 7. Обнаружение методов 9. Примечания по разработке адаптера 10. Чек-лист реализации адаптера Методы отправки Протокол отправки медиа Объединённая пересылка (опционально, см. §2.4) Обратное преобразование 11. Конструктор сообщений (MessageBuilder) — что нужно знать на стороне адаптера 12. Связанные документы
Статическое зеркало — интерактивная версия является основной Открыть интерактивную версию →

Спецификация методов отправки 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 Порядок определения формы

При реализации обработки медиапараметров адаптер СЛЕДУЕТ определять форму в следующем порядке:

  1. Тип bytes → прямая загрузка
  2. Строка начинается с http:// / https:// → обрабатывать как URL (прямая ссылка либо скачивание и загрузка, в зависимости от возможностей платформы)
  3. Строка начинается с file:// → отбросить префикс и обрабатывать как локальный путь
  4. Остальные строки → обрабатывать как локальный путь (если существует — прочитать и загрузить; если нет — вернуть стандартный формат ответа с ошибкой)
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 не задан явно):

  1. Явный параметр filename (наивысший приоритет)
  2. basename URL (например, https://host/a/b/report.pdf → report.pdf, необходимо отбросить query string)
  3. basename локального пути (например, /tmp/data/backup.zip → backup.zip)
  4. Генерация по умолчанию платформы (например, 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 возвращает стандартный формат ответа
    """

Требования к реализации:

  1. Платформа имеет нативную объединённую пересылку (серия OneBot11): ОБЯЗАТЕЛЬНО вызывать специализированные эндпоинты протокола (send_group_forward_msg / send_private_forward_msg) — реализации вроде NapCat отклоняют node-сегменты, переданные через send_msg (retcode 1400); при сбое специализированного эндпоинта МОЖНО откатиться к прямой отправке node-сегментов через send_msg
  2. Платформа не имеет нативной пересылки, но поддерживает rich text (Yunhu / Telegram / Kook / Discord / Matrix и др.): СЛЕДУЕТ отобразить узлы в свёрнутой rich-text-форме платформы (свёрнутая HTML-карточка / Card / Embed / список blockquote); справочные стили и список задач по каждому адаптеру см. в SDK/Adapter/ADAPTER_FORWARD_GUIDE.md
  3. Нет ни того, ни другого: ЗАПРЕЩЕНО реализовывать этот метод (тем более возвращать успех, отправив node-словари как простой текст) — когда метод не реализован, list_sends не содержит MergeForward, и вызывающий автоматически откатывается к обычному тексту
  4. Семантика отказа: допустимо вернуть стандартный формат ответа с ошибкой (status: "failed") или выбросить исключение; вызывающий откатится к простой отправке текста, контент не теряется
  5. ЗАПРЕЩЕНО внутри MergeForward снова вызывать Raw_ob12 для отправки тех же nodes (в Raw_ob12 OneBot11 уже встроена автоматическая маршрутизация чистых node-сегментов, возникнет цикл)
  6. Парсинг исходящих 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 возвращает стандартный формат ответа
    """

Требования к реализации:

  1. Должны обрабатываться все стандартные типы сегментов сообщений: как минимум поддерживаться text, image, audio, video, file, mention, reply
  2. Должны обрабатываться расширенные сегменты платформы: сегменты типа {platform}_xxx преобразовывать в соответствующие нативные вызовы платформы
  3. Должен возвращаться стандартный формат ответа: следовать стандарту API-ответов
  4. Неподдерживаемые сегменты следует пропускать с записью предупреждения; не выбрасывать исключения, приводящие к сбою отправки всего сообщения

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. Связанные документы

Сопутствующий справочник при реализации возвращаемых значений отправки:

Другие стороны того же адаптера: