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:
Mikhail Putilovskij 2026-03-29 00:55:24 +03:00
parent 36730ae716
commit 4f5c5679d5
5 changed files with 52 additions and 53 deletions

View file

@ -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 — тоже реализует этот протокол, заменяя один файл.
Адаптеры поверхностей и ядро не меняются вообще.