ErisPulse ErisPulse
Открыть интерактивную версию →
Разделы страницы
Статическое зеркало — интерактивная версия является основной Открыть интерактивную версию →

Система интерактивного диалога

Tip

Когда это нужно читать: при необходимости wait_reply, многоконтактного диалога, периодических напоминаний, взаимоисключающих сессий или трассировки цепочки. Если не нужно — пропустите, это не повлияет на использование других функций.

Что вы узнаете: полный синтаксис wait_reply с параметрами и причинами отмены, декларативная цепочка .got(), таймеры сессии (remind / escalate), многоканальное ожидание (expect / select) и сессионные взаимоисключающие аренды.

В этой статье не рассматривается: ветвящийся стейт-машинный диалог и восстановление после перезапуска (см. Conversation многоконтактный диалог); настройки стратегии сохранения в ящике и перекрытие во время выполнения (см. Сессионный ящик).

Note

В этой главе требуется ErisPulse 2.8.0+.

ErisPulse реализовал "непрерывное взаимодействие с пользователем" как инфраструктуру на уровне фреймворка: от одной wait_reply, до периодических напоминаний, многоканального ожидания, сессионных взаимоисключений и восстановления после перезапуска, все это управляется единым менеджером интерактивных сессий (Core/Event/interaction.py, sdk.interaction).

{!--< tips >!--} Каждая из описанных в статье возможностей имеет владельца (owner): ожидание, аренда и таймеры регистрируются с указанием имени модуля, при отключении модуля или адаптера фреймворк автоматически очищает их, и ожидание немедленно получает уведомление, а не ждет таймаута — это расширение системы владения на интерактивный уровень (см. Система владения). {!--< /tips >!--}

Ожидание ответа: wait_reply

Одной фразой: приостановить текущую корутину, ожидая следующего сообщения от целевого пользователя, вернуть событие ответа при совпадении, вернуть None при таймауте или отмене, pattern / regex / validator могут фильтровать неподходящие ответы.

wait_reply — основа интерактивных сессий — приостанавливает текущую корутину, ожидая следующего сообщения от целевого пользователя.

from ErisPulse.Core.Event import command

@command("ask")
async def ask_command(event):
    reply = await event.wait_reply(prompt="Введите ваше имя:", timeout=30)
    if reply is None:
        await event.reply("Таймаут")
        return
    await event.reply(f"Привет, {reply.get_text()}!")

Полный список параметров

Параметр Описание По умолчанию
prompt Сообщение-подсказка, отправляемое перед приостановкой None
timeout Время ожидания (секунды) 60
pattern Фильтр по шаблону (glob: * / ? / [seq]), если не совпадает — продолжать ожидание None
regex Регулярное выражение для фильтрации (должно совпадать, если заданы и pattern и regex), если не совпадает — продолжать ожидание None
validator Функция валидации (принимает Event, возвращает bool), если не проходит — продолжать ожидание None
callback Колбэк при получении ответа (альтернативный способ вместо возвращаемого значения) None
method Метод отправки подсказки "Text"
session Сессионное ожидание: любой ответ в рамках сессии (группа / канал) может быть использован False
# Принимать только числовые суммы, иначе продолжать ожидание
reply = await event.wait_reply("Введите сумму:", regex=r"\d+\s*元", timeout=30)

# Сессионное ожидание: сценарий совместной работы в группе, любой участник может ответить
reply = await event.wait_reply(session=True, prompt="Кто-нибудь может помочь ответить?")

Граница между ожиданием и командами (проникновение команд)

Во время ожидания, если поступает сообщение с зарегистрированной командой (например, /cancel), по умолчанию оно передается диспетчеру команд для выполнения, а не считается ответом (настройка ErisPulse.event.wait_reply.cmdpass, при True — наоборот — сообщения всегда считаются ответами). Текстовая проверка соответствует правилам диспетчера команд: alt_message имеет приоритет, если отсутствует, используется объединение сообщений (с 2.10.1 работает и для адаптеров с чисто message-сегментами).

Когда ожидание будет отменено

Ожидание больше не ограничено "только таймаутом" — следующие ситуации немедленно прекращают ожидание (wait_reply возвращает None), а не заставляют вызывающую сторону ждать до таймаута:

Событие Причина отмены (InteractionCancelled.reason) Описание
Модуль-владелец отключен / отключен owner_unload Очистка владельца: кто зарегистрировал ожидание, тот, кто исчезает, автоматически его отменяет
Адаптер остановлен / перезапущен platform_stop Все ожидания на этой платформе отменяются
В той же сессии новое ожидание / аренда conflict См. раздел "Сессионная арбитражная система"
Ответивший заблокирован / модуль-владелец отвязан revoked Проверка прав доступа: по контексту и по модулю
Ответ совпадает с ожиданием — Нормальный путь, возвращает событие ответа

Внутреннее исключение — InteractionCancelled (входит в иерархию InteractionError), wait_reply уже преобразует его в возвращение None; вызывающие, которым нужна причина, могут использовать низкоуровневый API sdk.interaction.register().

Полная цепочка проверки ответа

Когда поступает сообщение с ответом, менеджер интеракции проверяет его в следующем порядке (выполняется до сопоставления команд, приоритет сохранения диалога — даже если сообщение уже было признано другим процессором более высокого приоритета, приостановленный диалог может быть завершен):

Соответствие сессионного ключа (точное соответствие по пользователю → возврат к сессионному ожиданию)
  → Фильтрация текста по pattern / regex (если не совпадает — продолжать ожидание)
  → Валидация по validator (если не проходит — продолжать ожидание)
  → Проверка прав доступа (по контексту и владельцу, если не проходит — отменить ожидание)
  → Пробуждение ожидающей стороны + признание события (mark_processed)

Декларативный многоконтактный диалог: .got() цепочка (2.11+)

@command возвращает прокси-объект управления многоконтактным диалогом, с помощью .got() последовательно объявляются шаги сбора — функции шагов принимают уже собранные значения (включая параметры команды) по именам параметров, типы определяются автоматически по type= или аннотациям. Всё это компилируется в Conversation: каждый шаг — ветвь, переходы автоматически сохраняют контрольные точки, при перезапуске пользовательский ответ продолжится с сохраненного шага (фабрика восстановления автоматически регистрируется при декорировании и автоматически отменяется при отключении модуля).

@command("weather")
async def weather(event):
    pass  # Вход: первый .got автоматически отправит подсказку, не нужно спрашивать вручную

@weather.got("city", prompt="Просто ответьте названием города")
async def weather_city(event, city: str):
    await event.reply(f"{city}: солнечно, 25℃")

@weather.got("days", prompt="На сколько дней прогноз?", type=int, retry_prompt="Введите число")
async def weather_days(event, city: str, days: int):
    await event.reply(f"{city} на ближайшие {days} дней...")

Пояснение параметров

Параметр Описание
name Имя собранных значений (имя параметра в последующих функциях шагов; уникально в рамках процесса, повторное объявление вызывает ошибку при регистрации)
prompt Подсказка, автоматически отправляемая при входе на этот шаг
timeout Время ожидания на шаге (секунды или строки типа "90s" / "1h30m", по умолчанию 60s)
type Тип значения (int / float / str и т.д.; при ошибке парсинга автоматически повторно отправляется retry_prompt, максимум max_retries раз)
validator / pattern / regex Фильтрация и валидация ответа (семантика аналогична wait_reply)
session Сессионное ожидание (ответ может быть получен от любого участника сессии)
cmdpass Трёхзначный режим пропуска команд (по умолчанию команды, такие как /cancel, выполняются в процессе ожидания)

Семантика и границы

  • Любой шаг превышает таймаут / прерывается → вся цепочка завершается и контрольные точки удаляются (аналогично wait_reply); в функциях шагов можно в любое время использовать event.reply(...) для вывода промежуточных результатов
  • Один пользователь может иметь только одну приостановленную интеракцию — вторая цепочка ожидания отменяет предыдущую (InteractionCancelled("conflict")); для уведомления о взаимоисключении используйте Сессионные аренды
  • Собранные значения существуют только в рамках процесса; для сохранения сложного состояния между перезапусками используйте Conversation (с context + branch/goto + ручные контрольные точки)
  • @command возвращает прокси-объект: поведение, __name__, docstring, пользовательские атрибуты полностью идентичны оригинальному функции; command.unregister(прокси) автоматически распаковывает

Сессионные таймеры: remind / escalate

Превращение "таймаута" из возвращаемого значения в управляемую примитивную операцию. Таймеры привязаны к интерактивной сессии, автоматически отменяются при отключении модуля / остановке адаптера, максимальное количество активных remind в одной сессии — 5.

remind: напоминание при отсутствии ответа

@command("ticket")
async def ticket_command(event):
    await event.reply("Заявка создана, результат будет уведомлен здесь")
    # Если в течение 5 минут нет ответа, мягко напомнить один раз; любой ответ пользователя автоматически отменяет напоминание
    event.remind(300, "Есть ли ещё что-то? Результат будет уведомлен в ближайшее время")
    reply = await event.wait_reply(timeout=3600)
    ...
  • event.remind(delay, text=None, *, callback=None): при истечении delay отправляет text в текущую сессию (или выполняет callback(event), поддерживает синхронные / асинхронные функции). Обязательная проверка: text и callback должны быть выбраны (если не заданы, выбрасывается ValueError)
  • Возвращает Reminder — дескриптор: reminder.cancel() отменяет вручную, reminder.expired проверяет состояние
  • После ответа пользователя в этой сессии автоматически отменяется — это и есть смысл "напоминания": напоминание появляется только когда пользователь молчит
  • В Conversation также доступно: conv.remind(120, "Ещё думаете?")

escalate: обязательное уведомление при истечении времени

event.escalate(1800, lambda e: notify_master(f"Заявка не обработана 30 минут: {event.get_command_args()}"))

Единственное отличие от remind: не отменяется ответом пользователя — действие "повышения" (уведомление владельца, перенаправление на человека) — это обязательное уведомление при истечении времени, отменяется только вручную cancel() / отключением модуля / остановкой адаптера.

remind escalate
Действие при истечении Отправка текста / выполнение callback Выполнение callback
Ответ пользователя Автоматически отменяется Не влияет
Очистка владения (отключение / остановка платформы) Отменяется Отменяется
Максимальное количество на сессию 5 Не ограничено (очищается при отключении владения)

Многоканальное ожидание: expect + select

Одной фразой: expect только описывает ожидание, не регистрируя ожидание, select объединяет несколько ожиданий, при первом совпадении возвращает (индекс, событие ответа), несовпавшие автоматически удаляются.

Ожидание нескольких ожиданий одновременно, первый пришедший побеждает — типичный сценарий: ожидание одобрения администратором и одновременно ожидание отмены пользователем, совместное голосование.

which, reply = await event.select(
    event.expect(pattern="同意*", user="10001"),
    event.expect(pattern="拒绝*", user="10002"),
    event.expect(validator=lambda e: e.get_text() == "搁置", session=True),
    timeout=60,
)
if which is None:
    await event.reply("В течение 60 секунд не получено ни одного результата одобрения")
elif which == 0:
    await event.reply("Одобрено")
elif which == 1:
    await event.reply("Отклонено")
  • event.expect(...) конструирует описание ожидания (не регистрирует никаких ожиданий): поддерживает pattern / regex / validator / user (ограничение ответившего) / session (ответ может быть получен от любого участника)
  • event.select(*expectations, timeout=60): объединяет ожидания → при первом совпадении возвращает (индекс, событие ответа) → несовпавшие ожидания автоматически удаляются; при таймауте возвращается (None, None). Обязательная проверка: необходимо передать хотя бы одно ожидание, иначе выбрасывается ValueError
  • Событие, совпавшее с ожиданием, уже признано фреймворком (mark_processed), не будет повторно обработано другими процессорами

{!--< tips >!--} select по сравнению с ручной компиляцией asyncio.wait в многопоточном режиме: автоматическая очистка несовпавших ожиданий, автоматическое признание совпавшего события, все проверки прав доступа и очистка владения активны — не нужно самостоятельно управлять Future. {!--< /tips >!--}

Note

Начиная с 2.10.1 select является агрегирующим ожиданием: все ожидания объединяются в одно, с пользовательским критерием совпадения, ожидания по одному ключу (например, по одному user две разные pattern) больше не отменяют друг друга, первое совпадение возвращает. Критерий совпадения текста сообщения — alt_message имеет приоритет, при отсутствии используется объединение сообщений (аналогично правилам диспетчера команд).

Ограничения: event.wait_for(...) напрямую привязан к событию адаптера, не проходит через промежуточные слои и фильтры detail_type (безопасность доступа обеспечивается на уровне входа в диспетчер); для полной цепочки ожидания используйте wait_reply / select.

Взаимоисключающие аренды сессий: acquire / hold / get_owner_of

Владение переходит от "ресурса" к "сессии" — "кто сейчас занят этим пользователем" становится первостепенным вопросом.

# Запрос: кто сейчас занят этой сессией? (если свободна, возвращает None)
owner = sdk.interaction.get_owner_of(event)
if owner and owner != "MyModule":
    return  # Другой модуль уже взаимодействует, избегаем мешать

# Взаимоисключающая аренда: эксклюзивная сессия (стратегия deny, если занята возвращает None)
lease = sdk.interaction.acquire(event)          # По умолчанию TTL 1 час, можно передать ttl=
if lease is None:
    return  # Уже занята
try:
    ...  # Эксклюзивное взаимодействие
finally:
    lease.release()

Форма с контекстным менеджером (при неудаче выбрасывает SessionOccupiedError):

with sdk.interaction.hold(event) as lease:
    ...  # При выходе автоматически освобождается

Аренда поддерживает renew(ttl) для продления; TTL лениво просрочивается — просроченная аренда автоматически удаляется при следующем обращении.

Conversation.resume() при восстановлении диалога автоматически захватывает аренду (см. Conversation многоконтактный диалог раздел "Восстановление как захват") — восстановленный диалог автоматически владеет сессией, другие модули не могут вмешаться.

Сессионный ящик: event.history

Стратегия сохранения (7 дней / лимит сообщений) и API управления во время выполнения, риски и аудит см. в специальной статье Сессионный ящик.

Единая запись недавних сообщений в каждой сессии (со стороны пользователя и бота), служит общей базой для контекста ИИ, предотвращения повторений, анализа поведения — единая база фактов для модулей, каждый модуль больше не хранит историю отдельно.

messages = await event.history(20)   # Последние 20 сообщений в текущей сессии, по времени в порядке возрастания
for m in messages:
    print(m["role"], ":", m["text"])  # role: "user" / "bot"
  • Автоматическая запись: входящие сообщения (role=user) + отправленные ботом текстовые сообщения (role=bot)
  • Хранение: отдельная таблица SQLite, стратегия хранения = лимит на сессию (по умолчанию 50) + глобальный TTL (по умолчанию 7 дней)
  • Запись: буфер в памяти + фоновая пакетная запись на диск (задержка до 1 секунды), интерфейс запроса автоматически объединяет незаписанные буферные строки — чтение из одного процесса не влияет на запись; при нормальном завершении (sdk.uninit / выход процесса) автоматически записывается на диск. В случае жесткого сбоя / принудительного завершения последние около 1 секунды записи могут быть потеряны: эта база данных предназначена для кэширования недавнего контекста, не подходит для аудита или долгосрочного хранения
  • Настройка: ErisPulse.transcript = {enabled = true, max_per_session = 50, ttl_hours = 168}
  • Интерфейс менеджера: sdk.transcript.append() / get() / clear(), aflush() / flush() для ручной записи на диск

Транзакции сообщений: message_tx

Все отправки в рамках транзакции автоматически записываются в бухгалтерию; при выходе с ошибкой автоматически отменяются отправленные сообщения в обратном порядке (если адаптер не реализует delete_message, отмена пропускается, бухгалтерия всё равно записывается).

async with event.message_tx():
    await event.reply("Обработка, подождите")
    result = await do_something()          # Здесь выбрасывается исключение →
    await event.reply(f"Завершено: {result}")   # Предыдущее "Обработка" автоматически отменяется

Отправки вне транзакции не записываются (ноль накладных расходов); в транзакции можно в любой момент прочитать бухгалтерию, типичное применение — автоматическое удаление сообщений ботом (отправка с расписанием отмены) и аудит отправок:

import asyncio
from ErisPulse.runtime import get_send_receipts

async def delayed_delete(adapter, message_id: str, delay: float):
    await asyncio.sleep(delay)
    await adapter.delete_message(message_id)

async with event.message_tx():
    await event.reply("Временное уведомление")
    for r in get_send_receipts() or []:
        # Каждая бухгалтерия содержит platform / bot_id / message_id / trace_id
        asyncio.create_task(delayed_delete(adapter, r["message_id"], 30))

Чтение бухгалтерии — в пределах транзакции: только в message_tx() возвращает не None, вне транзакции всегда None; для захвата всех отправок (включая вне транзакции) используйте хуки message.sending/sent (см. Трассировка цепочки поле trace_id).

Трассировка цепочки: trace-id

Каждое входящее событие автоматически получает идентификатор трассировки (переиспользуется event["id"], если отсутствует, генерируется), который проходит через:

  • Контекст обработчика (get_current_trace_id() для чтения)
  • Отправку сообщений (в логах [Send] добавляется [trace:...], в хуках message.sending/sent поле trace_id)
  • Данные жизненного цикла (dict автоматически дополняется _trace_id)
  • Направленные события (lifecycle.emit(..., to=...)) и бухгалтерия транзакций сообщений

При обработке сообщения несколькими модулями, по одному идентификатору можно проследить всю цепочку (логи / медленные запросы / аудит).

Связь с другими системами

  • Владение: ожидание / аренда / таймеры все регистрируются с указанием владельца, при отключении — очищаются (см. Система владения)
  • Контекст: проверка прав доступа при совпадении ответа по контексту и владельцу; аудит вызовов между модулями — по направлению отправки (см. Контекст)
  • Conversation: многоконтактный диалог — это ветвящийся стейт-машинный диалог над интерактивной сессией (см. Conversation), его ожидания также обладают всеми семантиками отмены / проверки / владения из этой страницы

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