ErisPulse ErisPulse
Открыть интерактивную версию →
Разделы страницы
Статическое зеркало — интерактивная версия является основной Открыть интерактивную версию →

Коммуникация между модулями

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 синтезированных событий

При регистрации адаптера (начало жизненного цикла нового подключения) автоматически сбрасывается кэш дедупликации.

Связанные документы