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

ErisPulse 會話類型標準

Tip

何時需要閱讀本文:當你在適配器中將平台原生會話映射到標準類型(private/group/channel/guild/thread),或在模組中不確定 Send.To() 應傳入什麼目標類型、想釐清 event.reply() 的自動轉換時對照本文。不需要則跳過。

本文檔定義了 ErisPulse 支援的會話類型標準,包括接收事件類型和發送目標類型。

1. 核心概念

1.1 接收類型 && 發送類型

ErisPulse 區分兩種會話類型:

  • 接收類型(Receive Type):用於接收的事件的 detail_type 欄位
  • 發送類型(Send Type):用於發送訊息時 Send.To() 方法的目標類型

1.2 類型對應關係

接收類型 (detail_type)     發送類型 (Send.To)
─────────────────        ────────────────
private                 →        user
group                   →        group
channel                 →        channel
guild                   →        guild
thread                  →        thread
user                    →        user

關鍵點:

  • private 是接收時的類型,發送時的標準類型是 user
  • group、channel、guild、thread 在接收和發送時類型相同
  • 推薦路徑:直接使用 event.reply()——自動完成類型轉換與目標推斷,無需手動處理(private → user 的自動轉換即在此發生)
  • 手動發送時:請直接傳發送類型(如 Send.To("user", ...));手動 Send.To("private", ...) 傳接收類型雖也能被自動轉換,但不推薦(見 §6.1)

2. 標準會話類型

2.1 OneBot12 標準類型

private

  • 接收類型:private
  • 發送類型:user
  • 說明:一對一私聊訊息
  • ID 欄位:user_id
  • 適用平台:所有支援私聊的平台

group

  • 接收類型:group
  • 發送類型:group
  • 說明:群聊訊息,包括各種形式的群組(如 Telegram supergroup)
  • ID 欄位:group_id
  • 適用平台:所有支援群聊的平台

user

  • 接收類型:user
  • 發送類型:user
  • 說明:使用者類型,某些平台(如 Telegram)將私聊表示為 user 而非 private
  • ID 欄位:user_id
  • 適用平台:Telegram 等平台

2.2 ErisPulse 擴展類型

channel

  • 接收類型:channel
  • 發送類型:channel
  • 說明:頻道訊息,支援多個使用者的廣播式訊息
  • ID 欄位:channel_id
  • 適用平台:Discord, Telegram, Line 等

guild

  • 接收類型:guild
  • 發送類型:guild
  • 說明:伺服器/社群訊息,通常用於 Discord Guild 級別的事件
  • ID 欄位:guild_id
  • 適用平台:Discord 等

thread

  • 接收類型:thread
  • 發送類型:thread
  • 說明:主題/子頻道訊息,用於社群中的子討論區
  • ID 欄位:thread_id
  • 適用平台:Discord Threads, Telegram Topics 等

3. 平台類型映射

3.1 映射原則

適配器負責將平台的原生類型映射到 ErisPulse 標準類型:

平台原生類型 → ErisPulse 標準類型 → 發送類型

3.2 常見平台映射示例

Telegram

Telegram 類型          ErisPulse 接收類型    發送類型
─────────────────      ────────────────       ───────────
private                private                 user
group                  group                   group
supergroup             group                   group  # 映射到 group
channel                channel                 channel

Discord

Discord 類型          ErisPulse 接收類型    發送類型
─────────────────      ────────────────       ───────────
Direct Message         private                user
Text Channel           channel                channel
Guild                  guild                  guild
Thread                 thread                 thread

OneBot11

OneBot11 類型        ErisPulse 接收類型    發送類型
─────────────────      ────────────────       ───────────
private                private                user
group                  group                  group
discuss                group                  group  # 映射到 group

4. 自訂類型擴展

4.1 註冊自訂類型

適配器可以註冊自訂會話類型:

from ErisPulse.Core.Event import register_custom_type

# 註冊自訂類型
register_custom_type(
    receive_type="my_custom_type",
    send_type="custom",
    id_field="custom_id",
    platform="MyPlatform"
)

4.2 使用自訂類型

註冊後,系統會自動處理該類型的轉換和推斷:

# 自動推斷
receive_type = infer_receive_type(event, platform="MyPlatform")
# 返回: "my_custom_type"

# 轉換為發送類型
send_type = convert_to_send_type(receive_type, platform="MyPlatform")
# 返回: "custom"

# 獲取對應ID
target_id = get_target_id(event, platform="MyPlatform")
# 返回: event["custom_id"]

4.3 解除註冊自訂類型

from ErisPulse.Core.Event import unregister_custom_type

unregister_custom_type("my_custom_type", platform="MyPlatform")

5. 自動類型推斷

當事件沒有明確的 detail_type 欄位時,系統會根據存在的 ID 欄位自動推斷類型:

Note


2.7.0+ 行為變更:detail_type 只有在是已知會話類型(標準或自定義)時才直接採用。notice/request 事件的 detail_type(如 group_member_increase、friend_increase)是語義子類型而非會話類型,會轉而根據 ID 欄位推斷正確的會話類型。

5.1 推斷優先級

優先級(從高到低):
1. group_id     → group
2. channel_id   → channel
3. guild_id     → guild
4. thread_id    → thread
5. user_id      → private

5.2 使用範例

# 事件只有 group_id
event = {"group_id": "123", "user_id": "456"}
receive_type = infer_receive_type(event)
# 返回: "group"(優先使用 group_id)

# 事件只有 user_id
event = {"user_id": "123"}
receive_type = infer_receive_type(event)
# 返回: "private"

# notice 事件的 detail_type 是語義子類型,2.7.0+ 會從 ID 欄位推斷
event = {"type": "notice", "detail_type": "group_member_increase", "group_id": "123"}
receive_type = infer_receive_type(event)
# 返回: "group"(而非 "group_member_increase")

6. API 使用示例

6.1 發送訊息

from ErisPulse import adapter

# 發送給使用者
await adapter.myplatform.Send.To("user", "123").Text("Hello")

# 發送給群組
await adapter.myplatform.Send.To("group", "456").Text("Hello")

# 自動轉換 private → user:手動傳遞接收類型屬不推薦寫法(可能有相容性問題)
await adapter.myplatform.Send.To("private", "789").Text("Hello")
# 內部自動轉換為: Send.To("user", "789")
# 推薦做法:手動發送時直接用發送類型 user,或用 event.reply() 自動完成轉換(見 6.2)

6.2 事件回覆

from ErisPulse.Core.Event import Event

# Event.reply() 自動處理類型轉換(推薦路徑)
await event.reply("回覆內容")
# 內部自動使用正確的發送類型(private → user 等轉換在此自動完成)

6.3 命令處理

from ErisPulse.Core.Event import command

@command(name="test")
async def handle_test(event):
    # 系統自動處理會話類型
    # 無需手動判斷 group_id 還是 user_id
    await event.reply("命令執行成功")

7. 核心 API 參考

7.1 類型轉換

from ErisPulse.Core.Event import convert_to_send_type, convert_to_receive_type

# 接收類型 → 發送類型
convert_to_send_type("private")  # → "user"
convert_to_send_type("group")    # → "group"

# 發送類型 → 接收類型
convert_to_receive_type("user")   # → "private"
convert_to_receive_type("group")  # → "group"

7.2 ID 欄位查詢

from ErisPulse.Core.Event import get_id_field, get_receive_type

get_id_field("group")    # → "group_id"
get_id_field("private")  # → "user_id"

get_receive_type("group_id")  # → "group"
get_receive_type("user_id")   # → "private"

7.3 一步獲取發送資訊

from ErisPulse.Core.Event import get_send_type_and_target_id

event = {"detail_type": "private", "user_id": "123"}
send_type, target_id = get_send_type_and_target_id(event)
# send_type = "user", target_id = "123"

# 直接用於 Send.To()
await adapter.Send.To(send_type, target_id).Text("Hello")

7.4 獲取目標 ID

from ErisPulse.Core.Event import get_target_id

event = {"detail_type": "group", "group_id": "456"}
get_target_id(event)  # → "456"

8. 工具方法

from ErisPulse.Core.Event import (
    is_standard_type,
    is_valid_send_type,
    get_standard_types,
    get_send_types,
    clear_custom_types,
)

is_standard_type("private")     # True
is_standard_type("custom_type") # False

is_valid_send_type("user")      # True
is_valid_send_type("invalid")   # False

get_standard_types()  # {"private", "group", "channel", "guild", "thread", "user"}
get_send_types()      # {"user", "group", "channel", "guild", "thread"}

clear_custom_types()                # 清除所有
clear_custom_types(platform="discord")  # 只清除指定平台的

9. 最佳實踐

7.1 適配器開發者

  1. 使用標準映射:盡可能映射到標準類型,而不是創建新類型
  2. 正確轉換:確保接收類型和發送類型的映射關係正確
  3. 保留原始數據:在 {platform}_raw 中保留原始事件類型
  4. 文檔說明:在適配器文檔中說明類型映射關係

7.2 模塊開發者

  1. 使用工具方法:使用 get_send_type_and_target_id() 等工具方法
  2. 避免硬編碼:不要寫 if group_id else "private" 這樣的代碼
  3. 考慮所有類型:代碼要支持所有標準類型,不僅僅是 private/group
  4. 靈活設計:使用事件包裝器的方法,而不是直接訪問字段

7.3 類型推斷

  • 優先使用 detail_type:如果有明確字段,不進行推斷
  • 合理使用推斷:只有在沒有明確類型時才使用
  • 注意優先級:了解推斷優先級,避免意外結果

10. 常見問題

Q1: 為什麼發送時 private 要轉換為 user?

A: 這是 OneBot12 標準的要求。private 是接收時的概念,發送時使用 user 更符合語義。

Q2: 如何支援新的會話類型?

A: 透過 register_custom_type() 註冊自定義類型,或直接使用標準類型中的 channel、guild 等。

Q3: 事件沒有 detail_type 怎麼辦?

A: 系統會根據存在的 ID 欄位自動推斷。優先級為:group > channel > guild > thread > user。

Q4: 適配器如何映射 Telegram supergroup?

A: 在適配器的轉換邏輯中,將 supergroup 映射為標準的 group 類型。

Q5: 郵箱等特殊平台如何處理?

A: 對於不通用或平台特有的類型,使用 {platform}_raw 和 {platform}_raw_type 保留原始數據,適配器自行處理。

11. 相關文件

適配器側(映射與轉換):

模組側(不想手動處理類型轉換):