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

ErisPulse セッションタイプ標準

Tip

このドキュメントを読むべきケース:アダプターでプラットフォームのネイティブセッションを標準タイプ(private/group/channel/guild/thread)にマッピングする場合や、モジュールで Send.To() にどのターゲットタイプを渡せばよいかわからない場合、event.reply() の自動変換を把握したい場合に本ドキュメントを参照してください。不要な場合はスキップしてください。

このドキュメントでは、受信イベントタイプと送信ターゲットタイプを含む、ErisPulse がサポートするセッションタイプの標準を定義します。

1. 基本概念

1.1 受信タイプ && 送信タイプ

ErisPulse は2種類のセッションタイプを区別します:

  • 受信タイプ(Receive Type):受信するイベントの detail_type フィールド
  • 送信タイプ(Send Type):メッセージ送信時に Send.To() メソッドへ渡すターゲットタイプ

1.2 タイプマッピング関係

受信タイプ (detail_type)     送信タイプ (Send.To)
─────────────────        ────────────────
private                 →        user
group                   →        group
channel                 →        channel
guild                   →        guild
thread                  →        thread
user                    →        user

重要なポイント:

  • private は受信時のタイプであり、送信時の標準タイプは user です
  • group、channel、guild、thread は受信時と送信時でタイプが同じです
  • 推奨パス:event.reply() を直接使用する——タイプ変換とターゲット推論が自動的に行われ、手動処理は不要です(private → user の自動変換はここで行われます)
  • 手動送信時:送信タイプを直接渡してください(例:Send.To("user", ...))。手動で Send.To("private", ...) のように受信タイプを渡しても自動変換されますが、推奨されません(§6.1 参照)

2. 標準セッションタイプ

2.1 OneBot12 標準タイプ

private

  • 受信タイプ:private
  • 送信タイプ:user
  • 説明:一対一のプライベートチャットメッセージ
  • ID フィールド:user_id
  • 対応プラットフォーム:プライベートチャットをサポートするすべてのプラットフォーム

group

  • 受信タイプ:group
  • 送信タイプ:group
  • 説明:グループチャットメッセージ。各種形式のグループ(Telegram の supergroup など)を含みます
  • ID フィールド:group_id
  • 対応プラットフォーム:グループチャットをサポートするすべてのプラットフォーム

user

  • 受信タイプ:user
  • 送信タイプ:user
  • 説明:ユーザータイプ。一部のプラットフォーム(Telegram など)では、プライベートチャットを private ではなく user として表現します
  • ID フィールド:user_id
  • 対応プラットフォーム:Telegram などのプラットフォーム

2.2 ErisPulse 拡張タイプ

channel

  • 受信タイプ:channel
  • 送信タイプ:channel
  • 説明:チャンネルメッセージ。複数ユーザーへのブロードキャスト形式のメッセージをサポートします
  • ID フィールド:channel_id
  • 対応プラットフォーム:Discord、Telegram、Line など

guild

  • 受信タイプ:guild
  • 送信タイプ:guild
  • 説明:サーバー/コミュニティメッセージ。通常、Discord の Guild レベルのイベントに使用されます
  • ID フィールド:guild_id
  • 対応プラットフォーム:Discord など

thread

  • 受信タイプ:thread
  • 送信タイプ:thread
  • 説明:トピック/サブチャンネルメッセージ。コミュニティ内のサブディスカッションに使用されます
  • ID フィールド:thread_id
  • 対応プラットフォーム:Discord Threads、Telegram Topics など

3. プラットフォームタイプマッピング

3.1 マッピングの原則

アダプターは、プラットフォームのネイティブタイプを ErisPulse 標準タイプにマッピングする役割を担います:

プラットフォームネイティブタイプ → ErisPulse 標準タイプ → 送信タイプ

3.2 一般的なプラットフォームのマッピング例

Telegram

Telegram タイプ         ErisPulse 受信タイプ   送信タイプ
─────────────────      ────────────────       ───────────
private                private                 user
group                  group                   group
supergroup             group                   group  # group にマッピング
channel                channel                 channel

Discord

Discord タイプ         ErisPulse 受信タイプ   送信タイプ
─────────────────      ────────────────       ───────────
Direct Message         private                user
Text Channel           channel                channel
Guild                  guild                  guild
Thread                 thread                 thread

OneBot11

OneBot11 タイプ       ErisPulse 受信タイプ   送信タイプ
─────────────────      ────────────────       ───────────
private                private                user
group                  group                  group
discuss                group                  group  # group にマッピング

4. カスタムタイプの拡張

4.1 カスタムタイプの登録

アダプターはカスタムセッションタイプを登録できます:

from ErisPulse.Core.Event import register_custom_type

# カスタムタイプの登録
register_custom_type(
    receive_type="my_custom_type",
    send_type="custom",
    id_field="custom_id",
    platform="MyPlatform"
)

4.2 カスタムタイプの使用

登録後、システムは自動的にこのタイプの変換と推論を処理します:

# 自動推論
receive_type = infer_receive_type(event, platform="MyPlatform")
# 戻り値: "my_custom_type"

# 送信タイプへの変換
send_type = convert_to_send_type(receive_type, platform="MyPlatform")
# 戻り値: "custom"

# 対応する ID の取得
target_id = get_target_id(event, platform="MyPlatform")
# 戻り値: event["custom_id"]

4.3 カスタムタイプの登録解除

from ErisPulse.Core.Event import unregister_custom_type

unregister_custom_type("my_custom_type", platform="MyPlatform")

5. 自動タイプ推論

イベントに明示的な detail_type フィールドがない場合、システムは存在する ID フィールドに基づいてタイプを自動推論します:

Note

2.7.0+ での動作変更:detail_type は、既知のセッションタイプ(標準またはカスタム)である場合にのみ直接採用されます。notice/request イベントの detail_type(group_member_increase、friend_increase など)はセマンティックサブタイプでありセッションタイプではないため、代わりに ID フィールドに基づいて正しいセッションタイプが推論されます。

5.1 推論の優先順位

優先順位(高い順):
1. group_id     → group
2. channel_id   → channel
3. guild_id     → guild
4. thread_id    → thread
5. user_id      → private

5.2 使用例

# イベントに group_id のみがある場合
event = {"group_id": "123", "user_id": "456"}
receive_type = infer_receive_type(event)
# 戻り値: "group"(group_id を優先使用)

# イベントに user_id のみがある場合
event = {"user_id": "123"}
receive_type = infer_receive_type(event)
# 戻り値: "private"

# notice イベントの detail_type はセマンティックサブタイプであり、2.7.0+ では ID フィールドから推論されます
event = {"type": "notice", "detail_type": "group_member_increase", "group_id": "123"}
receive_type = infer_receive_type(event)
# 戻り値: "group"("group_member_increase" ではなく)

6. API 使用例

6.1 メッセージ送信

from ErisPulse import adapter

# ユーザーに送信
await adapter.myplatform.Send.To("user", "123").Text("Hello")

# グループに送信
await adapter.myplatform.Send.To("group", "456").Text("Hello")

# 自動変換 private → user:受信タイプを手動で渡すのは非推奨の書き方です(互換性の問題が生じる可能性があります)
await adapter.myplatform.Send.To("private", "789").Text("Hello")
# 内部で自動変換されます: Send.To("user", "789")
# 推奨される方法:手動送信時は送信タイプ user を直接使用するか、event.reply() で自動変換を利用してください(6.2 参照)

6.2 イベントへの返信

from ErisPulse.Core.Event import Event

# Event.reply() は自動的にタイプ変換を処理します(推奨パス)
await event.reply("返信内容")
# 内部で正しい送信タイプが自動的に使用されます(private → user などの変換はここで自動的に行われます)

6.3 コマンド処理

from ErisPulse.Core.Event import command

@command(name="test")
async def handle_test(event):
    # システムが自動的にセッションタイプを処理します
    # group_id か user_id かを手動で判断する必要はありません
    await event.reply("コマンドが正常に実行されました")

7. コア API リファレンス

7.1 タイプ変換

from ErisPulse.Core.Event import convert_to_send_type, convert_to_receive_type

# 受信タイプ → 送信タイプ
convert_to_send_type("private")  # → "user"
convert_to_send_type("group")    # → "group"

# 送信タイプ → 受信タイプ
convert_to_receive_type("user")   # → "private"
convert_to_receive_type("group")  # → "group"

7.2 ID フィールドの照会

from ErisPulse.Core.Event import get_id_field, get_receive_type

get_id_field("group")    # → "group_id"
get_id_field("private")  # → "user_id"

get_receive_type("group_id")  # → "group"
get_receive_type("user_id")   # → "private"

7.3 ワンステップで送信情報を取得

from ErisPulse.Core.Event import get_send_type_and_target_id

event = {"detail_type": "private", "user_id": "123"}
send_type, target_id = get_send_type_and_target_id(event)
# send_type = "user", target_id = "123"

# Send.To() に直接使用
await adapter.Send.To(send_type, target_id).Text("Hello")

7.4 ターゲット ID の取得

from ErisPulse.Core.Event import get_target_id

event = {"detail_type": "group", "group_id": "456"}
get_target_id(event)  # → "456"

8. ユーティリティメソッド

from ErisPulse.Core.Event import (
    is_standard_type,
    is_valid_send_type,
    get_standard_types,
    get_send_types,
    clear_custom_types,
)

is_standard_type("private")     # True
is_standard_type("custom_type") # False

is_valid_send_type("user")      # True
is_valid_send_type("invalid")   # False

get_standard_types()  # {"private", "group", "channel", "guild", "thread", "user"}
get_send_types()      # {"user", "group", "channel", "guild", "thread"}

clear_custom_types()                # すべてクリア
clear_custom_types(platform="discord")  # 指定したプラットフォームのみクリア

9. ベストプラクティス

7.1 アダプター開発者

  1. 標準マッピングを使用:新しいタイプを作成するのではなく、可能な限り標準タイプにマッピングしてください
  2. 正しい変換:受信タイプと送信タイプのマッピング関係が正しいことを確認してください
  3. 元データの保持:{platform}_raw に元のイベントタイプを保持してください
  4. ドキュメントでの説明:アダプターのドキュメントでタイプマッピング関係を説明してください

7.2 モジュール開発者

  1. ユーティリティメソッドを使用:get_send_type_and_target_id() などのユーティリティメソッドを使用してください
  2. ハードコーディングを避ける:if group_id else "private" のようなコードを書かないでください
  3. すべてのタイプを考慮:コードは private/group だけでなく、すべての標準タイプをサポートする必要があります
  4. 柔軟な設計:フィールドに直接アクセスするのではなく、イベントラッパーのメソッドを使用してください

7.3 タイプ推論

  • detail_type を優先使用:明示的なフィールドがある場合は推論を行いません
  • 推論の適切な使用:明示的なタイプがない場合にのみ使用してください
  • 優先順位に注意:推論の優先順位を理解し、予期しない結果を避けてください

10. よくある質問

Q1: 送信時に private を user に変換するのはなぜですか?

A: これは OneBot12 標準の要件です。private は受信時の概念であり、送信時には user を使用する方がセマンティクスに適しています。

Q2: 新しいセッションタイプをサポートするには?

A: register_custom_type() でカスタムタイプを登録するか、標準タイプの channel、guild などを直接使用してください。

Q3: イベントに detail_type がない場合は?

A: システムは存在する ID フィールドに基づいて自動的に推論します。優先順位は group > channel > guild > thread > user です。

Q4: アダプターは Telegram の supergroup をどのようにマッピングしますか?

A: アダプターの変換ロジックで、supergroup を標準の group タイプにマッピングしてください。

Q5: メールなどの特殊なプラットフォームはどのように処理しますか?

A: 汎用性のないタイプやプラットフォーム固有のタイプについては、{platform}_raw と {platform}_raw_type を使用して元データを保持し、アダプター側で処理してください。

11. 関連ドキュメント

アダプター向け(マッピングと変換):

モジュール向け(タイプ変換を手動で処理したくない場合):

  • event.reply() を使用するだけで、タイプ変換とターゲット推論が自動的に行われます。詳細は Event ラッパークラス解説 を参照してください