Документация по функциям платформы 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 использует асинхронную неблокирующую архитектуру:
- Отправка сообщений не блокирует цикл обработки событий
- Множественные операции отправки могут выполняться одновременно
- Ответы API обрабатываются своевременно
- Соединение WebSocket остается активным
- Параллельная обработка нескольких аккаунтов, каждый аккаунт работает независимо
Обработка ошибок
Адаптер предоставляет полный механизм обработки ошибок:
- Автоматическое переподключение при сбоях сетевого соединения (поддерживается независимое переподключение для каждой учётной записи с интервалом 30 секунд)
- Обработка таймаутов при вызовах API (фиксированный таймаут 30 секунд; при превышении возвращается стандартный ответ об ошибке
retcode=33001) - Если учётная запись не подключена или соединение закрыто,
call_apiвозвращает стандартный ответ об ошибкеretcode=33001вместо выбрасывания исключенияConnectionError - Вызовы неподдерживаемых методов возвращают понятное текстовое сообщение
Расширенная обработка событий
В режиме нескольких учетных записей все события автоматически сопровождаются информацией об учетной записи:
{
"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: Получение информации о группе
Рекомендуемые практики
- Управление конфигурацией: Рекомендуется использовать конфигурации с несколькими аккаунтами для разделения роботов с различным назначением
- Обработка ошибок: Всегда проверяйте статус возвращаемых API-вызовов
- Отправка сообщений: Используйте подходящие типы сообщений, избегайте отправки не поддерживаемых сообщений
- Мониторинг подключения: Регулярно проверяйте состояние подключения, обеспечивая доступность сервиса
- Оптимизация производительности: При массовой отправке используйте метод Batch для уменьшения сетевых накладных расходов
- Вызовы методов: Рекомендуется использовать стандартное название с большой буквы (например,
.Text()), но также поддерживается нижний регистр для обеспечения совместимости с различными стилями программирования (такой способ может быть несовместим со старыми версиями)