Conversation: многоходовой диалог
Tip
Когда читать этот документ: когда нужны конечный автомат многоходового диалога и восстановление из контрольных точек. Если это не нужно — пропустите, на использование остальных функций это не влияет.
Когда команда должна последовательно запрашивать у пользователя информацию в несколько шагов (сбор данных при регистрации, анкеты, мастер настройки), используйте Conversation, чтобы выстроить в одной сессии цепочку «вопрос → ожидание ответа → проверка → следующий шаг». После тайм-аута или перезапуска диалог можно восстановить из контрольной точки.
Создание диалога
Диалог создаётся методом conversation() объекта Event:
from ErisPulse.Core.Event import command
@command("quiz")
async def quiz_handler(event):
conv = event.conversation(timeout=30)
await conv.say("🎮 Добро пожаловать в викторину!")
answer = await conv.choose("Вопрос 1: кто создатель Python?", [
"Guido van Rossum",
"James Gosling",
"Dennis Ritchie",
])
if answer is None:
await conv.say("Время вышло, приходите в следующий раз!")
return
if answer == 0:
await conv.say("Правильно!")
else:
await conv.say("Неправильно, правильный ответ — Guido van Rossum")
conv.stop()
Основной API
say(content, **kwargs)
Отправляет сообщение, возвращает self, поддерживая цепочки вызовов:
await conv.say("Первая строка").say("Вторая строка").say("Третья строка")
Можно также указать метод отправки:
await conv.say("https://example.com/image.jpg", method="Image")
wait(prompt=None, timeout=None)
Ожидает ответ пользователя, возвращает объект Event или None (тайм-аут):
# Простое ожидание
resp = await conv.wait()
if resp:
text = resp.get_text()
# Отправка подсказки и ожидание
resp = await conv.wait(prompt="Пожалуйста, введите ваше имя:")
# Своё время ожидания (переопределяет тайм-аут диалога по умолчанию)
resp = await conv.wait(prompt="Ответьте в течение 10 секунд:", timeout=10)
confirm(prompt=None, **kwargs)
Ожидает подтверждения пользователя (да/нет), возвращает True / False / None (тайм-аут):
result = await conv.confirm("Вы уверены, что хотите удалить все данные?")
if result is True:
await conv.say("Удалено")
elif result is False:
await conv.say("Отменено")
else:
await conv.say("Время ожидания истекло, ответа нет")
Встроенные распознаваемые слова подтверждения: да/yes/y/подтверждаю/точно/хорошо/ok/true/верно/ага/ладно/согласен/без проблем/можно/конечно...
Встроенные распознаваемые слова отрицания: нет/no/n/отмена/не/не надо/нельзя/cancel/false/неверно/неправильно/не/отказ...
choose(prompt, options, **kwargs)
Ожидает, пока пользователь выберет один из вариантов, возвращает индекс варианта (начиная с 0) или None:
choice = await conv.choose("Выберите цвет:", ["Красный", "Зелёный", "Синий"])
if choice is not None:
colors = ["Красный", "Зелёный", "Синий"]
await conv.say(f"Вы выбрали {colors[choice]}")
Пользователь может выбрать, введя номер (1/2/3) или текст варианта (Красный).
options_format="auto" (по умолчанию) автоматически выбирает встроенный стиль в зависимости от method: Markdown→маркированный список, Html→нумерованный список, остальные→простой текстовый список.
Также поддерживаются "list", "inline", "md", "html" или пользовательская функция.
Поддерживается merge_prompt=True для объединения подсказки и вариантов в одно сообщение, а также плейсхолдер, управляющий позицией вставки вариантов (по умолчанию {options}, настраивается через placeholder):
choice = await conv.choose(
"## Выберите\n{options}",
["Вариант А", "Вариант Б"],
method="Markdown",
merge_prompt=True,
)
# Собственное имя плейсхолдера
choice = await conv.choose(
"Выберите: [choices]",
["Вариант А", "Вариант Б"],
placeholder="[choices]",
)
collect(fields, **kwargs)
Пошаговый сбор информации, возвращает словарь данных или None:
data = await conv.collect([
{"key": "name", "prompt": "Введите имя"},
{"key": "age", "prompt": "Введите возраст",
"validator": lambda e: e.get("alt_message", "").strip().isdigit(),
"retry_prompt": "Возраст должен быть числом, введите ещё раз"},
{"key": "city", "prompt": "Введите город"},
])
if data:
await conv.say(f"Регистрация успешна!\nИмя: {data['name']}\nВозраст: {data['age']}\nГород: {data['city']}")
else:
await conv.say("Процесс регистрации прерван")
Конфигурация полей:
| Параметр | Описание | По умолчанию |
|---|---|---|
key |
Ключ поля (обязателен) | - |
prompt |
Подсказка | "Введите {key}" |
validator |
Функция проверки, принимает Event, возвращает bool | нет |
retry_prompt |
Подсказка при повторе после неудачной проверки | "Некорректный ввод, попробуйте ещё раз" |
max_retries |
Максимальное число повторных попыток | 3 |
condition |
Функция условия, принимает dict уже собранных данных, возвращает bool | нет |
Условные поля: с помощью condition можно реализовать динамические формы — поле собирается только при выполнении условия:
data = await conv.collect([
{"key": "has_car", "prompt": "У вас есть машина? (да/нет)"},
{"key": "car_brand", "prompt": "Введите марку машины",
"condition": lambda d: d.get("has_car", "").lower() in ("да", "yes", "y")},
])
stop()
Вручную завершает диалог, устанавливая is_active в False:
conv.stop()
is_active
Находится ли диалог в активном состоянии:
if conv.is_active:
await conv.say("Диалог ещё продолжается")
Управление активным состоянием
stateDiagram-v2
state "Активен" as active
state "Неактивен" as inactive
[*] --> active: event.conversation()
active --> active: say / wait / confirm / choose / collect
active --> inactive: stop()
active --> inactive: тайм-аут wait()
active --> inactive: тайм-аут или исчерпание повторов в collect()
inactive --> [*]
Диалог автоматически переходит в неактивное состояние в следующих случаях:
- Вызван метод
stop() wait()по тайм-ауту вернулNonecollect()вернулNoneиз-за тайм-аута на каком-либо шаге или исчерпания повторных попыток
После перехода в неактивное состояние все интерактивные методы (wait/confirm/choose/collect) немедленно возвращают None и больше не ожидают ввод пользователя.
Ветвления и переходы
Декоратор @conv.branch(name)
Метод branch() регистрирует ветвь диалога, а goto() выполняет переходы между ветвями:
@command("menu")
async def menu_handler(event):
conv = event.conversation(timeout=60)
@conv.branch("main")
async def main_menu():
await conv.say("=== Главное меню ===\n1. Личные данные\n2. Настройки\n3. Выход")
resp = await conv.wait()
if resp is None:
return
text = resp.get_text().strip()
if text == "1":
await conv.goto("profile")
elif text == "2":
await conv.goto("settings")
elif text == "3":
await conv.say("До свидания!")
conv.stop()
@conv.branch("profile")
async def profile():
await conv.say("=== Личные данные ===\nИмя: Alice\n0. Назад")
resp = await conv.wait()
if resp and resp.get_text().strip() == "0":
await conv.goto("main")
@conv.branch("settings")
async def settings():
await conv.say("=== Настройки ===\n1. Переключатель уведомлений\n0. Назад")
resp = await conv.wait()
if resp and resp.get_text().strip() == "0":
await conv.goto("main")
await conv.start() # Начало с первой зарегистрированной ветви
conv.start(name=None)
Запускает диалог, по умолчанию — с первой зарегистрированной ветви:
await conv.start() # С первой ветви
await conv.start("settings") # С указанной ветви
Контекст и персистентность
conv.context
У каждого экземпляра диалога есть встроенный словарь context для обмена состоянием между ветвями:
@conv.branch("step1")
async def step1():
conv.context["username"] = resp.get_text().strip()
await conv.goto("step2")
@conv.branch("step2")
async def step2():
name = conv.context.get("username", "Неизвестно")
await conv.say(f"Привет, {name}!")
save() / resume() / clear_saved()
Диалог поддерживает персистентность и может быть восстановлен после тайм-аута или прерывания:
# Сохранение состояния диалога (обычно вызывать вручную не нужно, см. «Автоматическое сохранение» ниже)
await conv.save()
# ... позже восстановление в той же сессии ...
conv2 = event.conversation()
if await conv2.resume():
await conv2.say("С возвращением! Продолжим прерванный диалог")
else:
await conv2.say("Предыдущий диалог не найден")
# Очистка сохранённого диалога
await conv.clear_saved()
Ключ хранения включает измерение target (conversation:{platform}:{user_id}:{target_id}), поэтому диалоги одного пользователя в разных сессиях не перезаписывают друг друга; архивы старого формата (без target) автоматически мигрируют при resume().
Автоматические контрольные точки и восстановление после перезапуска
Автоматическое сохранение
Фреймворк автоматически поддерживает контрольные точки в следующих случаях; обычно вручную вызывать save() не нужно:
| Момент | Поведение |
|---|---|
Переход между ветвями goto() / start() |
Автосохранение (текущая ветвь + context) |
stop() / тайм-аут wait() / сбой collect() |
Автоочистка (конечное состояние диалога) |
TTL контрольных точек
Архивы содержат метку времени; архивы старше ErisPulse.interaction.checkpoint_ttl (по умолчанию 24 часа) удаляются:
- Ленивое отбрасывание: если при восстановлении обнаруживается, что архив просрочен, он автоматически отбрасывается
- Активная фоновая очистка: во фреймворке есть периодическая задача GC (лениво запускается после первого использования контрольных точек), которая активно перечисляет и удаляет просроченные архивы, чтобы при долгой работе просроченные контрольные точки не накапливались в storage бесконечно. Если после активной очистки архива в сессию придёт сообщение, оно обрабатывается как «контрольная точка отсутствует»
[ErisPulse.interaction]
checkpoint_ttl = 86400 # секунды
Автоматическое восстановление после перезапуска
После перезапуска фреймворка идущие диалоги (ожидающие корутины в памяти) теряются, но контрольные точки сохраняются. Если зарегистрировать фабрику восстановления через register_resume_handler, фреймворк после перезапуска при получении первого сообщения в этой сессии автоматически продолжит диалог:
from ErisPulse.Core.Event.wrapper import Conversation
@Conversation.register_resume_handler() # можно передать platform="onebot11", чтобы ограничить платформу
def make_conversation(event) -> Conversation:
# Задача фабрики: заново создать диалог и перерегистрировать все ветви
conv = event.conversation(timeout=60)
@conv.branch("menu")
async def menu(conv, event):
...
return conv
После регистрации, когда пользователь, находившийся до перезапуска в ветви menu, пришлёт первое сообщение, фреймворк автоматически: восстановит context → захватит это сообщение → продолжит диалог из сохранённой ветви. Без зарегистрированной фабрики этот механизм не создаёт накладных расходов.
Восстановление означает захват
При успешном resume() фреймворк автоматически делает две вещи:
- Захват сессии: автоматически выполняет acquire эксклюзивной аренды сессии — другие модули могут через
sdk.interaction.get_owner_of(event)узнать, что «этот пользователь занят диалогом»; если сессия уже занята другим модулем, восстановление отменяется (возвращает False), чтобы два диалога не конфликтовали - Возврат истории: последние 10 сообщений из входящего ящика сессии помещаются в
conv.recent_history(контекст LLM у AI-модуля не обрывается после восстановления); можно отключить черезresume(with_history=0)
if await conv.resume(with_history=20):
for m in conv.recent_history:
print(m["role"], ":", m["text"])
Ручное восстановление (если не использовать автоматический механизм)
@command("continue")
async def continue_handler(event):
conv = event.conversation()
# ... регистрация ветвей ...
if await conv.resume():
conv.goto(conv.get_current_branch())
Типовые шаблоны потоков
Пошаговая регистрация
@command("register")
async def register_handler(event):
conv = event.conversation(timeout=60)
await conv.say("Добро пожаловать! Начинаем регистрацию.")
data = await conv.collect([
{"key": "username", "prompt": "Введите имя пользователя (3-20 символов)",
"validator": lambda e: 3 <= len(e.get_text().strip()) <= 20},
{"key": "email", "prompt": "Введите адрес электронной почты",
"validator": lambda e: "@" in e.get_text() and "." in e.get_text(),
"retry_prompt": "Неверный формат email, введите ещё раз"},
])
if not data:
await event.reply("Регистрация отменена")
return
confirmed = await conv.confirm(
f"Подтвердить данные регистрации?\nИмя пользователя: {data['username']}\nEmail: {data['email']}"
)
if confirmed:
await conv.say("✅ Регистрация успешно завершена!")
else:
await conv.say("❌ Регистрация отменена")
Циклический диалог
@command("chat")
async def chat_handler(event):
conv = event.conversation(timeout=120)
await conv.say("Включён режим диалога. Введите «выход», чтобы завершить.")
while conv.is_active:
resp = await conv.wait()
if resp is None:
await conv.say("Время вышло, диалог завершён")
break
text = resp.get_text().strip()
if text == "выход":
await conv.say("До свидания!")
conv.stop()
elif text == "помощь":
await conv.say("Доступные команды: выход, помощь, статус")
elif text == "статус":
await conv.say("Диалог активен")
else:
await conv.say(f"Вы сказали: {text}")
Связанные документы
- Класс-обёртка Event - все методы объекта Event
- Начало работы с обработкой событий - основы обработки событий