docs: update README with Matrix MVP runbook and feature status
Add step-by-step setup for running Matrix surface with real platform-agent, document all available commands, and clearly list what works vs what is blocked (StateBackend cross-chat load, hardcoded tokens, missing /reset, no file upload API).
This commit is contained in:
parent
fbcf44980e
commit
b3331464d9
1 changed files with 98 additions and 28 deletions
126
README.md
126
README.md
|
|
@ -4,12 +4,10 @@
|
||||||
|
|
||||||
## Статус
|
## Статус
|
||||||
|
|
||||||
Прототип в разработке. Matrix-адаптер по умолчанию работает через `MockPlatformClient`, но может переключаться на реальный direct-agent backend через `MATRIX_PLATFORM_BACKEND=real`.
|
| Поверхность | Статус |
|
||||||
|
|---|---|
|
||||||
| Поверхность | Статус | Описание |
|
| Telegram | 🔨 В разработке, отдельный worktree `feat/telegram-adapter` |
|
||||||
|---|---|---|
|
| Matrix | ✅ Рабочий прототип, подключается к реальному агенту |
|
||||||
| Telegram | 🔨 В разработке | DM + Forum Topics mode, активная реализация сейчас в отдельном worktree |
|
|
||||||
| Matrix | 🔨 В разработке | Незашифрованные комнаты: бот создаёт private Space и отдельную room на каждый чат |
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -96,40 +94,112 @@ class PlatformClient(Protocol):
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Быстрый старт
|
## Запуск Matrix-поверхности
|
||||||
|
|
||||||
|
### 1. Зависимости и тесты
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Зависимости
|
uv sync
|
||||||
uv sync # или: pip install -e ".[dev]"
|
|
||||||
|
|
||||||
# Тесты
|
|
||||||
pytest tests/ -v
|
pytest tests/ -v
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Переменные окружения
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cp .env.example .env
|
||||||
|
```
|
||||||
|
|
||||||
|
Обязательные переменные:
|
||||||
|
|
||||||
|
```env
|
||||||
|
# Matrix аккаунт бота
|
||||||
|
MATRIX_HOMESERVER=https://matrix.example.org
|
||||||
|
MATRIX_USER_ID=@lambda-bot:example.org
|
||||||
|
MATRIX_PASSWORD=... # или MATRIX_ACCESS_TOKEN=...
|
||||||
|
|
||||||
|
# Выбор backend: mock (по умолчанию) или real (подключение к platform-agent)
|
||||||
|
MATRIX_PLATFORM_BACKEND=real
|
||||||
|
|
||||||
|
# URL WebSocket endpoint platform-agent (только при MATRIX_PLATFORM_BACKEND=real)
|
||||||
|
AGENT_WS_URL=ws://127.0.0.1:8000/agent_ws/
|
||||||
|
AGENT_BASE_URL=http://127.0.0.1:8000
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Запуск platform-agent (для real backend)
|
||||||
|
|
||||||
|
platform-agent — отдельный репозиторий, сейчас клонируется в `external/platform-agent`.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd external/platform-agent
|
||||||
|
|
||||||
|
# Создать .env с параметрами LLM провайдера
|
||||||
|
cat > .env <<EOF
|
||||||
|
PROVIDER_MODEL=openai/gpt-4o-mini
|
||||||
|
PROVIDER_URL=https://openrouter.ai/api/v1
|
||||||
|
PROVIDER_API_KEY=sk-or-...
|
||||||
|
EOF
|
||||||
|
|
||||||
|
# Запустить
|
||||||
|
uv run uvicorn src.main:app --host 127.0.0.1 --port 8000
|
||||||
|
```
|
||||||
|
|
||||||
|
Проверить что работает: `curl http://127.0.0.1:8000/agent_ws/` должен вернуть ответ об апгрейде до WebSocket.
|
||||||
|
|
||||||
|
### 4. Запуск бота
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Первый запуск или сброс состояния
|
||||||
|
rm -f lambda_matrix.db && rm -rf matrix_store
|
||||||
|
|
||||||
# Запустить Matrix бота
|
|
||||||
cp .env.example .env # заполнить MATRIX_* переменные
|
|
||||||
PYTHONPATH=. uv run python -m adapter.matrix.bot
|
PYTHONPATH=. uv run python -m adapter.matrix.bot
|
||||||
```
|
```
|
||||||
|
|
||||||
### Telegram worktree
|
### 5. Онбординг пользователя
|
||||||
|
|
||||||
Текущая Telegram-разработка идёт в отдельном worktree:
|
Пригласи Matrix-аккаунт бота в личный DM. Бот создаст:
|
||||||
|
- Private Space `Lambda — {имя}`
|
||||||
|
- Рабочую комнату `Чат 1` и пригласит туда
|
||||||
|
|
||||||
```bash
|
Дальнейшее общение ведётся в рабочей комнате.
|
||||||
cd .worktrees/telegram
|
|
||||||
export BOT_TOKEN=...
|
|
||||||
PYTHONPATH=. python -m adapter.telegram.bot
|
|
||||||
```
|
|
||||||
|
|
||||||
### Matrix manual QA
|
---
|
||||||
|
|
||||||
Пока Matrix-бот тестируется в незашифрованных комнатах:
|
## Функционал Matrix MVP
|
||||||
|
|
||||||
```bash
|
### Работает
|
||||||
cd /path/to/surfaces-bot
|
|
||||||
rm -f lambda_matrix.db
|
| Функция | Команда | Примечание |
|
||||||
rm -rf matrix_store
|
|---|---|---|
|
||||||
PYTHONPATH=. uv run python -m adapter.matrix.bot
|
| Онбординг | *(автоматически при invite)* | Создаёт Space + рабочую комнату |
|
||||||
```
|
| Новый чат | `!new` | Создаёт дополнительную комнату |
|
||||||
|
| Список чатов | `!chats` | Активные чаты пользователя |
|
||||||
|
| Переименование | `!rename <название>` | |
|
||||||
|
| Архивация | `!archive` | |
|
||||||
|
| Диалог с агентом | *(любое сообщение)* | Стриминг ответа через WebSocket |
|
||||||
|
| Изоляция контекста | *(автоматически)* | Каждая комната — отдельный thread_id агента |
|
||||||
|
| Сохранение контекста | `!save [имя]` | Агент сохраняет краткое резюме разговора |
|
||||||
|
| Список сохранений | `!load` | Выбор по номеру |
|
||||||
|
| Состояние контекста | `!context` | Текущая сессия и список сохранений |
|
||||||
|
| Справка | `!help` | |
|
||||||
|
| Подтверждения | `!yes` / `!no` | Для опасных действий |
|
||||||
|
|
||||||
|
### Не работает — блокеры на стороне platform-agent
|
||||||
|
|
||||||
|
| Функция | Почему не работает |
|
||||||
|
|---|---|
|
||||||
|
| `!load` в другом чате | platform-agent использует `StateBackend` — файлы живут в памяти отдельно для каждого `thread_id`. Файл, сохранённый в чате A, не виден в чате B. Фикс: переключить platform-agent на `FilesystemBackend` с общим хранилищем. |
|
||||||
|
| Счётчик токенов в `!context` | platform-agent отдаёт `tokens_used=0` хардкодом в `MsgEventEnd`. Наш код перехватывает значение корректно. |
|
||||||
|
| `!reset` | platform-agent не имеет endpoint `/reset`. Задокументировано в ТЗ к платформе. |
|
||||||
|
| Файловые вложения | Нет API загрузки файлов в область видимости агента. ТЗ передано платформе. |
|
||||||
|
| Персистентность между рестартами | platform-agent использует `MemorySaver` (in-memory). Все разговоры теряются при рестарте процесса. |
|
||||||
|
| E2EE комнаты | `python-olm` не собирается на macOS/ARM. Ограничение инфраструктуры. |
|
||||||
|
|
||||||
|
### Не работает — пока не реализовано нами
|
||||||
|
|
||||||
|
| Функция | Статус |
|
||||||
|
|---|---|
|
||||||
|
| `!settings`, `!skills`, `!soul`, `!safety` | Заглушки MVP. Требуют готового SDK платформы. |
|
||||||
|
| Вложения (изображения, документы) | Только текстовые сообщения в текущем MVP. |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue