Surfaces_team/surfaces
4
0
Fork 0
Code Issues 5 Pull requests Projects Releases Packages Wiki Activity Actions
surfaces/docs/reports/2026-04-01-final-report.md

16 KiB
Raw Permalink Blame History

Отчёт о проделанной работе — 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

Проект движется по инженерной логике: исследование ограничений → адаптация архитектуры → фиксация решений → реализация. Не по формальному чеклисту.