ErisPulse セッションタイプ標準
このドキュメントでは、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 のラッパークラスが存在するため、
event.reply()メソッドを使用するだけで、タイプ変換を気にする必要はありません。
2. 標準的な会話タイプ
2.1 OneBot12 標準タイプ
private
- 受信タイプ:
private - 送信タイプ:
user - 説明: 1対1のプライベートチャットメッセージ
- 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 を直接使用するのがより良い選択です
6.2 イベントの返信
from ErisPulse.Core.Event import Event
# Event.reply() は自動的に型変換を処理する
await event.reply("返信内容")
# 内部で正しい送信タイプが自動的に使用される
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 アダプタ開発者
- 標準マッピングの使用：可能な限り、新しい型を作成するのではなく、標準型にマッピングする。
- 正しい変換：送信型と受信型のマッピング関係が正しくなるようにする。
- 元のデータの保持：
{platform}_rawに元のイベント型を保持する。 - ドキュメントの説明：アダプタのドキュメントに型のマッピング関係を説明する。
7.2 モジュール開発者
- ツールメソッドの使用：
get_send_type_and_target_id()などのツールメソッドを使用する。 - ハードコーディングの回避：
if group_id else "private"のようなコードを書かない。 - すべての型を考慮する：コードは、private/group だけでなく、すべての標準型をサポートするようにする。
- 柔軟な設計：イベントラッパーのメソッドを使用する、または直接フィールドにアクセスしないようにする。
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 を使用して元のデータを保持し、アダプターで独自に処理します。