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>
2026-03-27 00:35:42 +03:00 · 2026-03-27 00:35:42 +03:00 · b6df29bd9b
commit b6df29bd9b
29 changed files with 2504 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,127 @@
+# 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           — логика: IncomingEvent → OutgoingEvent
+    session.py           — управление сессиями и чатами
+    auth.py              — аутентификация
+    settings.py          — коннекторы, скиллы, 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(...) -> User: ...
+    async def create_session(...) -> Session: ...
+    async def send_message(...) -> AgentResponse: ...
+    async def close_session(...) -> None: ...
+    async def get_settings(...) -> UserSettings: ...
+    async def update_settings(...) -> None: ...
+```
+
+Сейчас: `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, МАИ