基礎概念
Note
L1 コア必読——ドキュメントのトップページにある「L1 コア5編」のうち第2編(モジュール開発入門 → 基礎概念 → Event ラッパークラス → 設定ファイルの説明 → 例外キャッチ)。
ユーザーがメッセージを送信してからボットが返信するまでの間に、どのコンポーネントを経由するのでしょうか?アダプターとモジュールはそれぞれ何を担当しているのでしょうか?このドキュメントを読み終えれば、ハンドラーを書く際に直面する設計上の問いに、サンプルをただ写経するのではなく自分で答えられるようになります。
イベント駆動アーキテクチャ
ErisPulse はイベント駆動アーキテクチャを採用しており、すべてのやり取りはイベントを通じて伝達・処理されます。
イベントフロー
ユーザーがメッセージを送信
│
▼
プラットフォームが受信
│
▼
アダプターがプラットフォームのネイティブイベントを受信
│
▼
OneBot12 標準イベントに変換
│
▼
イベントシステムに投入
│
▼
登録済みのハンドラーに配信
│
▼
モジュールがイベントを処理
│
▼
アダプターを通じてレスポンスを送信
│
▼
プラットフォームがユーザーに表示
OneBot12 標準
ErisPulse は OneBot12 をコアイベント標準として使用しています。OneBot12 は汎用のチャットボットアプリケーションインターフェース標準であり、統一されたイベント形式を定義しています。
すべてのアダプターはプラットフォーム固有のイベントを OneBot12 形式に変換し、コードの一貫性を保証します。
コアコンポーネント
1. SDK オブジェクト
SDK はすべての機能の統一エントリーポイントであり、コアコンポーネントへのアクセスを提供します。
from ErisPulse import sdk
# コアモジュールへのアクセス
sdk.storage # ストレージシステム
sdk.config # 設定システム
sdk.logger # ログシステム
sdk.adapter # アダプターシステム
sdk.module # モジュールシステム
sdk.router # ルーティングシステム
sdk.client # HTTP クライアント
sdk.lifecycle # ライフサイクルシステム
Warning
ルートから統一インポート:from ErisPulse.Core import adapter / import ErisPulse.Core.adapter
このような書き方でバインドされるのはサブモジュールではなくマネージャーインスタンス(AdapterManager シングルトン)です。ErisPulse.Core
パッケージの re-export は同名のサブモジュールをシャドウイングします。テストの作成、patch、またはモジュールオブジェクト自体が必要な場合は、必ず
from ErisPulse import sdk のルートインポートを使用してください(sdk.adapter がマネージャーインスタンスです)。
2. Event オブジェクト
Event オブジェクトはイベントデータをカプセル化し、便利なアクセスメソッドを提供します。
@command("info")
async def info_handler(event):
# イベント情報の取得
event_id = event.get_id()
user_id = event.get_user_id()
platform = event.get_platform()
text = event.get_text()
# 返信の送信
await event.reply(f"ユーザー: {user_id}, プラットフォーム: {platform}")
3. アダプター
アダプターは ErisPulse と外部プラットフォームの間の橋渡し役です。
役割:
- プラットフォームのネイティブイベントを受信
- OneBot12 標準形式に変換
- 標準形式のイベントをプラットフォームに送信
アダプターの例:
- Yunhu アダプター:Yunhu プラットフォームと通信
- Telegram アダプター:Telegram Bot API と通信
- OneBot11 アダプター:OneBot11 互換のアプリケーションと通信
- Email アダプター:メールの送受信を処理
4. モジュール
モジュールは機能拡張の基本単位であり、以下のことができます:
- イベントハンドラーの登録
- ビジネスロジックの実装
- アダプターを呼び出してメッセージを送信
- コアモジュールが提供するサービスの利用
モジュール検出メカニズム
ErisPulse は Python の importlib.metadata.entry_points を通じてインストール済みのモジュールを検出します。モジュールは pyproject.toml でエントリーポイントを宣言します:
[project.entry-points."erispulse.module"]
MyModule = "my_package:Main"
SDK の初期化時に、すべての erispulse.module グループのエントリーポイントをスキャンし、モジュールクラスを ModuleManager に登録します。その後、依存関係に従ってトポロジカルソートし、順次初期化します。
最小構成のモジュール
from ErisPulse.Core.Bases import BaseModule
from ErisPulse import sdk
class Main(BaseModule):
def __init__(self):
self.sdk = sdk
self.logger = sdk.logger.get_child("MyModule")
async def on_load(self, event):
self.logger.info("モジュールがロードされました")
async def on_unload(self, event):
self.logger.info("モジュールがアンロードされました")
モジュールのライフサイクル
- 登録:SDK がモジュールクラスを検出し、マネージャーに登録
- ロード:モジュールインスタンスを作成し、
on_load(event)を呼び出す(event = {"module_name": "MyModule"}) - アンロード:
on_unload(event)を呼び出し、リソースをクリーンアップ
ロード戦略
get_load_strategy() を通じてモジュールのロード動作を宣言します:
from ErisPulse.loaders import ModuleLoadStrategy
class Main(BaseModule):
@staticmethod
def get_load_strategy():
return ModuleLoadStrategy(
lazy_load=True, # 遅延読み込みするかどうか(デフォルト True)
priority=0 # ロード優先度、数値が大きいほど先に初期化
)
lazy_load=True(デフォルト):モジュールは初めてsdk.MyModuleでアクセスされた時に初期化され、起動時間を短縮します- **
lazy_load=False**:SDK 起動時に即座に初期化されます。ライフサイクルイベントのリスニングや定期タスクの実行が必要なモジュールに適しています - **
priority**:同じ優先度のモジュールは登録順にロードされます。数値が大きいほど先に初期化されます
遅延読み込みのメカニズムの詳細については、遅延読み込みシステム を参照してください。
イベントタイプ
ErisPulse は 5 種類のイベントをサポートしています:
| イベントタイプ | デコレーター | 説明 |
|---|---|---|
| メッセージイベント | @message.on_message() |
ユーザーが送信したすべてのメッセージ(個人チャット、グループチャット) |
| コマンドイベント | @command("name") |
コマンドプレフィックスで始まるメッセージ(例:/hello) |
| 通知イベント | @notice.on_friend_add() など |
システム通知(友達追加、グループメンバーの変更など) |
| リクエストイベント | @request.on_friend_request() など |
ユーザーリクエスト(友達リクエスト、グループ招待) |
| メタイベント | @meta.on_connect() など |
システムレベルのイベント(接続、切断、ハートビート) |
各イベントタイプの詳細な使い方とコード例については、イベント処理入門 を参照してください。
コアモジュールの説明
Storage(ストレージ)
SQLite ベースのキーバリューストアシステムで、データの永続化に使用されます。
# 値の設定
sdk.storage.set("key", "value")
# 値の取得
value = sdk.storage.get("key", "default_value")
# 一括操作
sdk.storage.set_multi({
"key1": "value1",
"key2": "value2"
})
# トランザクション
with sdk.storage.transaction():
sdk.storage.set("key1", "value1")
sdk.storage.set("key2", "value2")
Config(設定)
TOML 形式の設定ファイル管理。
# 設定の取得
config = sdk.config.getConfig("MyModule", {})
# 設定の保存
sdk.config.setConfig("MyModule", {"key": "value"})
# ネストされた設定の読み取り
value = sdk.config.getConfig("MyModule.subkey", "default")
Logger(ログ)
モジュール化されたログシステム。
# ログの記録
sdk.logger.info("これは情報メッセージです")
sdk.logger.warning("これは警告メッセージです")
sdk.logger.error("これはエラーメッセージです")
# 子ロガーの取得
child_logger = sdk.logger.get_child("submodule")
child_logger.info("サブモジュールのログ")
属性アクセスのシンタックスシュガー
get_child() メソッドを使用するほかに、属性アクセスの方法で子ロガーを作成することもできます。これはより簡潔なシンタックスシュガーの書き方です:
# 属性アクセスで子ロガーを作成
sdk.logger.mymodule.info("モジュールメッセージ")
# ネストされたアクセスをサポート
sdk.logger.mymodule.database.info("データベースメッセージ")
Router(ルーティング)
HTTP と WebSocket のルーティング管理。FastAPI + Uvicorn ベース。デコレータールーティング、ミドルウェア、グループ化、レート制限、CORS をサポートします。
from ErisPulse.Core import HttpRequest
@sdk.router.get("MyModule", "/api")
async def handler(request: HttpRequest):
data = await request.json()
return {"status": "ok"}
ルーティング API の全容(WebSocket、ミドルウェア、レート制限、CORS など)については、ルーティングマネージャー を参照してください。
Client(ネットワーククライアント)
統一されたネットワーククライアントで、HTTP リクエスト、WebSocket 接続、コネクションプール管理、自動リトライ、タイムアウト制御、リクエスト統計、ライフサイクルイベント統合を集約しています。
from ErisPulse.Core import client
# HTTP リクエスト
resp = await client.get("https://api.example.com/users")
data = await resp.json()
# リトライとタイムアウト付き
resp = await client.get(url, timeout=30, max_retries=3)
# WebSocket 接続
ws = await client.ws_connect("wss://example.com/ws")
async for text in ws.iter_text():
await ws.send_text(f"Echo: {text}")
ネットワーククライアント API の全容については、ネットワーククライアント を参照してください。
SendDSL メッセージ送信
アダプターはメソッドチェーンによるメッセージ送信インターフェースを提供します。
基本的な送信
# アダプターインスタンスの取得
yunhu = sdk.adapter.get("yunhu")
# メッセージの送信
await yunhu.Send.To("user", "U1001").Text("Hello")
# 送信アカウントの指定
await yunhu.Send.Using("bot1").To("group", "G1001").Text("グループメッセージ")
チェーン修飾
# ユーザーをメンション
await yunhu.Send.To("group", "G1001").At("U2001").Text("@メッセージ")
# メッセージに返信
await yunhu.Send.To("group", "G1001").Reply("msg123").Text("返信")
# 全員にメンション
await yunhu.Send.To("group", "G1001").AtAll().Text("お知らせ")
Event の返信メソッド
Event オブジェクトは便利な返信メソッドを提供します:
@command("test")
async def test_handler(event):
# シンプルなテキスト返信
await event.reply("返信内容")
# 画像の送信
await event.reply("http://example.com/image.jpg", method="Image")
# 音声の送信
await event.reply("http://example.com/voice.mp3", method="Voice")
遅延読み込みシステム
ErisPulse はデフォルトでモジュールの遅延読み込みを有効にしており、モジュールは初めてアクセスされた時(例:sdk.MyModule)にのみ初期化されるため、起動速度が大幅に向上します。
from ErisPulse.loaders import ModuleLoadStrategy
class Main(BaseModule):
@staticmethod
def get_load_strategy():
return ModuleLoadStrategy(
lazy_load=True, # 遅延読み込みを有効化(デフォルト)
priority=0 # ロード優先度、数値が大きいほど先に初期化
)
遅延読み込みを無効化すべきシナリオ(lazy_load=False):
- ライフサイクルイベントをリスニングするモジュール(例:
core.init.complete) - 定期タスクやバックグラウンドサービスを起動するモジュール
- 他のモジュールがロードされる前に初期化を完了させる必要があるモジュール
遅延読み込みのメカニズムと注意事項の詳細については、遅延読み込みシステム を参照してください。
次のステップ
- L1 パスに沿って続ける:次は Event ラッパークラス で、イベントオブジェクトのすべての読み書きメソッドを習得しましょう
- 書きながら学びたい:イベント処理入門 ではイベントタイプ別にコピーしてすぐ使えるハンドラーの書き方を紹介しています。よくあるタスクの例 では、永続化、定期タスク、権限制御などのよく使う機能をカバーしています