init: surfaces-bot — Telegram & Matrix prototype
- Surface Protocol: unified IncomingMessage/OutgoingUI/ChatContext - Telegram: Forum Topics (group + topics per chat) - Matrix: Space + rooms per chat - MockPlatformClient with PlatformClient Protocol - docs: surface-protocol, telegram/matrix specs, api-contract, claude-code-guide - project scaffold: src/, tests/, pyproject.toml Co-Authored-By: Claude Sonnet 4-6 <noreply@anthropic.com>
This commit is contained in:
commit
b6df29bd9b
29 changed files with 2504 additions and 0 deletions
250
docs/matrix-prototype.md
Normal file
250
docs/matrix-prototype.md
Normal file
|
|
@ -0,0 +1,250 @@
|
|||
# Matrix — описание прототипа
|
||||
|
||||
## Концепция
|
||||
|
||||
Один бот, каждый чат — отдельная комната, все комнаты собраны в Space.
|
||||
|
||||
При первом входе бот создаёт для пользователя личное пространство (Space) —
|
||||
это как папка в Element. Внутри Space бот создаёт комнату для каждого нового
|
||||
чата с агентом. Пользователь видит аккуратную структуру: одно пространство,
|
||||
внутри — список чатов. История хранится нативно в Matrix — это часть протокола,
|
||||
ничего дополнительно делать не нужно.
|
||||
|
||||
Matrix выбран как внутренняя поверхность: команды лаборатории, тестировщики,
|
||||
разработчики скиллов. Поэтому UX здесь — про удобство работы, а не онбординг.
|
||||
|
||||
---
|
||||
|
||||
## Аутентификация
|
||||
|
||||
### Флоу
|
||||
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. Создаёт комнату `Настройки` (закреплена вверху)
|
||||
3. Создаёт первую комнату-чат `Чат 1`
|
||||
4. Приглашает пользователя во все комнаты
|
||||
5. Пишет в `Чат 1` приветствие
|
||||
|
||||
### Управление чатами
|
||||
Команды работают в любой комнате Space:
|
||||
|
||||
| Команда | Действие |
|
||||
|---|---|
|
||||
| `!new` | Создать новый чат (новую комнату в Space) |
|
||||
| `!new Название` | Создать чат с именем |
|
||||
| `!rename Название` | Переименовать текущую комнату |
|
||||
| `!archive` | Вывести комнату из Space (не удалять) |
|
||||
| `!chats` | Показать список чатов |
|
||||
|
||||
### Создание нового чата
|
||||
1. Пользователь пишет `!new` или `!new Анализ конкурентов`
|
||||
2. Бот создаёт новую комнату в Space
|
||||
3. Приглашает пользователя
|
||||
4. Пишет приветствие и создаёт сессию на платформе
|
||||
5. Пользователь переходит в новую комнату — начинает диалог
|
||||
|
||||
### В моке
|
||||
- Space и комнаты создаются реально через matrix-nio
|
||||
- Сессии — через MockPlatformClient
|
||||
- История хранится в Matrix нативно
|
||||
|
||||
---
|
||||
|
||||
## Основной диалог
|
||||
|
||||
### Флоу сообщения
|
||||
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)
|
||||
└── Готово. Отчёт: [...]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Комната «Настройки»
|
||||
|
||||
Специальная комната для управления агентом. Закреплена вверху Space.
|
||||
Команды работают только здесь — не мешают диалогу в чатах.
|
||||
|
||||
### Коннекторы
|
||||
```
|
||||
!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 — состояние агента и платформы
|
||||
!sessions — список активных сессий
|
||||
!whoami — текущий аккаунт платформы
|
||||
```
|
||||
|
||||
```
|
||||
Статус:
|
||||
Платформа: ✅ доступна
|
||||
Агент: ✅ активен (сессия #abc123)
|
||||
Аккаунт: user@lambda.lab
|
||||
Активных чатов: 3
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## FSM состояния
|
||||
|
||||
```
|
||||
[Invite] → AuthPending → AuthConfirmed
|
||||
↓
|
||||
SpaceSetup → Idle (в комнате Настройки)
|
||||
↓
|
||||
[новая комната] → SessionCreated → Idle (в чате)
|
||||
↓
|
||||
ReceivingMessage → WaitingResponse → Idle
|
||||
↓
|
||||
WaitingReaction (confirm) → [✅/❌] → Idle
|
||||
↓
|
||||
LongTask → [тред со статусами] → Done → Idle
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Стек
|
||||
|
||||
- Python 3.11+
|
||||
- matrix-nio (async) — Matrix клиент
|
||||
- MockPlatformClient → `platform/interface.py`
|
||||
- structlog для логирования
|
||||
- SQLite для хранения `matrix_user_id → platform_user_id`, состояния скиллов, маппинга `chat_id → room_id`
|
||||
Loading…
Add table
Add a link
Reference in a new issue