Mikhail Putilovskij
4f5c5679d5
Remove session management concepts (no create_session/close_session/
DELETE /sessions — Master handles container lifecycle automatically).
Update PlatformClient contract, ChatContext, project structure tree,
and FSM diagrams across all docs to match the implemented core/.
- README.md: fix core/ structure tree + PlatformClient snippet
- docs/surface-protocol.md: remove session.py/_template.py, fix
ChatContext (drop session_id), fix PlatformClient contract, fix
"free features" list
- docs/telegram-prototype.md: remove "создаёт сессию на платформе"
- docs/matrix-prototype.md: same + remove !sessions, fix FSM
(SessionCreated → ChatCreated), fix status block
- docs/user-flow.md: rewrite sequence diagram to POST /users/{id}/
chats/{id}/messages; update FSM states
130 lines
6.2 KiB
Markdown
130 lines
6.2 KiB
Markdown
# Lambda Lab 3.0 — Surfaces
|
||
|
||
Команда поверхностей. Telegram и Matrix боты для взаимодействия пользователя с AI-агентом Lambda.
|
||
|
||
## Статус
|
||
|
||
Прототип в разработке. SDK платформы ещё не готов — работаем через `MockPlatformClient`.
|
||
|
||
| Поверхность | Статус | Описание |
|
||
|---|---|---|
|
||
| Telegram | 🔨 В разработке | Forum Topics: одна группа, чат = тема |
|
||
| Matrix | 🔨 В разработке | Space + комнаты: чат = отдельная комната |
|
||
|
||
---
|
||
|
||
## Концепция
|
||
|
||
Пользователь получает персонального AI-агента через привычный мессенджер.
|
||
Агент выполняет реальные задачи: разбирает почту, ищет информацию, работает с файлами, управляет календарём.
|
||
|
||
**Поверхности** — тонкие клиенты. Вся бизнес-логика на стороне платформы.
|
||
Задача команды: сделать интерфейс удобным, надёжным и легко расширяемым.
|
||
|
||
---
|
||
|
||
## Архитектура
|
||
|
||
```
|
||
surfaces-bot/
|
||
core/ — общее ядро, не зависит от транспорта
|
||
protocol.py — унифицированные структуры (IncomingMessage, OutgoingUI, ...)
|
||
handler.py — EventDispatcher: IncomingEvent → OutgoingEvent
|
||
handlers/ — обработчики по типам событий
|
||
store.py — StateStore Protocol + InMemoryStore + SQLiteStore
|
||
chat.py — ChatManager: метаданные чатов C1/C2/C3
|
||
auth.py — AuthManager: аутентификация
|
||
settings.py — SettingsManager: коннекторы, скиллы, SOUL, безопасность
|
||
|
||
adapter/
|
||
telegram/ — aiogram 3.x адаптер
|
||
matrix/ — matrix-nio адаптер
|
||
|
||
platform/
|
||
interface.py — PlatformClient Protocol (контракт к SDK)
|
||
mock.py — MockPlatformClient (заглушка)
|
||
|
||
docs/ — документация
|
||
.claude/agents/ — агенты для Claude Code
|
||
```
|
||
|
||
**Ключевой принцип:** добавить новую поверхность = написать один адаптер-конвертер.
|
||
Ядро (`core/`) не трогается. Подробнее: [`docs/surface-protocol.md`](docs/surface-protocol.md)
|
||
|
||
---
|
||
|
||
## Функционал прототипа
|
||
|
||
### Telegram ([подробнее](docs/telegram-prototype.md))
|
||
|
||
- **Чаты** — Forum Topics: бот создаёт личную группу пользователя, каждый чат = отдельная тема
|
||
- **Аутентификация** — привязка Telegram аккаунта к аккаунту платформы
|
||
- **Диалог** — typing indicator, передача файлов, подтверждение опасных действий через inline-кнопки
|
||
- **Настройки** через `/settings`: коннекторы (Gmail, GitHub, Notion...), скиллы, личность агента (SOUL), безопасность, подписка
|
||
|
||
### Matrix ([подробнее](docs/matrix-prototype.md))
|
||
|
||
- **Чаты** — Space + комнаты: бот создаёт личное пространство, каждый чат = комната
|
||
- **Аутентификация** — привязка Matrix аккаунта к аккаунту платформы
|
||
- **Диалог** — typing, файлы, подтверждение действий через реакции 👍/❌, треды для долгих задач
|
||
- **Настройки** — отдельная комната «Настройки» с командами `!connectors`, `!skills`, `!soul`, `!safety`, `!status`
|
||
|
||
---
|
||
|
||
## Замена SDK
|
||
|
||
Вся работа с платформой идёт через `PlatformClient` Protocol:
|
||
|
||
```python
|
||
class PlatformClient(Protocol):
|
||
async def get_or_create_user(self, external_id: str, platform: str, ...) -> User: ...
|
||
async def send_message(self, user_id: str, chat_id: str, text: str, ...) -> MessageResponse: ...
|
||
async def get_settings(self, user_id: str) -> UserSettings: ...
|
||
async def update_settings(self, user_id: str, action: Any) -> None: ...
|
||
```
|
||
|
||
Бот не управляет lifecycle контейнеров — это делает Master (платформа).
|
||
Бот передаёт `user_id` + `chat_id` + сообщение; платформа сама решает нужно ли поднять контейнер.
|
||
|
||
Сейчас: `MockPlatformClient` в `platform/mock.py`.
|
||
Когда SDK готов: добавляем `SdkPlatformClient`, меняем одну строку в DI. Адаптеры и ядро не трогаем.
|
||
|
||
---
|
||
|
||
## Быстрый старт
|
||
|
||
```bash
|
||
# Зависимости
|
||
uv sync # или: pip install -e ".[dev]"
|
||
|
||
# Тесты
|
||
pytest tests/ -v
|
||
|
||
# Запустить Telegram бота
|
||
cp .env.example .env # заполнить TELEGRAM_BOT_TOKEN
|
||
python -m adapter.telegram.bot
|
||
|
||
# Запустить Matrix бота
|
||
cp .env.example .env # заполнить MATRIX_* переменные
|
||
python -m adapter.matrix.bot
|
||
```
|
||
|
||
---
|
||
|
||
## Документация
|
||
|
||
| Файл | Содержание |
|
||
|---|---|
|
||
| [`docs/surface-protocol.md`](docs/surface-protocol.md) | Унификация поверхностей — все структуры, как добавить новую поверхность |
|
||
| [`docs/telegram-prototype.md`](docs/telegram-prototype.md) | Функционал Telegram прототипа |
|
||
| [`docs/matrix-prototype.md`](docs/matrix-prototype.md) | Функционал Matrix прототипа |
|
||
| [`docs/api-contract.md`](docs/api-contract.md) | Контракт к SDK платформы |
|
||
| [`docs/user-flow.md`](docs/user-flow.md) | FSM и user journey |
|
||
| [`docs/claude-code-guide.md`](docs/claude-code-guide.md) | Гайд по работе с Claude Code |
|
||
|
||
---
|
||
|
||
## Команда
|
||
|
||
Поверхности и интеграции
|
||
Lambda Lab 3.0, МАИ
|