125 lines
12 KiB
Markdown
125 lines
12 KiB
Markdown
# Требования к master-service
|
||
|
||
Источник: `meetings/meeting_1_document.md` + уточнение от тимлида
|
||
|
||
## Назначение
|
||
|
||
Master-service — это control plane платформы AI-агентов. Он управляет sandbox-контейнерами с AI-Agent, рабочими пространствами пользователей, чатами, пользовательскими файлами, проверкой доступа и выдачей временного p2p-доступа к контейнеру.
|
||
|
||
После старта sandbox и успешной авторизации Master должен оставаться плоскостью управления, а не постоянным data-plane прокси: рабочий трафик к агенту должен идти напрямую по выданному p2p-каналу.
|
||
|
||
## Границы ответственности
|
||
|
||
### В scope
|
||
|
||
- оркестрация sandbox
|
||
- управление workspace и chat volume
|
||
- хранение чатов? и файлов пользователя
|
||
- хранение и выдача артефактов
|
||
- проверка доступа
|
||
- выдача и отзыв p2p-доступа
|
||
- учет сессий, TTL и cleanup-процессов
|
||
- хранение служебных метаданных
|
||
|
||
### Вне scope
|
||
|
||
- Telegram/Discord/Slack интеграции и их transport-логика
|
||
- бизнес-логика AI-Agent внутри sandbox
|
||
- реализация LLM-level защиты от prompt injection
|
||
- реализация конкретных lambda-tools и browser tools
|
||
|
||
## Основные сущности
|
||
|
||
- **User** — владелец workspace
|
||
- **Workspace** — пользовательское хранилище с мягкой квотой 10 GB
|
||
- **Chat** — изолированная рабочая область внутри workspace
|
||
- **SandboxSession** — активный runtime AI-Agent для конкретного чата
|
||
- **AccessLease** — временное право на p2p-доступ к sandbox
|
||
- **ChatFile** — файл, прикрепленный к чату
|
||
- **Artifact** — результат, созданный агентом и подготовленный к выдаче наружу
|
||
- **DependencyBundle** — предзагруженный набор зависимостей tool/runtime
|
||
- **LambdaToolBundle** — платформенный read-only набор тулов
|
||
|
||
## Функциональные требования
|
||
|
||
### 1. Управление workspace и chat storage
|
||
|
||
- **FR-001** Master должен создавать workspace пользователя при первом обращении
|
||
- **FR-002** Master должен вести мягкую квоту workspace в 10 GB на пользователя без физического резервирования места
|
||
- **FR-003** Master должен создавать, получать, перечислять и удалять чаты пользователя
|
||
- **FR-004** Каждый chat должен иметь собственную изолированную директорию с файлами и историей
|
||
- **FR-005** История сообщений чата в первой версии должна храниться рядом с чатом в файле `history.md`
|
||
- **FR-006** Master должен сохранять пользовательские вложения в директорию соответствующего чата до запуска или во время работы sandbox
|
||
- **FR-007** Master должен предоставлять операции списка, чтения метаданных, удаления и очистки файлов чата
|
||
|
||
### 2. Оркестрация sandbox
|
||
|
||
- **FR-008** Master должен поднимать sandbox-контейнер AI-Agent по первому сообщению или при отсутствии активной sandbox-сессии
|
||
- **FR-009** Master должен переиспользовать активную sandbox-сессию, пока не истек TTL бездействия
|
||
- **FR-010** Master должен завершать sandbox после периода неактивности; стартовое значение TTL — около 1 часа, но параметр должен быть конфигурируемым
|
||
- **FR-011** После завершения sandbox данные чата и workspace должны сохраняться и использоваться при следующем старте
|
||
- **FR-012** Master должен уметь пересоздать sandbox на другом узле при сохранности данных и доступности нужных volume
|
||
|
||
### 3. Подключение volume и runtime-ресурсов
|
||
|
||
- **FR-013** При старте sandbox Master должен подключать volume текущего чата
|
||
- **FR-014** При старте sandbox Master должен подключать volume с dependency cache
|
||
- **FR-015** При старте sandbox Master должен подключать volume с lambda-tools в режиме read-only
|
||
- **FR-016** Если используются user-tools, Master должен подключать их так, чтобы агент мог их только исполнять, но не менять
|
||
- **FR-017** Master должен проверять наличие нужных dependency bundle на текущем узле и при отсутствии инициировать загрузку из внутреннего хранилища
|
||
|
||
### 4. Доступ и p2p-соединение
|
||
|
||
- **FR-018** Master должен аутентифицировать внутренние запросы от интеграционного слоя и других доверенных сервисов
|
||
- **FR-019** Master должен авторизовывать доступ по связке user/workspace/chat/sandbox
|
||
- **FR-020** После успешной проверки доступа Master должен выдавать временные параметры p2p-подключения к sandbox
|
||
- **FR-021** Выданный p2p-доступ должен быть ограничен по времени и привязан к конкретной sandbox-сессии
|
||
- **FR-022** Master должен уметь отзывать p2p-доступ при остановке sandbox, смене прав или завершении сессии
|
||
- **FR-023** Master не должен проксировать постоянный трафик к агенту после выдачи p2p-доступа, кроме управляющих операций
|
||
|
||
### 5. Хранение чатов, файлов и артефактов
|
||
|
||
- **FR-024** Master должен хранить центральные метаданные о пользователях, чатах, sandbox-сессиях, lease, файлах и артефактах
|
||
- **FR-025** Master должен отделять метаданные чата в центральной БД от фактической истории сообщений в `history.db`
|
||
- **FR-026** Master должен поддерживать загрузку артефактов в S3-совместимое объектное хранилище
|
||
- **FR-027** Master должен хранить связь между артефактом, пользователем, чатом и способом внешней доставки
|
||
- **FR-028** После подтвержденной отправки артефакт должен быть помечен на удаление или удален по policy
|
||
|
||
### 6. Lifecycle и cleanup
|
||
|
||
- **FR-029** Master должен отслеживать `last_read` и/или `last_update` для файлов чата
|
||
- **FR-030** Файлы чата должны автоматически удаляться после 3 дней неактивности
|
||
- **FR-031** Master должен поддерживать удаление всего workspace после длительной неактивности аккаунта; срок должен быть конфигурируемым
|
||
- **FR-032** Cleanup должен быть безопасным: нельзя удалять данные активного sandbox или чата с действующим lease
|
||
|
||
### 7. Наблюдаемость и аудит
|
||
|
||
- **FR-033** Master должен логировать создание и остановку sandbox, подключение volume, выдачу доступа и cleanup-операции
|
||
- **FR-034** Master должен собирать метрики по активным sandbox, времени запуска, ошибкам старта, cleanup и storage usage
|
||
- **FR-035** Master должен предоставлять аудитный след по операциям доступа к chat/file/artifact ресурсам
|
||
|
||
## Нефункциональные требования
|
||
|
||
- **NFR-001** Master должен быть control-plane сервисом и не содержать бизнес-логику AI-Agent
|
||
- **NFR-002** Все данные разных пользователей должны быть изолированы на уровне путей, mount policy и access policy
|
||
- **NFR-003** Повторный запрос на создание chat или запуск sandbox не должен приводить к дублированию ресурсов при одинаковом идемпотентном ключе
|
||
- **NFR-004** Политики TTL, cleanup, квоты и lease должны задаваться конфигом
|
||
- **NFR-005** Решение должно позволять горизонтально масштабировать Master и пересоздавать sandbox независимо от конкретного инстанса сервиса
|
||
- **NFR-006** Отказ sandbox не должен приводить к потере chat history и пользовательских файлов
|
||
- **NFR-007** Все security-чувствительные операции должны быть трассируемы и наблюдаемы
|
||
|
||
## Явные ограничения первой версии
|
||
|
||
- один master-service отвечает за orchestration и storage metadata
|
||
- история сообщений хранится в `history.md` внутри chat directory
|
||
- workspace quota считается по фактическому размеру файлов, без hard reservation
|
||
- heavy tools и browser automation не выносятся в отдельный сервис, пока это не потребуется
|
||
- интеграции мессенджеров считаются внешними клиентами master-service
|
||
|
||
## Открытые вопросы
|
||
|
||
- какой именно transport используется для p2p-доступа: raw TCP, WebSocket, gRPC или другой вариант = WebSocket
|
||
- какой срок inactivity cleanup для всего аккаунта считается продуктовым дефолтом
|
||
- нужен ли отдельный API для скачивания chat files наружу или достаточно metadata + object/file gateway
|
||
- подтверждается ли доставка артефакта внешней интеграцией явно или cleanup идет только по TTL
|
||
- одна sandbox-сессия должна соответствовать одному chat или допустим multiplex нескольких чатов на один runtime
|