227 lines
9.5 KiB
Markdown
227 lines
9.5 KiB
Markdown
# Lambda Lab 3.0 — Surfaces
|
||
|
||
Matrix-бот для взаимодействия пользователя с AI-агентом Lambda.
|
||
|
||
## Интеграция для платформы
|
||
|
||
Бот — это один Docker-контейнер (`matrix-bot`), который вы добавляете в свою инфраструктуру рядом с агентами.
|
||
|
||
### Что бот ожидает от вас
|
||
|
||
**1. HTTP-эндпоинт агента**
|
||
Бот подключается к агенту через `lambda_agent_api.AgentApi` по адресу `AGENT_BASE_URL`.
|
||
Протокол — WebSocket поверх HTTP, контракт описан в `docs/deploy-architecture.md`.
|
||
|
||
**2. Shared volume**
|
||
Бот пишет файлы пользователей в Docker volume, смонтированный как `/agents`.
|
||
Агент должен видеть тот же volume — как `/workspace`.
|
||
|
||
```
|
||
Bot container Agent container
|
||
/agents/ ←──── named Docker volume ────→ /workspace/
|
||
```
|
||
|
||
Бот кладёт входящие файлы по пути `surfaces/matrix/{user}/{room}/inbox/{file}` и передаёт агенту этот относительный путь. Исходящие файлы агент пишет в свой `/workspace/`, бот читает их оттуда же.
|
||
|
||
**3. Конфиг агентов**
|
||
Файл `config/matrix-agents.yaml` — маппинг Matrix-пользователей на агентов. Вы заполняете его под свою инфраструктуру. Пример в `config/matrix-agents.example.yaml`.
|
||
|
||
### Что бот не делает
|
||
|
||
- Не управляет lifecycle агент-контейнеров (запуск/остановка — на вашей стороне)
|
||
- Не хранит историю разговоров (это в памяти агента)
|
||
- Не обрабатывает аутентификацию пользователей — любой Matrix-пользователь, который пишет боту, получает доступ
|
||
|
||
### Минимальный чеклист
|
||
|
||
- [ ] Заполнить `.env` (по шаблону `.env.example`)
|
||
- [ ] Заполнить `config/matrix-agents.yaml` (ID агентов и маппинг пользователей)
|
||
- [ ] Убедиться что `AGENT_BASE_URL` доступен из контейнера бота
|
||
- [ ] Смонтировать один и тот же named volume в бот (`/agents`) и в агент (`/workspace`)
|
||
- [ ] Запустить: `docker compose -f docker-compose.prod.yml up -d --build`
|
||
|
||
---
|
||
|
||
## Статус
|
||
|
||
Matrix MVP готов к деплою. Telegram — в отдельном worktree, не входит в этот handoff.
|
||
|
||
---
|
||
|
||
## Архитектура
|
||
|
||
```
|
||
surfaces-bot/
|
||
core/ — общее ядро, не зависит от транспорта
|
||
protocol.py — унифицированные структуры (IncomingMessage, OutgoingUI, ...)
|
||
handler.py — EventDispatcher: IncomingEvent → OutgoingEvent
|
||
store.py — StateStore Protocol + InMemoryStore + SQLiteStore
|
||
chat.py — ChatManager
|
||
auth.py — AuthManager
|
||
settings.py — SettingsManager
|
||
|
||
adapter/
|
||
matrix/ — matrix-nio адаптер
|
||
|
||
sdk/
|
||
interface.py — PlatformClient Protocol (контракт к SDK)
|
||
real.py — RealPlatformClient (через AgentApi)
|
||
mock.py — MockPlatformClient (заглушка для тестов)
|
||
|
||
config/
|
||
matrix-agents.yaml — реестр агентов
|
||
|
||
docs/ — документация
|
||
```
|
||
|
||
Подробнее: [`docs/surface-protocol.md`](docs/surface-protocol.md)
|
||
|
||
---
|
||
|
||
## Деплой
|
||
|
||
### Переменные окружения
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
| Переменная | Обязательна | Описание |
|
||
|---|---|---|
|
||
| `MATRIX_HOMESERVER` | ✓ | URL Matrix-сервера |
|
||
| `MATRIX_USER_ID` | ✓ | `@bot:example.org` |
|
||
| `MATRIX_PASSWORD` | ✓ | пароль (или `MATRIX_ACCESS_TOKEN`) |
|
||
| `MATRIX_PLATFORM_BACKEND` | ✓ | `real` для продакшна |
|
||
| `AGENT_BASE_URL` | ✓ | HTTP-URL агента, например `http://platform-agent:8000` |
|
||
| `MATRIX_AGENT_REGISTRY_PATH` | ✓ | путь к реестру внутри контейнера: `/app/config/matrix-agents.yaml` |
|
||
| `SURFACES_WORKSPACE_DIR` | | путь к shared volume в контейнере (по умолчанию `/agents`) |
|
||
| `SURFACES_SHARED_VOLUME` | | имя Docker volume (по умолчанию `surfaces-agents`) |
|
||
|
||
### Реестр агентов
|
||
|
||
`config/matrix-agents.yaml` — статический маппинг пользователей на агентов:
|
||
|
||
```yaml
|
||
user_agents:
|
||
"@user0:matrix.lambda.coredump.ru": agent-0
|
||
"@user1:matrix.lambda.coredump.ru": agent-1
|
||
|
||
agents:
|
||
- id: agent-0
|
||
label: "Agent 0"
|
||
- id: agent-1
|
||
label: "Agent 1"
|
||
```
|
||
|
||
Если `user_agents` не задан или пользователь не найден — используется первый агент из списка.
|
||
|
||
### Production (bot-only)
|
||
|
||
```bash
|
||
docker compose --env-file .env -f docker-compose.prod.yml up -d --build
|
||
```
|
||
|
||
Поднимает только `matrix-bot`. Монтирует shared volume в `/agents`. Требует внешний `AGENT_BASE_URL`.
|
||
|
||
### Fullstack E2E (bot + agent)
|
||
|
||
```bash
|
||
docker compose --env-file .env -f docker-compose.fullstack.yml up --build
|
||
```
|
||
|
||
Поднимает `matrix-bot` вместе с локальным `platform-agent`. `AGENT_BASE_URL` перекрывается на `http://platform-agent:8000`. Shared volume виден как `/agents` в боте и `/workspace` в агенте.
|
||
|
||
### Сброс состояния (локально)
|
||
|
||
```bash
|
||
rm -f lambda_matrix.db && rm -rf matrix_store
|
||
```
|
||
|
||
---
|
||
|
||
## Shared volume: передача файлов
|
||
|
||
```
|
||
Bot (/agents) Agent (/workspace)
|
||
└── surfaces/matrix/{user}/{room}/inbox/file ←── одно и то же хранилище
|
||
```
|
||
|
||
Бот пишет входящие файлы в `/agents/surfaces/matrix/{user}/{room}/inbox/{stamp}-{filename}` и передаёт агенту относительный путь. Исходящие файлы агент пишет в `/workspace/...`, бот читает из `/agents/...`.
|
||
|
||
---
|
||
|
||
## Онбординг пользователя
|
||
|
||
1. Пользователь приглашает бота в личные сообщения (DM) на Matrix-сервере
|
||
2. Бот создаёт private Space `Lambda — {display_name}` и комнату `Чат 1`
|
||
3. Дальнейшее общение — в рабочих комнатах, не в DM
|
||
|
||
**Требование:** незашифрованные комнаты. E2EE не поддержан.
|
||
|
||
---
|
||
|
||
## Команды Matrix
|
||
|
||
### Работающие
|
||
|
||
| Команда | Действие |
|
||
|---|---|
|
||
| *(любое сообщение)* | Диалог с агентом, стриминг ответа |
|
||
| `!new [название]` | Создать новый чат |
|
||
| `!chats` | Список активных чатов |
|
||
| `!rename <название>` | Переименовать текущую комнату |
|
||
| `!archive` | Архивировать чат |
|
||
| `!clear` | Сбросить контекст текущего чата |
|
||
| `!yes` / `!no` | Подтвердить / отменить действие агента |
|
||
| `!list` | Файлы в очереди вложений |
|
||
| `!remove <n>` / `!remove all` | Удалить вложение из очереди |
|
||
| `!help` | Справка |
|
||
|
||
### Не работают / заглушки
|
||
|
||
| Команда | Статус |
|
||
|---|---|
|
||
| `!save` / `!load` / `!context` | Нестабильны: зависят от агента, сессии теряются при рестарте |
|
||
| `!settings` и подкоманды | Заглушки MVP, требуют готового SDK платформы |
|
||
|
||
---
|
||
|
||
## Отправка файлов агенту
|
||
|
||
Matrix-клиент отправляет файлы и текст отдельными событиями. Файл без текстовой инструкции ставится в очередь.
|
||
|
||
```
|
||
[отправил файл]
|
||
!list
|
||
1. report.pdf
|
||
|
||
прочитай и сделай summary ← файл уйдёт агенту вместе с этим текстом
|
||
```
|
||
|
||
---
|
||
|
||
## Известные ограничения
|
||
|
||
| Проблема | Причина |
|
||
|---|---|
|
||
| История теряется при рестарте агента | `platform-agent` использует `MemorySaver` (in-memory) |
|
||
| E2EE | `python-olm` не собирается на macOS/ARM |
|
||
|
||
---
|
||
|
||
## Разработка
|
||
|
||
```bash
|
||
uv sync
|
||
pytest tests/ -v
|
||
pytest tests/adapter/matrix/ -v # только Matrix
|
||
```
|
||
|
||
## Документация
|
||
|
||
| Файл | Содержание |
|
||
|---|---|
|
||
| [`docs/deploy-architecture.md`](docs/deploy-architecture.md) | **Читать первым.** Топология деплоя, volume-контракт, AgentApi, конфигурация |
|
||
| [`docs/matrix-prototype.md`](docs/matrix-prototype.md) | Команды бота, UX, передача файлов |
|
||
| [`docs/known-limitations.md`](docs/known-limitations.md) | Известные ограничения и обходные пути |
|
||
| [`docs/surface-protocol.md`](docs/surface-protocol.md) | Внутренний протокол событий (для расширения) |
|