Коммуникация между модулями
Tip
Когда читать эту статью: при необходимости вызова между модулями (RPC), определении контракта сервиса, целевой рассылке событий или восстановлении при холодном запуске. Если это не требуется — пропустите, это не повлияет на использование других функций.
Что вы узнаете: мнемоника выбора модели коммуникации (RPC / целевое событие / широковещательное),
meta.servicesкак контракт и каталог сервисов, конфигурация аудита исходящих вызовов, ленивое пробуждение и восстановление при холодном запуске.В этой статье не рассматривается: механизм регистрации / запуска / приоритетов самого события жизненного цикла (см. Управление жизненным циклом); конфигурация ленивого загрузки и объявление activate_on (см. Система ленивой загрузки).
Note
Содержание этой главы требует ErisPulse 2.8.0+.
В ErisPulse между модулями существует трехуровневая модель коммуникации, отсортированная по "точка-точка → целевая → широковещательная":
| Уровень | API | Семантика | Типичные сценарии |
|---|---|---|---|
| RPC | await sdk.module.call("Chat", "get_history", ...) |
Точечный запрос-ответ с контрактом / аудитом / таймаутом | Вызов функционала другого модуля (получение истории, перевод, возврат средств) |
| Целевое событие | await lifecycle.emit("message_received", {...}, to="Chat") |
Рассылка только модулям, зарегистрировавшим жизненный цикл-хук | Уведомление о состоянии от upstream в downstream ("получено новое сообщение") |
| Широковещательное событие | await lifecycle.emit("config.updated", {...}) |
Событие жизненного цикла, видимое по всей рамочной архитектуре | Горячая перезагрузка конфигурации, появление/исчезновение модулей |
{!--< tips >!--}
Мнемоника выбора: используйте call, если нужно получить ответ, используйте emit(..., to=...), если нужно уведомить только один модуль, используйте emit(...) для уведомления всех.
{!--< /tips >!--}
RPC: module.call
result = await sdk.module.call("Chat", "get_history", session_id, n=20)
Различия между module.call() и прямым доступом к атрибуту sdk.module.Chat.get_history(...) (без изменений):
module.call() |
Прямой доступ к атрибуту | |
|---|---|---|
| Целевой модуль не зарегистрирован / не активирован | Выбрасывает ModuleNotAvailableError |
Выбрасывает AttributeError |
| Ленивая загрузка модуля | Автоматически активируется (модули, управляемые событиями, используют блокировку активации) | Асинхронная инициализация модуля выбрасывает RuntimeError |
current_owner |
Присваивается целевому модулю (его внутренние wait_reply / отправка / логи корректно привязаны) | Сохраняется вызывающий модуль |
| Таймаут | По умолчанию 30 секунд (timeout= позволяет перезаписать, None отключает таймаут) |
Нет |
| scope аудит | Вызыватель проходит через контрольный пункт actions.<вызыватель>.call |
Нет |
| Проверка контракта | Белый список meta.services |
Нет |
Система исключений
ModuleError # Базовый класс исключений модульной системы
└── ModuleCallError # Базовый класс для вызовов между модулями (содержит атрибуты module / method)
├── ModuleNotAvailableError # Целевой модуль не зарегистрирован / не активирован / активация не удалась
├── ServiceNotProvidedError # Метод не в белом списке / приватный метод / не существует
└── ModuleCallTimeoutError # Время ожидания асинхронного метода истекло
Все исключения входят в систему ErisPulseError, можно поймать их через from ErisPulse.Core import ModuleCallError.
Контракт сервиса: meta.services
Поставщик сервиса объявляет белый список предоставляемых методов в get_meta() (в симметрии с commands):
from ErisPulse.Core.Bases import BaseModule, ModuleMeta
class ChatModule(BaseModule):
@staticmethod
def get_meta() -> ModuleMeta:
return ModuleMeta(
name="聊天",
services=[
"get_history", # Простая форма
{"name": "translate", "description": "把文本翻译成指定语言"}, # С описанием
],
)
async def get_history(self, session_id, n=20): ...
async def translate(self, text, target_lang): ...
def _internal_helper(self): ... # Методы с подчеркиванием всегда запрещены для внешнего вызова
По умолчанию разработчик не замечает:
- Если
servicesне объявлен → все публичные методы по умолчанию доступны дляmodule.call()(как и при прямом доступе к атрибуту), без необходимости каких-либо объявления - После объявления → доступ сужается до белого списка, вызов за пределами списка выбрасывает
ServiceNotProvidedError— используется для маркировки "эти методы — те, что публично обещаны" - Основной контроль за ограничениями находится у пользователя:
scope.actionsопределяет "кто может вызывать кого" (см. аудит ниже),servicesмодуля автора — лишь объявление сервиса, два уровня не заменяют друг друга
Описание сервиса: для каждого сервиса можно добавить описание, читаемое человеком / ИИ — если не нужно, ничего не пишите, описание автоматически берется из первой строки docstring (рамка уже требует стиля docstring):
async def translate(self, text, target_lang):
"""把文本翻译成指定语言""" # ← Эта строка автоматически становится описанием сервиса
...
Подсказки по параметрам: вызывающей стороне (особенно ИИ-агентам) нужно знать, что означает каждый параметр. Если не нужно, ничего не пишите,
подсказки автоматически берутся из :param: строк docstring:
async def render_card(self, html, width=800, height=0):
"""渲染 HTML 为图片文件
:param html: 要渲染的 HTML 文本 ← Автоматически становится подсказкой параметра
:param width: 画布宽度像素,0 为按内容自适应
:param height: 画布高度像素,0 为按内容自适应
"""
Для тонкой настройки (переопределение docstring / мультиязычность) используйте словарь для описания description и parameters
(оба поддерживают словарь i18n; parameters объединяется с docstring по параметрам, при явном объявление параметра в словаре он имеет приоритет,
объявленные параметры, которых нет в сигнатуре, будут отфильтрованы):
services=[
{"name": "translate", "description": "把文本翻译成指定语言"},
{"name": "summarize", "description": {"i18n": "Chat.meta.svc.summarize", "default": "摘要对话"}},
{
"name": "render_card",
"description": "渲染 HTML 为图片文件",
"parameters": {"html": "HTML 文本", "width": "宽度像素,0 为自适应"},
},
]
Служба каталога: services()
sdk.module.services()
# {'Chat': [{'name': 'get_history', 'signature': '(session_id, n=20)',
# 'description': '把文本翻译成指定语言',
# 'parameters': {'session_id': '会话 ID', 'n': '返回条数'}}]}
sdk.module.services("Chat") # Только для определенного модуля
- В каталоге перечислены только модули с явно объявленным
meta.services(модули без объявления не появляются в каталоге) - Каждый сервис снабжен строкой сигнатуры метода (
inspect.signature), описанием и подсказками по параметрам - Ленивые модули также попадают в каталог (обнаружение сервисов происходит до загрузки) — вызывающая сторона может решить,
нужно ли
call()для активации целевого модуля - Также включены в топологию:
sdk.module.get_topology()для каждого модуля содержит полеservices
{!--< tips >!--}
Путь к MCP: каталог сервисов (имя + сигнатура + описание + подсказки по параметрам) — это форма MCP tool —
каждый сервис по сути имеет вид {"name", "description", "parameters"}.
В будущем фреймворк может напрямую экспортировать services() как конечную точку MCP-сервера, чтобы ИИ мог обнаруживать и вызывать возможности модуля;
scope.actions.call аудит становится естественным брандмауэром безопасности для вызовов ИИ.
{!--< /tips >!--}
Аудит исходящих вызовов: кто может вызывать кого
Каждый вызов module.call() проходит через контрольный пункт scope исходящих вызовов от имени вызывающего модуля:
[ErisPulse.scope.actions.CallerModule.call]
deny = ["Chat.get_history"] # Запретить CallerModule вызывать Chat.get_history
# allow = ["Chat.get_*"] # Или белый список: разрешить вызывать только сервисы Chat, начинающиеся на get_
- Формат
name—<目标模块>.<方法名>, поддерживает точное / шаблон /re:регулярное выражение - Вызовы фреймворка (без контекста owner, например, запуск скриптов) не подвергаются аудиту
- Отказ в вызове выбрасывает
ModuleCallError(TRACE логcore.module.call_denied)
Способы настройки см. в Scope в разделе исходящего аудита.
Направленные события: параметр to в lifecycle.emit
События жизненного цикла поддерживают направленную передачу: указание to для целевого владельца (owner) заставляет событие доставляться только хукам, зарегистрированным с этим
владельцем (хуки, зарегистрированные в on_load, автоматически присваиваются владельцу модуля),
остальные модули и обработчики с * не получают уведомления.
from ErisPulse.Core.lifecycle import lifecycle
# Отправитель: событие доставляется только хукам, зарегистрированным модулем Chat
await lifecycle.emit("message_received", {"text": "hi", "from": "u1"}, to="Chat")
# Подписчик (внутри модуля Chat): регистрирует хук с таким же именем, owner автоматически записывается при регистрации
@lifecycle.on("message_received")
async def on_message_received(data): ...
@lifecycle.on("message") # Префикс родительского события также действует (фильтруется по owner)
async def on_any(data): ...
Семантические детали:
- Если у целевого владельца нет зарегистрированных хуков → событие тихо отбрасывается (не отправляется туда, где его нет),
можно заранее проверить наличие хуков с помощью
lifecycle.has_handlers("message_received") - Если
data— словарь, автоматически добавляется_trace_id(не перезаписывает уже существующее значение), интегрируется с системой трассировки - Широковещательные и направленные события используют одну и ту же систему регистрации хуков:
emit(...)безtoрассылает по всей системе, сto— одно и то же событие видно только целевому модулю emit_sync/submit_event(совместимый API) также поддерживают параметрto=
Note
Направленные события — это лёгкие уведомления, не проверяются на существование целевого модуля и не активируют ленивую загрузку; если нужно проверить существование цели, аудит контракта или получить возвращаемое значение, используйте RPC: module.call.
Ленивая загрузка и вызов
module.call() прозрачно активирует ленивые модули:
- Модули, управляемые событиями (
activate_onобъявлен) → используют блокировку активации_activate(), после активации stub-триггер автоматически удаляется - Обычные ленивые модули → синхронная инициализация или обычный путь загрузки (идемпотентно)
- Активация не удалась →
ModuleNotAvailableError
То есть: вызывающий модуль не должен заботиться о том, загружен ли целевой модуль, и не нужно ждать какого-либо события для его активации.
Направленные события (lifecycle.emit(..., to=...)) не активируют ленивую загрузку — если целевой модуль не загружен, у него нет хуков,
событие тихо отбрасывается; если нужно гарантировать доставку, используйте module.call().
Воспроизведение при холодном запуске
Новый / перезапущенный модуль пропустил часть чата — get_load_strategy(replay=...) позволяет фреймворку после готовности модуля
воспроизвести последние сообщения из почтового ящика сессии для этого модуля:
from ErisPulse.loaders import ModuleLoadStrategy
class MyAIModule(BaseModule):
@staticmethod
def get_load_strategy():
return ModuleLoadStrategy(
lazy_load=False,
priority=100,
replay="5m", # Воспроизвести последние 5 минут (возможны и другие форматы: "1h" / "300" секунд)
)
async def on_load(self, event):
@message.on_message()
async def handle(e):
if e.get("replayed"):
# Синтезированное событие: только для восстановления контекста, не вызывает побочных эффектов, таких как отправка
...
Семантические детали:
- Источник данных — почтовый ящик сессии (
sdk.transcript.recent()), воспроизведение происходит в фоне после загрузки модуля, не блокируя запуск - Синтезированное событие снабжается флагом
replayed: True, полнымиplatform / detail_type / user_id / alt_message, доставляется только обработчикам этого модуля — другие модули не затрагиваются воспроизведением - Если почтовый ящик не включен / нет записей / указано недопустимое время воспроизведения (
replay_invalidпредупреждение) — тихо пропускается
Дедупликация событий
При повторном подключении websocket-платформы часто повторно отправляются одни и те же события (с одинаковым event["id"]) — на входе распределения по id делается
LRU-дедупликация (емкость 4096), одно и то же событие доставляется только один раз.
[ErisPulse.framework]
event_dedupe = true # По умолчанию включено; в тестовой среде можно отключить для фиксированных id синтезированных событий
При регистрации адаптера (начало жизненного цикла нового подключения) автоматически сбрасывается кэш дедупликации.
Связанные документы
- Система взаимодействий - wait_reply / таймеры / многопоточное ожидание / взаимное исключение сессий
- Scope - полная конфигурация аудита исходящих вызовов
- Система ownership - как контекст owner проходит через межмодульные вызовы
- Система ленивой загрузки - ленивая загрузка и активация на основе событий (activate_on)
- Управление жизненным циклом - механизм широковещательной шины событий