surfaces/docs/telegram-prototype.md

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

Концепция

Один бот, несколько чатов, две поверхности:

• базовая поверхность — личка с ботом (DM)
• опциональная advanced-поверхность — Topics в пользовательской Forum-группе

При первом запуске пользователь начинает в DM: бот создаёт первый чат и переключает пользователя в него. Если позже пользователь подключает Forum-группу через /forum, существующие чаты получают соответствующие темы в супергруппе.

DM и Forum используют один и тот же chat_id: пользователь может писать либо в личке, либо в forum topic, а платформа видит единый разговор.

---

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

Флоу

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

В моке

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

---

Чаты в DM и Forum Topics

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

• После /start бот создаёт Чат #1 в DM
• В DM активный чат хранится как active_chat_id
• Ответы в личке приходят в общий поток с тегом [Чат #N]
• После /forum пользователь привязывает свою супергруппу с Topics
• Каждый чат может получить соответствующую тему (forum_thread_id)
• В forum-теме ответы приходят без тега, прямо в тему
• История forum-разговоров хранится нативно в Telegram

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

В DM доступны команды:

Команда	Действие
/new	Создать новый чат
/chats	Показать список всех чатов
/forum	Подключить Forum-группу

В forum-темах поддерживается тот же разговорный контекст, а /new может зарегистрировать текущую тему как отдельный чат.

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

1. Пользователь пишет /new [название] или нажимает кнопку
2. Бот создаёт новый чат в локальной БД: Чат #N или указанное название
3. Если Forum уже подключён, бот дополнительно создаёт новую тему в привязанной группе
4. В DM бот переключает active_chat_id на новый чат

В моке

• DM-чаты работают сразу после /start
• Если Forum подключён, темы создаются реально через Bot API
• Сообщения из DM и forum topic передаются в MockPlatformClient с одним и тем же chat_id

---

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

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

1. Пользователь пишет текст в DM или в forum topic
2. Бот показывает typing...
3. Запрос уходит в платформу (сейчас — MockPlatformClient)
4. Бот отвечает:
   • в DM: с тегом [Чат #N]
   • в forum topic: без тега, в ту же тему

Вложения

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

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

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

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

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

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

---

Настройки

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

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

⚙️ Настройки

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

Коннекторы

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

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

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

Скиллы

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

🧩 Скиллы

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

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

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

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

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

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

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

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

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

Уведомления

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

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

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

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

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

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

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

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

Подписка

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

💳 Подписка

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

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

---

FSM состояния

[Start] -> ChatState.idle
              ↓
      ForumSetupState.waiting_for_group
              ↓
      ChatState.waiting_response -> ChatState.idle
              ↓
           SettingsState.*

---

Стек

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