surfaces/docs/reports/2026-04-01-surfaces-progress-report.md

# Отчёт о проделанной работе

**Проект:** Lambda Lab 3.0 — Surfaces  
**Команда:** Surfaces Team  
**Дата:** 2026-04-01  
**Период отчёта:** текущий этап разработки прототипов Telegram и Matrix  

---

## 1. Цель этапа

Целью текущего этапа было собрать работоспособный прототип двух поверхностей для взаимодействия пользователя с AI-агентом Lambda:

- Telegram-бота
- Matrix-бота

При этом важным требованием было не ждать готовности платформенного SDK, а сразу строить систему вокруг собственного контракта и мок-реализации платформы. Это позволило параллельно двигаться по UX, архитектуре и интеграционным сценариям, не блокируясь внешними зависимостями.

---

## 2. Что было сделано на уровне архитектуры

### 2.1. Сформировано общее ядро

В репозитории выделено общее `core/`, которое не зависит от конкретного транспорта и используется обеими поверхностями.

Реализованы:

- единый протокол событий и ответов
- диспетчеризация входящих событий через `EventDispatcher`
- менеджмент чатов
- менеджмент аутентификации
- менеджмент настроек
- общее state-хранилище (`InMemoryStore`, `SQLiteStore`)

Это позволило построить Telegram и Matrix как тонкие адаптеры, которые:

- принимают события транспорта
- конвертируют их в единый формат ядра
- передают в `core`
- рендерят результат обратно в транспорт

### 2.2. Зафиксирован платформенный контракт

Вместо ожидания готового SDK был введён собственный контракт через:

- [`sdk/interface.py`](/Users/a/MAI/sem2/lambda/surfaces-bot/sdk/interface.py)
- [`sdk/mock.py`](/Users/a/MAI/sem2/lambda/surfaces-bot/sdk/mock.py)

За счёт этого:

- UX и интеграционный слой можно развивать уже сейчас
- реальные платформенные вызовы можно позже подключить заменой одной реализации
- транспортные адаптеры и `core` не придётся переписывать

### 2.3. Уточнена текущая архитектурная стратегия

По ходу работы часть исходных планов была пересмотрена и адаптирована под реальные ограничения платформ и API.

Ключевые изменения:

- `platform/` был переименован в `sdk/` для устранения конфликта имён и более точного смысла слоя
- Telegram ушёл от идеи автоматического создания групп ботом: Bot API этого не позволяет
- Matrix ушёл от Space-first реализации к DM-first / room-first модели как к более реалистичному первому рабочему этапу

---

## 3. Telegram: текущее состояние

### 3.1. Организация разработки

Telegram-часть выделена в отдельный worktree:

- ветка: `feat/telegram-adapter`

Это позволило вести Telegram независимо от Matrix и не смешивать контексты разработки.

### 3.2. Что реализовано

В Telegram-адаптере уже собран рабочий базовый UX:

- стартовый onboarding через `/start`
- основной диалог в DM
- создание новых чатов
- список чатов и переключение между ними
- меню настроек
- подтверждение действий через inline-кнопки
- базовая работа с вложениями

Отдельно реализован **Forum Topics mode** как расширение поверх DM-сценария:

- команда `/forum`
- подключение уже существующей forum-group через пересланное сообщение
- проверка, что бот является администратором с правом управления темами
- синхронизация существующих локальных чатов с forum topics
- routing сообщений из topic обратно в нужный chat context
- routing confirm callbacks внутри topic

### 3.3. Принятые продуктовые решения

Во время разработки были приняты важные решения по UX Telegram:

- основным пользовательским сценарием остаётся DM-first
- Forum Topics не являются обязательным режимом, а выступают как advanced mode
- контекст чатов должен синхронизироваться между DM и topic-представлением
- пользователь не должен сталкиваться с невозможной автоматизацией создания групп со стороны бота

### 3.4. Что ещё не закрыто

Для Telegram остаются открытые задачи, в первую очередь в области polish и согласованности UX:

- не все сценарии forum synchronization доведены до конца
- есть оставшиеся вопросы по командам в topic-контексте
- нужен дополнительный проход по UX-деталям и ручному QA

Актуальный follow-up зафиксирован в issue:

- `#15` Telegram forum topics: remaining UX and synchronization gaps

---

## 4. Matrix: текущее состояние

### 4.1. Что реализовано

В `main` уже добавлен Matrix-адаптер, включающий:

- Matrix bot entrypoint
- converter layer
- room metadata store
- routing входящих событий
- обработку реакций
- обработку приглашения в DM
- базовый onboarding
- platform-aware command hints
- набор adapter-level тестов

### 4.2. Главный архитектурный сдвиг

Изначально Matrix рассматривался через модель:

- персональный Space
- settings-room
- отдельные room-чаты внутри Space

Однако по ходу реализации был выбран более прагматичный маршрут первого этапа:

- **DM-first onboarding**
- затем **room-per-chat**

Текущее поведение:

- пользователь приглашает бота в комнату
- бот приветствует пользователя
- первый контекст привязывается к `C1`
- команда `!new` создаёт **реальную новую Matrix room**
- бот приглашает пользователя в эту новую комнату

Это уже соответствует целевому принципу:

> новый чат пользователя должен быть отдельной сущностью транспорта, а не только внутренней записью в `core`

### 4.3. Критические баги, которые были обнаружены и исправлены

Во время ручной проверки Matrix были найдены и устранены несколько важных проблем:

1. **бот не принимал invite корректно**
   - причина: подписка только на `RoomMemberEvent`
   - исправление: добавлена поддержка `InviteMemberEvent`

2. **бот отвечал сам себе и уходил в цикл**
   - симптом: спам приветствиями и сообщениями типа `Введите !start`
   - причина: отсутствие фильтра собственных сообщений
   - исправление: события от `self.client.user_id` теперь игнорируются

3. **дублировалось стартовое приветствие**
   - причина: invite-flow был неидемпотентным
   - исправление: room onboarding сделан идемпотентным

4. **слишком агрессивные timeout/retry при sync**
   - исправление: настроен более мягкий transport config через `AsyncClientConfig`

5. **команды и подсказки были Telegram-ориентированными**
   - исправление: тексты в ядре стали platform-aware (`/start` для Telegram, `!start` для Matrix)

### 4.4. Что подтверждено тестами

Для Matrix собран и пройден набор тестов:

- converter tests
- dispatcher tests
- reactions tests
- store tests
- интеграционные тесты core-сценариев

Примеры покрытых сценариев:

- разбор команд `!new`, `!skills`, `!yes`, `!no`
- invite onboarding
- защита от self-loop
- создание реальной Matrix room на `!new`
- mapping `room_id -> chat_id`

### 4.5. Ограничение текущей реализации

Главное незакрытое ограничение Matrix на текущий момент:

## encrypted DM пока не поддержан

Причина не в логике бота, а во внешнем crypto-stack:

- для E2EE в `matrix-nio` нужен `python-olm`
- на текущей macOS/ARM среде сборка `python-olm` не воспроизводится корректно
- поэтому в рабочем сценарии Matrix пока используется **только незашифрованный room flow**

Это означает:

- незашифрованные комнаты и room-per-chat можно развивать и тестировать уже сейчас
- encrypted DM нужно рассматривать как отдельную инфраструктурную подзадачу

### 4.6. Что ещё остаётся по Matrix

Открытые направления:

- ручной QA текущего Matrix-бота
- доработка UX и edge-cases room-per-chat
- дальнейшее развитие settings-команд
- возможное возвращение к Space lifecycle как следующему этапу
- отдельный infrastructure task по E2EE / `python-olm`

Для ручного тестирования создан issue:

- `#14` Manual QA: test Matrix bot and record issues / gaps

---

## 5. Что было сделано с точки зрения git и процесса

### 5.1. Основные изменения были оформлены коммитами

На текущем этапе были сделаны и запушены в репозиторий следующие ключевые коммиты:

- `82eb711` — базовый Matrix adapter + platform-aware command hints
- `14c091b` — реальное создание новых Matrix rooms на `!new`
- `6a843e8` — transport timeout tuning для Matrix sync
- `27f3da8` — обновление README под фактическую архитектуру проекта

### 5.2. Проведён аудит backlog

По открытым issue был выполнен аудит:

- закрыты уже выполненные задачи
- устаревшие issue переписаны под текущую архитектуру
- не выполненные и актуальные задачи оставлены открытыми

В частности:

- закрыт issue `#13` по Matrix research
- актуализированы старые Telegram и Matrix issue под текущие реальные пути, ограничения и UX-модель

---

## 6. Что изменилось по сравнению с изначальным планом

Это важный блок для руководителя: проект движется не просто по “чеклисту задач”, а по реальным ограничениям платформ.

### 6.1. Telegram

Изначально планировался сценарий, где бот создаёт Forum-группу сам.

Фактический результат исследования и реализации показал:

- Telegram Bot API этого не позволяет
- группа создаётся пользователем вручную
- бот подключается к уже существующей группе

Это не регресс, а корректная адаптация архитектуры под реальные ограничения API.

### 6.2. Matrix

Изначально планировался Space-first UX.

Фактически первым рабочим этапом стала модель:

- DM-first onboarding
- затем room-per-chat

Причина:

- так можно получить работающий transport flow раньше
- это проще в отладке
- это не блокирует дальнейший переход к Space lifecycle

### 6.3. Платформенный слой

Изначально существовали старые пути и слои, которые затем были пересобраны в более понятную форму.

Итоговое направление:

- `sdk/interface.py`
- `sdk/mock.py`
- `core/` как единый уровень бизнес-логики
- transport adapters отдельно

Это повысило устойчивость архитектуры и упростило дальнейшую замену mock на реальный SDK.

---

## 7. Основные результаты этапа

К концу текущего этапа проект достиг следующих результатов:

### Telegram

- есть рабочий Telegram adapter
- реализован основной DM flow
- реализован Forum Topics mode
- собрана отдельная ветка/worktree под Telegram
- основные пользовательские сценарии уже можно проверять руками

### Matrix

- есть рабочий Matrix adapter
- invite/onboarding flow уже функционирует
- реализована модель room-per-chat
- устранены основные критические баги цикла и self-processing
- собран базовый test suite

### Общий уровень проекта

- ядро и контракты унифицированы
- backlog приведён в соответствие с реальной архитектурой
- README актуализирован под текущее состояние
- ручной QA Matrix вынесен в отдельную управляемую задачу

---

## 8. Текущие риски и ограничения

### Технические риски

1. **Matrix E2EE**
   - blocked внешним crypto-stack
   - не решается только правками Python-кода в проекте

2. **Telegram forum synchronization**
   - функциональность уже есть, но остаются edge-cases и UX-недоработки

3. **Расхождение старых документов и новых решений**
   - backlog уже частично синхронизирован
   - но часть старых design assumptions всё ещё может встречаться в документации

### Процессные риски

1. требуется более строгий feature-branch workflow для следующих этапов Matrix
2. для Telegram и Matrix желательно продолжать раздельную работу по веткам/worktree
3. ручной QA остаётся критичным, особенно для Matrix transport behavior

---

## 9. Следующие шаги

### Ближайшие

1. Провести ручной QA Matrix-бота по issue `#14`
2. Зафиксировать воспроизводимые проблемы Matrix
3. Продолжить Telegram в worktree `feat/telegram-adapter`
4. Довести Telegram forum synchronization gaps по issue `#15`

### Среднесрочные

1. Расширить покрытие тестами
2. Довести Matrix settings workflow
3. Уточнить и обновить `docs/api-contract.md`
4. Отдельно решить вопрос Matrix E2EE support

### Стратегические

1. Подготовить замену `MockPlatformClient` на реальный SDK
2. Довести обе поверхности до более стабильного demo-ready состояния
3. Выровнять UX Telegram и Matrix вокруг общих принципов surface protocol

---

## 10. Краткий вывод для руководителя

На текущем этапе команда не просто написала часть кода, а уже собрала работающий каркас двух поверхностей вокруг общего ядра и собственного платформенного контракта.

Главный практический результат:

- Telegram уже находится в стадии реального UX-прототипа
- Matrix уже имеет рабочий transport-слой и модель отдельных комнат для чатов
- архитектура проекта стала значительно устойчивее и ближе к реальной интеграции с платформой

При этом команда корректно адаптировала исходные планы под реальные ограничения Telegram Bot API и Matrix ecosystem, не пытаясь “продавить” заведомо неверные решения.

То есть проект движется не по формальному чеклисту, а по зрелой инженерной логике:

- исследование
- фиксация архитектурных решений
- рабочая реализация
- ручной QA
- корректировка backlog под фактическое состояние системы

Это хороший признак для дальнейшего перехода от прототипа к более устойчивой демонстрационной версии.


## 8. Дополнение: итоги отдельной Telegram-сессии по Forum Topics

В рамках отдельной рабочей сессии в Telegram worktree `feat/telegram-adapter` был проведён focused pass по качеству и устойчивости **Forum Topics mode**. Целью этой работы было не просто добавить функциональность, а довести forum-сценарии до состояния, в котором их можно стабильно демонстрировать, вручную тестировать и развивать дальше без постоянных расхождений между UX, кодом и документацией.

### 8.1. Что было выявлено в начале сессии

При аудите Telegram-ветки подтвердилось, что базовая реализация уже существует:

- Telegram adapter реализован
- Forum Topics mode уже добавлен
- `/forum` onboarding присутствует
- forum thread routing реализован
- confirm callbacks внутри forum thread уже работают

Однако вместе с этим были обнаружены существенные проблемы двух типов.

**Первый тип — расхождение документации и фактической реализации.**
Часть документов всё ещё описывала старую DM-only или forum-only модель, тогда как код фактически уже работал как hybrid `DM + Forum Topics`.

**Второй тип — реальные поведенческие баги forum mode.**
Наиболее заметные проблемы:

- нестабильный onboarding подключения forum group
- слабая диагностика ошибок подключения
- возможность сломать соответствие `topic -> chat` через команды управления чатами внутри topic
- неполная согласованность UX внутри forum topics

### 8.2. Исправление документации

Были актуализированы Telegram-документы, чтобы они соответствовали реальному состоянию ветки:

- `docs/telegram-prototype.md`
- `docs/superpowers/specs/2026-03-31-telegram-adapter-design.md`

Что было отражено в документации:

- Telegram работает как hybrid-модель `DM + Forum Topics`
- DM остаётся базовой поверхностью
- Forum Topics — расширенный режим поверх того же chat context
- `/forum` подключает уже существующую forum-group пользователя
- один и тот же `chat_id` может быть доступен как из DM, так и из forum topic
- forum thread routing и confirm callbacks уже входят в реализованную модель адаптера

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

### 8.3. Разбор и исправление проблемного onboarding `/forum`

Изначально `/forum` опирался на пересланное сообщение из супергруппы и ожидал, что Telegram отдаст боту `forward_from_chat`.

В реальном запуске было установлено, что этот сценарий ненадёжен:

- Telegram/aiogram может присылать не `forward_from_chat`, а `forward_origin`
- в ряде случаев бот видит только `forward_origin_type=user`
- из такого payload невозможно надёжно восстановить `group_id`

То есть даже при визуально «правильной» пересылке сообщение не обязательно содержит необходимые данные о группе.

Для диагностики в onboarding были добавлены stage-level логи. Теперь логируются:

- запуск `/forum`
- получение onboarding message
- тип forward metadata
- наличие или отсутствие данных о группе
- тип найденного chat
- проверка forum-enabled supergroup
- права бота (`administrator` / `can_manage_topics`)
- успешная привязка forum group
- создание и привязка topics
- завершение onboarding

Это позволило быстро локализовать проблему и убедиться, что узкое место было именно в механике получения `group_id`.

### 8.4. Перевод onboarding на Telegram-native `request_chat`

Вместо ненадёжного forwarding-only flow основной путь подключения forum group был переведён на **Telegram-native выбор чата** через `request_chat`.

Было сделано следующее:

- добавлена новая клавиатура выбора forum-group
- `/forum` теперь предлагает пользователю выбрать подходящую group кнопкой
- бот получает `chat_shared.chat_id` напрямую
- после выбора выполняется проверка реальных прав бота в группе
- старый forwarding path оставлен как fallback

Это решение даёт несколько преимуществ:

- не зависит от нестабильных forwarded metadata
- даёт детерминированный `chat_id`
- лучше соответствует реальному Telegram API
- делает onboarding заметно понятнее для пользователя

### 8.5. Исправление ошибки `USER_RIGHTS_MISSING`

После внедрения `request_chat` на реальном запуске проявилась новая ошибка:

- `TelegramBadRequest: USER_RIGHTS_MISSING`

Ошибка возникала ещё на этапе отправки кнопки выбора forum-group.

Причина: в `KeyboardButtonRequestChat` был указан слишком жёсткий набор `bot_administrator_rights`, из-за чего Telegram отклонял сам запрос на показ кнопки.

Исправление:

- из `request_chat` были убраны жёсткие `bot_administrator_rights`
- фактическая проверка нужных прав оставлена на следующем шаге через `get_chat_member`

В результате onboarding сохранил строгую проверку прав, но перестал ломаться на этапе отправки UI.

### 8.6. Исправление опасного поведения внутри forum topics

После успешного onboarding был отдельно проверен UX внутри уже созданных topics. Здесь обнаружился критичный баг: пользователь мог использовать `/chats` в topic-контексте и переключать активный чат через inline callbacks.

Это приводило к рассинхронизации:

- Telegram topic визуально оставался темой одного чата
- FSM и routing переключались на другой чат
- пользователь начинал фактически разговаривать «в чате 4 внутри темы чата 2»

Чтобы устранить этот класс ошибок, были введены ограничения для topic-контекста.

Теперь внутри forum topic:

- `/chats` не открывает механизм переключения и сообщает, что эта функция доступна только в DM
- callback `switch:<chat_id>:<name>` запрещён
- callback `new_chat` из списка чатов запрещён

Это устранило основной сценарий, которым пользователь мог руками сломать привязку `topic -> chat`.

### 8.7. Что покрыто тестами

В рамках этой же сессии были расширены Telegram-specific тесты. Покрыты сценарии:

- forum routing helpers
- `/forum` переводит FSM в setup state
- подключение группы через `forward_from_chat`
- подключение группы через `forward_origin`
- подключение группы через `chat_shared`
- негативные сценарии без метаданных группы
- негативный сценарий для supergroup без Topics
- routing сообщений в forum thread
- создание forum topic при `/new` в DM
- регистрация чата в текущем topic
- confirm callback внутри forum thread
- запрет `/chats` внутри topic
- запрет `switch` callback внутри topic
- запрет `new_chat` callback внутри topic

Проверка выполнялась командами:

- `pytest tests/adapter/telegram/test_forum.py -q`
- `pytest tests/core/test_dispatcher.py tests/core/test_integration.py -q`

Результат: ключевые улучшения forum mode закреплены тестами, а не остались только на уровне ручной отладки.

### 8.8. Что ещё осталось как follow-up

Во время сессии были зафиксированы проблемы, которые разумно вынести в отдельную follow-up задачу, а не смешивать с текущими исправлениями.

Оставшиеся gap'ы:

- глобальные команды Telegram всё ещё видны и в topic-контексте, хотя часть из них логически там отключена
- `/new <name>` внутри уже связанного topic может переименовать локальный чат, но не переименовывает сам Telegram topic
- callback `new_chat` из DM-списка пока не синхронизирован с forum topic creation так же, как `/new` в DM

Эти пункты были вынесены в отдельный issue:

- `#15` — `Telegram forum topics: remaining UX and synchronization gaps`

### 8.9. Git-результат Telegram-сессии

По итогам сессии изменения были оформлены отдельным коммитом и опубликованы в удалённую ветку.

**Commit:**

- `a1b7a14` — `Improve Telegram forum onboarding and topic safety`

**Push:**

- `origin/feat/telegram-adapter`

### 8.10. Практический результат этой Telegram-сессии

На выходе Telegram Forum Topics mode стал существенно устойчивее и пригоднее для демонстрации и дальнейшей разработки.

Главные практические улучшения:

- forum onboarding стал надёжнее за счёт `request_chat`
- диагностика ошибок onboarding стала прозрачной
- пользователю стало сложнее случайно сломать topic-context
- документация приведена в соответствие с кодом
- изменения закреплены тестами
- остаточные проблемы не потеряны и вынесены в issue tracker

Итог: Telegram forum mode из состояния «уже работает, но легко ломается и плохо диагностируется» был переведён в состояние «работает заметно устойчивее, ограничивает опасные сценарии и имеет понятный backlog дальнейших улучшений».