From 4f5c5679d5b0ab7a2fbf8927e443898e51d1e3a9 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Sun, 29 Mar 2026 00:55:24 +0300 Subject: [PATCH] docs: sync all markdown with current architecture MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- README.md | 23 +++++++++++++---------- docs/matrix-prototype.md | 10 ++++------ docs/surface-protocol.md | 33 +++++++++++++++++---------------- docs/telegram-prototype.md | 4 ++-- docs/user-flow.md | 35 ++++++++++++++++------------------- 5 files changed, 52 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index 23ae9ba..aedfc16 100644 --- a/README.md +++ b/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. Адаптеры и ядро не трогаем. diff --git a/docs/matrix-prototype.md b/docs/matrix-prototype.md index 6e9b6bd..5e57c88 100644 --- a/docs/matrix-prototype.md +++ b/docs/matrix-prototype.md @@ -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 ↓ diff --git a/docs/surface-protocol.md b/docs/surface-protocol.md index eb2069b..ca66000 100644 --- a/docs/surface-protocol.md +++ b/docs/surface-protocol.md @@ -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 — тоже реализует этот протокол, заменяя один файл. Адаптеры поверхностей и ядро не меняются вообще. diff --git a/docs/telegram-prototype.md b/docs/telegram-prototype.md index e867f99..c58a1e5 100644 --- a/docs/telegram-prototype.md +++ b/docs/telegram-prototype.md @@ -51,11 +51,11 @@ 1. Пользователь пишет `/new` или нажимает кнопку 2. Бот спрашивает название (опционально, можно пропустить) 3. Бот создаёт новую тему в группе: «Чат 1», «Чат 2» и т.д. -4. Бот отправляет в новую тему приветствие и создаёт сессию на платформе +4. Бот отправляет в новую тему приветствие; при первом сообщении платформа автоматически поднимает контейнер ### В моке - Группа и темы создаются реально через Bot API -- Сессии на платформе — через MockPlatformClient +- Сообщения передаются в MockPlatformClient с `chat_id` (C1, C2...) - История в темах хранится нативно в Telegram, ничего не нужно делать --- diff --git a/docs/user-flow.md b/docs/user-flow.md index 30fa15c..efe22f1 100644 --- a/docs/user-flow.md +++ b/docs/user-flow.md @@ -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 поднимает контейнер,
монтирует нужный чат, запускает агента + 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 ``` ---