アダプター標準化ガイド(総綱)
Tip
この文書をいつ読むべきか:新しいアダプターを開発する場合や、あるプラットフォーム向けに新しい機能を追加して「標準に取り込むか {platform}_ 拡張とするか」の判断、命名の付け方、プラットフォーム差異の処理方法を決める必要があるときは、まず本文をお読みください。特定分野の具体的な仕様を調べたいだけであれば、§2 標準マップの該当ドキュメントへ直接ジャンプできます。
このドキュメントは ErisPulse アダプター標準化の総綱です:クロスプラットフォーム標準化の原則、標準マップ、差異処理パターン、新機能が標準に入るフローを確立し、インタラクティブコンポーネント標準(ボタン/キーボード、ドロップダウン選択など)とインタラクションコールバックイベントの完全な定義を示します。アダプター開発者は新機能を実装する際に標準定義を優先採用し、モジュール開発者が同一コードで任意のプラットフォームにおいて一貫した体験——命名の一貫性、パラメータの一貫性、戻り値の一貫性——を得られるようにします。
1. 標準化原則
- 命名の一貫性:同一概念はすべてのプラットフォームで同一の命名を使用する(例:取り消しは
delete_messageに統一、ボタンセグメントはkeyboardに統一)、プラットフォームによって異ならない - パラメータの一貫性:標準アクション/セグメント/メソッドのパラメータ構造はすべてのプラットフォームで一貫させる。プラットフォーム固有パラメータはオプションの拡張パラメータまたは拡張フィールドとして提供し、標準シグネチャを汚染しない
- 戻り値の一貫性:すべての API/送信呼び出しは標準レスポンス構造(
status/retcode/data/message_id/message)を返す。data内の標準フィールド(例:user_id/user_name)のセマンティクスは一貫している。プラットフォームの生データは{platform}_rawに格納する - 拡張は根拠付き:プラットフォーム固有機能は
{platform}_接頭辞で命名する(セグメント:yunhu_form、アクション:yunhu.board、イベントフィールド:qqbot_button_id)、非クロスプラットフォームであることを明確に識別する - 差異はアダプター層で吸収:モジュールコードは標準に向けたプログラミングを行い、プラットフォーム差異はアダプターが変換する(パラメータマッピング、フィールド標準化、機能縮退)。モジュールにプラットフォーム分岐の記述を要求しない
- 機能縮退でもエラーを出さない:プラットフォームが標準機能をサポートしていない場合、優雅に縮退する(
retcode=10002を返す、コンポーネントをテキスト化してalt_messageに格納する)。例外をスローしてモジュールロジックを中断しない
2. 標準マップ
| 分野 | 標準ドキュメント | カバー内容 |
|---|---|---|
| イベント変換 | イベント変換標準 | イベント構造、標準メッセージセグメント(text/image/mention/reply/keyboard など)、プラットフォーム拡張セグメント仕様 |
| インタラクティブコンポーネント | 本ドキュメント §5 | ボタン/キーボード、ドロップダウン選択、カード、インタラクションコールバックイベント標準フィールド、デコレーター規約、各プラットフォームマッピング |
| API アクション | API アクション標準 | OneBot12 標準アクション(ユーザー/グループ/チャンネル/メッセージ管理/メタアクション)の統一インターフェースと ApiDSL |
| リクエスト操作 | リクエスト操作仕様 | リクエストイベントフィールド(request_id)、Request DSL(approve/reject)とリクエストタイプのコンテキスト保持 |
| 送信メソッド | 送信メソッド仕様 | Send クラスメソッドの命名、パラメータ、デコレーター、逆変換(OB12→プラットフォーム) |
| セッションタイプ | セッションタイプ標準 | user/group/channel/guild/dms などのセッションタイプ定義とマッピング |
| API レスポンス | API レスポンス標準 | 標準レスポンス構造と retcode 規約 |
3. 標準化ワークフロー(新機能がどのように標準に入るか)
プラットフォーム固有機能({platform}_ 接頭辞)
│ ≥2 のプラットフォームで同種の機能が出現
▼
共通性の識別(汎用概念とパラメータサブセットの抽出)
│
▼
標準ドラフト(命名 + パラメータ + 戻り値 + 各プラットフォームマッピング表)
│ レビュー
▼
本総綱/各分野の標準ドキュメントに記載 + フレームワーク基底クラス/アダプターによる互換レイヤー実装
│
▼
標準セグメント/アクション(接頭辞なし)——モジュールはクロスプラットフォームで使用可能
例:ボタンは当初各プラットフォームで独立実装(telegram_inline_keyboard / 云湖 buttons / QQBot keyboard)→ ≥3 のプラットフォームで出現 → 汎用構造を抽出(label/type/data + rows)→ 標準 keyboard セグメントを公開 → 各アダプターが互換レイヤーを実装(デコレーターが汎用構造を受け入れる + 標準セグメント変換 + ネイティブセグメントの透過)。
3.1 命名規則
| 対象 | 規則 | 例 |
|---|---|---|
| 標準メッセージセグメント | 小文字、汎用概念は接頭辞なし | keyboard、select、mention |
| プラットフォーム拡張セグメント | {platform}_ 接頭辞 |
telegram_sticker、yunhu_form |
| 標準 API アクション | OB12 標準名(snake_case) | get_group_info、delete_message |
| プラットフォーム拡張アクション | {platform}. 接頭辞またはプロトコル汎用名 |
yunhu.board、send_poke(OB11 拡張) |
| デコレーター | PascalCase、汎用機能はフレームワーク基底クラスへ | .Keyboard(rows)、.At(uid) |
| イベント標準フィールド | 汎用概念は接頭辞なし | interaction_id、button_data、request_id |
| イベントプラットフォームフィールド | {platform}_ 接頭辞 |
qqbot_event_id、telegram_chat_id |
3.2 パラメータと戻り値の規則
- 標準パラメータはすべてのプラットフォームで同名同義。単位/フォーマットは標準ドキュメントで明確化する(例:秒単位のタイムスタンプ、文字列 ID)
- 必須パラメータは各プラットフォーム機能の共通サブセットを採る。プラットフォーム拡張機能はオプションパラメータとする
- プラットフォームの強い制約(例:QQBot のリッチメディアは event_id と混在送信できない)はアダプターが自動処理/縮退し、モジュールに露出させない
- 戻り値
dataの標準フィールドは全プラットフォームで一貫。プラットフォームの追加情報はdata内のプラットフォーム命名フィールドまたは{platform}_rawに格納する
4. 差異処理パターン(アダプター層)
| パターン | 説明 | 例 |
|---|---|---|
| パラメータマッピング | 標準パラメータ → プラットフォームネイティブパラメータ | delete_message(message_id) → TG deleteMessage(chat_id, message_id)(登録テーブルで chat_id を補完) |
| 構造変換 | 標準セグメント → プラットフォームネイティブ構造 | keyboard セグメント → inline_keyboard / buttons / QQBot keyboard |
| アクションマッピング | 標準アクション名 → プラットフォームアクション名 | get_self_info → get_login_info(OB11) |
| フィールド標準化 | プラットフォームレスポンス → 標準フィールド | getMe() → {user_id, user_name, user_displayname} |
| 合成識別子 | プラットフォームにネイティブ識別子がない場合に決定論的 ID を生成 | TG join request に ID なし → tjr_{chat}_{user}_{date} |
| 機能縮退 | 非対応時はテキスト化/10002 を返す | Kook に keyboard なし → alt_message でテキスト化。get_friend_list → 10002 |
| 正規化 | プラットフォームの不整形データ → 標準フォーマット | QQBot @マーカーの openid → bot_id(名称の正規化) |
| デュアルトラック互換 | 標準構造とプラットフォームネイティブ構造の両方を受け入れる | .Keyboard() は汎用 rows またはネイティブ構造を受け入れる |
5. インタラクティブコンポーネント標準
5.1 コンポーネント一覧と状態
| コンポーネント | 標準セグメント type | 状態 | サポート済みプラットフォーム |
|---|---|---|---|
| ボタン/キーボード(keyboard) | keyboard |
✅ 標準化済み | Telegram / 云湖 / QQBot |
| ドロップダウン選択(select) | select |
📋 予約(構造は §5.4 参照) | Discord / Telegram(bot) |
| カード(card) | card |
📋 予約(§5.5 参照) | Kook / 云湖 |
| モーダル(modal) | modal |
📋 予約 | Discord |
デコレーターの階層規約:汎用インタラクティブコンポーネントの Send デコレーターはアダプターの Send クラスで実装する(フレームワーク基底クラスには組み込まない)。命名は §5.2 の規約に従い、パラメータは本ドキュメントの標準構造に従う。
5.2 keyboard ボタン/インラインキーボード
メッセージセグメント構造(送信方向)
標準 keyboard セグメント = rows の二次元配列。各ボタンは
{"label": "表示テキスト", "type": "callback" | "link", "data": "コールバックデータまたはリンク先"}。
プラットフォーム固有のオプションフィールドも許可される(アダプターは能力に応じてマッピングまたは無視する)。
構造定義の一次ソース:完全なメッセージセグメント JSON、フィールド表とフィールドのセマンティクスは イベント変換標準 §4.1.1 keyboard ボタン/インラインキーボードセグメント を参照。 本節では繰り返し記載しない。
各プラットフォームマッピング対照
| プラットフォーム | 標準セグメント → ネイティブ構造 | ネイティブ構造リファレンス |
|---|---|---|
| Telegram | reply_markup.inline_keyboard:[{text, callback_data | url}] |
callback→callback_data(≤64 バイト)、link→url |
| 云湖 | content.buttons:[{label, action_type}] |
callback→action_type:2 + action + value、link→action_type:1 + url |
| QQBot | keyboard.content.rows:[{label, type, data}] |
callback→type:2 + data、link→type:0 + data(メッセージは markdown タイプである必要あり) |
| Kook | カード action-group モジュール:[{type, text, value, click}] |
callback→click:return + value、link→click:link + url |
| Discord | components[].components:[{label, style, custom_id | url}] |
callback→style:1 + custom_id、link→style:5 + url |
Send デコレーター(各アダプターの Send クラスが実装)
汎用デコレーターは各アダプターが自分の Send クラス内で実装する(フレームワーク基底クラスは変更しない):
.Keyboard(rows):標準命名。§5.2 の汎用 rows 構造を受け入れ、内部的に標準keyboardメッセージセグメントを生成する(またはプラットフォームネイティブ構造に直接変換)。Raw_ob12が統一的に処理する.Buttons(rows):オプションのセマンティックエイリアス。動作は同一- 後方互換:プラットフォームネイティブ構造を検出した場合はそのまま透過(エラーなし、変換なし)
- プラットフォームネイティブ拡張セグメント(例:
telegram_inline_keyboard)は引き続き透過され、影響を受けない
# 同じコードで任意のプラットフォーム(各アダプターがデコレーターと変換を提供)
rows = [[{"label": "いいね", "type": "callback", "data": "like:1"},
{"label": "ホーム", "type": "link", "data": "https://example.com"}]]
await adapter.Send.To("group", gid).Keyboard(rows).Text("選択してください")
アダプター互換リスト:QQBot / Telegram / 云湖 は実装済み(デコレーター + 標準セグメント変換)。 新しいアダプターは本ドキュメントに従って実装すればよい(§7 Checklist 参照)。
5.3 インタラクションコールバックイベント(ボタンクリック後)
ユーザーがボタンをクリックした後、プラットフォームがプッシュするイベントは以下の標準フィールドを必ず提供しなければならない(detail_type はプラットフォーム命名を保持可能):
| 標準フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
interaction_id |
str | はい | 今回のインタラクションの ID(応答に使用可能、例:ローディング表示/トースト) |
button_data |
str | はい | ボタンの返送データ(§5.2 の data に相当) |
button_label |
str | いいえ | ボタンの表示テキスト |
user_id |
str | はい | クリックしたユーザー |
message_id |
str | いいえ | ボタンがあるメッセージ |
group_id / channel_id |
str | いいえ | 送信元セッション |
detail_type の規約:各プラットフォームの既存命名を保持する(qqbot_interaction / telegram_callback_query /
yunhu_a2ui_button など)が、標準フィールドは必ず揃えておくこと——モジュールは event.get("button_data") でクロスプラットフォームに値を取得できる。
Event 拡張メソッドの提案(アダプターの EventMixin が提供):
def get_button_data(self) -> str: ... # button_data
def get_interaction_id(self) -> str: ... # interaction_id
インタラクションへの応答(プラットフォームの機能に応じて):adapter.reply_interaction(interaction_id, code=0)(QQBot)/
answerCallbackQuery(Telegram)など。命名はプラットフォームのメソッド群に従い、統一は強制しない。
各プラットフォームのコールバックイベントマッピング
| プラットフォーム | ネイティブイベント | detail_type | interaction_id の取得元 | button_data の取得元 |
|---|---|---|---|---|
| Telegram | callback_query |
telegram_callback_query(notice) |
callback_query.id |
callback_query.data |
| 云湖 | ボタンクリックイベント | yunhu_button_click / yunhu_a2ui_button |
buttonId / sourceComponentId |
value / actionName |
| QQBot | INTERACTION_CREATE |
qqbot_interaction |
interaction.id |
data.resolved.button_data |
| Kook | ボタンクリックイベント | kook_button_click |
msg_id+value |
value |
| Discord | INTERACTION_CREATE |
discord_interaction |
interaction.id |
data.custom_id |
5.4 select ドロップダウン選択(予約)
{
"type": "select",
"data": {
"placeholder": "選択してください",
"options": [
{"label": "オプションA", "data": "opt:A"},
{"label": "オプションB", "data": "opt:B"}
],
"min_values": 1,
"max_values": 1
}
}
コールバックイベントは §5.3 のフィールドを再利用する(button_data = 選択された data、複数選択時は JSON 配列)。
最初の実装プラットフォーム:Discord(select menu)、Telegram(keyboard 切り替え)。未実装プラットフォームがこのセグメントを
受け取った場合は alt_message 内でテキストリストに縮退させるべきである。
5.5 card カード(予約、標準化は当面保留)
カードの構造は差異が極めて大きく(Kook のフル機能カードモジュール vs 云湖 html vs QQ markdown+keyboard)、 当面は強い標準化を行わない。推奨事項:
- リッチテキストカードは
text+keyboardの組み合わせで表現する(ほとんどのシナリオで十分) - プラットフォームのフル機能カードは引き続き
{platform}_card拡張セグメントを使用する(例:kook_card) - ≥2 のプラットフォームで同種構造のカード機能が出現した時点でレビューして昇格を検討する
6. 将来の候補(Roadmap)
以下の機能はすでに ≥2 のプラットフォームで出現しているか、出現が見込まれるものであり、優先度に応じて標準化を推進する:
| 候補 | 関連プラットフォーム | 優先度 | 備考 |
|---|---|---|---|
| select ドロップダウン選択 | Discord / Telegram | 高 | 構造ドラフトは §5.4 参照 |
| リアクション/絵文字リアクション(reactions) | QQBot / Telegram / Discord / Kook | 高 | アクション + イベントの両側を標準化 |
| グループ管理アクション(ミュート/キック/承認) | QQBot / 云湖 / OB11 | 高 | 多くはすでにプラットフォームアクションとして実装済み、標準シグネチャの抽出待ち |
| アナウンス/掲示板 | 云湖 / Telegram / Discord | 中 | set_announcement 系アクション |
| ファイルリソースモデル(file_id 二段式) | 各プラットフォーム | 低(一時保留) | 送信は SendDSL.File(file, filename) による直送がすでに標準パス(URL/パス/bytes の直送、送信メソッド仕様 §2.1 参照)。file_id モデルはバックエンドが本来備えている場合にのみ透過、API アクション標準 §3.5 参照 |
| カード card | Kook / 云湖 | 低 | 構造差異が大きい、§5.5 参照 |
| フォーム form | 云湖 | 低 | プラットフォーム固有、{platform}_ 接頭辞を保持 |
| メディアのトランスコード/サイズ検出 | 各プラットフォーム | 低 | アダプター内部実装、対外的な標準化はしない |
7. 新規アダプター開発者向け標準 Checklist
新しいアダプターを開発する際は、このチェックリストに従って実装する(★ は必須、その他は推奨):
- ★ イベントを OneBot12 標準構造に変換、
BaseConverterを継承 - ★ 標準メッセージセグメントの送受信サポート(text/image/mention/reply/keyboard…。メディアセグメントは 送信メソッド仕様 §2.1 の形態等級分類と縮退ステップに従って処理)
- ★
Raw_ob12を実装(標準セグメント → プラットフォーム構造変換を含む。標準keyboardセグメントは必須) - ★ 標準レスポンス構造を返す(
make_response/make_error) - ★ マルチアカウント:
AccountConfigClass(BotAccountConfig)+ アカウント解決(アカウント名 /bot_idマッチング) - ★ Send クラスは
BaseAdapter.Sendを継承し、_apply_modifiers/send_contextを使用 - ☆ Api DSL:標準アクションをプラットフォーム API にマッピング(API アクション標準参照)
- ☆ Request DSL:リクエストイベントに
request_id+accept/rejectを含む(異種エンドポイントプラットフォームはリクエストタイプのコンテキスト保持を含む) - ☆ インタラクティブコンポーネント:
keyboardセグメント変換 + インタラクションコールバック標準フィールド +.Keyboard()/.Buttons()デコレーター(アダプターの Send クラスが実装) - ☆ EventMixin:
get_raw_event()/get_button_data()などのプラットフォーム拡張メソッド - ☆ ライフサイクルタスクは
runtime.spawn_backgroundを使用 - ☆ 設定の読み取りは
self.cfgを使用 - ☆ フレームワークのソフト依存:ErisPulse のハード依存を宣言しない + 実行時バージョン検出
- ☆ i18n:設定フィールドとログの多言語化
- ☆ platform-guide プラットフォームドキュメント + アダプターリポジトリの platform-features.md
8. 関連ドキュメント
- 各分野の標準は §2 標準マップを参照
- フレームワーク内蔵アダプターはリファレンス実装として参照可能:QQBot(v5 パラダイム全体)、OneBot11(Api DSL マッピング)、云湖(BaseConverter + Web API 拡張)