docs: add final progress report for 2026-04-01

2026-04-01 02:14:17 +03:00 · 2026-04-01 02:14:17 +03:00 · 1c6e028e48
commit 1c6e028e48
parent 27f3da86a7
1 changed files with 280 additions and 0 deletions
--- a/docs/reports/2026-04-01-final-report.md
+++ b/docs/reports/2026-04-01-final-report.md
@ -0,0 +1,280 @@
+# Отчёт о проделанной работе — 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
+
+Проект движется по инженерной логике: исследование ограничений → адаптация архитектуры → фиксация решений → реализация. Не по формальному чеклисту.