Surfaces_team/surfaces
4
0
Fork 0
Code Issues 5 Pull requests Projects Releases Packages Wiki Activity Actions

docs: sync all markdown with current architecture

Browse source 
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:
Mikhail Putilovskij 2026-03-29 00:55:24 +03:00
parent 36730ae716
commit 4f5c5679d5
5 changed files with 52 additions and 53 deletions
Download patch file Download diff file Expand all files Collapse all files

23
README.md
View file

@ -29,10 +29,12 @@
surfaces-bot/ surfaces-bot/
core/ — общее ядро, не зависит от транспорта core/ — общее ядро, не зависит от транспорта
protocol.py — унифицированные структуры (IncomingMessage, OutgoingUI, ...) protocol.py — унифицированные структуры (IncomingMessage, OutgoingUI, ...)
handler.py — логика: IncomingEvent → OutgoingEvent handler.py — EventDispatcher: IncomingEvent → OutgoingEvent
session.py — управление сессиями и чатами handlers/ — обработчики по типам событий
auth.py — аутентификация store.py — StateStore Protocol + InMemoryStore + SQLiteStore
settings.py — коннекторы, скиллы, SOUL, безопасность chat.py — ChatManager: метаданные чатов C1/C2/C3
auth.py — AuthManager: аутентификация
settings.py — SettingsManager: коннекторы, скиллы, SOUL, безопасность
adapter/ adapter/
telegram/ — aiogram 3.x адаптер telegram/ — aiogram 3.x адаптер
@ -75,14 +77,15 @@ surfaces-bot/
```python ```python
class PlatformClient(Protocol): class PlatformClient(Protocol):
async def get_or_create_user(...) -> User: ... async def get_or_create_user(self, external_id: str, platform: str, ...) -> User: ...
async def create_session(...) -> Session: ... async def send_message(self, user_id: str, chat_id: str, text: str, ...) -> MessageResponse: ...
async def send_message(...) -> AgentResponse: ... async def get_settings(self, user_id: str) -> UserSettings: ...
async def close_session(...) -> None: ... async def update_settings(self, user_id: str, action: Any) -> None: ...
async def get_settings(...) -> UserSettings: ...
async def update_settings(...) -> None: ...
``` ```
Бот не управляет lifecycle контейнеров — это делает Master (платформа).
Бот передаёт `user_id` + `chat_id` + сообщение; платформа сама решает нужно ли поднять контейнер.
Сейчас: `MockPlatformClient` в `platform/mock.py`. Сейчас: `MockPlatformClient` в `platform/mock.py`.
Когда SDK готов: добавляем `SdkPlatformClient`, меняем одну строку в DI. Адаптеры и ядро не трогаем. Когда SDK готов: добавляем `SdkPlatformClient`, меняем одну строку в DI. Адаптеры и ядро не трогаем.

10
docs/matrix-prototype.md
View file

@ -65,12 +65,12 @@ Space: «Lambda — {display_name}»
1. Пользователь пишет `!new` или `!new Анализ конкурентов` 1. Пользователь пишет `!new` или `!new Анализ конкурентов`
2. Бот создаёт новую комнату в Space 2. Бот создаёт новую комнату в Space
3. Приглашает пользователя 3. Приглашает пользователя
4. Пишет приветствие и создаёт сессию на платформе 4. Пишет приветствие; при первом сообщении платформа автоматически поднимает контейнер
5. Пользователь переходит в новую комнату — начинает диалог 5. Пользователь переходит в новую комнату — начинает диалог
### В моке ### В моке
- Space и комнаты создаются реально через matrix-nio - Space и комнаты создаются реально через matrix-nio
- Сессии — через MockPlatformClient - Сообщения передаются в MockPlatformClient с `chat_id` (C1, C2...)
- История хранится в Matrix нативно - История хранится в Matrix нативно
--- ---
@ -208,15 +208,13 @@ Matrix поддерживает реакции на сообщения (`m.react
### Статус и диагностика ### Статус и диагностика
``` ```
!status — состояние агента и платформы !status — состояние платформы и чатов
!sessions — список активных сессий
!whoami — текущий аккаунт платформы !whoami — текущий аккаунт платформы
``` ```
``` ```
Статус: Статус:
Платформа: ✅ доступна Платформа: ✅ доступна
Агент: ✅ активен (сессия #abc123)
Аккаунт: user@lambda.lab Аккаунт: user@lambda.lab
Активных чатов: 3 Активных чатов: 3
``` ```
@ -230,7 +228,7 @@ Matrix поддерживает реакции на сообщения (`m.react
↓ ↓
SpaceSetup → Idle (в комнате Настройки) SpaceSetup → Idle (в комнате Настройки)
↓ ↓
[новая комната] → SessionCreated → Idle (в чате) [новая комната] → ChatCreated → Idle (в чате)
↓ ↓
ReceivingMessage → WaitingResponse → Idle ReceivingMessage → WaitingResponse → Idle
↓ ↓

33
docs/surface-protocol.md
View file

@ -23,10 +23,12 @@ Surface Protocol — это общий язык между адаптерами
surfaces-bot/ surfaces-bot/
core/ core/
protocol.py — все унифицированные структуры данных protocol.py — все унифицированные структуры данных
handler.py — логика: IncomingEvent → OutgoingEvent handler.py — EventDispatcher: IncomingEvent → OutgoingEvent
session.py — управление сессиями и чатами handlers/ — обработчики по типам событий (start, message, chat, settings, callback)
auth.py — AuthFlow store.py — StateStore Protocol + InMemoryStore + SQLiteStore
settings.py — SettingsAction, управление настройками chat.py — ChatManager: метаданные чатов C1/C2/C3
auth.py — AuthManager, AuthFlow
settings.py — SettingsManager, SettingsAction
adapter/ adapter/
telegram/ — aiogram адаптер telegram/ — aiogram адаптер
@ -35,7 +37,6 @@ surfaces-bot/
matrix/ — matrix-nio адаптер matrix/ — matrix-nio адаптер
converter.py — matrix-nio Event → IncomingEvent, OutgoingEvent → Matrix API converter.py — matrix-nio Event → IncomingEvent, OutgoingEvent → Matrix API
bot.py — точка входа, клиент bot.py — точка входа, клиент
_template.py — шаблон для новой поверхности
platform/ platform/
interface.py — Protocol: PlatformClient interface.py — Protocol: PlatformClient
@ -169,16 +170,15 @@ class OutgoingTyping:
Унифицированные события для управления чатами и подключением. Унифицированные события для управления чатами и подключением.
### ChatContext ### ChatContext
Состояние чата — общее для всех поверхностей. Метаданные чата — общие для всех поверхностей. Хранятся ботом, lifecycle контейнера управляет платформа (Master).
```python ```python
@dataclass @dataclass
class ChatContext: class ChatContext:
chat_id: str # "C1" | "C2" — ID в воркспейсе платформы chat_id: str # "C1" | "C2" — ID чата в воркспейсе платформы
display_name: str # «Чат 1» | «Анализ рынка» display_name: str # «Чат 1» | «Анализ рынка»
platform: str platform: str
surface_ref: str # room_id в Matrix | topic_id в Telegram surface_ref: str # room_id в Matrix | topic_id в Telegram
session_id: str | None # активная сессия платформы
created_at: datetime created_at: datetime
is_archived: bool is_archived: bool
``` ```
@ -281,8 +281,7 @@ class MySurfaceAdapter:
Любая новая поверхность получает без дополнительного кода: Любая новая поверхность получает без дополнительного кода:
- управление сессиями (создание, переключение, закрытие) - управление чатами (`ChatContext`, C1/C2/C3)
- управление чатами (`ChatContext`)
- аутентификацию (`AuthFlow`) - аутентификацию (`AuthFlow`)
- подтверждение действий (`ConfirmationRequest`) - подтверждение действий (`ConfirmationRequest`)
- все настройки (коннекторы, скиллы, SOUL, безопасность, подписка) - все настройки (коннекторы, скиллы, SOUL, безопасность, подписка)
@ -297,15 +296,17 @@ class MySurfaceAdapter:
```python ```python
class PlatformClient(Protocol): class PlatformClient(Protocol):
async def get_or_create_user(self, user_id: str, platform: str) -> User: ... async def get_or_create_user(self, external_id: str, platform: str,
async def create_session(self, user_id: str, chat_id: str) -> Session: ... display_name: str | None = None) -> User: ...
async def send_message(self, session_id: str, text: str, attachments: list) -> AgentResponse: ... async def send_message(self, user_id: str, chat_id: str, text: str,
async def close_session(self, session_id: str) -> None: ... attachments: list | None = None) -> MessageResponse: ...
async def get_chat_history(self, user_id: str, chat_id: str) -> list[Message]: ...
async def get_settings(self, user_id: str) -> UserSettings: ... 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` реализует этот протокол сейчас. `MockPlatformClient` реализует этот протокол сейчас.
Реальный SDK — тоже реализует этот протокол, заменяя один файл. Реальный SDK — тоже реализует этот протокол, заменяя один файл.
Адаптеры поверхностей и ядро не меняются вообще. Адаптеры поверхностей и ядро не меняются вообще.

4
docs/telegram-prototype.md
View file

@ -51,11 +51,11 @@
1. Пользователь пишет `/new` или нажимает кнопку 1. Пользователь пишет `/new` или нажимает кнопку
2. Бот спрашивает название (опционально, можно пропустить) 2. Бот спрашивает название (опционально, можно пропустить)
3. Бот создаёт новую тему в группе: «Чат 1», «Чат 2» и т.д. 3. Бот создаёт новую тему в группе: «Чат 1», «Чат 2» и т.д.
4. Бот отправляет в новую тему приветствие и создаёт сессию на платформе 4. Бот отправляет в новую тему приветствие; при первом сообщении платформа автоматически поднимает контейнер
### В моке ### В моке
- Группа и темы создаются реально через Bot API - Группа и темы создаются реально через Bot API
- Сессии на платформе — через MockPlatformClient - Сообщения передаются в MockPlatformClient с `chat_id` (C1, C2...)
- История в темах хранится нативно в Telegram, ничего не нужно делать - История в темах хранится нативно в Telegram, ничего не нужно делать
--- ---

35
docs/user-flow.md
View file

@ -11,7 +11,7 @@
sequenceDiagram sequenceDiagram
actor User actor User
participant Bot as Telegram/Matrix Bot participant Bot as Telegram/Matrix Bot
participant Platform as Lambda Platform participant Platform as Lambda Platform (Master)
User->>Bot: /start User->>Bot: /start
Bot->>Platform: GET /users/{tg_id}?platform=telegram Bot->>Platform: GET /users/{tg_id}?platform=telegram
@ -23,20 +23,13 @@ sequenceDiagram
Bot->>User: Добро пожаловать обратно Bot->>User: Добро пожаловать обратно
end end
User->>Bot: Любое сообщение loop Диалог (бот не управляет сессиями — Master делает это автоматически)
Bot->>Platform: POST /sessions (создаём сессию) User->>Bot: Сообщение в чат C1/C2/...
Platform-->>Bot: {session_id, agent_id} Bot->>Platform: POST /users/{user_id}/chats/{chat_id}/messages
Note over Platform: Master поднимает контейнер,<br/>монтирует нужный чат, запускает агента
loop Диалог Platform-->>Bot: {message_id, response, tokens_used}
User->>Bot: Сообщение
Bot->>Platform: POST /sessions/{id}/messages
Platform-->>Bot: {response}
Bot->>User: Ответ агента Bot->>User: Ответ агента
end end
User->>Bot: /end или таймаут
Bot->>Platform: DELETE /sessions/{id}
Bot->>User: Сессия завершена
``` ```
--- ---
@ -45,15 +38,19 @@ sequenceDiagram
```mermaid ```mermaid
stateDiagram-v2 stateDiagram-v2
[*] --> Idle: /start [*] --> Unauthenticated: первый контакт
Idle --> InSession: любое сообщение Unauthenticated --> Idle: /start (auth confirmed)
InSession --> InSession: сообщение пользователя
InSession --> Idle: /end Idle --> WaitingResponse: сообщение пользователя
WaitingResponse --> Idle: ответ получен
WaitingResponse --> Error: ошибка платформы
Idle --> Idle: /new (создан новый чат)
Idle --> ConfirmAction: агент запрашивает подтверждение
ConfirmAction --> Idle: подтверждено / отменено
InSession --> Error: ошибка платформы
Error --> Idle: /start Error --> Idle: /start
Error --> InSession: retry
``` ```
--- ---