docs: update core design and api-contract with platform container architecture
This commit is contained in:
parent
8e955045b2
commit
53685747f6
2 changed files with 92 additions and 79 deletions
|
|
@ -1,11 +1,18 @@
|
|||
# API Contract — Lambda Platform
|
||||
|
||||
> **Статус:** ЧЕРНОВИК — проектируем сами, не ждём SDK
|
||||
> **Автор:** @architect
|
||||
> **Последнее обновление:** заполнить дату
|
||||
> **Статус:** ЧЕРНОВИК — проектируем сами, уточняем с Азаматом когда SDK будет готов
|
||||
> **Последнее обновление:** 2026-03-29
|
||||
|
||||
Это описание того, что нам нужно от платформы.
|
||||
`MockPlatformClient` реализует этот контракт. При подключении реального SDK — только он меняется.
|
||||
---
|
||||
|
||||
## Архитектурный контекст
|
||||
|
||||
Каждому пользователю выделяется **один LXC-контейнер** с workspace 10 ГБ.
|
||||
Workspace содержит директории чатов: `C1/`, `C2/`, `C3/` — файлы + `history.db` в каждом.
|
||||
|
||||
**Master** управляет lifecycle контейнера (запуск, заморозка, пробуждение).
|
||||
Бот **не управляет lifecycle** — он передаёт `user_id` + `chat_id` + сообщение.
|
||||
Master сам решает: нужно ли поднять контейнер, смонтировать нужный чат, запустить агента.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -28,6 +35,7 @@ Authorization: Bearer {SERVICE_TOKEN}
|
|||
## Users
|
||||
|
||||
### GET /users/{external_id}?platform={platform}
|
||||
|
||||
Получает или создаёт пользователя.
|
||||
|
||||
**Query params:**
|
||||
|
|
@ -47,50 +55,15 @@ Authorization: Bearer {SERVICE_TOKEN}
|
|||
|
||||
---
|
||||
|
||||
## Sessions
|
||||
|
||||
### POST /sessions
|
||||
Создаёт новую сессию с AI-агентом.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"user_id": "usr_abc123",
|
||||
"platform": "telegram",
|
||||
"context": {}
|
||||
}
|
||||
```
|
||||
|
||||
**Response 201:**
|
||||
```json
|
||||
{
|
||||
"session_id": "ses_xyz789",
|
||||
"agent_id": "agt_def456",
|
||||
"created_at": "2025-01-15T10:30:00Z",
|
||||
"expires_at": "2025-01-16T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### GET /sessions/{session_id}
|
||||
Получает информацию о сессии.
|
||||
|
||||
**Response 200:** — см. структуру выше + поле `status: "active" | "closed"`
|
||||
**Response 404:** `{"error": "SESSION_NOT_FOUND", "message": "..."}`
|
||||
|
||||
### DELETE /sessions/{session_id}
|
||||
Завершает сессию.
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
{"closed": true}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Messages
|
||||
|
||||
### POST /sessions/{session_id}/messages
|
||||
Отправляет сообщение и получает ответ агента.
|
||||
Бот не управляет сессиями явно. Отправка сообщения — единственная операция.
|
||||
Master решает: нужен ли новый контейнер, или разбудить существующий.
|
||||
|
||||
### POST /users/{user_id}/chats/{chat_id}/messages
|
||||
|
||||
Отправляет сообщение пользователя агенту. Master поднимает/размораживает контейнер,
|
||||
монтирует нужный чат (`C1/`, `C2/`...), запускает агента.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
|
|
@ -110,28 +83,46 @@ Authorization: Bearer {SERVICE_TOKEN}
|
|||
}
|
||||
```
|
||||
|
||||
### GET /sessions/{session_id}/messages?limit=20&offset=0
|
||||
История сообщений сессии.
|
||||
---
|
||||
|
||||
## Settings
|
||||
|
||||
### GET /users/{user_id}/settings
|
||||
|
||||
Настройки пользователя: скиллы, коннекторы, SOUL, безопасность, план.
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"message_id": "msg_qwe012",
|
||||
"user_text": "Привет",
|
||||
"response": "Привет!",
|
||||
"tokens_used": 42,
|
||||
"created_at": "2025-01-15T10:31:00Z"
|
||||
}
|
||||
]
|
||||
{
|
||||
"skills": {"web-search": true, "browser": false},
|
||||
"connectors": {"gmail": {"connected": true, "email": "user@gmail.com"}},
|
||||
"soul": {"name": "Лямбда", "style": "friendly"},
|
||||
"safety": {"email-send": true, "file-delete": true},
|
||||
"plan": {"name": "Beta", "tokens_used": 800, "tokens_limit": 1000}
|
||||
}
|
||||
```
|
||||
|
||||
### POST /users/{user_id}/settings
|
||||
|
||||
Применяет действие над настройками.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"action": "toggle_skill",
|
||||
"payload": {"skill": "browser", "enabled": true}
|
||||
}
|
||||
```
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
{"ok": true}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error format
|
||||
|
||||
Все ошибки возвращаются в едином формате:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "ERROR_CODE",
|
||||
|
|
@ -140,11 +131,15 @@ Authorization: Bearer {SERVICE_TOKEN}
|
|||
}
|
||||
```
|
||||
|
||||
Коды ошибок: `SESSION_NOT_FOUND`, `USER_NOT_FOUND`, `RATE_LIMITED`, `PLATFORM_ERROR`
|
||||
Коды ошибок: `USER_NOT_FOUND`, `RATE_LIMITED`, `PLATFORM_ERROR`, `CONTAINER_UNAVAILABLE`
|
||||
|
||||
---
|
||||
|
||||
## TODO (открытые вопросы к команде платформы)
|
||||
## Открытые вопросы к Азамату (SDK)
|
||||
|
||||
- [ ] Нужна ли стриминговая передача ответа (SSE / WebSocket)?
|
||||
- [ ] Как обрабатываются вложения (изображения, файлы)?
|
||||
- [ ] Точный формат эндпоинта отправки сообщения — URL, поля
|
||||
- [ ] Как передавать вложения (файлы, изображения)? Через S3 pre-signed URL или напрямую?
|
||||
- [ ] Стриминговый ответ (SSE / WebSocket) или только sync?
|
||||
- [ ] Как обрабатывается `chat_id` на стороне платформы — это имя директории (C1/C2) или наш произвольный идентификатор?
|
||||
- [ ] Есть ли endpoint для получения истории чата или она хранится только в `history.db` внутри контейнера?
|
||||
- [ ] Формат `SettingsAction` — совпадает с нашим или другой?
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue