# Matrix — описание прототипа ## Концепция Один бот, каждый чат — отдельная комната, все комнаты собраны в personal Space. При первом входе бот создаёт для пользователя личное пространство (Space) — это как папка в Element. Внутри Space бот создаёт комнату для каждого нового чата с агентом. Пользователь видит аккуратную структуру: одно пространство, внутри — список чатов. История хранится нативно в Matrix — это часть протокола, ничего дополнительно делать не нужно. Matrix выбран как внутренняя поверхность: команды лаборатории, тестировщики, разработчики скиллов. Поэтому UX здесь прагматичный: минимум магии, явные команды `!`, локальный state-store и нативные Matrix rooms. --- ## Аутентификация ### Флоу 1. Пользователь приглашает бота в личные сообщения или пишет в общей комнате 2. Бот проверяет `@user:matrix.org` — есть ли аккаунт на платформе 3. Если нет — бот отправляет одноразовый код или ссылку 4. Пользователь подтверждает, платформа возвращает токен 5. Бот сохраняет привязку `matrix_user_id → platform_user_id` ### В моке - Любой пользователь проходит аутентификацию автоматически - Бот отвечает: «Добро пожаловать, {display_name}. Создаю ваше пространство...» - Демонстрирует флоу без реальной платформы --- ## Чаты через Space + комнаты (вариант Б) ### Структура ``` Space: «Lambda — {display_name}» ├── 💬 Чат 1 ← первый чат, создаётся автоматически ├── 💬 Чат 2 └── 💬 Исследование рынка ← пользователь сам называет ``` ### Создание Space При первом входе бот: 1. Создаёт Space `Lambda — {display_name}` 2. Создаёт первую комнату-чат `Чат 1` 3. Передаёт `invite=[matrix_user_id]` прямо в `room_create(...)` для Space и комнаты 4. Привязывает `chat_id ↔ room_id` в локальном состоянии 5. Пишет приветствие в `Чат 1` ### Управление чатами Команды работают в зарегистрированных комнатах бота: | Команда | Действие | |---|---| | `!new` | Создать новый чат (новую комнату в Space) | | `!new Название` | Создать чат с именем | | `!help` | Показать шпаргалку по доступным командам | | `!rename Название` | Переименовать текущую комнату | | `!archive` | Архивировать чат и вывести бота из комнаты | | `!chats` | Показать список чатов | | `!settings`, `!skills`, `!soul`, `!safety`, `!plan`, `!status`, `!whoami` | Настройки и диагностика | ### Создание нового чата 1. Пользователь пишет `!new` или `!new Анализ конкурентов` 2. Бот создаёт новую комнату в Space 3. Сразу приглашает пользователя через `room_create(..., invite=[user_id])` 4. Регистрирует комнату в локальном состоянии и `ChatManager` 5. Пользователь переходит в новую комнату — начинает диалог ### В моке - Space и комнаты создаются реально через matrix-nio - Сообщения передаются в MockPlatformClient с `chat_id` (C1, C2...) - История хранится в Matrix нативно - Дефолтные `skills`, `safety`, `soul`, `plan` подмешиваются даже после частичных локальных обновлений настроек ### Переименование и архивирование - `!rename` обновляет имя комнаты через state event `m.room.name` - `!archive` архивирует чат в `ChatManager` и делает `room_leave(...)` - Если бот потерял локальное состояние и видит комнату как `unregistered:*`, то `!rename` и `!archive` возвращают защитное сообщение вместо сломанного действия --- ## Основной диалог ### Флоу сообщения 1. Пользователь пишет текст в комнату-чат 2. Бот показывает typing (m.typing event) 3. Запрос уходит в платформу (MockPlatformClient) 4. Бот отвечает в той же комнате ### Вложения - Файлы, изображения отправляются как Matrix media events - Бот принимает `m.file`, `m.image`, `m.audio` - Передаёт в платформу как `attachments` через `IncomingMessage` - В моке: подтверждение получения + заглушка-ответ ### Реакции как действия Matrix поддерживает реакции на сообщения (`m.reaction`). Используем это для подтверждения действий агента: ``` Агент: Хочу отправить письмо на vasya@mail.ru Тема: «Отчёт за неделю» 👍 — подтвердить ❌ — отменить ``` Пользователь ставит реакцию — бот обрабатывает. Нативно и удобно. ### Треды для длинных задач Если агент выполняет долгую задачу (deep research, генерация документа), бот создаёт тред от своего первого ответа и пишет промежуточные статусы туда. Основной чат не засоряется. ``` Бот: Начинаю исследование по теме «AI агенты 2025» [→ в треде] └── Ищу источники... (1/4) └── Анализирую статьи... (2/4) └── Формирую отчёт... (3/4) └── Готово. Отчёт: [...] ``` --- ## Настройки и диагностика Отдельной комнаты `Настройки` в текущей версии нет. Команды вызываются как обычные `!`-команды из зарегистрированных комнат бота, а `!settings` отдаёт сводный dashboard по скиллам, личности, безопасности и активным чатам. ### Коннекторы ``` !connectors — показать список !connect gmail — подключить Gmail (OAuth ссылка) !connect github — подключить GitHub !connect calendar — подключить Google Calendar !connect notion — подключить Notion !disconnect gmail — отключить ``` Статус: ``` Коннекторы: ✅ Gmail — подключён (user@gmail.com) ❌ GitHub — не подключён → !connect github ❌ Google Calendar — не подключён ❌ Notion — не подключён ``` В моке: OAuth ссылка-заглушка → «Подключено ✓» ### Скиллы ``` !skills — показать список !skill on browser — включить Browser Use !skill off browser — выключить ``` Статус: ``` Скиллы: ✅ web-search — поиск в интернете ✅ fetch-url — чтение веб-страниц ✅ email — чтение почты (требует Gmail) ❌ browser — управление браузером ❌ image-gen — генерация изображений ❌ video-gen — генерация видео ✅ files — работа с файлами ❌ calendar — календарь (требует Google Calendar) ``` В моке: состояние хранится локально. ### Личность агента ``` !soul — показать текущий SOUL.md !soul name Лямбда — задать имя агента !soul style brief — стиль: brief | friendly | formal !soul priority «разбирать почту утром» — приоритетная задача !soul reset — сбросить к дефолту ``` В моке: SOUL.md генерируется и хранится локально, агент обращается по имени. ### Безопасность ``` !safety — показать настройки !safety on email-send — требовать подтверждение перед отправкой письма !safety off calendar-create — не спрашивать для создания событий ``` Статус: ``` Подтверждение требуется для: ✅ отправка письма ✅ удаление файлов ✅ публикация в соцсетях ❌ создание события в календаре ❌ поиск в интернете ``` ### Подписка ``` !plan — показать текущий план ``` ``` Подписка: Beta (бесплатно) Токены этот месяц: 800 / 1000 ━━━━━━━━░░ 80% ``` Заглушка, реализует другая команда. ### Статус и диагностика ``` !status — состояние платформы и чатов !whoami — текущий аккаунт платформы ``` ``` Статус: Платформа: ✅ доступна Аккаунт: user@lambda.lab Активных чатов: 3 ``` --- ## FSM состояния ``` [Invite] → AuthPending → AuthConfirmed ↓ SpaceSetup → Idle (в комнате Настройки) ↓ [новая комната] → ChatCreated → Idle (в чате) ↓ ReceivingMessage → WaitingResponse → Idle ↓ WaitingReaction (confirm) → [✅/❌] → Idle ↓ LongTask → [тред со статусами] → Done → Idle ``` --- ## Стек - Python 3.11+ - matrix-nio (async) — Matrix клиент - MockPlatformClient → `platform/interface.py` - structlog для логирования - SQLite / in-memory store для хранения `matrix_user_id → platform_user_id`, состояния скиллов и маппинга `chat_id → room_id` --- ## Ограничения текущей версии - Ручной QA и текущая разработка идут только в незашифрованных комнатах - После рестарта бот делает bootstrap sync и стартует с `since`, поэтому старые события не должны переигрываться повторно - Если удалить локальную БД/стор, старые Matrix rooms останутся, но команды, завязанные на локальную регистрацию чатов, перестанут работать для этих комнат до повторного онбординга