アダプタ標準変換規格
Tip
このドキュメントを読むべきタイミング:アダプタ内でプラットフォームのネイティブイベントを OneBot12 標準イベントに変換する際、必須フィールド、メッセージセグメント構造、拡張フィールド命名規則({platform}_ プレフィックス)、会話タイプの推論を確認する必要がある場合。不要であれば飛ばしてください。
1. 核心原則
- 厳密な互換性:すべての標準フィールドは OneBot12 規格に完全に準拠する。
- 明確な拡張:プラットフォーム固有の機能は
{platform}_プレフィックスを付ける(例:yunhu_form)。 - データの完全性:元のイベントデータは
{platform}_rawフィールドに、元のイベントタイプは{platform}_raw_typeフィールドに保持する。 - 時間の統一:すべてのタイムスタンプは 10 位の Unix タイムスタンプ(秒単位)に変換する。
- プラットフォームの統一:
platform項目の命名は、ErisPulse に登録した名前/別称と一致する。
2. 標準フィールド要件
2.1 必須フィールド
| フィールド | 型 | 説明 |
|---|---|---|
| id | string | イベントの一意な識別子 |
| time | integer | Unix タイムスタンプ(秒単位) |
| type | string | イベントのタイプ |
| detail_type | string | イベントの詳細タイプ(会話タイプ標準を参照) |
| sub_type | string | イベントのサブタイプ |
| platform | string | プラットフォーム名 |
| self | object | ロボット自身の情報 |
| self.platform | string | プラットフォーム名 |
| self.user_id | string | ロボットのユーザーID |
OneBot12 基準:
self.platform/self.user_idとメッセージイベントのmessage_idは OneBot12 基準で定義されたフィールドであり、フレームワークは基準定義を直接採用し、独自の拡張キー(self.account_idは動的アカウントが user_id を取得する前に代用する限定拡張キー、§6 を参照)を導入しない。
detail_type 規格:
- ErisPulse 標準会話タイプを使用する(会話タイプ標準を参照)
- 対応するタイプ:
private,group,user,channel,guild,thread - アダプタは、プラットフォームのネイティブタイプを標準タイプにマッピングする。
2.2 メッセージイベントフィールド
| フィールド | 型 | 説明 |
|---|---|---|
| message_id | string | メッセージID(OneBot12 基準必須フィールド、アダプタはイベントの最上層に生成する) |
| message | array | メッセージセグメントの配列 |
| alt_message | string | メッセージセグメントの代替テキスト |
| user_id | string | ユーザーID |
| user_nickname | string | ユーザーのニックネーム(オプション) |
2.3 通知イベントフィールド
| フィールド | 型 | 説明 |
|---|---|---|
| user_id | string | ユーザーID |
| user_nickname | string | ユーザーのニックネーム(オプション) |
| operator_id | string | 操作者のID(オプション) |
2.4 要求イベントフィールド
| フィールド | 型 | 説明 |
|---|---|---|
| user_id | string | ユーザーID |
| user_nickname | string | ユーザーのニックネーム(オプション) |
| comment | string | 要求のコメント(オプション) |
| request_id | string | 要求の識別子(強く推奨、同意/拒否操作に使用) |
request_id フィールドの説明:
request_idは要求イベントの唯一の操作識別子であり、RequestDSL を通じて同意/拒否操作に使用される。- アダプタは、プラットフォームのネイティブの要求識別子をこのフィールドにマッピングする。
- プラットフォームに要求IDがない場合、アダプタはユニークな識別子(例:タイムスタンプ+ユーザーIDのハッシュ)を生成する。
request_idが欠落している場合、event.approve()/event.reject()はValueErrorをスローする。
3. イベント形式の例
3.1 メッセージイベント (message)
{
"id": "1234567890",
"time": 1752241223,
"type": "message",
"detail_type": "group",
"platform": "yunhu",
"self": {
"platform": "yunhu",
"user_id": "bot_123"
},
"message": [
{
"type": "text",
"data": {
"text": "抽奖 超级大奖"
}
}
],
"alt_message": "抽奖 超级大奖",
"user_id": "user_456",
"user_nickname": "YingXinche",
"group_id": "group_789",
"yunhu_raw": {...},
"yunhu_raw_type": "message.receive.normal",
"yunhu_command": {
"name": "抽奖",
"args": "超级大奖"
}
}
3.2 通知イベント (notice)
{
"id": "1234567891",
"time": 1752241224,
"type": "notice",
"detail_type": "group_member_increase",
"platform": "yunhu",
"self": {
"platform": "yunhu",
"user_id": "bot_123"
},
"user_id": "user_456",
"user_nickname": "YingXinche",
"group_id": "group_789",
"operator_id": "",
"yunhu_raw": {...},
"yunhu_raw_type": "bot.followed"
}
3.3 要求イベント (request)
{
"id": "1234567892",
"time": 1752241225,
"type": "request",
"detail_type": "friend",
"platform": "onebot11",
"self": {
"platform": "onebot11",
"user_id": "bot_123"
},
"user_id": "user_456",
"user_nickname": "YingXinche",
"comment": "请加好友",
"request_id": "req_abc123",
"onebot11_raw": {...},
"onebot11_raw_type": "request"
}
4. メッセージセグメント標準
4.1 標準メッセージセグメント
標準メッセージセグメントにはプラットフォームのプレフィックスを付けない。
| タイプ | 説明 | data フィールド |
|---|---|---|
text |
純テキスト | text: str |
image |
画像 | file, url: str |
voice |
音声(即時録音の音声、audio とは区別) |
file, url: str |
audio |
音楽(再生可能な音楽ファイル、voice とは区別) |
file, url: str |
video |
動画 | file, url: str |
file |
ファイル | file, url: str, filename: str |
mention |
@ユーザー | user_id: str, user_name: str |
mention_all |
@全員 | data フィールドなし |
reply |
返信 | message_id: str, user_id: str(返信の元送信者、受信方向はアダプタが可能な限り記入) |
location |
位置 | latitude: float, longitude: float, title: str(オプション), content: str(オプション) |
face |
表情(ErisPulse 跨プラットフォーム拡張セグメント) | id: str |
keyboard |
ボタン/インラインキーボード(ErisPulse 跨プラットフォーム拡張セグメント) | rows: list[list[button]](4.1.1 参照) |
OneBot12 基準とのフィールドマッピング:メディアセグメント(
image/voice/audio/video/file)は OneBot12 基準ではfile_id: strである。本標準のfile(送信形態の超集合:URL / 本地パス / bytes)とurl(受信回路)は、アダプタによってプラットフォームのfile_idリソースに双方向にマッピングされる。face/keyboardは OneBot12 基準の外の拡張セグメントである。
メディアセグメント file フィールド形式(送信方向、image / audio / video / file に共通):
| 形態 | 例 | アダプタの要件 |
|---|---|---|
| HTTP(S) URL | https://example.com/a.png |
必須 |
| 本地ファイルパス | /tmp/a.png、C:\tmp\a.png |
必須 |
| 二進数データ | bytes |
必須 |
file:// URI / Base64 / Data URI |
file:///tmp/a.png、data:image/png;base64,... |
推奨 |
完全なメディア送信プロトコル(形態判定順序、ファイル名推論、能力降格の段階)は 送信方法規格 §2.1 を参照。
フィールドの方向意味:
file:送信方向のコンテンツソース(上記の形態);受信方向はアダプタが可能な限りプラットフォームで取得可能な形態を記入する (通常はダウンロード可能な URL、またはget_file類のアクションで利用可能なリソース識別子)url:受信方向のプラットフォームの回路(アダプタがプラットフォームのイベントを変換する際に可能な限り記入し、モジュールが直接取得できるようにする);送信方向は記入しなくてもよいfilename:fileセグメントのファイル名(送信方向はオプション、欠落時はアダプタが 送信方法規格 §2.1.3 の推論順序に従って生成する;受信方向はプラットフォームの元のファイル名を記入する)
{
"type": "text",
"data": {
"text": "Hello World"
}
}
4.1.1 keyboard ボタン/インラインキーボードセグメント(跨プラットフォーム共通)
ボタン/インラインキーボードは、Telegram / 云湖 / QQBot / Kook / Discord 等の複数のプラットフォームで対応しており、跨プラットフォーム共通概念であるため、標準メッセージセグメント(プラットフォームのプレフィックスなし)として扱う。アダプタは標準セグメントを
プラットフォームのネイティブ構造に変換する。プラットフォームのネイティブ拡張セグメント(例:telegram_inline_keyboard)はそのまま透かす。
{
"type": "keyboard",
"data": {
"rows": [
[
{"label": "选项A", "type": "callback", "data": "vote:A"},
{"label": "官网", "type": "link", "data": "https://example.com"}
]
]
}
}
フィールドの説明:
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
rows |
二次元配列 | はい | 各サブ配列が一行のボタン |
rows[][].label |
str | はい | ボタンの表示テキスト |
rows[][].type |
str | はい | callback(クリックでデータを戻す)/ link(URL にジャンプ) |
rows[][].data |
str | はい | コールバックデータ(type=callback)またはジャンプアドレス(type=link) |
rows[][].* |
Any | いいえ | プラットフォーム特有のオプションフィールド(例:web_app、menus)、アダプタは能力に応じてマッピングまたは無視する |
アダプタの変換参考(完全なマッピングとインタラクティブコールバックイベントの標準は 跨プラットフォームインタラクティブコンポーネント標準 を参照):
| プラットフォーム | 標準セグメント → プラットフォームのネイティブ |
|---|---|
| Telegram | inline_keyboard:[{text, callback_data | url}] |
| 云湖 | buttons:[{label, action_type: 2=コールバック | 1=ジャンプ, ...}] |
| QQBot | keyboard.content.rows:[{label, type: 2=コールバック | 0=ジャンプ, data}](markdown メッセージ形式が必要) |
| Kook | カードの action-group モジュール |
| Discord | components:action_row + buttons(custom_id/url) |
4.2 プラットフォーム拡張メッセージセグメント
プラットフォーム固有のメッセージセグメントにはプラットフォームのプレフィックスを付ける:
// 云湖 - フォーム
{"type": "yunhu_form", "data": {"form_id": "123456", "form_name": "报名表"}}
// Telegram - ステッカー
{"type": "telegram_sticker", "data": {"file_id": "CAACAgIAAxkBAA...", "emoji": "😂"}}
拡張メッセージセグメントの要件:
- data 内部のフィールドはプレフィックスを付けない:
{"type": "yunhu_form", "data": {"form_id": "..."}}ではなく{"type": "yunhu_form", "data": {"yunhu_form_id": "..."}} - 降格のソリューションを提供する:モジュールが拡張メッセージセグメントを認識できない場合、アダプタは
alt_messageにテキストの代替を提供する - ドキュメントの完全性:各拡張メッセージセグメントは、
type、dataの構造、使用場面をアダプタのドキュメントで説明する必要がある
5. 未知イベントの処理
認識できないイベントタイプに対しては、警告イベントを生成する:
{
"id": "1234567893",
"time": 1752241223,
"type": "unknown",
"platform": "yunhu",
"yunhu_raw": {...},
"yunhu_raw_type": "unknown",
"warning": "Unsupported event type: special_event",
"alt_message": "This event type is not supported by this system."
}
6. 拡張命名規則
6.1 フィールド命名
ルール:{platform}_{field_name}
プラットフォーム前缀 フィールド名 完全フィールド名
──────── ─────── ──────────
yunhu command yunhu_command
telegram sticker_file_id telegram_sticker_file_id
onebot11 anonymous onebot11_anonymous
email subject email_subject
要件:
platformはアダプタ登録時のプラットフォーム名と完全一致する(大文字小文字を区別)field_nameはsnake_case命名を使用__で始まる名前は禁止(Python が予約)- 標準フィールド(例:
type、time、messageなど)と同名の名前は禁止
6.2 メッセージセグメントタイプ命名
ルール:{platform}_{segment_type}
標準メッセージセグメントタイプ(text、image、audio、video、mention、reply など)はプラットフォームのプレフィックスを付けない。プラットフォーム固有のメッセージセグメントタイプのみプレフィックスを付ける。
6.3 原始データフィールド命名
以下のフィールド名は予約フィールドであり、すべてのアダプタは以下の要件を遵守する:
| 予約フィールド | 型 | 説明 |
|---|---|---|
{platform}_raw |
any |
プラットフォームの元のイベントデータの完全なコピー |
{platform}_raw_type |
string |
プラットフォームの元のイベントタイプの識別子 |
要件:
{platform}_rawは元のデータの深いコピー(参照ではなく)である必要がある{platform}_raw_typeは文字列である必要がある(プラットフォームが数値型を使用している場合も文字列に変換する)- これらのフィールドはすべてのイベントで存在する必要がある(取得できない場合は
nullと空文字列""とする)
6.4 プラットフォーム特有のフィールドの例
{
"yunhu_command": {
"name": "抽奖",
"args": "超级大奖"
},
"yunhu_form": {
"form_id": "123456"
},
"telegram_sticker": {
"file_id": "CAACAgIAAxkBAA..."
}
}
6.5 嵌套拡張フィールド
拡張フィールドは単純な値でも、ネストされたオブジェクトでもよい:
{
"telegram_chat": {
"id": 123456,
"type": "supergroup",
"title": "My Group"
},
"telegram_forward_from": {
"user_id": "789",
"user_name": "ForwardUser"
}
}
ネストされたフィールドの要件:
- トップレベルのキーにはプラットフォームのプレフィックスを付ける
- ネストされた内部のフィールドにはプラットフォームのプレフィックスを付けない
- ネストの深さは 3 層を超えないように推奨
6.6 self フィールドの拡張
self オブジェクトの標準の必須フィールド(platform、user_id)は §2.1 を参照。以下は ErisPulse が拡張したオプションフィールドである:
| フィールド | 型 | 説明 |
|---|---|---|
self.user_name |
string |
ロボットのニックネーム |
self.avatar |
string |
ロボットのアバターのURL |
self.account_id |
string |
限定拡張キー(アカウント名の代用):動的に注入されたアカウントが user_id を取得する前に、アカウント名/アカウント識別子で代用して記入し、イベントの所属を保証する。self.user_id が利用可能になったら優先的に記入する。フレームワークは account_id or user_id の口径で両方を互換的に扱う——アカウント名の代用時は reply() がアカウント名マッチングで正しいアカウントにルーティングされる |
実行時境界:イベントは常に
self.user_idを保持する必要がある(バインドが確立していない期間も含む)。接続層がバインドテーブルを戻し、connect meta が到着する前に受信したイベントは、ロボットのuser_idが取得されていない場合はアカウント名でself.account_idを代用して注入する(フレームワークはaccount_id or user_idの口径で解析し、アカウント名はアカウント名マッチングルーターで正しいアカウントに戻る)。取得済みの場合は優先的にself.user_idを記入する——フレームワークはイベントの任意の段階で「このイベントはどのアカウントから来たのか」を判断できる必要がある。欠落した場合の結果は明確である:event.reply()にアカウントを注入せず、アカウントが指定されていない送信は最初の有効なアカウントに降格し、複数アカウントのアダプタでは「デフォルトアカウントから発信された」と表現される。
Bot 状態の追跡:アダプタは
type: "meta"イベントを送信してフレームワークに Bot の接続状態を通知する。サポートされるdetail_type:connect(オンライン)、heartbeat(ハートビート)、disconnect(オフライン)。システムはこの中からselfフィールドの Bot 元情報を自動抽出して状態を追跡する。また、通常のイベントのselfフィールドも自動的に Bot を発見する。アダプタシステム API - Bot 状態管理を参照。
7. 会話タイプの拡張
ErisPulse は OneBot12 標準の private、group の上に以下の会話タイプを拡張している:
| タイプ | OneBot12 標準 | ErisPulse 拡張 | 説明 |
|---|---|---|---|
private |
✅ | — | 1対1のプライベートチャット |
group |
✅ | — | グループチャット |
user |
— | ✅ | ユーザータイプ(Telegram など) |
channel |
— | ✅ | チャンネル(放送型) |
guild |
— | ✅ | サーバー/コミュニティ |
thread |
— | ✅ | トピック/サブチャンネル |
アダプタのカスタムタイプ拡張:
from ErisPulse.Core.Event.session_type import register_custom_type
# アダプタ起動時に登録
register_custom_type(
receive_type="email", # 受信イベントの detail_type
send_type="email", # 送信時の対象タイプ
id_field="email_id", # 対応する ID フィールド名
platform="email" # プラットフォーム識別子
)
カスタムタイプの要件:
- アダプタの
start()時に登録し、shutdown()時に登録解除する receive_typeは標準タイプと重複しないid_fieldは{対象}_idの命名パターンに従う
完全な会話タイプの定義とマッピング関係は 会話タイプ標準 を参照。
8. モジュール開発者ガイド
8.1 拡張フィールドのアクセス
from ErisPulse.Core.Event import message
@message()
async def handle_message(event):
# 標準フィールドのアクセス
text = event.get_text()
user_id = event.get_user_id()
# プラットフォーム拡張フィールドのアクセス - 方法1: 直接 get
yunhu_command = event.get("yunhu_command")
# プラットフォーム拡張フィールドのアクセス - 方法2: ポイント式アクセス(Event 包装クラス)
# event.yunhu_command
# 原始データのアクセス
raw_data = event.get("yunhu_raw")
raw_type = event.get_raw_type()
# プラットフォームの判断
platform = event.get_platform()
if platform == "yunhu":
pass
elif platform == "telegram":
pass
8.2 拡張メッセージセグメントの処理
@message()
async def handle_message(event):
message_segments = event.get("message", [])
for segment in message_segments:
seg_type = segment.get("type")
seg_data = segment.get("data", {})
if seg_type == "text":
text = seg_data["text"]
elif seg_type.startswith("yunhu_"):
if seg_type == "yunhu_form":
form_id = seg_data["form_id"]
elif seg_type.startswith("telegram_"):
if seg_type == "telegram_sticker":
file_id = seg_data["file_id"]
8.3 最適実践
- 標準フィールドを優先する:拡張フィールドが必ず存在すると仮定しない
- プラットフォームの判断:拡張フィールドの存在でプラットフォームを推論するのではなく、
event.get_platform()を使用する - 優雅な降格:拡張メッセージセグメントを処理できない場合は、
alt_messageをバックアップとして使用する - プレフィックスをハードコードしない:
platform変数を使用して動的に結合する
# ✅ 推奨
platform = event.get_platform()
raw_data = event.get(f"{platform}_raw")
# ❌ 推奨しない
raw_data = event.get("yunhu_raw")
8.4 要求イベントの処理
モジュール開発者は event.approve() と event.reject() を使用して要求イベントを操作できる:
from ErisPulse.Core.Event import request
# フレンドリクエスト:自動で承認
@request.on_friend_request()
async def handle_friend_request(event):
user_name = event.get_user_nickname() or event.get_user_id()
comment = event.get_comment()
# 承認
result = await event.approve()
if result.get("status") == "ok":
print(f"{user_name} のフレンドリクエストを承認しました")
else:
print(f"フレンドリクエストの承認に失敗しました: {result.get('message')}")
# グループリクエスト:条件に応じて決定
@request.on_group_request()
async def handle_group_request(event):
comment = event.get_comment()
# 拒否
result = await event.reject(comment="暫定的に新しいグループに参加しません")
アダプタ経由での直接操作(イベントハンドラ外のシナリオに適用):
from ErisPulse import adapter
# request_id で直接操作
await adapter.myplatform.Request("req_abc123").accept()
await adapter.myplatform.Request("req_abc123").reject()
# 特定の Bot アカウントで操作
await adapter.myplatform.Request("req_abc123").Using("bot1").accept()
# コメントを付けて
await adapter.myplatform.Request("req_abc123").accept(comment="ようこそ")
9. notice / request イベントの会話タイプ推論
9.1 問題の背景
notice イベントと request イベントの detail_type は意味のサブタイプ(例:group_member_increase、friend_increase)であり、会話タイプ(例:group、private)ではない。
type detail_type 含義 会話タイプ
──── ─────────── ──── ────────
message group グループメッセージ group(detail_type が会話タイプ)
message private プライベートメッセージ private(detail_type が会話タイプ)
notice group_member_increase グループメンバー増加 group(group_id から推論)
notice friend_increase フレンド増加 private(user_id から推論)
request friend フレンドリクエスト private(user_id から推論)
request group グループリクエスト group(detail_type が会話タイプ)
9.2 推論ルール
infer_receive_type() の推論順序:
detail_typeが既知の会話タイプ(private/group/channel/guild/thread/user)の場合、そのまま使用detail_typeがカスタム会話タイプの場合、そのまま使用- それ以外(notice/request の意味のサブタイプ)の場合、ID フィールドから推論:
group_idがあれば →"group"channel_idがあれば →"channel"guild_idがあれば →"guild"thread_idがあれば →"thread"user_idがあれば →"private"
9.3 event.reply() の送信先推論
notice/request イベントにおける event.reply() の送信先は会話タイプの推論で決定される:
- グループ通知イベント(
group_idがある)→ グループに返信 - フレンド通知イベント(
user_idだけがある)→ ユーザーのプライベートチャットに返信
from ErisPulse.Core.Event import notice
@notice.on_group_increase()
async def handle_welcome(event):
group_id = event.get("group_id") # "group_789"
user_id = event.get("user_id") # "user_456"
# event.reply() はグループ(group/group_789)に送信
await event.reply("ようこそ!")
# 管理者に通知したい場合(プライベートチャット)、送信先を明示的に指定する:
await adapter.Send.To("user", "admin_id").Text(f"新メンバー {user_id} が {group_id} に参加しました")
9.4 アダプタ開発の推奨
notice/request イベントに正しい ID フィールドを含めるようにする:
| detail_type | 必須の ID フィールド | 推論される会話タイプ |
|---|---|---|
group_member_increase |
group_id + user_id |
group |
group_member_decrease |
group_id + user_id |
group |
friend_increase |
user_id |
private |
friend_decrease |
user_id |
private |
friend(リクエスト) |
user_id |
private |
group(リクエスト) |
group_id |
group |
10. 関連ドキュメント
変換器を実装する際に併せて参照:
- 会話タイプ標準 - 会話タイプの定義とマッピング関係
- API レスポンス標準 - アダプタ API レスポンス形式の標準
同じアダプタの送信側:
- 送信方法規格 - Send クラスのメソッド命名、パラメータ規格および逆変換要件
- API アクション標準 - OneBot12 標準 API アクションの統一インターフェース
各プラットフォームの既知の拡張イベントとメッセージセグメントを確認:
- 各プラットフォームの特徴ドキュメント - 各プラットフォームの特徴や既知の拡張イベント、メッセージセグメントなどを確認できるドキュメントにアクセスできます。