简体中文 English 繁體中文 日本語 Русский
本文为静态镜像，内容以交互版为准 在交互式文档中心打开 →

Стандарт типов сессий ErisPulse

Данный документ определяет стандарты типов сессий, поддерживаемых ErisPulse, включая типы событий приема и типы целей отправки.

1. Основные понятия

1.1 Типы получения и отправки

ErisPulse различает два типа сессий:

1.2 Соответствие типов

Тип получения (detail_type)     Тип отправки (Send.To)
─────────────────        ────────────────
private                 →        user
group                   →        group
channel                 →        channel
guild                   →        guild
thread                  →        thread
user                    →        user

Ключевые моменты:

2. Стандартные типы сессий

2.1 Стандартные типы OneBot12

private

group

user

2.2 Расширенные типы ErisPulse

channel

guild

thread

3. Типы платформ

3.1 Принципы отображения

Адаптер отвечает за сопоставление нативных типов платформ с типами стандарта ErisPulse:

Нативный тип платформы → Тип стандарта ErisPulse → Тип отправки

3.2 Примеры распространённых платформ

Telegram

Тип Telegram           Тип приёма ErisPulse    Тип отправки
─────────────────      ────────────────       ───────────
private                private                 user
group                  group                   group
supergroup             group                   group  # Сопоставлено с group
channel                channel                 channel

Discord

Тип Discord            Тип приёма ErisPulse    Тип отправки
─────────────────      ────────────────       ───────────
Direct Message         private                user
Text Channel           channel                channel
Guild                  guild                  guild
Thread                 thread                 thread

OneBot11

Тип OneBot11           Тип приёма ErisPulse    Тип отправки
─────────────────      ────────────────       ───────────
private                private                user
group                  group                  group
discuss                group                  group  # Сопоставлено с group

4. Расширение пользовательских типов

4.1 Регистрация пользовательского типа

Адаптер может зарегистрировать пользовательский тип сессии:

from ErisPulse.Core.Event import register_custom_type

# Регистрация пользовательского типа
register_custom_type(
    receive_type="my_custom_type",
    send_type="custom",
    id_field="custom_id",
    platform="MyPlatform"
)

4.2 Использование пользовательского типа

После регистрации система будет автоматически обрабатывать преобразование и определение этого типа:

# Автоматическое определение
receive_type = infer_receive_type(event, platform="MyPlatform")
# Возвращает: "my_custom_type"

# Преобразование в тип отправки
send_type = convert_to_send_type(receive_type, platform="MyPlatform")
# Возвращает: "custom"

# Получение соответствующего ID
target_id = get_target_id(event, platform="MyPlatform")
# Возвращает: event["custom_id"]

4.3 Отмена регистрации пользовательского типа

from ErisPulse.Core.Event import unregister_custom_type

unregister_custom_type("my_custom_type", platform="MyPlatform")

5. Автоматическое определение типа

Когда у события отсутствует явное поле detail_type, система автоматически определяет тип по наличию идентификатора:

Note

Изменение поведения в 2.7.0+: detail_type используется напрямую только в том случае, если он представляет собой известный тип сессии (стандартный или пользовательский). У событий notice и request detail_type (например, group_member_increase, friend_increase) является семантическим подтипом, а не типом сессии, и в этом случае тип сессии определяется по идентификатору.

5.1 Приоритет определения

Приоритет (от высокого к низкому):
1. group_id     → group
2. channel_id   → channel
3. guild_id     → guild
4. thread_id    → thread
5. user_id      → private

5.2 Примеры использования

# У события есть только group_id
event = {"group_id": "123", "user_id": "456"}
receive_type = infer_receive_type(event)
# Возвращает: "group" (group_id используется с приоритетом)

# У события есть только user_id
event = {"user_id": "123"}
receive_type = infer_receive_type(event)
# Возвращает: "private"

# У события notice detail_type является семантическим подтипом, начиная с 2.7.0 будет использоваться определение по идентификатору
event = {"type": "notice", "detail_type": "group_member_increase", "group_id": "123"}
receive_type = infer_receive_type(event)
# Возвращает: "group" (а не "group_member_increase")

6. Примеры использования API

6.1 Отправка сообщений

from ErisPulse import adapter

# Отправка пользователю
await adapter.myplatform.Send.To("user", "123").Text("Hello")

# Отправка в группу
await adapter.myplatform.Send.To("group", "456").Text("Hello")

# Автоматическое преобразование private → user (не рекомендуется, может вызвать проблемы совместимости)
await adapter.myplatform.Send.To("private", "789").Text("Hello")
# Внутри автоматически преобразуется в: Send.To("user", "789") # Использование user в качестве типа сессии является более предпочтительным выбором

6.2 Ответ на событие

from ErisPulse.Core.Event import Event

# Event.reply() автоматически обрабатывает преобразование типа
await event.reply("Содержание ответа")
# Внутри автоматически используется правильный тип отправки

6.3 Обработка команд

from ErisPulse.Core.Event import command

@command(name="test")
async def handle_test(event):
    # Система автоматически обрабатывает тип сессии
    # Не нужно вручную проверять group_id или user_id
    await event.reply("Команда выполнена успешно")

7. Основная API-справка

7.1 Преобразование типов

from ErisPulse.Core.Event import convert_to_send_type, convert_to_receive_type

# Тип получения → Тип отправки
convert_to_send_type("private")  # → "user"
convert_to_send_type("group")    # → "group"

# Тип отправки → Тип получения
convert_to_receive_type("user")   # → "private"
convert_to_receive_type("group")  # → "group"

7.2 Запрос полей ID

from ErisPulse.Core.Event import get_id_field, get_receive_type

get_id_field("group")    # → "group_id"
get_id_field("private")  # → "user_id"

get_receive_type("group_id")  # → "group"
get_receive_type("user_id")   # → "private"

7.3 Получение информации для отправки одним шагом

from ErisPulse.Core.Event import get_send_type_and_target_id

event = {"detail_type": "private", "user_id": "123"}
send_type, target_id = get_send_type_and_target_id(event)
# send_type = "user", target_id = "123"

# Непосредственно используется в Send.To()
await adapter.Send.To(send_type, target_id).Text("Hello")

7.4 Получение идентификатора цели

from ErisPulse.Core.Event import get_target_id

event = {"detail_type": "group", "group_id": "456"}
get_target_id(event)  # → "456"

8. Утилитарные методы

from ErisPulse.Core.Event import (
    is_standard_type,
    is_valid_send_type,
    get_standard_types,
    get_send_types,
    clear_custom_types,
)

is_standard_type("private")     # True
is_standard_type("custom_type") # False

is_valid_send_type("user")      # True
is_valid_send_type("invalid")   # False

get_standard_types()  # {"private", "group", "channel", "guild", "thread", "user"}
get_send_types()      # {"user", "group", "channel", "guild", "thread"}

clear_custom_types()                # Очистить все
clear_custom_types(platform="discord")  # Очистить только для указанной платформы

9. Лучшие практики

7.1 Разработчики адаптеров

  1. Использование стандартных маппингов: по возможности маппите на стандартные типы, а не создавайте новые типы
  2. Правильное преобразование: убедитесь, что маппинг между типами приема и отправки корректен
  3. Сохранение исходных данных: сохраняйте исходный тип события в {platform}_raw
  4. Описание в документации: в документации адаптера укажите отношения между типами

7.2 Разработчики модулей

  1. Использование вспомогательных методов: используйте вспомогательные методы, такие как get_send_type_and_target_id()
  2. Избегайте жесткого кодирования: не пишите код вида if group_id else "private"
  3. Учет всех типов: код должен поддерживать все стандартные типы, а не только private/group
  4. Гибкое проектирование: используйте методы оберток событий, а не прямой доступ к полям

9.3 Вывод типов

10. Часто задаваемые вопросы

В1: Почему при отправке private нужно преобразовывать в user?

О: Это требование стандарта OneBot12. private — это понятие, относящееся к получению, при отправке использование user более соответствует семантике.

В2: Как поддержать новые типы сессий?

О: Зарегистрируйте пользовательский тип с помощью register_custom_type() или используйте стандартные типы, такие как channel, guild и т.д.

В3: Что делать, если у события нет detail_type?

О: Система автоматически определит тип на основе существующих полей ID. Приоритет определяется следующим образом: group > channel > guild > thread > user.

В4: Как адаптер отображает Telegram supergroup?

О: В логике преобразования адаптера supergroup отображается в стандартный тип group.

В5: Как обрабатывать специальные платформы, такие как электронная почта?

О: Для неуниверсальных или платформенно-специфичных типов используйте {platform}_raw и {platform}_raw_type для сохранения исходных данных, а адаптер будет обрабатывать их самостоятельно.

11. Связанные документы