モジュール間通信
Tip
この記事を読むタイミング:RPCによるモジュール間呼び出し、サービス契約、宛先指定イベント、またはコールドスタート時のイベントリプレイが必要な場合。必要なければ飛ばしても、他の機能の使用に影響はありません。
この記事を読んだ後には:3層通信モデル(RPC / 宛先指定イベント / ブロードキャスト)の選択のコツ、
meta.servicesによるサービス契約とサービスディレクトリ、出向き監査の設定方法、およびラグドウォーキングとコールドスタート時のイベントリプレイについて理解できます。この記事では扱いません:ライフサイクルイベントシステム自体の登録 / 発火 / 優先度のメカニズム(ライフサイクル管理を参照);ラグドロードの設定と activate_on の宣言(ラグドロードシステムを参照)。
Note
本章の内容は ErisPulse 2.8.0+ が必要です。
ErisPulse では、モジュール間には3層の通信モデルが存在し、「点対点 → 宛先指定 → ブロードキャスト」の順序で構成されています:
| 層 | API | 意味 | 代表的なシナリオ |
|---|---|---|---|
| RPC | await sdk.module.call("Chat", "get_history", ...) |
点対点のリクエスト-レスポンス、契約 / 監査 / タイムアウト付き | 他のモジュールの機能を呼び出す(履歴の取得、翻訳、返金など) |
| 宛先指定イベント | await lifecycle.emit("message_received", {...}, to="Chat") |
指定されたモジュールが登録したライフサイクルフックにのみ配信 | 上流の状態変化を下流に通知する(「新しいメッセージを受け取りました」など) |
| ブロードキャスト | 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)
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 # メソッドが services ホワイトリストにない / 私的メソッド / 存在しない
└── 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はサービス面の宣言に過ぎず、2つの層は互いに置換不可能
サービス紹介:各サービスに人間 / AI が読める説明を付ける——不要なら何も書かなくてよい、説明はメソッドの docstring 首行(フレームワークは docstring 形式を要求している)から自動取得:
async def translate(self, text, target_lang):
"""テキストを指定された言語に翻訳する""" # ← この行がサービス紹介として自動取得される
...
パラメータ提示:呼び出し元(特に AI エージェント)は各パラメータの意味を知る必要がある。不要なら何も書かなくてよい、提示はメソッドの docstring の :param: 行から自動取得:
async def render_card(self, html, width=800, height=0):
"""HTMLを画像ファイルにレンダリングする
:param html: レンダリングするHTMLテキスト ← 自動的にパラメータ提示として取得される
:param width: 画布の幅ピクセル、0は内容に応じて自動調整
:param height: 画布の高さピクセル、0は内容に応じて自動調整
"""
微調整が必要な場合(docstring を上書き / 多言語対応)は dict 形式で description と parameters を宣言(両方とも i18n 辞書に対応;parameters はパラメータと docstring をマージし、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 サーバエンドポイントとして公開し、AI がモジュールの能力を発見して呼び出せるようにする。また、scope.actions.call 審査は AI 呼び出しのセキュリティゲートとして自然に機能する。
{!--< /tips >!--}
出力審査: 誰が誰を呼び出せるか
module.call() は呼び出し元モジュールの立場で scope の出力ゲートを通過する:
[ErisPulse.scope.actions.CallerModule.call]
deny = ["Chat.get_history"] # CallerModule が Chat の get_history を呼び出すことを禁止
# allow = ["Chat.get_*"] # またはホワイトリスト:get で始まるサービスのみを許可
nameの形式は<ターゲットモジュール>.<メソッド名>、正確な一致 / glob /re:正規表現が可能- フレームワーク層の呼び出し(owner コンテキストがない、例:起動スクリプト)は審査制約を受けない
- 拒否された呼び出しは
ModuleCallErrorをスロー(TRACE ログcore.module.call_denied)
設定方法は 作用域(scope) の出力側の詳細を参照。
指定イベント: lifecycle.emit の to パラメータ
ライフサイクルイベントは指定送信をサポート:to でターゲット所有者(owner)を指定すると、イベントはその 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): ...
意味の詳細:
- ターゲット owner に登録されたフックがない → イベントは静かに破棄(存在しない場所には送らない)、
lifecycle.has_handlers("message_received")で事前に検出可能 dataが dict の場合、_trace_idが自動的に付与される(既存値を上書きしない)、全トラッキングと連携- ブロードキャストと指定は同じフック登録を共有:
emit(...)にtoを指定しないと全フレームワークにブロードキャスト、toを指定すると同一イベントはターゲットモジュールにのみ見える emit_sync/submit_event(互換 API)もto=パラメータをサポート
Note
指定イベントは軽量な通知であり、ターゲットの検証やラグジュアリーな起動は行わない;ターゲットの存在性検証、契約審査、または返り値が必要な場合は、RPC: module.call を使用してください。
ラグジュアリーなモジュールと呼び出し
module.call() はラグジュアリーなモジュールに対して透明な起動を行う:
- イベント駆動ラグジュアリーなモジュール(
activate_onで宣言)→ 活性化ロック_activate()を通る、活性化後はトリガースタブが自動的に登録解除 - 通常のラグジュアリーなモジュール → 同期初期化または通常のロード経路(冪等)
- 起動に失敗 →
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)、同じ id のイベントは1回しか配信されない。
[ErisPulse.framework]
event_dedupe = true # 既定で有効;テスト環境で固定 id の合成イベントを生成する場合は無効化可能
アダプターが登録(新接続のライフサイクルの起点)されたときに、自動的に重複除去キャッシュがリセットされる。
関連ドキュメント
- インタラクションセッションシステム - wait_reply / タイマー / マルチウェイティング / セッション排他
- 作用域(scope) - 出力側の審査の完全な設定
- 所有権(owner)システム - 跨モジュール呼び出しで owner コンテキストがどのように貫かれるか
- ラグジュアリーなロードシステム - ラグジュアリーなロードとイベント駆動のアクティベーション(activate_on)
- ライフサイクル管理 - ブロードキャスト層のイベントバスのメカニズム