ErisPulse ErisPulse
Открыть интерактивную версию →
Разделы страницы
Информация о документе Основная информация Обновление парадигмы v5 (4.3.0) Соответствие стандартизации События запросов и Request DSL Обработка ошибок call_api Двойная совместимость полей аккаунта и send_context Инъекция полей событий Спецификация кодов ошибок Стандартные действия API (DSL API) Операции с запросами (Request DSL) Удобные методы Event Ручное вызов Request DSL Поддерживаемые типы отправки сообщений Вызов без учёта регистра Вызов неподдерживаемых методов Базовые типы сообщений Цепочные модифицирующие методы (возвращают self, поддерживают цепочные вызовы) Отправка исходных (raw) сообщений Другие типы сообщений Функции управления События стандарта OneBot12 Новая функция: поле исходного типа события События сообщений (Message Events) События уведомлений (Notice Events) События запросов (Request Events) Мета-события (Meta Events) Параметры конфигурации Конфигурация аккаунтов Пример конфигурации Конфигурация по умолчанию Возвращаемые значения методов отправки Методы отправки сообщений Методы цепочечного изменения Стандарт ответа API Спецификация кодов ошибок Синтаксис отправки с несколькими аккаунтами Асинхронная обработка Обработка ошибок Расширенная обработка событий Управление интерфейсом Стандартные возможности OneBot12 Стандартный формат сообщений Стандартные API Рекомендуемые практики
Статическое зеркало — интерактивная версия является основной Открыть интерактивную версию →

Документация по функциям платформы OneBot12

OneBot12Adapter — это адаптер, построенный на основе протокола OneBot V12, выступающий в качестве базового протокольного адаптера для фреймворка ErisPulse.


Информация о документе

  • Версия соответствующего модуля: 4.6.2
  • Сопровождающий: ErisPulse
  • Версия протокола: OneBot V12
  • Последнее обновление: 2026-11-10

Основная информация

  • Краткое описание платформы: OneBot V12 — это универсальный стандарт интерфейса приложений для чат-ботов, базовый протокол для фреймворка ErisPulse.
  • Название адаптера: OneBot12Adapter
  • Поддерживаемые версии протокола/API: OneBot V12
  • Поддержка нескольких аккаунтов: Полностью архитектура с поддержкой нескольких аккаунтов, позволяет одновременно настроить и запустить несколько OneBot12-аккаунтов.

Обновление парадигмы v5 (4.3.0)

Данный адаптер завершил выравнивание с парадигмой v5 (инкрементальное обновление, API совместим):

  • Наследование BaseConverter: общие поля конвертера (id/time/platform/self/raw) формируются фреймворком через build_base_event и переопределяются по именам полей OB11 (echo/time/self_id)
  • Привязка задач spawn_background: задачи подключения в режиме Client теперь используют Runtime.spawn_background (привязка через owner, автоматическое освобождение при shutdown)
  • Мягкая зависимость от фреймворка: установка адаптера больше не объявляет жёсткую зависимость от ErisPulse, что позволяет избежать изменения версии фреймворка при разрешении зависимостей pip; во время выполнения проверяется ErisPulse>=2.7.1, и при слишком низкой версии выводится предупреждение в журнал
  • Журналирование версии при запуске: при инициализации выводится сообщение о загрузке OneBot12Adapter vX.Y.Z

Уже имеющиеся возможности (поддерживаются с версии 4.2.0): мультиаккаунтность, отображение стандартных действий Api DSL (get_self_info→get_login_info и т.д.), Request DSL (одобрение запросов друзей/групп: event.approve() / event.reject()), EventMixin, i18n.

Соответствие стандартизации

В этом разделе описывается поведение адаптера с точки зрения соответствия стандартам ErisPulse. Подробности спецификаций см. в документации SDK: «Спецификация действий запросов» (docs/ru/standards/request-action-spec.md) и «Спецификация ответов API» (docs/ru/standards/api-response.md).

События запросов и Request DSL

  • Гарантия request_id: при пробрасывании событий запросов гарантируется поле верхнего уровня request_id (приоритет у нативного request_id; реализация в стиле OB11 в качестве отката использует маппинг поля flag; если оба отсутствуют, поле не синтезируется) — для использования в Request DSL
  • Откат к аккаунту по умолчанию: если DSL Request (основанный на действии handle_quick_request) не указывает аккаунт явно через Using(), используется аккаунт-источник события запроса (request_context), что обеспечивает корректную маршрутизацию event.approve()/event.reject() внутри цепочки событий

Обработка ошибок call_api

  • Когда аккаунт не подключён или соединение закрыто, call_api больше не выбрасывает ConnectionError, а возвращает стандартный ответ о неудаче (status="failed", retcode=33001)
  • При таймауте вызова API также возвращается стандартный ответ о неудаче (retcode=33001)

Двойная совместимость полей аккаунта и send_context

  • call_api принимает как стандартное поле account_id, так и старое имя поля _account_id (приоритет у стандартного имени); ApiDSL фреймворка адаптируется автоматически, в коде модулей рекомендуется использовать account_id
  • Все методы Send/Recall/Edit/Batch читают send_context: внутри цепочки событий автоматически используется аккаунт-источник текущего события, при этом приоритет у аккаунта, явно указанного через Using()

Инъекция полей событий

  • Во все события инъектируется self.account_id (имя аккаунта-источника); в режиме нескольких аккаунтов события могут быть корректно перенаправлены обратно на аккаунт-источник
  • Все события обязательно содержат поле onebot12_raw_type (исходный тип события, соответствует спецификации преобразования событий)
  • Сегмент сообщений с эмодзи-стикерами называется onebot12_sticker (метод .Sticker() отправляет этот сегмент внутри)

Спецификация кодов ошибок

retcode Значение Сценарий возникновения
0 Успех Действие выполнено успешно
33001 Сетевая ошибка Аккаунт не подключён, соединение закрыто, таймаут вызова API
10002 Неподдерживаемое действие Запрос действия, не поддерживаемого бэкендом
10003 Ошибка параметров Отсутствуют обязательные параметры

Исходные данные ответа, возвращённые бэкендом, сохраняются в поле onebot12_raw.


Стандартные действия API (DSL API)

OneBot12 поддерживает все стандартные имена действий OB12, API DSL по умолчанию напрямую делегирует call_api (без отображения):

from ErisPulse import sdk
ob12 = sdk.adapter.get("onebot12")

result = await ob12.Api.get_self_info()
result = await ob12.Api.get_friend_list()
await ob12.Api.delete_message(message_id="MSG_ID")

# Указание аккаунта (множественные аккаунты)
result = await ob12.Api.Using("main").get_self_info()

# Расширения платформы
result = await ob12.Api.call("extend_action", param=1)

Поддерживаемые действия определяются реализацией бэкенда (NapCat/Lagrange/LLOneBot и др.); действия, которые не поддерживаются бэкендом, возвращают ошибку и прозрачно передаются.

Операции с запросами (Request DSL)

На основе стандарта OneBot12, действие handle_quick_request обрабатывает запросы от друзей и приглашения в группы, позволяя принять или отклонить их:

Удобные методы Event

from ErisPulse.Core.Event import request

@request.on_friend_request()
async def handle_friend_request(event):
    if event.get("platform") != "onebot12":
        return
    comment = event.get("comment", "")
    if comment == "passphrase":
        await event.approve()      # Принять
    else:
        await event.reject()       # Отклонить

Ручное вызов Request DSL

await ob12.Request("request_flag").accept()
await ob12.Request("request_flag").reject()
await ob12.Request("request_flag").Using("main").accept()

Поддерживаемые типы отправки сообщений

Все методы отправки реализованы через цепочный синтаксис, например:

from ErisPulse.Core import adapter
onebot12 = adapter.get("onebot12")

# Отправка с использованием аккаунта по умолчанию
await onebot12.Send.To("group", group_id).Text("Hello World!")

# Отправка с указанием конкретного аккаунта
await onebot12.Send.To("group", group_id).Account("main").Text("Сообщение от основного аккаунта")

Вызов без учёта регистра

Все методы отправки и цепочные модифицирующие методы поддерживают вызов без учёта регистра, адаптер автоматически сопоставит их с правильными стандартными именами методов:

# Все следующие варианты вызова эквивалентны
await onebot12.Send.To("user", 123).Text("hello")
await onebot12.Send.To("user", 123).text("hello")
await onebot12.Send.To("user", 123).TEXT("hello")

# Цепочные модифицирующие методы также поддерживаются
await onebot12.Send.To("group", 123).At(456).Text("hello")
await onebot12.Send.To("group", 123).at(456).TEXT("hello")
await onebot12.Send.To("group", 123).AT(456).text("hello")

Вызов неподдерживаемых методов

При вызове несуществующего метода адаптер вернёт дружелюбное текстовое сообщение вместо выбрасывания исключения:

# Вызов неподдерживаемого метода
result = await onebot12.Send.To("user", 123).UnsupportedMethod("test")

# Возвращаемый результат — отправленное текстовое сообщение
# Содержимое сообщения: [Неподдерживаемый тип отправки] Имя метода: UnsupportedMethod, Параметры: [args[0]: 'test']

Базовые типы сообщений

  • .Text(text: str): отправка простого текстового сообщения
  • .Image(file: Union[str, bytes], filename: str = "image.png"): отправка изображения (поддерживаются URL, Base64 или bytes)
  • .Audio(file: Union[str, bytes], filename: str = "audio.ogg"): отправка аудиосообщения
  • .Voice(file: Union[str, bytes], filename: str = "voice.ogg"): отправка голосового сообщения (псевдоним Audio, совместимо с OneBot11)
  • .Video(file: Union[str, bytes], filename: str = "video.mp4"): отправка видеосообщения

Цепочные модифицирующие методы (возвращают self, поддерживают цепочные вызовы)

  • .At(user_id: Union[str, int]): упоминание пользователя (можно вызывать несколько раз)
  • .AtAll(): упоминание всех участников
  • .Reply(message_id: Union[str, int]): ответ на сообщение

Отправка исходных (raw) сообщений

  • .Raw_ob12(message: Union[Dict, List[Dict]], **kwargs): отправка сообщения в исходном формате OneBot12 (соответствует соглашениям об именовании)

Другие типы сообщений

  • .Sticker(file_id: str): отправка эмодзи/стикера (сегмент сообщения onebot12_sticker)
  • .Location(latitude: float, longitude: float, title: str = "", content: str = ""): отправка местоположения

Функции управления

  • .Recall(message_id: Union[str, int]): отзыв сообщения
  • .Edit(message_id: Union[str, int], content: Union[str, List[Dict]]): редактирование сообщения
  • .Raw(message_segments: List[Dict]): отправка нативных сегментов сообщений OneBot12
  • .Batch(target_ids: List[str], message: Union[str, List[Dict]], target_type: str = "user"): массовая отправка сообщений

События стандарта OneBot12

Адаптер OneBot12 полностью соответствует стандарту OneBot12, формат событий не требует преобразования и передаётся в фреймворк напрямую.

Новая функция: поле исходного типа события

В соответствии со спецификацией standards/event-conversion.md все события сохраняют поле исходного типа события onebot12_raw_type:

{
    "id": "event-id",
    "type": "message",              # тип события
    "onebot12_raw_type": "message", # исходный тип события (совпадает с type)
    "detail_type": "private",
    "self": {"user_id": "bot-id"},
    "user_id": "user-id",
    "message": [{"type": "text", "data": {"text": "Hello"}}],
    "alt_message": "Hello",
    "time": 1234567890
}

События сообщений (Message Events)

# Личное сообщение
{
    "id": "event-id",
    "type": "message",
    "onebot12_raw_type": "message",
    "detail_type": "private",
    "self": {"user_id": "bot-id"},
    "user_id": "user-id",
    "message": [{"type": "text", "data": {"text": "Hello"}}],
    "alt_message": "Hello",
    "time": 1234567890
}

# Групповое сообщение
{
    "id": "event-id",
    "type": "message",
    "onebot12_raw_type": "message",
    "detail_type": "group",
    "self": {"user_id": "bot-id"},
    "user_id": "user-id",
    "group_id": "group-id",
    "message": [{"type": "text", "data": {"text": "Hello group"}}],
    "alt_message": "Hello group",
    "time": 1234567890
}

События уведомлений (Notice Events)

# Добавление участника в группу
{
    "id": "event-id",
    "type": "notice",
    "onebot12_raw_type": "notice",
    "detail_type": "group_member_increase",
    "self": {"user_id": "bot-id"},
    "group_id": "group-id",
    "user_id": "user-id",
    "operator_id": "operator-id",
    "sub_type": "approve",
    "time": 1234567890
}

# Удаление участника из группы
{
    "id": "event-id",
    "type": "notice",
    "onebot12_raw_type": "notice",
    "detail_type": "group_member_decrease",
    "self": {"user_id": "bot-id"},
    "group_id": "group-id",
    "user_id": "user-id",
    "operator_id": "operator-id",
    "sub_type": "leave",
    "time": 1234567890
}

События запросов (Request Events)

# Запрос дружбы
{
    "id": "event-id",
    "type": "request",
    "onebot12_raw_type": "request",
    "detail_type": "friend",
    "self": {"user_id": "bot-id"},
    "user_id": "user-id",
    "comment": "Текст заявки",
    "request_id": "request-flag",
    "flag": "request-flag",
    "time": 1234567890
}

# Приглашение в группу
{
    "id": "event-id",
    "type": "request",
    "onebot12_raw_type": "request",
    "detail_type": "group",
    "self": {"user_id": "bot-id"},
    "group_id": "group-id",
    "user_id": "user-id",
    "comment": "Текст заявки",
    "request_id": "request-flag",
    "flag": "request-flag",
    "sub_type": "invite",
    "time": 1234567890
}

Мета-события (Meta Events)

# Событие жизненного цикла
{
    "id": "event-id",
    "type": "meta_event",
    "onebot12_raw_type": "meta_event",
    "detail_type": "lifecycle",
    "self": {"user_id": "bot-id"},
    "sub_type": "enable",
    "time": 1234567890
}

# Событие heartbeat
{
    "id": "event-id",
    "type": "meta_event",
    "onebot12_raw_type": "meta_event",
    "detail_type": "heartbeat",
    "self": {"user_id": "bot-id"},
    "interval": 5000,
    "status": {"online": true},
    "time": 1234567890
}

Параметры конфигурации

Конфигурация аккаунтов

Для каждого аккаунта можно настроить следующие параметры:

  • mode: Режим работы аккаунта ("server" или "client")
  • server_path: Путь WebSocket для режима "server"
  • server_token: Токен аутентификации для режима "server" (необязательно)
  • client_url: Адрес WebSocket для режима "client"
  • client_token: Токен аутентификации для режима "client" (необязательно)
  • enabled: Включён ли аккаунт
  • platform: Идентификатор платформы, по умолчанию "onebot12"
  • implementation: Идентификатор реализации, например "go-cqhttp" (необязательно)

Пример конфигурации

[OneBotv12_Adapter.accounts.main]
mode = "server"
server_path = "/onebot12-main"
server_token = "main_token"
enabled = true
platform = "onebot12"
implementation = "go-cqhttp"

[OneBotv12_Adapter.accounts.backup]
mode = "client"
client_url = "ws://127.0.0.1:3002"
client_token = "backup_token"
enabled = true
platform = "onebot12"
implementation = "shinonome"

[OneBotv12_Adapter.accounts.test]
mode = "client"
client_url = "ws://127.0.0.1:3003"
enabled = false

Конфигурация по умолчанию

Если не настроены никакие аккаунты, адаптер создаст следующую конфигурацию по умолчанию:

[OneBotv12_Adapter.accounts.default]
mode = "server"
server_path = "/onebot12"
enabled = true
platform = "onebot12"

Возвращаемые значения методов отправки

Методы отправки сообщений

Все методы отправки сообщений (например, .Text(), .Image(), .Raw_ob12() и т. д.) возвращают объект asyncio.Task, который можно непосредственно ожидать для получения результата отправки:

task = await onebot12.Send.To("group", 123456).Text("Hello")

Методы цепочечного изменения

Все методы цепочечного изменения (например, .At(), .AtAll(), .Reply()) возвращают self, что позволяет использовать цепочку вызовов:

# Комбинирование нескольких методов изменения
await onebot12.Send.To("group", 123456).Reply("msg123").At(789).At(790).Text("Текст")

Стандарт ответа API

Адаптер следует стандартизированному формату возврата ErisPulse (standards/api-response.md):

# Успешный ответ
{
    "status": "ok",              # Обязательно: статус выполнения
    "retcode": 0,                # Обязательно: код возврата (0 означает успех)
    "data": {                     # Обязательно: данные ответа
        "message_id": "123456",
        "time": 1632847927.599013
    },
    "message_id": "123456",       # Обязательно: ID сообщения (пустая строка, если отсутствует)
    "message": "",                # Обязательно: сообщение об ошибке (пусто при успехе)
    "echo": "1234",               # Необязательно: возвращается как есть из запроса echo
    "onebot12_raw": {...}        # Необязательно: исходные данные ответа
}

# Ответ об ошибке
{
    "status": "failed",           # Обязательно: статус выполнения
    "retcode": 10003,            # Обязательно: код возврата (ненулевой означает ошибку)
    "data": None,                # Обязательно: значение null при ошибке
    "message_id": "",            # Обязательно: пустая строка при ошибке
    "message": "Отсутствуют обязательные параметры",    # Обязательно: описание ошибки
    "echo": "1234",              # Необязательно: возвращается как есть из запроса echo
    "onebot12_raw": {...}        # Необязательно: исходные данные ответа
}

Спецификация кодов ошибок

Следует стандартным кодам ошибок OneBot12:

  • 0: Успех
  • 1xxxx: Ошибка запроса действия
  • 2xxxx: Ошибка обработчика действия
  • 3xxxx: Ошибка выполнения действия (33001 — тайм-аут сети)

Синтаксис отправки с несколькими аккаунтами

# Метод выбора аккаунта
await onebot12.Send.Using("main").To("group", 123456).Text("Сообщение от основного аккаунта")
await onebot12.Send.Using("backup").To("group", 123456).Image("http://example.com/image.jpg")

# Способ вызова API
await onebot12.call_api("send_message", account_id="main", 
    detail_type="group", group_id=123456, 
    content=[{"type": "text", "data": {"text": "Hello"}}])

Асинхронная обработка

Адаптер OneBot12 использует асинхронную неблокирующую архитектуру:

  1. Отправка сообщений не блокирует цикл обработки событий
  2. Множественные операции отправки могут выполняться одновременно
  3. Ответы API обрабатываются своевременно
  4. Соединение WebSocket остается активным
  5. Параллельная обработка нескольких аккаунтов, каждый аккаунт работает независимо

Обработка ошибок

Адаптер предоставляет полный механизм обработки ошибок:

  1. Автоматическое переподключение при сбоях сетевого соединения (поддерживается независимое переподключение для каждой учётной записи с интервалом 30 секунд)
  2. Обработка таймаутов при вызовах API (фиксированный таймаут 30 секунд; при превышении возвращается стандартный ответ об ошибке retcode=33001)
  3. Если учётная запись не подключена или соединение закрыто, call_api возвращает стандартный ответ об ошибке retcode=33001 вместо выбрасывания исключения ConnectionError
  4. Вызовы неподдерживаемых методов возвращают понятное текстовое сообщение

Расширенная обработка событий

В режиме нескольких учетных записей все события автоматически сопровождаются информацией об учетной записи:

{
    "type": "message",
    "onebot12_raw_type": "message",  // Исходный тип события
    "detail_type": "private",
    "self": {"user_id": "123456"},  // ID учетной записи, отправившей событие (стандартное поле)
    "platform": "onebot12",
    // ... другие поля события
}

Управление интерфейсом

# Получить информацию обо всех аккаунтах
accounts = onebot12.accounts

# Проверить статус подключения аккаунта
connection_status = {
    account_id: connection is not None and not connection.closed
    for account_id, connection in onebot12.connections.items()
}

# Динамически включить/отключить аккаунт (требуется перезапуск адаптера)
onebot12.accounts["test"].enabled = False

Стандартные возможности OneBot12

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

OneBot12 использует стандартизированный формат сообщений:

# Текстовое сообщение
{"type": "text", "data": {"text": "Привет"}}

# Изображение
{"type": "image", "data": {"file_id": "image-id"}}

# Упоминание
{"type": "mention", "data": {"user_id": "user-id", "user_name": "Username"}}

# Ответ на сообщение
{"type": "reply", "data": {"message_id": "msg-id"}}

Стандартные API

Соблюдение стандартных API OneBot12:

  • send_message: Отправка сообщения
  • delete_message: Отмена сообщения
  • edit_message: Редактирование сообщения
  • get_message: Получение сообщения
  • get_self_info: Получение информации о себе
  • get_user_info: Получение информации о пользователе
  • get_group_info: Получение информации о группе

Рекомендуемые практики

  1. Управление конфигурацией: Рекомендуется использовать конфигурации с несколькими аккаунтами для разделения роботов с различным назначением
  2. Обработка ошибок: Всегда проверяйте статус возвращаемых API-вызовов
  3. Отправка сообщений: Используйте подходящие типы сообщений, избегайте отправки не поддерживаемых сообщений
  4. Мониторинг подключения: Регулярно проверяйте состояние подключения, обеспечивая доступность сервиса
  5. Оптимизация производительности: При массовой отправке используйте метод Batch для уменьшения сетевых накладных расходов
  6. Вызовы методов: Рекомендуется использовать стандартное название с большой буквы (например, .Text()), но также поддерживается нижний регистр для обеспечения совместимости с различными стилями программирования (такой способ может быть несовместим со старыми версиями)