# Matrix — описание прототипа

## Концепция

Один бот, каждый чат — отдельная комната, все комнаты собраны в personal Space.

При первом invite бот создаёт для пользователя личное пространство (Space) и первую рабочую комнату.
История хранится нативно в Matrix. UX прагматичный: явные `!`-команды, локальный state-store, нативные Matrix rooms.

Matrix — внутренняя поверхность: команда лаборатории, тестировщики, разработчики скиллов.

---

## Онбординг

1. Пользователь приглашает бота в личные сообщения (DM) на Matrix-сервере
2. Бот принимает invite, создаёт Space `Lambda — {display_name}` и первую комнату `Чат 1`
3. Приглашает пользователя в `Чат 1` и пишет приветствие
4. Дальнейшее общение ведётся в рабочих комнатах, не в DM

```
Space: «Lambda — {display_name}»
  ├── 💬 Чат 1              ← создаётся автоматически при invite
  ├── 💬 Чат 2
  └── 💬 Исследование рынка ← пользователь называет сам через !new
```

**Требование:** незашифрованные комнаты. E2EE не поддержан (инфраструктурное ограничение).

---

## Работающие команды

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

| Команда | Действие |
|---|---|
| `!new` | Создать новый чат (новую комнату в Space) |
| `!new Название` | Создать чат с именем |
| `!chats` | Список активных чатов |
| `!rename <название>` | Переименовать текущую комнату |
| `!archive` | Архивировать чат |
| `!help` | Справка |

### Контекст

| Команда | Действие |
|---|---|
| `!clear` | Сбросить контекст текущего чата (создаёт новый thread у агента) |
| `!reset` | Псевдоним для `!clear` |

### Подтверждения

| Команда | Действие |
|---|---|
| `!yes` | Подтвердить действие агента |
| `!no` | Отменить действие агента |

### Вложения (файловая очередь)

Matrix-клиенты отправляют файлы и текст отдельными событиями. Файл без текстовой инструкции ставится в очередь, а не уходит агенту сразу.

| Команда | Действие |
|---|---|
| `!list` | Показать файлы в очереди |
| `!remove <n>` | Удалить файл из очереди по номеру |
| `!remove all` | Очистить всю очередь |

Как отправить файлы агенту:
1. Отправь один или несколько файлов в рабочую комнату
2. Напиши текстовое сообщение с инструкцией, например: `что на изображении?`
3. Бот отправит агенту текст вместе со всеми файлами из очереди

---

## Диалог

- Любое текстовое сообщение уходит агенту, бот показывает typing-индикатор
- Ответ стримится по WebSocket и выводится в ту же комнату
- Каждая комната имеет свой `platform_chat_id` — контексты изолированы между комнатами

---

## Передача файлов

### Пользователь → Агент
Бот сохраняет файл в shared volume: `{workspace_path}/{filename}`
и передаёт агенту относительный путь как `workspace_path`.

### Агент → Пользователь
Агент эмитит путь к файлу в своём workspace. Бот читает файл из `/agents/...`
и отправляет пользователю как Matrix file message.

---

## Известные ограничения

| Проблема | Причина |
|---|---|
| `!save` / `!load` / `!context` | Нестабильны: `!save` зависит от агента (пишет файл в workspace), сессии хранятся in-memory и теряются при рестарте |
| Первый чанк ответа иногда пропадает после tool/file flow | Баг в upstream `platform-agent`; подробности: `docs/reports/2026-04-22-platform-streaming-final-bug-report-ru.md` |
| Персистентность истории между рестартами агента | `platform-agent` использует `MemorySaver` (in-memory) |
| E2EE комнаты | `python-olm` не собирается на macOS/ARM |
| `!settings` и настройки скиллов/SOUL/безопасности | Заглушки MVP, требуют готового SDK платформы |