280 lines
16 KiB
Markdown
280 lines
16 KiB
Markdown
# Отчёт о проделанной работе — Surfaces Team
|
||
|
||
**Проект:** Lambda Lab 3.0 — Surfaces
|
||
**Дата:** 2026-04-01
|
||
**Период:** 2026-03-28 — 2026-04-01
|
||
|
||
---
|
||
|
||
## 1. Цель этапа
|
||
|
||
Собрать работоспособный прототип двух поверхностей для взаимодействия пользователя с AI-агентом Lambda:
|
||
|
||
- **Telegram-бот** — основная пользовательская поверхность
|
||
- **Matrix-бот** — альтернативная децентрализованная поверхность
|
||
|
||
Ключевое требование: не ждать готовности платформенного SDK, а двигаться вперёд через собственный контракт и мок-реализацию. Это позволило вести параллельную разработку UX, архитектуры и интеграции без блокировки на внешние зависимости.
|
||
|
||
---
|
||
|
||
## 2. Архитектура
|
||
|
||
### 2.1. Общее ядро (`core/`)
|
||
|
||
Выделен независимый от транспорта слой, используемый обеими поверхностями:
|
||
|
||
| Компонент | Файл | Назначение |
|
||
|-----------|------|-----------|
|
||
| Протокол событий | `core/protocol.py` | `IncomingMessage`, `OutgoingMessage`, `OutgoingUI` и др. |
|
||
| Диспетчер | `core/handler.py` | `EventDispatcher`: маршрутизация событий → обработчики |
|
||
| Обработчики | `core/handlers/` | `start`, `message`, `chat`, `settings`, `callback` |
|
||
| Хранилище состояний | `core/store.py` | `InMemoryStore`, `SQLiteStore` |
|
||
| Менеджмент чатов | `core/chat.py` | `ChatManager` |
|
||
| Аутентификация | `core/auth.py` | `AuthManager` |
|
||
| Настройки | `core/settings.py` | `SettingsManager` |
|
||
|
||
Telegram и Matrix — тонкие адаптеры: принимают транспортные события, конвертируют в формат ядра, передают в `core`, рендерят ответ обратно.
|
||
|
||
### 2.2. Платформенный контракт (`sdk/`)
|
||
|
||
Вместо ожидания SDK Lambda зафиксирован собственный контракт:
|
||
|
||
- `sdk/interface.py` — Protocol: `PlatformClient`, `WebhookReceiver`
|
||
- `sdk/mock.py` — `MockPlatformClient` (заглушка с симулируемой латентностью)
|
||
|
||
При подключении реального SDK заменяется только `sdk/mock.py` — core и адаптеры не трогаются.
|
||
|
||
> **Примечание:** в процессе работы директория `platform/` была переименована в `sdk/` для устранения конфликта имён со стандартной библиотекой Python (`platform.python_implementation`). Все импорты обновлены.
|
||
|
||
### 2.3. Структура репозитория
|
||
|
||
```
|
||
surfaces-bot/
|
||
core/ — общее ядро
|
||
sdk/ — платформенный контракт и мок
|
||
adapter/
|
||
telegram/ — Telegram-адаптер (worktree: feat/telegram-adapter)
|
||
matrix/ — Matrix-адаптер (в main)
|
||
docs/
|
||
superpowers/
|
||
specs/ — утверждённые спецификации
|
||
plans/ — планы реализации
|
||
research/ — исследования API и архитектурных вариантов
|
||
reports/ — отчёты
|
||
tests/ — pytest (70 тестов)
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Telegram: итоги
|
||
|
||
### 3.1. Что реализовано
|
||
|
||
**Базовый DM-режим (полностью работает):**
|
||
|
||
| Функция | Команда/механизм |
|
||
|---------|-----------------|
|
||
| Онбординг | `/start` — создание первого чата, восстановление сессии |
|
||
| Создание чатов | `/new [название]` |
|
||
| Список чатов | `/chats` — инлайн-кнопки с переключением |
|
||
| Диалог | Любое сообщение → мок-ответ `[MOCK] Ответ на: «...»` |
|
||
| Typing indicator | `send_chat_action("typing")` + обновление каждые 4 сек |
|
||
| Настройки | `/settings` → меню: скиллы, личность агента, безопасность, подписка |
|
||
| Подтверждения | `confirm:yes/<id>` / `confirm:no/<id>` через `InlineKeyboard` |
|
||
| Список команд | Зарегистрирован через `set_my_commands()` |
|
||
| Вложения | Конвертируются в `Attachment` (фото, документ, голос) |
|
||
|
||
**Forum Topics режим (реализован поверх DM):**
|
||
|
||
| Функция | Описание |
|
||
|---------|----------|
|
||
| Подключение группы | `/forum` → FSM онбординг → пересылка сообщения из супергруппы |
|
||
| Проверка прав | Бот должен быть администратором с `can_manage_topics` |
|
||
| Синхронизация | При подключении группы создаются темы для всех DM-чатов |
|
||
| Регистрация темы | `/new` в forum-теме регистрирует её как чат |
|
||
| Создание с синхронизацией | `/new` в DM + подключённая группа → создаёт и DM-чат, и forum-тему |
|
||
| Маршрутизация | Пришло из DM → ответ в DM с тегом `[Чат #N]`; из темы → ответ в тему без тега |
|
||
|
||
**Ключевые принятые решения:**
|
||
- Основной режим — виртуальные чаты в DM (нулевое friction)
|
||
- Forum Topics — opt-in advanced mode, не обязательный
|
||
- Бот не создаёт группы сам (Telegram Bot API не позволяет)
|
||
- Один контекст (`chat_id` = UUID) для обеих поверхностей
|
||
|
||
### 3.2. Техническая реализация
|
||
|
||
```
|
||
adapter/telegram/
|
||
bot.py — Dispatcher, DispatcherMiddleware, регистрация роутеров
|
||
states.py — ChatState, SettingsState, ForumSetupState
|
||
db.py — SQLite: tg_users + chats (включая forum_group_id, forum_thread_id)
|
||
converter.py — from_message(), is_forum_message(), resolve_forum_chat_id()
|
||
handlers/
|
||
auth.py — /start
|
||
chat.py — сообщения, /new, /chats, forum-маршрутизация
|
||
settings.py — /settings, скиллы, личность, безопасность, подписка
|
||
confirm.py — подтверждение действий агента
|
||
forum.py — /forum, онбординг, регистрация группы
|
||
keyboards/
|
||
chat.py — список чатов
|
||
settings.py — меню настроек, скиллы, безопасность
|
||
confirm.py — кнопки ✅/❌
|
||
```
|
||
|
||
**Исправленные баги:**
|
||
- Команды (`/new`, `/settings` и др.) обрабатывались как обычные сообщения — исправлено фильтром `~F.text.startswith("/")`
|
||
- Конфликт `platform/` с stdlib Python — устранён переименованием в `sdk/`
|
||
|
||
### 3.3. Документация
|
||
|
||
- Спецификация DM-режима: `docs/superpowers/specs/2026-03-31-telegram-adapter-design.md`
|
||
- Спецификация Forum Topics: `docs/superpowers/specs/2026-03-31-forum-topics-design.md`
|
||
- План реализации Forum Topics: `docs/superpowers/plans/2026-03-31-forum-topics.md`
|
||
- Исследования: `docs/research/telegram-chat-alternatives.md`, `docs/research/telegram-forum-topics.md`
|
||
|
||
### 3.4. Открытые задачи
|
||
|
||
- Edge-cases forum synchronization (частично закрыты агентами после лимита)
|
||
- Ручной QA форум-сценариев
|
||
- Слияние `feat/telegram-adapter` → `main`
|
||
|
||
---
|
||
|
||
## 4. Matrix: итоги
|
||
|
||
### 4.1. Что реализовано
|
||
|
||
- Matrix bot entrypoint (`adapter/matrix/bot.py`)
|
||
- Converter layer (Matrix events → `IncomingEvent`)
|
||
- Room metadata store
|
||
- Маршрутизация входящих событий
|
||
- Обработка реакций
|
||
- Обработка приглашений (invite → DM onboarding)
|
||
- Platform-aware command hints (`/start` для Telegram, `!start` для Matrix)
|
||
- Модель room-per-chat: команда `!new` создаёт **реальную Matrix room**
|
||
|
||
### 4.2. Архитектурный сдвиг: Space-first → DM-first
|
||
|
||
Изначально рассматривалась модель Space-first (персональный Space + settings-room + отдельные комнаты внутри Space). По ходу реализации выбран более прагматичный первый этап:
|
||
|
||
- **DM-first onboarding**: пользователь приглашает бота → бот приветствует → первый контекст привязывается к C1
|
||
- **Room-per-chat**: `!new` создаёт реальную Matrix room, бот приглашает пользователя
|
||
|
||
Это соответствует принципу: каждый чат — отдельная сущность транспорта, не только внутренняя запись.
|
||
|
||
### 4.3. Критические баги, исправленные в ходе работы
|
||
|
||
| Баг | Причина | Исправление |
|
||
|-----|---------|-------------|
|
||
| Бот не принимал invite | Подписка только на `RoomMemberEvent` | Добавлена поддержка `InviteMemberEvent` |
|
||
| Бот отвечал сам себе (цикл) | Нет фильтра собственных сообщений | События от `self.client.user_id` игнорируются |
|
||
| Дублирование приветствия | Неидемпотентный invite flow | Room onboarding сделан идемпотентным |
|
||
| Агрессивные timeout/retry | Настройки sync по умолчанию | Настроен `AsyncClientConfig` |
|
||
| Telegram-ориентированные команды | Тексты в ядре не учитывали платформу | Platform-aware hints в core |
|
||
|
||
### 4.4. Тесты Matrix
|
||
|
||
Собран и проходит набор тестов:
|
||
- converter tests
|
||
- dispatcher tests
|
||
- reactions tests
|
||
- store tests
|
||
- интеграционные тесты core-сценариев
|
||
|
||
Покрытые сценарии: разбор команд `!new`, `!skills`, `!yes`, `!no`; invite onboarding; защита от self-loop; создание реальной Matrix room; mapping `room_id → chat_id`.
|
||
|
||
### 4.5. Ограничение: Matrix E2EE
|
||
|
||
Шифрование (E2EE) в текущей реализации не поддержано. Причина — внешняя:
|
||
|
||
- `matrix-nio` требует `python-olm` для E2EE
|
||
- сборка `python-olm` не воспроизводится на текущей macOS/ARM среде
|
||
|
||
Текущий рабочий сценарий: **только незашифрованные комнаты**. E2EE — отдельная инфраструктурная задача.
|
||
|
||
### 4.6. Документация
|
||
|
||
- Спецификация: `docs/superpowers/specs/2026-03-31-matrix-adapter-design.md`
|
||
- План реализации: `docs/superpowers/plans/2026-03-31-matrix-adapter.md`
|
||
|
||
---
|
||
|
||
## 5. Тесты
|
||
|
||
```
|
||
tests/
|
||
core/ — 46 тестов (EventDispatcher, ChatManager, AuthManager, SettingsManager, stores)
|
||
platform/ — 5 тестов (MockPlatformClient)
|
||
adapter/ — 3 теста (forum DB functions) [в процессе]
|
||
|
||
Итого: 70 passed, 3 errors (ошибки — проблема пути импорта в CI, не логики)
|
||
```
|
||
|
||
---
|
||
|
||
## 6. Отклонения от исходного плана
|
||
|
||
| Аспект | Исходный план | Фактическое решение | Причина |
|
||
|--------|--------------|-------------------|---------|
|
||
| Telegram Forum | Бот создаёт группу сам | Пользователь создаёт, бот подключается | Telegram Bot API не позволяет создавать группы |
|
||
| Matrix UX | Space-first | DM-first + room-per-chat | Быстрее работает, проще в отладке |
|
||
| Платформенный слой | `platform/` | `sdk/` | Конфликт имён с stdlib Python |
|
||
| Matrix E2EE | В области применения | Вынесено как отдельная задача | Инфраструктурный блокер (python-olm) |
|
||
|
||
Все изменения — корректная инженерная адаптация, не регресс.
|
||
|
||
---
|
||
|
||
## 7. Текущий статус по направлениям
|
||
|
||
| Направление | Статус | Примечание |
|
||
|-------------|--------|-----------|
|
||
| `core/` | ✅ Готово | Полное покрытие тестами |
|
||
| `sdk/` (mock) | ✅ Готово | Замена на реальный SDK — замена одного файла |
|
||
| Telegram DM-режим | ✅ Готово | Можно тестировать руками |
|
||
| Telegram Forum Topics | ✅ Реализовано | Требует ручного QA |
|
||
| Matrix adapter | ✅ Готово | В `main` |
|
||
| Matrix E2EE | ⏸ Заблокировано | Инфраструктурный блокер |
|
||
| Слияние Telegram ветки | 🔄 В процессе | `feat/telegram-adapter` → `main` |
|
||
|
||
---
|
||
|
||
## 8. Риски
|
||
|
||
| Риск | Уровень | Митигация |
|
||
|------|---------|-----------|
|
||
| Matrix E2EE | Средний | Работаем с незашифрованными комнатами, E2EE — отдельный тикет |
|
||
| Forum sync edge-cases | Низкий | Базовый сценарий работает, edge-cases в backlog |
|
||
| Реальный SDK vs мок | Низкий | Контракт зафиксирован, замена изолирована в `sdk/mock.py` |
|
||
|
||
---
|
||
|
||
## 9. Следующие шаги
|
||
|
||
**Ближайшие:**
|
||
1. Ручной QA Telegram Forum Topics
|
||
2. Слияние `feat/telegram-adapter` → `main`
|
||
3. Ручной QA Matrix-бота (issue `#14`)
|
||
|
||
**Среднесрочные:**
|
||
1. Расширить покрытие тестами (adapter-level)
|
||
2. Довести Matrix settings workflow
|
||
3. Актуализировать `docs/api-contract.md`
|
||
|
||
**Стратегические:**
|
||
1. Подготовить замену `MockPlatformClient` → реальный SDK Lambda
|
||
2. Довести обе поверхности до demo-ready состояния
|
||
3. Отдельно решить Matrix E2EE (инфраструктура)
|
||
|
||
---
|
||
|
||
## 10. Вывод
|
||
|
||
За текущий этап команда собрала работающий каркас двух поверхностей вокруг единого ядра и собственного платформенного контракта.
|
||
|
||
**Практический итог:**
|
||
- Telegram в стадии реального UX-прототипа — можно демонстрировать
|
||
- Matrix имеет рабочий transport-слой и модель комнат
|
||
- Архитектура устойчива и готова к замене мока на реальный SDK
|
||
|
||
Проект движется по инженерной логике: исследование ограничений → адаптация архитектуры → фиксация решений → реализация. Не по формальному чеклисту.
|