技術標準
Tip
この記事を読むタイミング:アダプターを開発または修正する際、イベント変換、APIレスポンス、送信メソッドなどが ErisPulse のクロスプラットフォーム標準に準拠しているか確認する必要がある場合、この目次から対応する規格を参照してください。どの記事から読み始めるか迷う場合は、まず下の概要を読んでください。
概要:アダプターの標準化ガイド —— 標準化の原則、標準マップ、命名規則、差異処理モード、および開発者のチェックリスト。新規アダプターや新機能を開発する際には、まずこれを読んでください。
このドキュメントは、ErisPulse の技術標準規格を含み、各コンポーネント間の一貫性と互換性を確保します。
標準ドキュメント一覧
- セッションタイプ標準 - ErisPulse セッションタイプの定義とマッピング仕様
- イベント変換標準 - プラットフォームイベント変換仕様、拡張命名規則、メッセージセグメント標準
- API レスポンス標準 - アダプター API レスポンス形式標準および拡張要件
- 送信メソッド仕様 - Send クラスメソッドの命名、パラメータ仕様および逆変換要件
- リクエスト操作仕様 - リクエストイベントフィールド要件、Request DSL(approve/reject)、異種エンドポイントにおけるリクエストタイプのコンテキスト保持およびアダプター実装要件
- API アクション標準 - OneBot12 標準 API アクション統一インターフェース(ユーザー/グループ/チャンネル/メッセージ管理/ファイル(チャンク含む)/メタアクション)
- アダプター標準化ガイド(総則) - 標準化原則/ワークフロー/命名規則 + インタラクションコンポーネント標準(ボタンキーボード/インタラクションコールバックイベント)と各プラットフォームのマッピング
標準の概要
ErisPulse は OneBot12 をコアイベント標準として採用し、その上に拡張および細分化を行っています。
コア原則
- 互換性:すべての標準は OneBot12 標準と互換性を保つ必要があります
- 拡張性:プラットフォーム特有の機能はプレフィックス方式で拡張し、衝突を避ける
- 一貫性:タイムスタンプ、ID形式などの重要なフィールドは統一して処理する
- 追跡可能性:デバッグや問題のトラブルシューティングのために元のデータを保持する
標準の必要性
1. クロスプラットフォーム互換性の確保
異なるプラットフォームのイベント形式はそれぞれ異なり、標準化された変換により以下が保証されます:
- モジュールコードは一度書けば、すべてのプラットフォームで実行可能
- イベント処理ロジックは一貫性を保つ
- 開発および保守コストを削減
2. API インターフェースの規範化
統一された API レスポンス形式により以下が保証されます:
- モジュールは一貫して API エラーを処理できる
- エラーメッセージは統一され、理解しやすい
- 戻り値のデータ構造は一貫している
3. コード品質の向上
標準規格により以下が助けられます:
- コードスタイルの一貫性を保つ
- 名前衝突を減らす
- コードの可読性を高める
標準を遵守することのメリット
アダプター開発者にとって
- 明確な変換ルール
- 統一されたレスポンス形式
- 調整およびテストが容易
モジュール開発者にとって
- 一貫したイベントインターフェース
- 予測可能な API 挙動
- クロスプラットフォーム開発が簡素化
最終ユーザーにとって
- 穏やかなシステム動作
- 統一されたメッセージ形式
- 良好な互換性
標準準拠チェックリスト
イベント変換
- すべての標準フィールドが正しくマッピングされている
- プラットフォーム固有のフィールドにプレフィックスが付与されている
- タイムスタンプが10桁の秒単位に変換されている
- 生データが {platform}_raw に保存されている
- 元のイベントタイプが {platform}_raw_type に保存されている
- メッセージセグメントの alt_message が生成されている
- リクエストイベントに request_id フィールドが含まれている
API レスポンス
- status フィールドが含まれている
- retcode フィールドが含まれている
- data フィールドが含まれている
- message_id フィールドが含まれている
- message フィールドが含まれている
- リターンコードが OneBot12 仕様に準拠している
送信メソッドの命名
- パスカルケース(PascalCase)を使用している
- Task オブジェクトを返す
- 修飾メソッドは self を返す
- パラメータの命名が規範に準拠している
メディア送信(Image / Voice / Video / File)
-
fileパラメータはすべての形式を必須サポート:HTTP(S) URL / ローカルパス /bytes -
fileパラメータは可能な限りの形式をサポートすることが望ましい:file://URI / Base64 / Data URI(サポート不可の場合はフォールバック階層に従いretcode=10002を返す) - 形式判定の順序が規範に準拠している(bytes → URL →
file://→ パス) -
Fileのファイル名は導出順序に従って生成されている(明示的なfilename> URL の basename > パスの basename > プラットフォームのデフォルト) - プラットフォームのメディア制限がアダプタードキュメントで宣言されている
- サポート対象外のメディアタイプはフォールバック階層に従って処理されている(近縁タイプへのフォールバックまたは
retcode=10002を返す。例外をスローせず、サイレントに破棄しない)
プロトコルの詳細は 送信メソッド規範 §2.1 を参照
リクエスト操作
- Request 内部クラスで _do_accept / _do_reject がオーバーライドされている(公開エントリの accept()/reject() はオーバーライドしないこと)
- 操作は標準の API レスポンス形式を返す
- サポート対象外の操作は retcode=10002 を返す
関連ドキュメント
- プラットフォーム特性ガイド - 各プラットフォームの特性の違いを理解する
- 開発者ガイド - 自作モジュールおよびアダプターの開発