ErisPulse ErisPulse
インタラクティブ版で開く →
このページのセクション
静的ミラーです。内容はインタラクティブ版が正となります インタラクティブ版で開く →

イベントコンバーター実装ガイド

Tip

この文書を読むべきタイミング:アダプター開発パス内では必読(イベントコンバーター)。必要なければスキップしても、他の機能の利用には影響しません。

アダプターがプラットフォームのネイティブイベントを受信すると、イベントコンバーター (Converter) がそれを ErisPulse の統一された OneBot12 標準形式へ変換します。プラットフォームイベントがどのようにフレームワークへ取り込まれるかは、この1つのクラスが決定します。

Converter の責務

プラットフォームネイティブイベント ──→ Converter.convert() ──→ OneBot12 標準イベント

Converter は順方向変換(受信方向)のみを担当します。つまり、プラットフォームのネイティブイベントデータを OneBot12 標準形式に変換します。逆方向変換(送信方向)は Send.Raw_ob12() メソッドが処理します。

基本原則

  1. 無損失変換:元のデータは必ず {platform}_raw フィールドに完全な形で保持すること
  2. 標準互換:変換後のイベントは OneBot12 標準形式に準拠すること
  3. プラットフォーム拡張:プラットフォーム固有のデータは {platform}_ プレフィックス付きフィールドに保存すること

BaseConverter 基底クラス(推奨)

2.7.0 以降、フレームワークは BaseConverter 基底クラス(ErisPulse.Core.Bases)を提供しており、OneBot12 イベントの共通フィールド構築とよく使うメッセージセグメントのヘルパーをカプセル化しているため、コンバーターは型マッピングに集中するだけでよくなります:

from ErisPulse.Core.Bases import BaseConverter


class MyConverter(BaseConverter):
    def __init__(self):
        super().__init__(platform="myplatform")

    def convert(self, raw_event: dict) -> dict | None:
        if not isinstance(raw_event, dict):
            return None
        event_type = raw_event.get("type", "")
        base = self.build_base_event(raw_event, event_type)  # id/time/platform/self/raw
        if event_type == "message":
            base["type"] = "message"
            base["detail_type"] = "group" if raw_event.get("group_id") else "private"
            base["user_id"] = str(raw_event.get("sender_id", ""))
            base["message"] = [self.text(raw_event.get("content", ""))]
            base["alt_message"] = raw_event.get("content", "")
            return base
        return None

build_base_event() が自動的に埋める共通フィールド:

フィールド 供給元
id raw_event["event_id"]、未指定時は UUID を自動生成
time raw_event["timestamp"]、未指定時は現在時刻
platform コンストラクタで渡された platform
self {"platform": ..., "user_id": raw_event["bot_id"]}
{platform}_raw 元のイベント(「無損失変換」の原則を満たす)
{platform}_raw_type 元のイベントタイプ

よく使うメッセージセグメントのヘルパーメソッド(いずれも静的メソッドで、そのまま再利用できます):

converter.text("hi")          # {"type": "text", "data": {"text": "hi"}}
converter.at("123456")        # {"type": "at", "data": {"user_id": "123456"}}
converter.image("file.png")   # {"type": "image", "data": {"file": "file.png"}}

手動で実装する場合、build_base_event の共通フィールド構築は毎回書く必要があるボイラープレートコードです。BaseConverter を使えばこの部分を省略でき、「無損失変換」(元のイベントは常に {platform}_raw に入る)も自然に満たされます。

convert() メソッド

メソッドシグネチャ

def convert(self, raw_event: dict) -> dict:
    """
    プラットフォームのネイティブイベントを OneBot12 標準形式に変換する

    :param raw_event: プラットフォームのネイティブイベントデータ
    :return: OneBot12 標準形式のイベント辞書
    """
    pass

戻り値の構造

変換後のイベント辞書には、以下の標準フィールドを含める必要があります:

{
    "id": "イベントの一意なID",
    "time": 1234567890,           # Unix タイムスタンプ(秒)
    "type": "message",             # イベントタイプ
    "detail_type": "private",      # 詳細タイプ
    "platform": "myplatform",      # プラットフォーム名
    "self": {
        "platform": "myplatform",
        "user_id": "bot_user_id"
    },

    # メッセージイベントのフィールド
    "user_id": "sender_id",
    "message": [...],              # OneBot12 メッセージセグメントのリスト
    "alt_message": "プレーンテキストの内容",

    # 元のデータを必ず保持する
    "myplatform_raw": { ... },     # プラットフォームネイティブイベントの完全なデータ
    "myplatform_raw_type": "ネイティブイベントの型名",
}

必須フィールドのマッピング

共通フィールド(すべてのイベントタイプ)

OB12 フィールド 型 説明
id str イベントの一意な識別子
time int Unix タイムスタンプ(秒)
type str イベントタイプ:message / notice / request / meta
detail_type str 詳細タイプ:private / group / friend など
platform str プラットフォーム名。アダプターの登録名と一致させること
self dict ボット情報:{"platform": "...", "user_id": "..."}

メッセージイベントの追加フィールド

OB12 フィールド 型 説明
user_id str 送信者 ID
message list[dict] OneBot12 メッセージセグメントのリスト
alt_message str プレーンテキストの代替内容

通知イベントの追加フィールド

OB12 フィールド 型 説明
user_id str 関連するユーザー ID
operator_id str 操作者の ID(グループメンバーの増減など)

メッセージセグメントの変換

OneBot12 標準では、以下のメッセージセグメントタイプが定義されています:

# テキスト
{"type": "text", "data": {"text": "Hello"}}

# 画像
{"type": "image", "data": {"file": "https://example.com/img.jpg"}}

# 音声
{"type": "audio", "data": {"file": "https://example.com/audio.mp3"}}

# 動画
{"type": "video", "data": {"file": "https://example.com/video.mp4"}}

# ファイル
{"type": "file", "data": {"file": "https://example.com/doc.pdf"}}

# @メンション
{"type": "mention", "data": {"user_id": "123"}}

# @全員
{"type": "mention_all", "data": {}}

# 返信
{"type": "reply", "data": {"message_id": "msg_123"}}

プラットフォームに対応していないメッセージセグメントタイプがある場合は、そのセグメントを省略するか、最も近い標準タイプに変換できます。

alt_message のレンダリング規約

alt_message はメッセージイベントのプレーンテキストの代替内容で、ログのアーカイブ、extract_text によるテキストマッチング、コマンドディスパッチのフォールバックに使用されます。各アダプターは alt_message を生成する際、以下の規約に従う必要があります(特に mention セグメントに注意):

  • mention セグメントは優先的に @ニックネーム とレンダリングします。プラットフォームがニックネームを提供しない場合は @{user_id} にフォールバックし、user_id が all(@全員)の場合は @メンバー全員 とレンダリングします
  • ニックネームと user_id の両方が欠けている場合はそのセグメントを省略し、空の "@" を出力してはいけません。"@ ヘルプ" のようになると、テキストマッチングやコマンド解析の基準が汚染されます
  • data.get("user_name", fallback) の罠に注意:メッセージセグメントの構築時に user_name のデフォルトとして空文字列が保存されていると、キーが存在するためにフォールバックが永久に機能しません。data.get("user_name") or data.get("user_id") という書き方を使うべきです
  • その他のメッセージセグメントのレンダリングスタイル([画像]、[音声] など)や、セグメント間の連結方法("" または " ")は、アダプター自身の既存の方針を維持し、強制的な統一は行いません
# mention セグメントのレンダリング例
data = seg.get("data") or {}
user_id = str(data.get("user_id") or "").strip()
user_name = str(data.get("user_name") or "").strip()
if user_id == "all":
    parts.append("@メンバー全員")
elif user_name:
    parts.append(f"@{user_name}")
elif user_id:
    parts.append(f"@{user_id}")

プラットフォーム拡張フィールド

プラットフォーム固有のデータは、標準フィールドとの衝突を避けるため {platform}_ プレフィックスを付けて保存する必要があります:

{
    # 標準フィールド
    "type": "message",
    "detail_type": "group",
    # ...

    # プラットフォーム拡張フィールド
    "myplatform_raw": { ... },          # 元のイベントデータ(必須)
    "myplatform_raw_type": "chat",      # 元のイベントタイプ(必須)

    # その他のプラットフォーム固有フィールド
    "myplatform_group_name": "グループ名",
    "myplatform_sender_role": "admin",
}

重要:{platform}_raw フィールドは必須です。ErisPulse のイベントシステムやモジュールは、プラットフォームの元のデータにアクセスするためにこのフィールドに依存している可能性があります。

完全な実装例

以下は完全な Converter の実装例です:

class MyConverter:
    def __init__(self, platform: str):
        self.platform = platform

    def convert(self, raw_event: dict) -> dict:
        event_type = raw_event.get("type", "")

        base_event = {
            "id": raw_event.get("id", ""),
            "time": raw_event.get("timestamp", 0),
            "platform": self.platform,
            "self": {
                "platform": self.platform,
                "user_id": raw_event.get("self_id", ""),
            },
            "myplatform_raw": raw_event,
            "myplatform_raw_type": event_type,
        }

        if event_type == "chat":
            return self._convert_message(raw_event, base_event)
        elif event_type == "notification":
            return self._convert_notice(raw_event, base_event)
        elif event_type == "request":
            return self._convert_request(raw_event, base_event)

        return base_event

    def _convert_message(self, raw: dict, base: dict) -> dict:
        base["type"] = "message"
        base["detail_type"] = "group" if raw.get("group_id") else "private"
        base["user_id"] = raw.get("sender_id", "")
        base["message"] = self._convert_message_segments(raw.get("content", ""))
        base["alt_message"] = raw.get("content", "")

        if raw.get("group_id"):
            base["group_id"] = raw["group_id"]

        return base

    def _convert_message_segments(self, content: str) -> list:
        segments = []
        if content:
            segments.append({"type": "text", "data": {"text": content}})
        return segments

    def _convert_notice(self, raw: dict, base: dict) -> dict:
        base["type"] = "notice"
        notification_type = raw.get("notification_type", "")

        if notification_type == "member_join":
            base["detail_type"] = "group_member_increase"
            base["user_id"] = raw.get("user_id", "")
            base["group_id"] = raw.get("group_id", "")
            base["operator_id"] = raw.get("operator_id", "")
        elif notification_type == "friend_add":
            base["detail_type"] = "friend_increase"
            base["user_id"] = raw.get("user_id", "")

        return base

    def _convert_request(self, raw: dict, base: dict) -> dict:
        base["type"] = "request"
        request_type = raw.get("request_type", "")

        if request_type == "friend":
            base["detail_type"] = "friend"
            base["user_id"] = raw.get("user_id", "")
            base["comment"] = raw.get("message", "")
        elif request_type == "group_invite":
            base["detail_type"] = "group"
            base["group_id"] = raw.get("group_id", "")
            base["user_id"] = raw.get("inviter_id", "")

        return base

リッチメディアメッセージの変換例

実際のプラットフォームのメッセージには、通常、画像、@メンション、返信などのリッチメディアコンテンツが含まれます。以下は、_convert_message_segments で複数のメッセージタイプを処理する例です:

def _convert_message_segments(self, raw_content: list) -> list:
    """プラットフォームのネイティブメッセージセグメントのリストを OneBot12 標準メッセージセグメントに変換する"""
    segments = []

    for item in raw_content:
        item_type = item.get("type", "")

        if item_type == "text":
            segments.append({
                "type": "text",
                "data": {"text": item.get("content", "")}
            })

        elif item_type == "image":
            file_url = item.get("url") or item.get("file_id", "")
            segments.append({
                "type": "image",
                "data": {"file": file_url}
            })

        elif item_type == "at":
            segments.append({
                "type": "mention",
                "data": {"user_id": item.get("target_id", "")}
            })

        elif item_type == "reply":
            segments.append({
                "type": "reply",
                "data": {"message_id": item.get("reply_to_id", "")}
            })

        elif item_type == "at_all":
            segments.append({"type": "mention_all", "data": {}})

        else:
            segments.append({
                "type": "text",
                "data": {"text": f"[未対応のメッセージタイプ: {item_type}]"}
            })

    return segments

よくある落とし穴

1. {platform}_raw フィールドの欠落

これは最もよくある間違いです。元のデータのフィールドが欠落すると、モジュールがプラットフォーム固有の情報にアクセスできなくなります。

base_event["myplatform_raw"] = raw_event        # 必須!
base_event["myplatform_raw_type"] = event_type   # 必須!

2. タイムスタンプ形式の誤り

OneBot12 標準では、time フィールドは Unix 秒単位のタイムスタンプ(整数)でなければなりません。プラットフォームがミリ秒のタイムスタンプや ISO 形式の文字列を返す場合は、変換が必要です:

import time

# ミリ秒 → 秒
"time": raw_event.get("timestamp", 0) // 1000

# ISO 文字列 → 秒
"time": int(time.mktime(time.strptime(raw_event["created_at"], "%Y-%m-%dT%H:%M:%S")))

3. self フィールドの欠落

self フィールドにはボット自身の情報が含まれ、user_id はボットのアカウント ID です。マルチボットのシナリオでは、このフィールドが極めて重要です:

"self": {
    "platform": self.platform,
    "user_id": raw_event.get("bot_id", ""),   # ボット自身の ID
}

4. detail_type に非標準の値を使用している

detail_type は、private、group、friend_increase、group_member_increase など、OneBot12 標準で定義された値を使用しなければなりません。プラットフォーム固有の命名は使用しないでください。

5. ラウンドトリップの一貫性

Converter が生成するメッセージセグメントタイプが、Send 側がサポートするメソッドと対応していることを確認してください。たとえば、Converter がプラットフォームの画像メッセージを {"type": "image", ...} に変換するなら、Send 側の Image() メソッドは画像の送信を処理できる必要があります。

ベストプラクティス

  1. 常に元のデータを保持する:{platform}_raw フィールドは省略できません
  2. 標準メッセージセグメントを使用する:プラットフォームのメッセージはできる限り OneBot12 標準のメッセージセグメントに変換します
  3. detail_type を適切に設定する:標準タイプ(private/group/channel など)を使用し、独自定義はしないでください
  4. エッジケースを処理する:元のイベントには一部のフィールドが欠けている可能性があるため、.get() を使い適切なデフォルト値を提供します
  5. パフォーマンスへの配慮:convert() はすべてのイベントで呼び出されるため、その中で時間のかかる処理を実行することは避けてください

関連ドキュメント

アダプター開発パスを続ける

正式な仕様に従う