Документация по функциям платформы Kook
KookAdapter — это адаптер, построенный на основе WebSocket-протокола бота Kook (开黑啦), объединяющий все функциональные модули Kook и предоставляющий единый интерфейс для обработки событий и операций с сообщениями.
Информация о документе
- Версия соответствующего модуля: 4.3.2
- Сопровождающий: ShanFish
- Последнее обновление: 2026-11-10
Основная информация
- Описание платформы: Kook (ранее 开黑啦) — это платформа сообщества, поддерживающая текстовую, голосовую и видеосвязь, предоставляющая полный интерфейс разработки ботов.
- Название адаптера: KookAdapter
- Поддержка нескольких аккаунтов: Поддерживает одновременную настройку нескольких ботов Kook.
- Способ подключения: WebSocket-длинное соединение (через шлюз Kook).
- Способ аутентификации: Аутентификация на основе токена бота.
- Поддержка цепочки модификаторов: Поддерживает методы цепочки модификаторов, такие как
.Reply(),.At(),.AtAll(). - Совместимость с OneBot12: Поддерживает отправку сообщений в формате OneBot12.
Описание конфигурации
KookAdapter поддерживает настройку нескольких аккаунтов, каждый из которых соответствует отдельному боту Kook.
# config.toml
# Аккаунт 1
[KookAdapter.accounts.default]
token = "YOUR_BOT_TOKEN" # Токен бота Kook (обязательно, формат: Bot xxx/xxx)
bot_id = "" # ID пользователя бота (необязательно, если не указано, будет извлечен из токена)
compress = true # Включить сжатие WebSocket (необязательно, по умолчанию true)
enabled = true # Включить аккаунт (необязательно, по умолчанию true)
# Аккаунт 2
[KookAdapter.accounts.bot2]
token = "ANOTHER_BOT_TOKEN"
bot_id = ""
enabled = true
Совместимость со старой конфигурацией: Если обнаружена старая конфигурация
[KookAdapter](с token), она автоматически переносится вaccounts.default.
Описание параметров конфигурации (для каждого аккаунта):
token: Токен бота Kook (обязательно), получаемый на разработческой платформе Kook, формат:Bot xxx/xxxbot_id: ID пользователя бота (необязательно), если не указано, адаптер попытается автоматически извлечь его из токена. Рекомендуется вручную указывать для обеспечения точностиcompress: Включить сжатие данных WebSocket (необязательно, по умолчаниюtrue), при включении используется zlib для распаковки данныхenabled: Включить этот аккаунт (необязательно, по умолчанию true)
API-среда:
- Базовый адрес API Kook:
https://www.kookapp.cn/api/v3 - WebSocket-шлюз получается динамически через API:
POST /gateway/index
Выравнивание по стандартам (4.3.2)
События и аккаунты
- Инъекция
self.account_idв события: все события содержат имя аккаунта, который их породил; при работе с несколькими аккаунтамиevent.reply()автоматически отправляет сообщение через аккаунт, принявший данное событие
Выравнивание сигнатур API
| Действие | Сигнатура | Описание |
|---|---|---|
| get_channel_info | (guild_id, channel_id) |
Новая сигнатура с guild_id в качестве первого параметра; при передаче только одного позиционного параметра сохраняется совместимость со старой сигнатурой (параметр интерпретируется как channel_id) |
| get_channel_member_list | (guild_id, channel_id) |
Те же правила совместимости, что и выше |
| get_guild_info / get_guild_list | - | В data используются поля guild_id / guild_name и т.п. (старые поля group_* сохранены, чтобы не нарушать работу существующих вызывающих сторон) |
Стандартизация кодов ошибок
Коды ошибок стандартизированы согласно SDK; исходные коды ошибок платформы Kook (401xx/4xxxx и т.д.) больше не используются напрямую в качестве retcode:
| retcode | Описание |
|---|---|
| 0 | Успех (в успешном ответе поле message — пустая строка) |
| 33001 | Сетевая ошибка (исключение при запросе, неинициализированный экземпляр API аккаунта и т.п.) |
| 34100 | Ошибка платформы (Kook вернул code, отличный от 0; исходный ответ сохраняется в kook_raw, исходный code дополнительно сохраняется в поле kook_code) |
| 10002 | Неподдерживаемое действие (get_guild_member_info / get_guild_member_list / set_guild_name / leave_guild / leave_channel возвращают его явно; неизвестные endpoint'ы API больше не выбрасывают исключения, вместо этого всегда возвращается 10002) |
Обновление парадигмы v5 (4.1.0)
Данный адаптер завершил выравнивание с парадигмой v5 (инкрементальное обновление, совместимость API):
- Наследование BaseConverter: общие поля конвертера формируются фреймворком через
build_base_event - Api DSL: сопоставление стандартных Api-действий (см. ниже)
- Стандартная секция keyboard:
{"type": "keyboard", "data": {"rows": [[{"label", "type": "callback|link", "data"}]]}}— текст и клавиатура автоматически объединяются в карточное сообщение Kook (section + action-group); модификатор .Keyboard(rows) принимает универсальную структуру - Привязка задач spawn_background: задачи подключения переведены на runtime.spawn_background
- Мягкая зависимость от фреймворка: во время выполнения проверяется наличие ErisPulse>=2.7.1 с выводом предупреждения; при запуске выводится журнал версий
Стандартные Api-действия
from ErisPulse import sdk
kook = sdk.adapter.get("kook")
result = await kook.Api.get_self_info() # GET /users/@me
result = await kook.Api.get_user_info(user_id) # POST /user/view
result = await kook.Api.get_guild_info(guild_id) # POST /guild/view (в data используются guild_id / guild_name)
result = await kook.Api.get_guild_list() # POST /guild/list
result = await kook.Api.get_channel_info(guild_id, channel_id) # POST /channel/view (новая сигнатура: guild_id — первый параметр)
result = await kook.Api.get_channel_list(guild_id) # POST /channel/list
await kook.Api.delete_message(msg_id) # POST /message/delete
result = await kook.Api.Using("main").get_self_info()
Кнопки (keyboard)
rows = [[{"label": "Вариант A", "type": "callback", "data": "vote:A"},
{"label": "Сайт", "type": "link", "data": "https://example.com"}]]
await kook.Send.To("channel", channel_id).Keyboard(rows).Text("Выберите вариант")
# Текст и кнопки автоматически объединяются в карточное сообщение Kook (section + action-group)
# Обратный вызов при нажатии кнопки (стандартные поля)
from ErisPulse.Core.Event import notice
@notice.on_notice()
async def handle_button(event):
if event.get("platform") == "kook" and event.get("button_data"):
data = event["button_data"]
Поддерживаемые типы отправки сообщений
Все методы отправки сообщений реализованы через цепочечный синтаксис, например:
from ErisPulse.Core import adapter
kook = adapter.get("kook")
await kook.Send.To("group", channel_id).Text("Hello World!")
Поддерживаемые типы отправки включают:
.Text(text: str)— отправка обычного текстового сообщения..Image(file: bytes | str)— отправка изображения, поддержка путей к файлу, URL, двоичных данных..Video(file: bytes | str)— отправка видео, поддержка путей к файлу, URL, двоичных данных..File(file: bytes | str, filename: str = None)— отправка файла, поддержка путей к файлу, URL, двоичных данных..Voice(file: bytes | str)— отправка голосового сообщения, поддержка путей к файлу, URL, двоичных данных..Markdown(text: str)— отправка сообщения в формате KMarkdown..Card(card_data: dict)— отправка карточного сообщения (CardMessage)..MergeForward(nodes, title="Объединённая пересылка")— отправка объединённого пересланного сообщения (отображается как карточка: заголовок header + каждый элемент сообщения как section, KMD-перекодировка, ≤40 элементов)..Raw_ob12(message: List[Dict], **kwargs)— отправка сообщения в формате OneBot12.
Методы цепочки модификаторов (можно комбинировать)
Методы цепочки модификаторов возвращают self, поддерживают цепочечное использование, должны вызываться до окончательного метода отправки:
.Reply(message_id: str)— ответить (цитировать) на указанное сообщение..At(user_id: str)— упомянуть пользователя, можно вызывать несколько раз для упоминания нескольких пользователей..AtAll()— упомянуть всех.
Примеры цепочечного вызова
# Базовая отправка
await kook.Send.To("group", channel_id).Text("Hello")
# Ответ на сообщение
await kook.Send.To("group", channel_id).Reply(msg_id).Text("Ответ")
# Упоминание пользователя
await kook.Send.To("group", channel_id).At("user_id").Text("Привет")
# Упоминание нескольких пользователей
await kook.Send.To("group", channel_id).At("user1").At("user2").Text("Упоминание нескольких пользователей")
# Упоминание всех
await kook.Send.To("group", channel_id).AtAll().Text("Анонс")
# Комбинированное использование
await kook.Send.To("group", channel_id).Reply(msg_id).At("user_id").Text("Сложное сообщение")
Поддержка сообщений OneBot12
Адаптер поддерживает отправку сообщений в формате OneBot12, что обеспечивает совместимость между платформами:
# Отправка сообщения в формате OneBot12
ob12_msg = [{"type": "text", "data": {"text": "Hello"}}]
await kook.Send.To("group", channel_id).Raw_ob12(ob12_msg)
# В сочетании с цепочечными модификаторами
ob12_msg = [{"type": "text", "data": {"text": "Ответное сообщение"}}]
await kook.Send.To("group", channel_id).Reply(msg_id).Raw_ob12(ob12_msg)
# Использование сегментов упоминания и ответа в Raw_ob12
ob12_msg = [
{"type": "text", "data": {"text": "Hello "}},
{"type": "mention", "data": {"user_id": "user_id"}},
{"type": "reply", "data": {"message_id": "msg_id"}}
]
await kook.Send.To("group", channel_id).Raw_ob12(ob12_msg)
Дополнительные методы операций
Помимо отправки сообщений, адаптер Kook поддерживает следующие операции:
# Редактирование сообщения (поддерживается только для KMarkdown type=9 и CardMessage type=10)
await kook.Send.To("group", channel_id).Edit(msg_id, "**Обновлённое содержимое**")
# Отмена отправки сообщения
await kook.Send.To("group", channel_id).Recall(msg_id)
# Загрузка файла (получение URL файла)
result = await kook.Send.Upload("C:/path/to/file.jpg")
file_url = result["data"]["url"]
Возвращаемые значения методов отправки
Все методы отправки возвращают объект Task, результат отправки можно получить напрямую через await. Возвращаемый результат соответствует стандартизированной спецификации возврата адаптеров ErisPulse:
{
"status": "ok", // Статус выполнения: "ok" или "failed"
"retcode": 0, // Код возврата (0 — успех, ошибки платформы единообразно 34100)
"data": {...}, // Данные ответа
"message_id": "xxx", // ID сообщения
"message": "", // Сообщение об ошибке (при успешном ответе — пустая строка)
"kook_raw": {...}, // Исходные данные ответа
"kook_code": 0 // Исходный code Kook (сохраняется при ошибке)
}
Описание кодов ошибок
| retcode | Описание |
|---|---|
| 0 | Успех |
| 33001 | Сетевая ошибка (исключение при запросе, неинициализированный экземпляр API аккаунта и т.д.) |
| 34100 | Ошибка платформы (Kook вернул ненулевой code, исходный ответ сохраняется в kook_raw, исходный code сохраняется отдельно в kook_code) |
| 10002 | Неподдерживаемое действие (см. спецификацию кодов ошибок «Стандартизированное соответствие (4.3.2)») |
Специфические типы событий
Для использования функций этой платформы требуется проверка platform=="kook"
Ключевые отличия
- Система каналов: Kook использует двухуровневую структуру: серверы (Guild) и каналы (Channel); канал является основной целью отправки сообщений
- Типы сообщений: Kook поддерживает множество типов сообщений: текст (1), изображения (2), видео (3), файлы (4), голосовые сообщения (8), KMarkdown (9), карточные сообщения (10) и другие
- Система личных сообщений: Kook различает сообщения каналов и личные сообщения, используя разные API-эндпоинты
- Порядковые номера сообщений: WebSocket Kook использует порядковый номер
snдля гарантии упорядоченности сообщений, поддерживает временное хранение сообщений и переупорядочивание пришедших не по порядку - Редактирование и отзыв сообщений: поддерживается редактирование уже отправленных сообщений (только KMarkdown и CardMessage) и отзыв сообщений
Расширенные поля
- Все специфические поля обозначены префиксом
kook_ - Исходные данные сохраняются в поле
kook_raw kook_raw_typeуказывает номер исходного типа сообщения Kook (например,1— текст,255— событие уведомления)self.account_idсобытия — это имя аккаунта, породившего событие (при работе с несколькими аккаунтамиevent.reply()автоматически обрабатывается от имени этого аккаунта)
Примеры специальных полей
# Текстовое сообщение канала
{
"type": "message",
"detail_type": "group",
"user_id": "ID пользователя",
"group_id": "ID канала",
"channel_id": "ID канала",
"message_id": "ID сообщения",
"self": {
"platform": "kook",
"user_id": "BotID",
"account_id": "default"
},
"kook_raw": {...},
"kook_raw_type": "1",
"message": [
{"type": "text", "data": {"text": "Hello"}}
],
"alt_message": "Hello"
}
# Сообщение с изображением
{
"type": "message",
"detail_type": "group",
"user_id": "ID пользователя",
"group_id": "ID канала",
"channel_id": "ID канала",
"message_id": "ID сообщения",
"kook_raw": {...},
"kook_raw_type": "2",
"message": [
{"type": "image", "data": {"file": "URL изображения", "url": "URL изображения"}}
],
"alt_message": "Содержимое изображения"
}
# Сообщение KMarkdown
{
"type": "message",
"detail_type": "group",
"user_id": "ID пользователя",
"group_id": "ID канала",
"message_id": "ID сообщения",
"kook_raw": {...},
"kook_raw_type": "9",
"message": [
{"type": "text", "data": {"text": "Извлечённый простой текст"}}
]
}
# Карточное сообщение
{
"type": "message",
"detail_type": "group",
"user_id": "ID пользователя",
"group_id": "ID канала",
"message_id": "ID сообщения",
"kook_raw": {...},
"kook_raw_type": "10",
"message": [
{"type": "json", "data": {"data": "JSON-содержимое карточки"}}
]
}
# Личное сообщение
{
"type": "message",
"detail_type": "private",
"user_id": "ID пользователя",
"message_id": "ID сообщения",
"kook_raw": {...},
"kook_raw_type": "1",
"message": [
{"type": "text", "data": {"text": "Содержимое личного сообщения"}}
]
}
Типы сегментов сообщений
Типы сообщений Kook автоматически преобразуются в соответствующие сегменты сообщений по полю type:
| Kook type | Тип преобразования | Описание |
|---|---|---|
| 1 | text |
Текстовое сообщение |
| 2 | image |
Сообщение с изображением |
| 3 | video |
Видеосообщение |
| 4 | file |
Сообщение с файлом |
| 8 | record |
Голосовое сообщение |
| 9 | text |
Сообщение KMarkdown (извлечение простого текста) |
| 10 | json |
Карточное сообщение (исходный JSON) |
Пример структуры сегмента сообщения:
{
"type": "image",
"data": {
"file": "URL изображения",
"url": "URL изображения"
}
}
Сегмент сообщения Mention
Когда сообщение содержит упоминание (@), перед сегментами сообщения вставляется сегмент mention:
{
"type": "mention",
"data": {
"user_id": "ID упомянутого пользователя"
}
}
Сегмент mention_all
Когда сообщение содержит упоминание всех, вставляется сегмент mention_all:
{
"type": "mention_all",
"data": {}
}
WebSocket-соединение
Процесс подключения
- Используя токен бота, вызовите
POST /gateway/index, чтобы получить адрес WebSocket-шлюза - Подключитесь к WebSocket-шлюзу
- Получите сигнал HELLO (s=1), подтвердите состояние подключения
- Начните цикл отправки пинга (PING, s=2, каждые 30 секунд)
- Получите события сообщений (s=0), используя номер sn для обеспечения упорядоченности
- Получите ответ PONG (s=3) на пинг
Типы сигналов
| Сигнал | s-значение | Описание |
|---|---|---|
| HELLO | 1 | Сигнал приветствия от сервера, получается после успешного подключения |
| PING | 2 | Пинг от клиента, отправляется каждые 30 секунд, содержит текущий sn |
| PONG | 3 | Ответ на пинг |
| RESUME | 4 | Сигнал возобновления подключения, содержит sn для восстановления сессии |
| RECONNECT | 5 | Сигнал от сервера о необходимости переподключения, требуется заново получить шлюз |
| RESUME_ACK | 6 | Ответ на успешное возобновление |
Переподключение при разрыве соединения
- При неожиданном разрыве соединения адаптер автоматически пытается переподключиться
- Если ранее был
sn > 0, сначала будет попытка RESUME (s=4) для восстановления соединения - При неудаче RESUME, сбрасываются sn и очередь сообщений, и начинается полное новое подключение (процесс HELLO)
- При получении сигнала RECONNECT (s=5) состояние очищается и происходит переподключение
Механизм нумерации сообщений
WebSocket Kook использует sn (последовательный номер) для обеспечения упорядоченности сообщений:
- При получении каждого сообщения (s=0), sn увеличивается
- Если получено сообщение с несопоставимым sn, переходит в режим временного хранения
- Сообщения в буфере сортируются по sn, ожидая поступления недостающих сообщений, после чего обрабатываются в порядке
- После очистки буфера автоматически выходит из режима временного хранения
Примеры использования
Обработка сообщений канала
from ErisPulse.Core.Event import message
from ErisPulse import sdk
kook = sdk.adapter.get("kook")
@message.on_message()
async def handle_group_msg(event):
if event.get("platform") != "kook":
return
if event.get("detail_type") != "group":
return
text = event.get_text()
channel_id = event.get("group_id")
if text == "hello":
await kook.Send.To("group", channel_id).Text("Hello!")
Обработка личных сообщений
@message.on_message()
async def handle_private_msg(event):
if event.get("platform") != "kook":
return
if event.get("detail_type") != "private":
return
text = event.get_text()
user_id = event.get("user_id")
await kook.Send.To("user", user_id).Text(f"Вы сказали: {text}")
Обработка уведомлений (реакции и т.д.)
from ErisPulse.Core.Event import notice
@notice.on_notice()
async def handle_notice(event):
if event.get("platform") != "kook":
return
sub_type = event.get("sub_type")
if sub_type == "added_reaction":
emoji = event.get("emoji", {})
user_id = event.get("user_id")
msg_id = event.get("message_id")
print(f"Пользователь {user_id} добавил реакцию к сообщению {msg_id}")
elif sub_type == "deleted_reaction":
emoji = event.get("emoji", {})
user_id = event.get("user_id")
msg_id = event.get("message_id")
print(f"Пользователь {user_id} удалил реакцию с сообщения {msg_id}")
Отправка медиа-сообщений
# Отправка изображения (URL)
await kook.Send.To("group", channel_id).Image("https://example.com/image.png")
# Отправка изображения (байты)
with open("image.png", "rb") as f:
image_bytes = f.read()
await kook.Send.To("group", channel_id).Image(image_bytes)
# Отправка видео
await kook.Send.To("group", channel_id).Video("https://example.com/video.mp4")
# Отправка файла
await kook.Send.To("group", channel_id).File("https://example.com/file.pdf", filename="document.pdf")
# Отправка голосового сообщения
await kook.Send.To("group", channel_id).Voice("https://example.com/voice.mp3")
Отправка сообщений KMarkdown и карточных сообщений
# KMarkdown
await kook.Send.To("group", channel_id).Markdown("**Жирный** *курсив* [ссылка](https://example.com)")
# Карточное сообщение
card = {
"type": "card",
"theme": "primary",
"size": "lg",
"modules": [
{"type": "header", "text": {"type": "plain-text", "content": "Заголовок"}},
{"type": "section", "text": {"type": "kmarkdown", "content": "Содержимое"}}
]
}
await kook.Send.To("group", channel_id).Card(card)
Редактирование и отмена сообщений
# Отправка сообщения
result = await kook.Send.To("group", channel_id).Markdown("**Оригинальное содержимое**")
msg_id = result["data"]["msg_id"]
# Редактирование сообщения (поддерживается только для KMarkdown и CardMessage)
await kook.Send.To("group", channel_id).Edit(msg_id, "**Обновлённое содержимое**")
# Отмена сообщения
await kook.Send.To("group", channel_id).Recall(msg_id)
Обработка уведомлений о редактировании и удалении личных сообщений
@notice.on_notice()
async def handle_private_notice(event):
if event.get("platform") != "kook":
return
sub_type = event.get("sub_type")
if sub_type == "updated_private_message":
msg_id = event.get("message_id")
content = event.get("content")
print(f"Личное сообщение обновлено: {msg_id}, новое содержимое: {content}")
elif sub_type == "deleted_private_message":
msg_id = event.get("message_id")
print(f"Личное сообщение удалено: {msg_id}")