surfaces/docs/telegram-prototype.md

Telegram — описание прототипа

ВНИМАНИЕ: Telegram-адаптер не является частью текущего MVP-деплоя. Код Telegram-поверхности находится в отдельной ветке feat/telegram-adapter. Данный документ описывает возможности этого адаптера, но многие концепции (например, AuthFlow и MockPlatformClient) устарели по отношению к актуальной архитектуре main.

Концепция

Один бот, несколько чатов через Topics в Forum-группе.

При первом запуске бот создаёт для пользователя персональную Forum-группу (супергруппу с включёнными темами). Каждый новый чат с агентом — отдельная тема внутри группы. Пользователь видит это как список чатов в одном месте.

Бот управляет группой от имени пользователя через Telegram Bot API: создаёт темы, переименовывает, архивирует.

---

Аутентификация

Флоу

1. Пользователь пишет боту /start
2. Бот проверяет — есть ли аккаунт на платформе привязанный к этому tg_user_id
3. Если нет — бот отправляет одноразовую ссылку или код для входа
4. Пользователь подтверждает, платформа возвращает токен сессии
5. Бот сохраняет привязку tg_user_id → platform_user_id

В моке

• Любой пользователь проходит аутентификацию автоматически
• Кнопка «Войти» → пауза 1 сек → «Вы вошли как {имя}»
• Демонстрирует флоу без реальной платформы

---

Чаты через Forum Topics (вариант В)

Как это работает

• Бот создаёт супергруппу с Topics для каждого нового пользователя
• Каждый чат = отдельная тема (Topic) в этой группе
• История хранится нативно в Telegram (в самой теме)
• Переключение между чатами = переключение между темами

Управление чатами

Внутри каждой темы доступны команды:

Команда	Действие
/new	Создать новый чат (новую тему)
/rename Название	Переименовать текущий чат
/archive	Архивировать текущий чат
/chats	Показать список всех чатов

Создание нового чата

1. Пользователь пишет /new или нажимает кнопку
2. Бот спрашивает название (опционально, можно пропустить)
3. Бот создаёт новую тему в группе: «Чат 1», «Чат 2» и т.д.
4. Бот отправляет в новую тему приветствие; при первом сообщении платформа автоматически поднимает контейнер

В моке

• Группа и темы создаются реально через Bot API
• Сообщения передаются в MockPlatformClient с chat_id (C1, C2...)
• История в темах хранится нативно в Telegram, ничего не нужно делать

---

Основной диалог

Флоу сообщения

1. Пользователь пишет текст в тему
2. Бот показывает typing...
3. Запрос уходит в платформу (сейчас — MockPlatformClient)
4. Бот отвечает текстом агента

Вложения

• Фото, документы, голосовые — передаются в платформу как attachments
• В моке: бот подтверждает получение файла и возвращает заглушку-ответ
• Форматы: PDF, изображения, текстовые файлы

Подтверждение действий

Если агент собирается выполнить потенциально опасное действие (отправить письмо, удалить файл, сделать запись в календарь):

Агент хочет выполнить действие:
📧 Отправить письмо на vasya@mail.ru
Тема: «Отчёт за неделю»

[✅ Подтвердить]  [❌ Отменить]

Пользователь нажимает кнопку — действие выполняется или отменяется. В моке: кнопки работают, действие логируется, ответ-заглушка.

---

Настройки

Доступны через /settings в любой теме или в главном меню бота. Реализованы как цепочка инлайн-кнопок.

Главное меню настроек

⚙️ Настройки

[🔗 Коннекторы]   [🧩 Скиллы]
[🧠 Личность]     [🔔 Уведомления]
[🔒 Безопасность] [💳 Подписка]

Коннекторы

Подключение внешних сервисов. Агент получает доступ через API Proxy, пароли пользователю вводить не нужно — только OAuth.

Коннектор	Способ подключения
Gmail / Outlook	OAuth ссылка
Google Calendar	OAuth ссылка
GitHub	OAuth ссылка
Notion	OAuth ссылка
Telegram (читать каналы)	Уже подключён

В моке: кнопка «Подключить» → ссылка-заглушка → «Подключено ✓»

Скиллы

Включение/выключение навыков агента.

🧩 Скиллы

✅ Поиск в интернете
✅ Чтение почты
❌ Управление браузером
❌ Генерация изображений
❌ Работа с календарём
✅ Работа с файлами
❌ Генерация видео

Каждый скилл — кнопка-переключатель. Нажал — включил/выключил. В моке: состояние хранится локально, платформа не вызывается.

Личность агента (SOUL.md)

Онбординг-анкета при первом входе, потом редактирование.

🧠 Личность агента

Как зовут твоего агента?
[_Лямбда_____________]

Что он должен делать в первую очередь?
[_Разбирать почту_____]

Стиль общения:
[Деловой] [Дружелюбный] [Краткий]

В моке: данные сохраняются, агент обращается к пользователю по имени из настроек.

Уведомления

Когда агент выполнил долгую задачу — уведомление в Telegram.

🔔 Уведомления

✅ Задача выполнена
✅ Требуется подтверждение действия
❌ Ежедневный дайджест
❌ Напоминания из календаря

В моке: уведомления отправляются через бот с задержкой (симуляция).

Безопасность

Какие действия требуют явного подтверждения.

🔒 Безопасность

Всегда спрашивать перед:
✅ Отправкой письма
✅ Удалением файлов
✅ Публикацией в соцсетях
❌ Созданием события в календаре
❌ Поиском в интернете

Подписка

Заглушка — реализует другая команда.

💳 Подписка

Текущий план: Beta (бесплатно)
Токены: ████████░░ 800/1000

[Подробнее о планах]

---

FSM состояния

[Start] → AuthPending → AuthConfirmed
                              ↓
                         GroupSetup → Idle
                                        ↓
                              ReceivingMessage → WaitingResponse → Idle
                                        ↓
                              ConfirmAction → [Confirmed/Cancelled] → Idle
                                        ↓
                              Settings → [подменю] → Idle

---

Стек

• Python 3.11+
• aiogram 3.x (Router, FSM, InlineKeyboard, Forum Topics API)
• MockPlatformClient → platform/interface.py
• structlog для логирования
• SQLite для хранения tg_user_id → platform_user_id и состояния скиллов