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

docs: generalize new surface guide and clean up legacy docs

Browse source
This commit is contained in:
Mikhail Putilovskij 2026-05-03 00:01:25 +03:00
parent 0f79494fbe
commit e7e3912b5f
9 changed files with 59 additions and 433 deletions
Download patch file Download diff file Expand all files Collapse all files

21
docs/surface-protocol.md
View file

@ -38,9 +38,10 @@ surfaces-bot/
converter.py — matrix-nio Event → IncomingEvent, OutgoingEvent → Matrix API
bot.py — точка входа, клиент
platform/
interface.py — Protocol: PlatformClient
mock.py — MockPlatformClient
sdk/
interface.py — Protocol: PlatformClient (контракт к SDK)
real.py — RealPlatformClient (через AgentApi)
mock.py — MockPlatformClient (для локальных тестов)
```
---
@ -140,7 +141,7 @@ class UIButton:
```
Telegram рендерит это как InlineKeyboard.
Matrix рендерит как текст с описанием реакций или HTML-кнопки.
Matrix рендерит как текст (в MVP).
### OutgoingNotification
Асинхронное уведомление — агент закончил долгую задачу.
@ -209,7 +210,7 @@ class ConfirmationRequest:
```
Telegram показывает как Inline-кнопки.
Matrix показывает как реакции 👍 / ❌.
Matrix показывает как запрос для `!yes` / `!no`.
Ядро не знает как именно — только получает `IncomingCallback` с `action: "confirm"`.
---
@ -304,9 +305,9 @@ class PlatformClient(Protocol):
async def update_settings(self, user_id: str, action: Any) -> None: ...
```
Бот **не управляет lifecycle контейнеров** — это делает Master (платформа).
Бот передаёт `user_id` + `chat_id` + текст; Master сам решает нужно ли поднять контейнер, смонтировать `C1/`/`C2/`, запустить агента.
Бот **не управляет lifecycle контейнеров** агентов. Запуск/перезапуск агентов — ответственность платформы.
Бот передаёт `user_id` + `chat_id` + текст.
`MockPlatformClient` реализует этот протокол сейчас.
Реальный SDK — тоже реализует этот протокол, заменяя один файл.
Адаптеры поверхностей и ядро не меняются вообще.
`MockPlatformClient` реализует этот протокол для локальных тестов.
Реальный SDK используется через `RealPlatformClient` (`sdk/real.py`), который подключается к `AgentApi` по WebSocket.
Адаптеры поверхностей и ядро не меняются вообще, привязка идёт через `config/matrix-agents.yaml`.