ErisPulse ErisPulse
在互動式文檔中心打開 →
本頁章節
本文為靜態鏡像,內容以互動版為準 在互動式文檔中心打開 →

事件系統 API

Tip

什麼時候需要閱讀這篇:當你需要註冊命令、監聽訊息/通知/請求事件,或使用 event.reply() / wait_reply() / confirm() 等事件互動方法時查閱本文。不需要則跳過。

本文檔詳細介紹了 ErisPulse 事件系統的 API。

事件系統將平台事件按類型分發到五類處理器:

flowchart LR
    A["平台事件<br/>(OneBot12 標準)"] --> B{"事件類型"}
    B --> C["command<br/>命令處理器"]
    B --> D["message<br/>訊息處理器"]
    B --> E["notice<br/>通知處理器"]
    B --> F["request<br/>請求處理器"]
    B --> G["meta<br/>元事件處理器"]
    C & D & E & F & G --> H["Event 包裝類<br/>reply / get_text / done 等"]

Command 命令模組

註冊命令

from ErisPulse.Core.Event import command

# 基本命令
@command("hello", help="發送問候")
async def hello_handler(event):
    await event.reply("你好!")

# 帶別名的命令
@command(["help", "h"], aliases=["幫助"], help="顯示幫助")
async def help_handler(event):
    pass

# 帶權限的命令
def is_admin(event):
    return event.get("user_id") in admin_ids

@command("admin", permission=is_admin, help="管理員命令")
async def admin_handler(event):
    pass

# 隱藏命令
@command("secret", hidden=True, help="秘密命令")
async def secret_handler(event):
    pass

# 命令組
@command("admin.reload", group="admin", help="重新載入模組")
async def reload_handler(event):
    pass

# 子命令(空格分隔的多 token 命令名)
# 匹配採用最長前綴:/admin add x 優先命中 admin add(args 為 ["x"]);
# 子命令未聲明 permission 時繼承父鏈上最近聲明權限的祖先命令
@command("admin add", help="新增管理員")
async def admin_add_handler(event):
    pass

命名衝突規則:命令名優先於別名。註冊與既有命令重名的別名時該別名不生效並輸出 警告;註冊與既有別名重名的命令時命令名優先生效、死別名自動移除——兩類衝突均有 WARNING 日誌,不會靜默劫持。

命令資訊

所有命令查詢 API 均支援可選的會話上下文:傳 event=(Event 或 dict)或 顯式 platform= / bot_id= / session_id=(與 event 叠加時顯式參數優先), 即按作用域模組維度過濾當前會話不可用模組的命令(詳見 advanced/scope.md); 全部為可選關鍵字參數,不傳時保持原有全量行為。

# 獲取命令幫助
help_text = command.help()

# 會話感知幫助:只列出當前會話可用的命令
help_text = command.help(event=event)

# 獲取特定命令(返回合併覆蓋後的生效參數;會話不可用時返回 None)
cmd_info = command.get_command("admin")
cmd_info = command.get_command("admin", event=event)

# 獲取所有命令(會話感知時過濾不可用模組的命令)
all_commands = command.get_commands()
all_commands = command.get_commands(event=event)

# 獲取命令組中的所有命令(支援會話感知過濾)
admin_commands = command.get_group_commands("admin")
admin_commands = command.get_group_commands("admin", event=event)

# 獲取所有可見命令
visible_commands = command.get_visible_commands()

# 會話感知的可見命令(event 或顯式關鍵字任一即可)
visible_commands = command.get_visible_commands(event=event)
visible_commands = command.get_visible_commands(
    platform=event.get("platform"),
    bot_id=event.get_self_account_id(),
    session_id=event.get_session_id(),
)

等待回覆

# 等待使用者回覆
@command("ask", help="詢問使用者資訊")
async def ask_command(event):
    reply = await command.wait_reply(
        event,
        prompt="請輸入你的名字:",  # 已在上面發送
        timeout=30.0
    )
    
    if reply:
        name = reply.get_text()
        await event.reply(f"你好,{name}!")

# 帶驗證的等待回覆
def validate_age(event_data):
    try:
        age = int(event_data.get_text())
        return 0 <= age <= 150
    except ValueError:
        return False

@command("age", help="詢問使用者年齡")
async def age_command(event):
    await event.reply("請輸入你的年齡:")
    
    reply = await command.wait_reply(
        event,
        timeout=60,
        validator=validate_age
    )
    
    if reply:
        age = int(reply.get_text())
        await event.reply(f"你的年齡是 {age} 歲")

# 帶回調的等待回覆
async def handle_confirmation(reply_event):
    text = reply_event.get_text().lower()
    if text in ["是", "yes", "y"]:
        await event.reply("操作已確認!")
    else:
        await event.reply("操作已取消。")

@command("confirm", help="確認操作")
async def confirm_command(event):
    await command.wait_reply(
        event,
        prompt="請輸入'是'或'否':",
        callback=handle_confirmation
    )

Message 訊息模組

訊息事件

from ErisPulse.Core.Event import message

# 監聽所有訊息
@message.on_message()
async def message_handler(event):
    sdk.logger.info(f"收到訊息: {event.get_text()}")

# 監聽私聊訊息
@message.on_private_message()
async def private_handler(event):
    user_id = event.get_user_id()
    sdk.logger.info(f"私聊來自: {user_id}")

# 監聽群聊訊息
@message.on_group_message()
async def group_handler(event):
    group_id = event.get_group_id()
    sdk.logger.info(f"群聊來自: {group_id}")

# 監聽@訊息
@message.on_at_message()
async def at_handler(event):
    mentions = event.get_mentions()
    sdk.logger.info(f"被@的使用者: {mentions}")

條件監聽

# 使用優先級控制執行順序
@message.on_message(priority=10)  # 數值越大優先級越高
async def high_priority_handler(event):
    pass

# 在處理器內部實現條件過濾
@message.on_message()
async def filtered_handler(event):
    if "關鍵詞" not in event.get_text():
        return
    # 處理包含關鍵詞的訊息
    pass

Notice 通知模組

通知事件

from ErisPulse.Core.Event import notice

# 好友新增
@notice.on_friend_add()
async def friend_add_handler(event):
    user_id = event.get_user_id()
    await event.reply("歡迎新增我為好友!")

# 好友刪除
@notice.on_friend_remove()
async def friend_remove_handler(event):
    user_id = event.get_user_id()
    sdk.logger.info(f"好友刪除: {user_id}")

# 群成員增加
@notice.on_group_increase()
async def member_increase_handler(event):
    user_id = event.get_user_id()
    await event.reply(f"歡迎新成員!")

# 群成員減少
@notice.on_group_decrease()
async def member_decrease_handler(event):
    user_id = event.get_user_id()
    sdk.logger.info(f"群成員離開: {user_id}")

Request 請求模組

請求事件

from ErisPulse.Core.Event import request

# 好友請求
@request.on_friend_request()
async def friend_request_handler(event):
    user_id = event.get_user_id()
    comment = event.get_comment()
    sdk.logger.info(f"好友請求: {user_id}, 備註: {comment}")

# 群邀請請求
@request.on_group_request()
async def group_request_handler(event):
    group_id = event.get_group_id()
    user_id = event.get_user_id()
    sdk.logger.info(f"群邀請: {group_id}, 來自: {user_id}")

Meta 元事件模組

元事件

from ErisPulse.Core.Event import meta

# 連接事件
@meta.on_connect()
async def connect_handler(event):
    platform = event.get_platform()
    sdk.logger.info(f"平台 {platform} 連接成功")

# 斷開連接事件
@meta.on_disconnect()
async def disconnect_handler(event):
    platform = event.get_platform()
    sdk.logger.info(f"平台 {platform} 斷開連接")

# 心跳事件
@meta.on_heartbeat()
async def heartbeat_handler(event):
    sdk.logger.debug("收到心跳")

Bot 狀態查詢

當適配器發送 meta 事件後,框架會自動追蹤 Bot 狀態。查詢 API 和生命週期事件監聽請參考 適配器系統 API - Bot 狀態管理。

Event 包裝類

Event 模組的事件處理器接收一個 Event 包裝類實例,它繼承自 dict 並提供了便捷方法。完整方法清單、參數簽名與行為以 Event 包裝類詳解 為準,本節僅作速覽。

能力速覽

  • 事件基礎資訊:get_id() / get_time() / get_type() / get_detail_type() / get_platform()
  • 機器人資訊:get_self_platform() / get_self_user_id() / get_self_account_id() / get_self_info()
  • 會話標識:get_target_id()(統一目標 ID,按 group_id → channel_id → guild_id → thread_id → user_id 取首個非空值);get_session_id()(格式 {platform}:{detail_type}:{target_id},如 "telegram:private:12345")
  • 訊息內容與發送者:get_message() / get_alt_message() / get_text() / get_user_id() / get_sender() / get_group_id() 等
  • 訊息類型判斷:is_message() / is_private_message() / is_group_message() / is_at_message() / has_mention() / get_mentions()
  • 回覆:reply(content, method=..., at_sender=..., quote=..., at_users=..., reply_to=..., at_all=..., via=...) / reply_ob12();平台能力查詢 supports() / available_methods();自由發送鏈 send_chain() 見 SendDSL 詳解
  • 命令資訊:get_command_name() / get_command_args() / is_command() 等
  • 互動會話:wait_reply() / confirm() / choose() / collect() / wait_for() / conversation()
  • 工具:to_dict()(過濾內部鍵)/ get_raw() / get_raw_type()

各方法的完整參數說明與範例見 Event 包裝類詳解; 多輪對話進階見 Conversation 多輪對話。

鏈路控制

event.done(claim=, stop=) 統一控制「認領」與「阻斷」兩個正交語義:

  • 認領(claim):標記事件已被處理(_processed),命令分發器據此跳過去重
  • 阻斷(stop):阻止向低優先級處理器傳播(_propagation_stopped)
# 認領 + 阻斷(預設)
event.done()

# 僅認領,不阻斷(低優先級觀察者仍能看到)
event.done(stop=False)

# 僅阻斷,不認領(如防火牆 / 限流)
event.done(claim=False)

# mark_processed 是主方法,done 是其別名
event.mark_processed()             # 等價 event.done()
event.mark_processed(stop=False)   # 等價 event.done(stop=False)

# 查詢狀態
event.is_processed()  # 是否已認領
event.is_stopped()    # 是否已阻斷傳播

平台擴展方法

適配器可以為 Event 註冊平台專有方法,僅在對應平台的實例上可用。

使用者:使用平台擴展方法

當適配器註冊了平台專有方法後,你可以在事件處理器中直接調用。各平台的方法不同,請參閱對應的 平台文件。

from ErisPulse.Core.Event import message

@message.on_message()
async def handle_message(event):
    platform = event.get_platform()

    # 根據平台調用專有方法
    if platform == "email":
        subject = event.get_subject()           # 郵件專有
        attachments = event.get_attachments()   # 郵件專有

查詢平台已註冊方法

from ErisPulse.Core.Event import get_platform_event_methods

# 查看某平台註冊了哪些方法
methods = get_platform_event_methods("email")
# ["get_subject", "get_from", "get_attachments", ...]

# 動態判斷並調用
for method_name in get_platform_event_methods(event.get_platform()):
    method = getattr(event, method_name)
    print(f"{method_name}: {method()}")

平台方法隔離

不同平台註冊的方法互不干擾:

# 郵件事件 - 只有郵件方法
event = Event({"platform": "email", "email_raw": {"subject": "Hello"}})
event.get_subject()      # ✅ "Hello"
event.get_chat_type()    # ❌ AttributeError

# Telegram 事件 - 只有 Telegram 方法
event = Event({"platform": "telegram", "telegram_raw": {"chat": {"type": "private"}}})
event.get_chat_type()    # ✅ "private"
event.get_subject()      # ❌ AttributeError

hasattr / dir 支援

hasattr(event, "get_subject")   # 僅當 platform="email" 時返回 True
"get_subject" in dir(event)     # 同上

適配器:註冊平台擴展方法

適配器可以透過裝飾器為 Event 註冊平台專有方法,方法的第一個參數為 self(Event 實例),可以自由存取事件資料。

單個方法註冊

from ErisPulse.Core.Event import register_event_method

@register_event_method("email")
def get_subject(self):
    """獲取郵件主旨"""
    return self.get("email_raw", {}).get("subject", "")

@register_event_method("email")
def get_from(self):
    """獲取寄件人"""
    return self.get("email_raw", {}).get("from", {})

批量註冊(Mixin 類)

當方法較多時,推薦使用 Mixin 類批量註冊:

from ErisPulse.Core.Event import register_event_mixin

class EmailEventMixin:
    def get_subject(self):
        return self.get("email_raw", {}).get("subject", "")

    def get_from(self):
        return self.get("email_raw", {}).get("from", {})

    def get_attachments(self):
        return self.get("email_raw", {}).get("attachments", [])

# 一次性註冊所有方法
register_event_mixin("email", EmailEventMixin)

回傳值規範

場景 回傳值 使用者使用方式
回傳資料(文字、字典等) 直接回傳值 subject = event.get_subject()
執行操作(發送訊息等) 回傳 asyncio.Task task = event.do_something() 可選 await

建議:非資料回傳的方法回傳 asyncio.Task,這樣使用者可以自行決定是否 await,即使不 await 操作也會執行完成。

@register_event_method("email")
def forward_email(self, to_address: str):
    """轉發郵件 — 回傳 Task,使用者可自行決定是否 await"""
    import asyncio
    return asyncio.create_task(
        self._do_forward(to_address)
    )

# 使用者可以 await 等待結果
await event.forward_email("[email protected]")

# 也可以不 await,操作在背景執行
event.forward_email("[email protected]")

注銷方法

from ErisPulse.Core.Event import unregister_event_method, unregister_platform_event_methods

# 注銷單個方法
unregister_event_method("email", "get_subject")

# 注銷某平台全部方法(適配器 shutdown 時呼叫)
unregister_platform_event_methods("email")

覆寫內建方法

register_event_mixin / register_event_method 支援覆寫 Event 內建方法(如 confirm、choose、collect、wait_reply、reply 等)。註冊的平台方法透過 Event.__getattribute__ 會優先於內建方法生效,因此適配器可以提供平台特色的互動實作。

內建實作作為 _builtin_* 函數導出,覆寫方可以呼叫它們作為回退:

from ErisPulse.Core.Event import register_event_mixin, _builtin_choose

class YunhuEventMixin:
    async def choose(self, prompt, options, timeout=60, method="Text"):
        # 云湖平台使用按鈕元件
        buttons = [[{"text": opt} for opt in options]]
        await self.reply(prompt)
        # ...等待按鈕回調或文字回覆...
        # 回退到內建邏輯
        return await _builtin_choose(self, None, options, timeout, "Text")

register_event_mixin("yunhu", YunhuEventMixin)

跨平台擴展(通配符)

register_event_method 和 register_event_mixin 支援傳 "*" 作為平台名,註冊的方法在所有平台的 Event 實例上都可用。適合 AI 對話、上下文管理等需要跨平台複用的功能模組。

註冊跨平台方法

from ErisPulse.Core.Event.wrapper import register_event_method

@register_event_method("*")
async def ai_chat(self, prompt: str):
    """self 為 Event 實例,可自由存取事件資料和內建方法"""
    await self.reply(f"AI: {prompt}")

註冊後,所有平台的事件處理器都能呼叫:

from ErisPulse.Core.Event import message

@message.on_message()
async def handler(event):
    await event.ai_chat(event.get_text())

方法解析優先級

透過屬性存取 Event 方法時,解析順序為:

  1. 平台特定方法(當前平台的覆寫)
  2. 通配符方法("*" 註冊的跨平台方法)
  3. 內建方法(reply、confirm 等)
  4. 字典鍵存取

因此通配符方法可以覆寫內建方法(如 reply),但會被同名的平台特定方法進一步覆寫。

優先級系統

事件處理器支援優先級,數值越大優先級越高:

# 高優先級處理器先執行
@message.on_message(priority=10)
async def high_priority_handler(event):
    pass

# 低優先級處理器後執行
@message.on_message(priority=0)
async def low_priority_handler(event):
    pass

相關文件

繼續查 API:

從範例學事件處理: