Система интерактивного диалога
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), его ожидания также обладают всеми семантиками отмены / проверки / владения из этой страницы
Связанные документы
- Conversation многоконтактный диалог - ветвящийся стейт-машинный диалог, автоматические контрольные точки и восстановление после перезапуска
- Система владения (owner) - полная картина и границы дизайна очистки владения
- Контекст (scope) - способы настройки проверки прав доступа и аудита отправки
- Межмодульная коммуникация - вызовы между модулями и направленные события