云湖プラットフォームの特徴ドキュメント
YunhuAdapterは、Yunhuプロトコルに基づいて構築されたアダプターであり、Yunhuのすべての機能モジュールを統合し、一貫したイベント処理とメッセージ操作のインターフェースを提供します。
ドキュメント情報
- 対応モジュールバージョン: 4.6.2
- メンテナ: ErisPulse
- 最終更新日: 2026-11-10
基本情報
- プラットフォーム紹介: Yunhuは、企業向けのリアルタイムコミュニケーションプラットフォームです。
- アダプタ名: YunhuAdapter
- 多アカウント対応: bot_idで識別可能な複数のYunhuロボットアカウントを構成可能
- 鏈式修飾子対応: .Reply()などの修飾子メソッドをチェーンで使用可能
- OneBot12互換: OneBot12形式のメッセージ送信に対応
v5 ファンタジー更新(4.4.0)
本アダプターはv5ファンタジーに完全に適合し、増分アップグレードでAPIは互換性を保持しています:
- 公式サービスAPI一覧(Api DSL拡張メソッド): 編集メッセージ、一括送信、メッセージリスト、ユーザー/グローバルボード、グループメンバーの禁止、グループメンバーの削除、グループメッセージタイプ制限、グループタグのCRUD、ユーザーにタグを付ける
- 標準 keyboard 段(跨プラットフォーム相互作用コンポーネント標準): {"type": "keyboard", "data": {"rows": [[{"label", "type": "callback|link", "data"}]]}} メッセージは自動的にYunhuのbuttonsに変換される。.Buttons(rows) / .Keyboard(rows) 修飾子は汎用構造を受け入れる(元の構造は後方互換)
- 相互作用コールバック標準フィールド: ボタンクリック/A2UIイベントには interaction_id / button_data という標準フィールドが含まれる
- spawn_background タスクの所属: WS接続タスクは
runtime.spawn_backgroundを使用 - フレームワークのソフト依存: ErisPulse>=2.7.1を実行時に検出し、警告を表示する。起動時にバージョンログを出力する
プラットフォーム拡張アクション(call / Api メソッド)
from ErisPulse import sdk
yunhu = sdk.adapter.get("yunhu")
# Api メソッド(公式サービスAPI)
await yunhu.Api.edit_message(msg_id, recv_id, "group", "text", {"text": "新内容"})
await yunhu.Api.batch_send(["userId1", "userId2"], "text", {"text": "公告"})
await yunhu.Api.get_message_list(group_id, "group", before=10)
await yunhu.Api.set_user_board(chat_id, "group", "看板内容", expire_time=3600)
await yunhu.Api.dismiss_global_board()
await yunhu.Api.gag_group_member(group_id, user_id, 600) # 禁言600秒、0=解除
await yunhu.Api.remove_group_member(group_id, user_id)
await yunhu.Api.set_group_msg_type_limit(group_id, "text,image")
await yunhu.Api.create_group_tag(group_id, "VIP", color="#FF5733")
await yunhu.Api.add_user_tag(group_id, user_id, "VIP")
# ボタンクリックコールバック(標準フィールド)
from ErisPulse.Core.Event import notice
@notice.on_notice()
async def handle_button(event):
if event.get("platform") == "yunhu" and event.get("button_data"):
data = event["button_data"] # 跨プラットフォーム統一取値
interaction_id = event["interaction_id"]
完全な標準説明は跨プラットフォーム相互作用コンポーネント標準をご覧ください。
標準化対応(4.6.2)
このバージョンではアダプターの標準化が完了し、応答構造とエラーコードはAPI応答規格に従います。
アカウントと多アカウントの完結
- イベント注入
self.account_id(内部アカウント名): 受信したイベントselfオブジェクトには、イベントを発生させたアカウント名が含まれており、event.reply()は自動的に受信したアカウントにルーティングされます。多アカウントの場面では、もう手動でUsing(bot_id)を使用する必要はありません。 call_api双重互換フィールド:account_id(標準名)/_account_id(旧名)の両方でアカウントを指定可能。フレームワークのApiDSL(Api.Using(...))は自動的に適応Sendはsend_contextを読み取る(イベントアカウントのバックアップ): イベント処理コンテキスト内でSendを呼び出す場合、デフォルトでは送信元アカウントにフォールバックする
エラーコード規格
| retcode | 含義 | 说明 |
|---|---|---|
| 0 | 成功 | — |
| 33001 | 网络错误 | 云湖服务器失败等网络类异常 |
| 34100 | 平台失败 | 云湖返回失败;原始响应保留在 yunhu_raw |
| 10002 | 不支持 | 资源不存在(机器人/用户/群不存在)或平台无对应能力的标准动作 |
| 10003 | 参数错误 | 缺少或无效参数 |
4.6.2 変更点:
_platformを追加した後、make_responseはフレームワークによって自動的にyunhu_rawを含む。プラットフォームの失敗はすべて34100を返す。"机器人/用户/群不存在" は34001から10002(リソースが存在しない)に変更された。
応答構造の調整
元の応答の非標準 self フィールドは data.self_info(bot_id を含む)に移動し、トップレベルには標準フィールドと yunhu_raw だけが残る:
{
"status": "ok",
"retcode": 0,
"data": {
"self_info": {"user_id": "bot_id"},
"messageInfo": {"msgId": "..."}
},
"message_id": "123456",
"message": "",
"yunhu_raw": {}
}
未知のイベントは静かに破棄されない
認識できないYunhuイベントは、type="unknown" イベント(detail_type は元のイベントタイプ、元のデータは yunhu_raw に保持)を生成し、警告ログを出力する。モジュールはこれに基づいて未対応のイベントタイプを調査できる。
プラットフォーム拡張メソッドの約定
歴史的なプラットフォーム拡張メソッド(edit_message / batch_send / set_user_board / gag_group_member / create_group_tag など)は引き続き使用可能。新しいプラットフォーム拡張はすべて Api.call("yunhu.xxx", **params) を通じて行う(下記「プラットフォーム拡張アクション」を参照)。
支持するメッセージ送信タイプ
すべての送信メソッドはチェーン構文で実現可能。例えば:
from ErisPulse.Core import adapter
yunhu = adapter.get("yunhu")
await yunhu.Send.To("user", user_id).Text("Hello World!")
サポートする送信タイプは以下の通りです:
.Text(text: str):純粋なテキストメッセージを送信。.Html(html: str):HTML形式のメッセージを送信。.HTML(html)は別名(標準 Send メソッドの命名と一致させる)。.Markdown(markdown: str):Markdown形式のメッセージを送信。.MergeForward(nodes, title="合并聊天记录"):合併転送メッセージを送信(折りたたみHTMLカードとしてレンダリングされ、htmlチャネルを通じて送信される)。.A2UI(text: str):A2UI形式のメッセージを送信。.Image(file: bytes, stream: bool = False, filename: str = None):画像メッセージを送信。ストリームアップロードとカスタムファイル名をサポート。.Video(file: bytes, stream: bool = False, filename: str = None):動画メッセージを送信。ストリームアップロードとカスタムファイル名をサポート。.File(file: bytes, stream: bool = False, filename: str = None):ファイルメッセージを送信。ストリームアップロードとカスタムファイル名をサポート。.Batch(target_ids: List[str], message: str, content_type: str = "text", **kwargs):一括メッセージ送信。.Edit(msg_id: str, text: str, content_type: str = "text", buttons: List = None):既存のメッセージを編集。.Recall(msg_id: str):メッセージを撤回。.Board(content: str, content_type: str = "text"):公告看板を送信。作用域はTo()から推測される(ターゲットを指定=ローカル看板、未指定=グローバル看板)。チェーン修飾:.Expire(duration)相対的な期限(秒)、.ExpireAt(timestamp)絶対的な期限(秒単位のタイムスタンプ)、.ForMember(member_id)グループメンバー看板;内容が空の場合は自動的に看板を撤回。旧式Board("local", "公告")明示的な scope 書き込みもまだ互換性がある。.DismissBoard():公告看板を撤回。作用域はTo()から推測され、.ForMember(member_id)もサポートする。旧式DismissBoard("local")書き込みもまだ互換性がある。.Stream(content_type: str, content_generator: AsyncGenerator, **kwargs):ストリームメッセージを送信。
グループ管理メソッド
すべてのグループ管理メソッドはチェーン構文でグループを指定する必要がある。例えば:
from ErisPulse.Core import adapter
yunhu = adapter.get("yunhu")
await yunhu.Send.To("group", group_id).Kick(user_id)
.Kick(user_id: str):グループメンバーを削除。ロボットはグループメンバーを削除する権限が必要。.Ban(user_id: str, duration: int = 600):ユーザーを禁止。durationは禁止時間(秒)、0は解除、-1は永久禁止。ロボットはユーザーを禁止する権限が必要。.CreateTag(tag: str, color: str = None, desc: str = None, sort: int = None):グループタグを作成。colorは#RRGGBB形式、sortが小さいほど前に表示される。ロボットはタググループを制御する権限が必要。.EditTag(tag: str, new_tag: str = None, color: str = None, desc: str = None, sort: int = None):グループタグを編集。各パラメータはオプションで、指定しない場合は変更しない。ロボットはタググループを制御する権限が必要。.DeleteTag(tag: str):グループタグを削除。ロボットはタググループを制御する権限が必要。.GetTagList():グループタグリストを取得。返却データにはlist配列が含まれる。.AddUserTag(user_id: str, tag: str):ユーザーにタグを追加。ロボットはタググループを制御する権限が必要。.RemoveUserTag(user_id: str, tag: str):ユーザーからタグを削除。ロボットはタググループを制御する権限が必要。.SetMsgTypeLimit(types: str):グループ内のメッセージタイプを制限。typesはメッセージタイプ名で、複数ある場合はカンマで区切る(例:"text,image,video")、空文字列は制限しない。ロボットはグループ情報を変更する権限が必要。
メッセージ検索メソッド
指定された会話(ユーザー/グループ)の履歴メッセージリストを取得するには、チェーン構文でターゲットを指定する必要がある。例えば:
from ErisPulse.Core import adapter
yunhu = adapter.get("yunhu")
result = await yunhu.Send.To("group", group_id).GetMessages(before=10)
.GetMessages(message_id: str = None, before: int = None, after: int = None):会話の履歴メッセージを取得。返却データにはlist配列とtotal総数が含まれる。message_id:メッセージID(オプション)。指定しない場合、beforeと組み合わせて最近のN件を返す。before:指定したメッセージIDの前のN件を返す。after:指定したメッセージIDの後のN件を返す。注意:
beforeとafterは少なくとも1つを指定する必要があり、0より大きくなければ、サーバーはメッセージを返さない。
Board 作用域は To() によって自動的に推測される:
To(target_type, target_id)を指定 → ローカル看板(指定されたユーザー/グループ)To()を指定しない → グローバル看板
# ローカル看板(60 秒後相対的な期限)
await yunhu.Send.To("group", group_id).Expire(60).Board("公告", content_type="markdown")
# グループメンバー看板(指定されたメンバーのみ表示)
await yunhu.Send.To("group", group_id).ForMember(user_id).Board("あなた専用")
# 絶対時間の期限
await yunhu.Send.To("group", group_id).ExpireAt(1785208268).Board("指定時間で期限切れ")
# グローバル看板
await yunhu.Send.Board("グローバル公告")
# ローカル看板をクリア(内容が空の場合は自動的に看板を撤回)
await yunhu.Send.To("group", group_id).Board("")
ボタンパラメータの説明
buttons パラメータは、ボタンのレイアウトと機能を示すネストされたリストです。各ボタンオブジェクトには以下のフィールドが含まれます:
| フィールド | タイプ | 必須 | 説明 |
|---|---|---|---|
text |
string | 是 | ボタン上の文字 |
actionType |
int | 是 | 動作タイプ:1: URL に移動2: コピー3: イベントを報告 |
url |
string | 否 | actionType=1 の場合、移動先の URL を使用する |
value |
string | 否 | actionType=2 の場合、この値がクリップボードにコピーされるactionType=3 の場合、この値がサブスクライバに送信される |
例:
buttons = [
[
{"text": "コピー", "actionType": 2, "value": "xxxx"},
{"text": "クリックして移動", "actionType": 1, "url": "http://www.baidu.com"},
{"text": "イベントを報告", "actionType": 3, "value": "xxxxx"}
]
]
await yunhu.Send.To("user", user_id).Buttons(buttons).Text("ボタン付きメッセージ")
注意:
- ユーザーがイベント報告ボタンをクリックした場合にのみ、通知を受け取る。コピーとURL移動は通知を受け取れない。
チェーン修飾メソッド(組み合わせ可能)
チェーン修飾メソッドは self を返し、チェーンで呼び出すことが可能。最終的な送信メソッドの前に呼び出す必要がある:
.Reply(message_id: str):指定されたメッセージに返信。.At(user_id: str):指定されたユーザーを@する。.AtAll():全員を@する。.Buttons(buttons: List):ボタンを追加する。
チェーン呼び出しの例
# 基礎的な送信
await yunhu.Send.To("user", user_id).Text("Hello")
# メッセージの返信
await yunhu.Send.To("group", group_id).Reply(msg_id).Text("返信メッセージ")
# 返信 + ボタン
await yunhu.Send.To("group", group_id).Reply(msg_id).Buttons(buttons).Text("返信とボタン付きメッセージ")
グループ管理の例
from ErisPulse.Core import adapter
yunhu = adapter.get("yunhu")
# グループメンバーの削除
await yunhu.Send.To("group", group_id).Kick(user_id)
# ユーザーの禁止(10分間)
await yunhu.Send.To("group", group_id).Ban(user_id, duration=600)
# 禁止の解除
await yunhu.Send.To("group", group_id).Ban(user_id, duration=0)
# 永久禁止
await yunhu.Send.To("group", group_id).Ban(user_id, duration=-1)
# グループタグの作成
await yunhu.Send.To("group", group_id).CreateTag("VIPユーザー", color="#FF5733", desc="VIP会員")
# グループタグの編集
await yunhu.Send.To("group", group_id).EditTag("VIPユーザー", new_tag="SVIPユーザー", color="#33C4FF")
# グループタグの削除
await yunhu.Send.To("group", group_id).DeleteTag("VIPユーザー")
# グループタグリストの取得
result = await yunhu.Send.To("group", group_id).GetTagList()
# ユーザーにタグを追加
await yunhu.Send.To("group", group_id).AddUserTag(user_id, "VIPユーザー")
# ユーザーからタグを削除
await yunhu.Send.To("group", group_id).RemoveUserTag(user_id, "VIPユーザー")
# メッセージタイプの制限
await yunhu.Send.To("group", group_id).SetMsgTypeLimit("text,image,video")
# メッセージタイプの制限を解除
await yunhu.Send.To("group", group_id).SetMsgTypeLimit("")
メッセージ検索の例
from ErisPulse.Core import adapter
yunhu = adapter.get("yunhu")
# グループの最近10件のメッセージを取得(合計10件返される)
result = await yunhu.Send.To("group", group_id).GetMessages(before=10)
# グループで指定されたメッセージIDの前の10件を取得(合計11件返される)
result = await yunhu.Send.To("group", group_id).GetMessages(message_id="msg_xxx", before=10)
# グループで指定されたメッセージIDの前後各10件を取得(合計21件返される)
result = await yunhu.Send.To("group", group_id).GetMessages(message_id="msg_xxx", before=10, after=10)
# ユーザー会話の履歴メッセージを取得
result = await yunhu.Send.To("user", user_id).GetMessages(message_id="msg_xxx", before=10)
OneBot12メッセージサポート
アダプターはOneBot12形式のメッセージを送信することをサポートし、跨プラットフォームメッセージの互換性を確保する:
.Raw_ob12(message: List[Dict], **kwargs):OneBot12形式のメッセージを送信。
# OneBot12形式のメッセージを送信
ob12_msg = [{"type": "text", "data": {"text": "Hello"}}]
await yunhu.Send.To("user", user_id).Raw_ob12(ob12_msg)
# チェーン修飾と組み合わせて使用
ob12_msg = [{"type": "text", "data": {"text": "返信メッセージ"}}]
await yunhu.Send.To("group", group_id).Reply(msg_id).Raw_ob12(ob12_msg)
標準APIアクション(ApiDSL)
Note
この機能には ErisPulse 2.7.0+ および YunhuAdapter 4.3.0+ が必要です。
Send チェーン送信に加えて、アダプターは Api 内部クラスを提供しており、OneBot12 標準 API アクションと Yunhu プラットフォームの拡張アクションを公開しています。すべてのメソッドは標準レスポンス形式を返します。
from ErisPulse.Core import adapter
yunhu = adapter.get("yunhu")
# 情報照会(公開 Web API 経由、認証不要)
result = await yunhu.Api.get_self_info() # ボット自身の情報
result = await yunhu.Api.get_user_info("7058262") # 任意のユーザー情報
result = await yunhu.Api.get_group_info("635409929") # グループ情報
# ファイル操作
result = await yunhu.Api.upload_file(type="path", name="a.png", path="./a.png")
result = await yunhu.Api.get_file("https://chat-file.jwznb.com/xxx")
# メッセージの取り消し(chat_id + chat_type の追加指定が必要)
await yunhu.Api.delete_message("msg_id", chat_id="123", chat_type="group")
# マルチアカウント:Bot アカウントを指定
info = await yunhu.Api.Using("bot1").get_self_info()
サポートされている標準アクション
| メソッド | 説明 | データソース |
|---|---|---|
get_self_info() |
ボット自身の情報 | 公開 Web API(bot-info) |
get_user_info(user_id) |
ユーザー情報(任意のユーザーを照会可能) | 公開 Web API(user/homepage) |
get_group_info(group_id) |
グループ情報 | 公開 Web API(group-info) |
upload_file(*, type, name, ...) |
ファイルのアップロード(image/video/file を自動判定) | Bot オープン API |
get_file(file_id) |
ファイルの取得(file_id は URL そのもの、Referer を自動付与してダウンロードし base64 で返す) | プロキシダウンロード |
delete_message(message_id, *, chat_id, chat_type) |
メッセージの取り消し | Bot オープン API(/bot/recall) |
メディアメッセージとホットリンク保護(4.6.3)
Yunhu メディア CDN(chat-img.jwznb.com など)では Referer によるホットリンク保護 が有効になっています:Referer なしの GET は一律 403 となるため、Referer: https://im.jwzhd.com/ を付与する必要があります。
- メディアメッセージ(image/video/file/audio)を受信した際、イベント内のメディアセグメントの
data.headers.Refererには既にこの値が含まれています。独自にダウンロードするモジュールはこのヘッダーを付与してください - または
call_api("get_file", file_id=<url>)を直接使用すると、アダプターがプロキシダウンロードして base64 を返します(ホットリンク保護を自動処理)
seg = event["message"][0] # {"type": "image", "data": {...}}
img = await bot.call_api("get_file", file_id=seg["data"]["url"])
raw_bytes = base64.b64decode(img["data"]["base64"])
注意:
get_self_info/get_user_info/get_group_infoは非公式の公開 Web API(chat-web-go.jwzhd.com)で実装されています。これらのインターフェースは認証不要ですが公式ドキュメントではないため、プラットフォームの更新により変更される可能性があります。失敗時には標準エラーレスポンスが返されます。
サポートされていない標準アクション
以下の標準アクションには Yunhu に対応する API が存在せず、呼び出すと retcode=10002(サポートされていない操作)が返されます:
get_friend_list(Bot オープン API の「ボットユーザーリスト」はまだリリース待ちの状態です)get_group_list/get_group_member_info/get_group_member_listset_group_name/leave_group
プラットフォーム拡張アクション
Api.call("yunhu.xxx", **params) を使用して Yunhu 固有のアクションを呼び出します(パラメータは OB12 スタイルの命名を採用し、アダプターが自動的に Yunhu のフィールドへ変換します):
| 拡張アクション | 説明 | 同等の Send メソッド |
|---|---|---|
yunhu.recall |
メッセージの取り消し(msg_id, chat_id, chat_type) | Send.To(...).Recall(msg_id) |
yunhu.kick |
グループメンバーの削除(group_id, user_id) | Send.To("group", g).Kick(uid) |
yunhu.ban |
ミュート(group_id, user_id, duration) | Send.To("group", g).Ban(uid, duration) |
yunhu.unban |
ミュート解除(group_id, user_id) | Send.To("group", g).Ban(uid, duration=0) |
yunhu.tag.create/edit/delete/list |
グループタグの CRUD(group_id, ...) | Send.To("group", g).CreateTag(...) など |
yunhu.tag.relate / yunhu.tag.relate_cancel |
ユーザーへのタグ追加/削除 | Send.To("group", g).AddUserTag(...) など |
yunhu.set_member_title / yunhu.unset_member_title |
メンバータイトルのセマンティックエイリアス(タグ≈タイトル、内部的に tag.relate にマッピング) | — |
yunhu.msg_type_limit |
グループメッセージタイプの制限(group_id, type) | Send.To("group", g).SetMsgTypeLimit(...) |
yunhu.get_messages |
履歴メッセージの取得(chat_id, chat_type, message_id?, before?, after?) | Send.To(...).GetMessages(...) |
yunhu.bot_info |
公開 bot-info 照会(bot_id) | — |
yunhu.user_homepage |
公開ユーザーホームページ照会(user_id) | — |
# プラットフォーム拡張の例
await yunhu.Api.call("yunhu.kick", group_id="123", user_id="456")
await yunhu.Api.call("yunhu.set_member_title", group_id="123", user_id="456", title="VIP")
result = await yunhu.Api.call("yunhu.get_messages", chat_id="123", chat_type="group", before=10)
タグとタイトル:Yunhu の「タグ」は OneBot12 のグループメンバー
titleとセマンティクス上同等です。yunhu.set_member_titleはyunhu.tag.relateのネイティブなセマンティックエイリアスであり、両者は内部的に同じエンドポイントへマッピングされます。グループメッセージイベントにおける送信者の役割は、senderUserLevelから標準のroleフィールド(owner/admin/member)へマッピングされます。
送信メソッドの返り値
すべての送信メソッドは Task オブジェクトを返し、直接 await して送信結果を取得できる。返り値は ErisPulse アダプターの標準化された返り値規格に従う:
{
"status": "ok", // 実行状態
"retcode": 0, // 返り値コード
"data": {...}, // 返り値データ(self_info は bot_id を含む、上記「返り値構造の調整」参照)
"message_id": "123456", // メッセージID
"message": "", // エラーメッセージ
"yunhu_raw": {...} // 元の返り値データ
}
4.6.2 変更点:元の返り値の非標準
selfフィールドはdata.self_infoに移動しました。bot_id を取得するにはresult["data"]["self_info"]["user_id"]を使用してください。
特有のイベントタイプ
platform=="yunhu" を検証してから本プラットフォームの特有機能を使用する必要があります。
核心的な違い点
- 特有のイベントタイプ:
- 表形式(例: 表形式のコマンド): yunhu_form
- 表情/ステッカー形式のメッセージ: yunhu_expression
- ボタンクリック: yunhu_button_click
- A2UIボタンクリック: yunhu_a2ui_button
- ロボットの設定: yunhu_bot_setting
- ショートカットメニュー: yunhu_shortcut_menu
- 標準フィールドの拡張(4.3.0+):
- メッセージイベントに標準の
roleフィールドが追加されました(Yunhu のsenderUserLevelからowner/admin/memberにマッピング) - 新たに
user_avatarフィールドが追加されました(送信者のアバター URL)
- メッセージイベントに標準の
- 拡張フィールド:
- すべての特有フィールドは
yunhu_で始まるプレフィックスが付いています - 元のデータは
yunhu_rawフィールドに保持されます - プライベートチャットでは
self.user_idはロボットのIDを表します
- すべての特有フィールドは
特殊フィールドの例
# 表形式のコマンド
{
"type": "message",
"detail_type": "private",
"yunhu_command": {
"name": "表形式のコマンド名",
"id": "コマンドID",
"form": {
"フィールドID1": {
"id": "フィールドID1",
"type": "input/textarea/select/radio/checkbox/switch",
"label": "フィールドラベル",
"value": "フィールド値"
}
}
}
}
# ボタンクリックイベント
{
"type": "notice",
"detail_type": "yunhu_button_click",
"user_id": "ボタンをクリックしたユーザーID",
"user_nickname": "ユーザーのニックネーム",
"message_id": "メッセージID",
"yunhu_button": {
"id": "ボタンID(空の場合あり)",
"value": "ボタンの値"
}
}
# A2UIボタンクリックイベント
{
"type": "notice",
"detail_type": "yunhu_a2ui_button",
"user_id": "操作ユーザーID",
"user_nickname": "ユーザーのニックネーム",
"message_id": "メッセージID",
"yunhu_a2ui": {
"recv_id": "受信者ID",
"recv_type": "受信者タイプ",
"action_name": "操作名",
"source_component_id": "元のコンポーネントID",
"form_context": {},
"interaction_json": "インタラクションデータのJSON文字列"
}
}
### ボタンクリックイベントの処理例
```python
from ErisPulse.Core.Event import notice
@notice.on_notice()
async def handle_yunhu_notice(event):
"""Yunhu通知イベントを処理する
すべての通知イベントを処理するには、on_notice()デコレータを使用し、
detail_typeで異なるタイプの通知を区別する
event.reply()は自動的にYunhuプラットフォームで返信する
"""
# ボタンクリックイベントかどうかを確認
if event.get("detail_type") == "yunhu_button_click":
user_id = event.get_user_id()
user_nickname = event.get_user_nickname()
button_value = event.get("yunhu_button", {}).get("value", "")
print(f"ユーザー {user_nickname}({user_id}) がボタンをクリックしました: {button_value}")
# event.reply()を使用して返信(プラットフォームに応じて正しい送信方法を選択する)
if button_value == "confirm":
await event.reply("確認ボタンをクリックしました!")
elif button_value == "cancel":
await event.reply("操作がキャンセルされました")
else:
await event.reply(f"選択を受け付けました: {button_value}")
# ショートカットメニューイベントを処理
elif event.get("detail_type") == "yunhu_shortcut_menu":
menu_id = event.get("yunhu_menu", {}).get("id", "")
await event.reply(f"ショートカットメニューが起動しました: {menu_id}")
# ロボットの設定変更
elif event.get("detail_type") == "yunhu_bot_setting":
settings = event.get("yunhu_setting", {})
await event.reply(f"設定が更新されました: {settings}")
# A2UIボタンイベントを処理
elif event.get("detail_type") == "yunhu_a2ui_button":
a2ui = event.get("yunhu_a2ui", {})
action_name = a2ui.get("action_name", "")
form_context = a2ui.get("form_context", {})
await event.reply(f"A2UI操作: {action_name}, フォームデータ: {form_context}")
チェーン呼び出しを使ってボタン付きメッセージを送信する
from ErisPulse import sdk
yunhu = sdk.adapter.get("yunhu")
buttons = [
[
{"text": "確認", "actionType": 3, "value": "confirm"},
{"text": "キャンセル", "actionType": 3, "value": "cancel"},
{"text": "詳細を表示", "actionType": 1, "url": "http://example.com/detail"}
]
]
# グループにボタン付きメッセージを送信
await yunhu.Send.To("group", "123456").Buttons(buttons).Text("以下の操作を確認してください")
# ユーザーのプライベートチャットにボタン付きメッセージを送信
await yunhu.Send.To("user", "789").Buttons(buttons).Text("あなたの好みの設定を選択してください")
A2UIメッセージの送信
from ErisPulse import sdk
yunhu = sdk.adapter.get("yunhu")
# A2UIメッセージを送信
await yunhu.Send.To("user", user_id).A2UI("A2UIインタラクションカードの内容")
ロボットの設定
{ "type": "notice", "detail_type": "yunhu_bot_setting", "group_id": "グループID(空の場合あり)", "user_nickname": "ユーザーのニックネーム", "yunhu_setting": { "設定項目ID": { "id": "設定項目ID", "type": "input/radio/checkbox/select/switch", "value": "設定値" } } }
ショートカットメニュー
{ "type": "notice", "detail_type": "yunhu_shortcut_menu", "user_id": "メニューを起動したユーザーID", "user_nickname": "ユーザーのニックネーム", "group_id": "グループID(プライベートチャットの場合)", "yunhu_menu": { "id": "メニューID", "type": "メニューのタイプ(整数)", "action": "メニューのアクション(整数)" } }
## Event Mixin 拡張メソッド
アダプターは以下のプラットフォーム固有のメソッドを登録し、`platform == "yunhu"` の場合にのみ使用可能:
| メソッド | 戻り値の型 | 説明 |
|------|----------|------|
| `get_raw_event()` | `dict` | Yunhuの元のイベントデータを取得(`yunhu_raw`) |
| `get_sender_level()` | `str` | 送信者のYunhuの元のレベル(owner/administrator/member/unknown) |
| `get_sender_role()` | `str` | 送信者のOneBot12標準のrole(owner/admin/member) |
| `get_sender_title()` | `str` | 送信者の頭語(標準の`title`フィールドのアクセサ、予約) |
| `get_sender_avatar()` | `str` | 送信者のアバターURL |
| `get_command()` | `dict` | コマンドデータ(コマンドメッセージイベントのみ、`yunhu_command`) |
| `get_button_value()` | `str` | ボタンクリックイベントのvalue(`yunhu_button.value`) |
| `get_a2ui_action()` | `str` | A2UIボタンクリックイベントのactionName |
| `get_a2ui_form_context()` | `dict` | A2UIボタンクリックイベントのフォームコンテキスト |
| `get_menu_id()` | `str` | ショートカットメニューイベントのID(`yunhu_menu.id`) |
| `get_setting()` | `dict` | ロボット設定イベントの設定データ(`yunhu_setting`) |
| `is_command_message()` | `bool` | コマンドメッセージかどうか |
| `is_button_click()` | `bool` | ボタンクリックイベントかどうか |
| `is_a2ui_button()` | `bool` | A2UIボタンクリックイベントかどうか |
```python
from ErisPulse.Core.Event import notice
@notice.on_notice()
async def handle_yunhu_notice(event):
if event.get("platform") != "yunhu":
return
if event.is_button_click():
value = event.get_button_value()
await event.reply(f"ボタンをクリックしました: {value}")
if event.get("detail_type") == "yunhu_shortcut_menu":
menu_id = event.get_menu_id()
拡張フィールドの説明
- すべての特有フィールドは
yunhu_プレフィックスで始まり、標準フィールドとの衝突を避ける - 元のデータは
yunhu_rawフィールドに保持され、Yunhuプラットフォームの完全な元のデータにアクセス可能 self.user_idはロボットのIDを表す(設定のbot_idから取得)- 表形式のコマンドは
yunhu_commandフィールドを通じて構造化データを提供 - ボタンクリックイベントは
yunhu_buttonフィールドを通じてボタンに関する情報を提供 - A2UIボタンクリックイベントは
yunhu_a2uiフィールドを通じてA2UIインタラクションに関する情報を提供 - ロボットの設定変更は
yunhu_settingフィールドを通じて設定項目のデータを提供 - ショートカットメニュー操作は
yunhu_menuフィールドを通じてメニューに関する情報を提供 - 表情/ステッカー形式のメッセージは
yunhu_expressionメッセージセグメントを通じてステッカーのデータを提供(sticker_id、ステッカーのパックID、画像のサイズなど)
表情/ステッカー形式のメッセージセグメント (yunhu_expression)
ユーザーが表情/ステッカーを送信すると、メッセージセグメントのタイプは yunhu_expression となる:
{
"type": "yunhu_expression",
"data": {
"sticker_id": "35154",
"sticker_pack_id": "1670",
"expression_id": "0",
"image_name": "sticker/fabb9077f2ba302402ea871cab3686ad7a3fc52c.gif",
"width": 500,
"height": 500
}
}
| フィールド | タイプ | 説明 |
|---|---|---|
sticker_id |
string | ステッカーの唯一の識別子 |
sticker_pack_id |
string | ステッカーのパックID |
expression_id |
string | 表情のID |
image_name |
string | 表情の画像のファイルパス |
width |
int | 画像の幅(オプション) |
height |
int | 画像の高さ(オプション) |
使用例:
from ErisPulse.Core.Event import message
@message.on_message()
async def handle_message(event):
if event.get_platform() == "yunhu":
for segment in event.get("message", []):
if segment.get("type") == "yunhu_expression":
data = segment["data"]
print(f"表情パックを受け取りました: sticker_id={data['sticker_id']}, パックID={data['sticker_pack_id']}")
多Bot設定
設定の説明
Yunhuアダプターは複数のYunhuロボットアカウントを同時に設定および実行できる。
# config.toml
[Yunhu_Adapter.accounts.bot1]
token = "your_bot1_token" # ロボットtoken(必須)
mode = "ws" # 受信モード(オプション、デフォルトは"ws"、"ws"または"webhook"可)
webhook_path = "/webhook/bot1" # Webhookのパス(オプション、デフォルトは"/webhook")
enabled = true # 有効かどうか(オプション、デフォルトはtrue)
[Yunhu_Adapter.accounts.bot2]
token = "your_bot2_token" # 第二のロボットのtoken
webhook_path = "/webhook/bot2" # 独自のwebhookパス
enabled = true
設定項目の説明:
token:Yunhuプラットフォームが提供するAPI token(必須)mode:受信モード(オプション、デフォルトは"ws"、"ws"または"webhook"可)webhook_path:Yunhuイベントを受け取るHTTPパス(オプション、デフォルトは"/webhook"、webhookモードのみ使用)enabled:このアカウントを有効にするかどうか(オプション、デフォルトはtrue)
重要な注意点:
- YunhuプラットフォームのロボットIDは実行時に自動検出され、設定に指定する必要はない
- webhookモードでは、各botに独立した
webhook_pathが必要で、独自のwebhookイベントを受け取れる - Yunhuプラットフォームでwebhookを設定する際、各botに該当するURLを設定する必要があります。例えば:
- Bot1:
https://your-domain.com/webhook/bot1 - Bot2:
https://your-domain.com/webhook/bot2
- Bot1:
Send DSLを使用してBotを指定
Using()メソッドを使用して、どのbotを使ってメッセージを送信するかを指定できる。このメソッドは2つのパラメータをサポートする:
- アカウント名:設定中のbot名(例:
bot1,bot2) - bot_id:設定中の
bot_id値
from ErisPulse.Core import adapter
yunhu = adapter.get("yunhu")
# アカウント名を使ってメッセージを送信
await yunhu.Send.Using("bot1").To("user", "user123").Text("Hello from bot1!")
# bot_idを使ってメッセージを送信(自動的に対応するアカウントにマッチ)
await yunhu.Send.Using("30535459").To("group", "group456").Text("Hello from bot!")
# 指定しない場合は最初に有効なbotを使用
await yunhu.Send.To("user", "user123").Text("Hello from default bot!")
ヒント:
bot_idを使用する場合、システムは設定の中で一致するアカウントを自動的に検索します。これはイベントの返信時に特に便利で、event["self"]["user_id"]を使用して同じアカウントに返信することができます。
イベント内のBot識別子
受信したイベントには、対応するbot_id情報が自動的に含まれます(4.6.2以降、内部アカウント名 self.account_id も注入):
from ErisPulse.Core.Event import message
@message.on_message()
async def handle_message(event):
if event["platform"] == "yunhu":
# 送信元のロボットIDを取得
bot_id = event["self"]["user_id"]
account_id = event["self"].get("account_id", "") # 内部アカウント名(例: bot1)
print(f"メッセージはBot: {bot_id}(アカウント: {account_id})から来ました")
# 4.6.2以降、event.reply()は受理アカウントに自動的にルーティングされるので、直接返信できます
await event.reply("返信メッセージ")
# まだ明示的にアカウントを指定して送信することもできます
yunhu = adapter.get("yunhu")
await yunhu.Send.Using(bot_id).To(
event["detail_type"],
event["user_id"] if event["detail_type"] == "private" else event["group_id"]
).Text("返信メッセージ")
ヒント:
call_apiは、account_id(標準名)と_account_id(旧名)の両方のアカウントフィールドをサポートしており、フレームワークの ApiDSL のUsing()とイベントアカウントのバックアップ(send_context)は自動的に適応されます。
ログ情報
アダプターはログに自動的に bot_id 情報を含め、デバッグや追跡に便利です。
[INFO] [yunhu] [bot:30535459] ユーザー user123 からのプライベートチャットメッセージを受け取りました
[INFO] [yunhu] [bot:12345678] メッセージ送信成功、message_id: abc123
管理インターフェース
# すべてのアカウント情報を取得
bots = yunhu.bots
# アカウントの有効状態を確認
bot_status = {
bot_name: bot_config.enabled
for bot_name, bot_config in yunhu.bots.items()
}
# アカウントの有効/無効を動的に変更(アダプターの再起動が必要)
yunhu.bots["bot1"].enabled = False
旧設定の互換性
旧版の [Yunhu_Adapter.bots.*] 設定(bot_idフィールドを含む)は accounts 形式に自動的に移行されます(bot_idは実行時に自動検出され、設定の値は無視されます)。新しい形式への移行を推奨します。