53 lines
4.1 KiB
Markdown
53 lines
4.1 KiB
Markdown
# Lambda Lab 3.0 — Surfaces
|
||
|
||
## What This Is
|
||
|
||
Surfaces (поверхности) — это тонкие адаптеры-клиенты, соединяющие мессенджеры с агентами платформы Lambda.
|
||
Текущая и главная реализация — **Matrix MVP**. Бот работает как stateless-прослойка: преобразует события Matrix во внутренний протокол `core/` и маршрутизирует их на внешние контейнеры агентов (через `AgentApi` по WebSocket).
|
||
|
||
## Core Value
|
||
|
||
Пользователь может бесшовно взаимодействовать с изолированными AI-агентами через нативные интерфейсы мессенджеров (с поддержкой пересылки файлов и работы в комнатах), в то время как сама платформа агентов не зависит от транспорта.
|
||
|
||
## Requirements
|
||
|
||
### Validated
|
||
|
||
- ✓ `core/` — унифицированный протокол событий, EventDispatcher, StateStore, ChatManager.
|
||
- ✓ `adapter/matrix/` — Space+rooms адаптер. Прием инвайтов, автосоздание иерархии комнат, команды `!new`, `!archive`, `!clear`, `!yes`/`!no`.
|
||
- ✓ `sdk/real.py` — интеграция с AgentApi. Поддержка WebSocket для обмена сообщениями и передачи вложений в обе стороны.
|
||
- ✓ Shared Volume — прямая передача файлов в локальные рабочие папки агентов (`/agents/`).
|
||
- ✓ Dynamic Routing — маршрутизация чатов к агентам на основе `config/matrix-agents.yaml`.
|
||
- ✓ Deployment — Разделение окружений на `docker-compose.prod.yml` (только бот) и `docker-compose.fullstack.yml` (бот + локальный агент для E2E).
|
||
|
||
### Out of Scope / Deferred
|
||
|
||
- E2EE для Matrix (отложено из-за сложностей сборки `python-olm` на кросс-платформенных средах).
|
||
- Интеграция с Master-сервисом платформы (временно используется прямое соединение с `platform-agent` через AgentApi).
|
||
- Telegram-адаптер (вынесен в легаси ветку `feat/telegram-adapter`, MVP фокусируется на Matrix).
|
||
|
||
## Context
|
||
|
||
- Стек: Python 3.11+, `matrix-nio`, `uv`, `pydantic`.
|
||
- Бот хранит только локальную привязку (`room_id` <-> `platform_chat_id`) в SQLite. Вся долговременная память и история диалогов хранятся на стороне агента.
|
||
- Жизненный цикл контейнеров агентов управляется платформой, а не ботом.
|
||
|
||
## Key Decisions
|
||
|
||
| Decision | Rationale | Outcome |
|
||
|----------|-----------|---------|
|
||
| Space+rooms для Matrix | Room-based UX и явные чаты (по одному на тред) удобнее, чем DM-каша | ✓ Good |
|
||
| Прямая интеграция AgentApi | Master API не был готов, прямое WebSocket соединение позволяет передавать стейт и файлы | ✓ Good |
|
||
| Shared Volume для файлов | Избавляет от необходимости гонять base64 по сети, быстрый прямой доступ к файлам | ✓ Good |
|
||
| Stateless бот | Бот легко перезапускать и масштабировать, память изолирована в агентах | ✓ Good |
|
||
|
||
## Evolution
|
||
|
||
**After each phase transition:**
|
||
1. Requirements invalidated? → Move to Out of Scope with reason
|
||
2. Requirements validated? → Move to Validated with phase reference
|
||
3. New requirements emerged? → Add to Active
|
||
4. Decisions to log? → Add to Key Decisions
|
||
|
||
---
|
||
*Last updated: 2026-05-03 after codebase consolidation*
|