docs: sync all markdown with current architecture
Remove session management concepts (no create_session/close_session/
DELETE /sessions — Master handles container lifecycle automatically).
Update PlatformClient contract, ChatContext, project structure tree,
and FSM diagrams across all docs to match the implemented core/.
- README.md: fix core/ structure tree + PlatformClient snippet
- docs/surface-protocol.md: remove session.py/_template.py, fix
ChatContext (drop session_id), fix PlatformClient contract, fix
"free features" list
- docs/telegram-prototype.md: remove "создаёт сессию на платформе"
- docs/matrix-prototype.md: same + remove !sessions, fix FSM
(SessionCreated → ChatCreated), fix status block
- docs/user-flow.md: rewrite sequence diagram to POST /users/{id}/
chats/{id}/messages; update FSM states
This commit is contained in:
parent
36730ae716
commit
4f5c5679d5
5 changed files with 52 additions and 53 deletions
23
README.md
23
README.md
|
|
@ -29,10 +29,12 @@
|
|||
surfaces-bot/
|
||||
core/ — общее ядро, не зависит от транспорта
|
||||
protocol.py — унифицированные структуры (IncomingMessage, OutgoingUI, ...)
|
||||
handler.py — логика: IncomingEvent → OutgoingEvent
|
||||
session.py — управление сессиями и чатами
|
||||
auth.py — аутентификация
|
||||
settings.py — коннекторы, скиллы, SOUL, безопасность
|
||||
handler.py — EventDispatcher: IncomingEvent → OutgoingEvent
|
||||
handlers/ — обработчики по типам событий
|
||||
store.py — StateStore Protocol + InMemoryStore + SQLiteStore
|
||||
chat.py — ChatManager: метаданные чатов C1/C2/C3
|
||||
auth.py — AuthManager: аутентификация
|
||||
settings.py — SettingsManager: коннекторы, скиллы, SOUL, безопасность
|
||||
|
||||
adapter/
|
||||
telegram/ — aiogram 3.x адаптер
|
||||
|
|
@ -75,14 +77,15 @@ surfaces-bot/
|
|||
|
||||
```python
|
||||
class PlatformClient(Protocol):
|
||||
async def get_or_create_user(...) -> User: ...
|
||||
async def create_session(...) -> Session: ...
|
||||
async def send_message(...) -> AgentResponse: ...
|
||||
async def close_session(...) -> None: ...
|
||||
async def get_settings(...) -> UserSettings: ...
|
||||
async def update_settings(...) -> None: ...
|
||||
async def get_or_create_user(self, external_id: str, platform: str, ...) -> User: ...
|
||||
async def send_message(self, user_id: str, chat_id: str, text: str, ...) -> MessageResponse: ...
|
||||
async def get_settings(self, user_id: str) -> UserSettings: ...
|
||||
async def update_settings(self, user_id: str, action: Any) -> None: ...
|
||||
```
|
||||
|
||||
Бот не управляет lifecycle контейнеров — это делает Master (платформа).
|
||||
Бот передаёт `user_id` + `chat_id` + сообщение; платформа сама решает нужно ли поднять контейнер.
|
||||
|
||||
Сейчас: `MockPlatformClient` в `platform/mock.py`.
|
||||
Когда SDK готов: добавляем `SdkPlatformClient`, меняем одну строку в DI. Адаптеры и ядро не трогаем.
|
||||
|
||||
|
|
|
|||
|
|
@ -65,12 +65,12 @@ Space: «Lambda — {display_name}»
|
|||
1. Пользователь пишет `!new` или `!new Анализ конкурентов`
|
||||
2. Бот создаёт новую комнату в Space
|
||||
3. Приглашает пользователя
|
||||
4. Пишет приветствие и создаёт сессию на платформе
|
||||
4. Пишет приветствие; при первом сообщении платформа автоматически поднимает контейнер
|
||||
5. Пользователь переходит в новую комнату — начинает диалог
|
||||
|
||||
### В моке
|
||||
- Space и комнаты создаются реально через matrix-nio
|
||||
- Сессии — через MockPlatformClient
|
||||
- Сообщения передаются в MockPlatformClient с `chat_id` (C1, C2...)
|
||||
- История хранится в Matrix нативно
|
||||
|
||||
---
|
||||
|
|
@ -208,15 +208,13 @@ Matrix поддерживает реакции на сообщения (`m.react
|
|||
|
||||
### Статус и диагностика
|
||||
```
|
||||
!status — состояние агента и платформы
|
||||
!sessions — список активных сессий
|
||||
!status — состояние платформы и чатов
|
||||
!whoami — текущий аккаунт платформы
|
||||
```
|
||||
|
||||
```
|
||||
Статус:
|
||||
Платформа: ✅ доступна
|
||||
Агент: ✅ активен (сессия #abc123)
|
||||
Аккаунт: user@lambda.lab
|
||||
Активных чатов: 3
|
||||
```
|
||||
|
|
@ -230,7 +228,7 @@ Matrix поддерживает реакции на сообщения (`m.react
|
|||
↓
|
||||
SpaceSetup → Idle (в комнате Настройки)
|
||||
↓
|
||||
[новая комната] → SessionCreated → Idle (в чате)
|
||||
[новая комната] → ChatCreated → Idle (в чате)
|
||||
↓
|
||||
ReceivingMessage → WaitingResponse → Idle
|
||||
↓
|
||||
|
|
|
|||
|
|
@ -23,10 +23,12 @@ Surface Protocol — это общий язык между адаптерами
|
|||
surfaces-bot/
|
||||
core/
|
||||
protocol.py — все унифицированные структуры данных
|
||||
handler.py — логика: IncomingEvent → OutgoingEvent
|
||||
session.py — управление сессиями и чатами
|
||||
auth.py — AuthFlow
|
||||
settings.py — SettingsAction, управление настройками
|
||||
handler.py — EventDispatcher: IncomingEvent → OutgoingEvent
|
||||
handlers/ — обработчики по типам событий (start, message, chat, settings, callback)
|
||||
store.py — StateStore Protocol + InMemoryStore + SQLiteStore
|
||||
chat.py — ChatManager: метаданные чатов C1/C2/C3
|
||||
auth.py — AuthManager, AuthFlow
|
||||
settings.py — SettingsManager, SettingsAction
|
||||
|
||||
adapter/
|
||||
telegram/ — aiogram адаптер
|
||||
|
|
@ -35,7 +37,6 @@ surfaces-bot/
|
|||
matrix/ — matrix-nio адаптер
|
||||
converter.py — matrix-nio Event → IncomingEvent, OutgoingEvent → Matrix API
|
||||
bot.py — точка входа, клиент
|
||||
_template.py — шаблон для новой поверхности
|
||||
|
||||
platform/
|
||||
interface.py — Protocol: PlatformClient
|
||||
|
|
@ -169,16 +170,15 @@ class OutgoingTyping:
|
|||
Унифицированные события для управления чатами и подключением.
|
||||
|
||||
### ChatContext
|
||||
Состояние чата — общее для всех поверхностей.
|
||||
Метаданные чата — общие для всех поверхностей. Хранятся ботом, lifecycle контейнера управляет платформа (Master).
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class ChatContext:
|
||||
chat_id: str # "C1" | "C2" — ID в воркспейсе платформы
|
||||
chat_id: str # "C1" | "C2" — ID чата в воркспейсе платформы
|
||||
display_name: str # «Чат 1» | «Анализ рынка»
|
||||
platform: str
|
||||
surface_ref: str # room_id в Matrix | topic_id в Telegram
|
||||
session_id: str | None # активная сессия платформы
|
||||
created_at: datetime
|
||||
is_archived: bool
|
||||
```
|
||||
|
|
@ -281,8 +281,7 @@ class MySurfaceAdapter:
|
|||
|
||||
Любая новая поверхность получает без дополнительного кода:
|
||||
|
||||
- управление сессиями (создание, переключение, закрытие)
|
||||
- управление чатами (`ChatContext`)
|
||||
- управление чатами (`ChatContext`, C1/C2/C3)
|
||||
- аутентификацию (`AuthFlow`)
|
||||
- подтверждение действий (`ConfirmationRequest`)
|
||||
- все настройки (коннекторы, скиллы, SOUL, безопасность, подписка)
|
||||
|
|
@ -297,15 +296,17 @@ class MySurfaceAdapter:
|
|||
|
||||
```python
|
||||
class PlatformClient(Protocol):
|
||||
async def get_or_create_user(self, user_id: str, platform: str) -> User: ...
|
||||
async def create_session(self, user_id: str, chat_id: str) -> Session: ...
|
||||
async def send_message(self, session_id: str, text: str, attachments: list) -> AgentResponse: ...
|
||||
async def close_session(self, session_id: str) -> None: ...
|
||||
async def get_chat_history(self, user_id: str, chat_id: str) -> list[Message]: ...
|
||||
async def get_or_create_user(self, external_id: str, platform: str,
|
||||
display_name: str | None = None) -> User: ...
|
||||
async def send_message(self, user_id: str, chat_id: str, text: str,
|
||||
attachments: list | None = None) -> MessageResponse: ...
|
||||
async def get_settings(self, user_id: str) -> UserSettings: ...
|
||||
async def update_settings(self, user_id: str, action: SettingsAction) -> None: ...
|
||||
async def update_settings(self, user_id: str, action: Any) -> None: ...
|
||||
```
|
||||
|
||||
Бот **не управляет lifecycle контейнеров** — это делает Master (платформа).
|
||||
Бот передаёт `user_id` + `chat_id` + текст; Master сам решает нужно ли поднять контейнер, смонтировать `C1/`/`C2/`, запустить агента.
|
||||
|
||||
`MockPlatformClient` реализует этот протокол сейчас.
|
||||
Реальный SDK — тоже реализует этот протокол, заменяя один файл.
|
||||
Адаптеры поверхностей и ядро не меняются вообще.
|
||||
|
|
|
|||
|
|
@ -51,11 +51,11 @@
|
|||
1. Пользователь пишет `/new` или нажимает кнопку
|
||||
2. Бот спрашивает название (опционально, можно пропустить)
|
||||
3. Бот создаёт новую тему в группе: «Чат 1», «Чат 2» и т.д.
|
||||
4. Бот отправляет в новую тему приветствие и создаёт сессию на платформе
|
||||
4. Бот отправляет в новую тему приветствие; при первом сообщении платформа автоматически поднимает контейнер
|
||||
|
||||
### В моке
|
||||
- Группа и темы создаются реально через Bot API
|
||||
- Сессии на платформе — через MockPlatformClient
|
||||
- Сообщения передаются в MockPlatformClient с `chat_id` (C1, C2...)
|
||||
- История в темах хранится нативно в Telegram, ничего не нужно делать
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@
|
|||
sequenceDiagram
|
||||
actor User
|
||||
participant Bot as Telegram/Matrix Bot
|
||||
participant Platform as Lambda Platform
|
||||
participant Platform as Lambda Platform (Master)
|
||||
|
||||
User->>Bot: /start
|
||||
Bot->>Platform: GET /users/{tg_id}?platform=telegram
|
||||
|
|
@ -23,20 +23,13 @@ sequenceDiagram
|
|||
Bot->>User: Добро пожаловать обратно
|
||||
end
|
||||
|
||||
User->>Bot: Любое сообщение
|
||||
Bot->>Platform: POST /sessions (создаём сессию)
|
||||
Platform-->>Bot: {session_id, agent_id}
|
||||
|
||||
loop Диалог
|
||||
User->>Bot: Сообщение
|
||||
Bot->>Platform: POST /sessions/{id}/messages
|
||||
Platform-->>Bot: {response}
|
||||
loop Диалог (бот не управляет сессиями — Master делает это автоматически)
|
||||
User->>Bot: Сообщение в чат C1/C2/...
|
||||
Bot->>Platform: POST /users/{user_id}/chats/{chat_id}/messages
|
||||
Note over Platform: Master поднимает контейнер,<br/>монтирует нужный чат, запускает агента
|
||||
Platform-->>Bot: {message_id, response, tokens_used}
|
||||
Bot->>User: Ответ агента
|
||||
end
|
||||
|
||||
User->>Bot: /end или таймаут
|
||||
Bot->>Platform: DELETE /sessions/{id}
|
||||
Bot->>User: Сессия завершена
|
||||
```
|
||||
|
||||
---
|
||||
|
|
@ -45,15 +38,19 @@ sequenceDiagram
|
|||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Idle: /start
|
||||
[*] --> Unauthenticated: первый контакт
|
||||
|
||||
Idle --> InSession: любое сообщение
|
||||
InSession --> InSession: сообщение пользователя
|
||||
InSession --> Idle: /end
|
||||
Unauthenticated --> Idle: /start (auth confirmed)
|
||||
|
||||
Idle --> WaitingResponse: сообщение пользователя
|
||||
WaitingResponse --> Idle: ответ получен
|
||||
WaitingResponse --> Error: ошибка платформы
|
||||
|
||||
Idle --> Idle: /new (создан новый чат)
|
||||
Idle --> ConfirmAction: агент запрашивает подтверждение
|
||||
ConfirmAction --> Idle: подтверждено / отменено
|
||||
|
||||
InSession --> Error: ошибка платформы
|
||||
Error --> Idle: /start
|
||||
Error --> InSession: retry
|
||||
```
|
||||
|
||||
---
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue