互動會話系統
Tip
何時需要閱讀本文:需要使用 wait_reply、多輪對話、定時提醒、會話互斥或鏈路追蹤時。若不需要則可跳過,這不會影響其他功能的使用。
閱讀本文後你將了解:
wait_reply的完整參數用法與取消原因、.got()聲明式多輪鏈、 會話定時器(remind / escalate)、多路等待(expect / select)與會話互斥租約。本文未涵蓋:多輪對話的分支狀態機與重啟恢復(請見Conversation 多輪對話); 收件箱保留策略旋鈕與執行時覆蓋(請見會話收件箱)。
Note
本章內容需要 ErisPulse **2.8.0+**。
ErisPulse 將「與使用者的持續互動」建構為框架級基礎設施:從一條 wait_reply,
到定時提醒、多路等待、會話互斥、重啟恢復,全部由統一的
互動會話管理器(Core/Event/interaction.py,sdk.interaction)調度。
{!--< tips >!--} 本文涵蓋的每一項能力都附帶歸屬(owner):互動等待、租約、定時器全部記錄 註冊時的模組名,模組卸載 / 适配器關閉時由框架自動清理,等待方立即得到通知 而非干等超時——這是歸屬權系統在互動維度的延伸(請見 歸屬權系統)。 {!--< /tips >!--}
等待回覆:wait_reply
簡介:掛起當前協程,等待目標用戶的下一個消息,命中則返回回覆事件,超時或被取消則返回 None,pattern / regex / validator 可過濾不合格的回覆。
wait_reply 是交互會話的基石——掛起當前協程,等待目標用戶在下一個消息中「回覆」。
from ErisPulse.Core.Event import command
@command("ask")
async def ask_command(event):
reply = await event.wait_reply(prompt="請輸入你的名字:", timeout=30)
if reply is None:
await event.reply("超時了")
return
await event.reply(f"你好,{reply.get_text()}!")
全參數一覽
| 參數 | 說明 | 預設值 |
|---|---|---|
prompt |
掛起前發送的提示訊息 | None |
timeout |
等待超時(秒) | 60 |
pattern |
glob 過濾(* / ? / [seq]),不匹配則繼續等待 |
None |
regex |
正則過濾(與 pattern 同時設定時須都匹配),不匹配則繼續等待 | None |
validator |
校驗函數(接收 Event,返回 bool),失敗則繼續等待 | None |
callback |
收到回覆時的回調(替代回傳值式的一種寫法) | None |
method |
prompt 的發送方法 | "Text" |
session |
會話級等待:同會話(群 / 頻道)中任何人的回覆均可命中 | False |
# 只接受數字金額,否則繼續等
reply = await event.wait_reply("請輸入金額:", regex=r"\d+\s*元", timeout=30)
# 會話級等待:群協作場景,任何群友回答均可
reply = await event.wait_reply(session=True, prompt="哪位大神幫忙答一下?")
等待與命令的邊界(命令穿透)
等待期間收到已註冊命令(如 /cancel)的訊息時,預設放行給命令分發器執行、
不作為回覆消費(設定項 ErisPulse.event.wait_reply.cmdpass,True 則反轉——
訊息一律作為回覆)。判定文字口徑與命令分發一致:alt_message 優先、
缺失時回退訊息段拼接(2.10.1 起純 message 段適配器同樣生效)。
等待何時會被取消
等待不再是「只能等超時」——以下情況會讓等待立即終止(wait_reply 返回 None),
而不是讓呼叫方一直等到超時:
| 觸發 | 取消原因(InteractionCancelled.reason) |
說明 |
|---|---|---|
| 歸屬模組被卸載 / 禁用 | owner_unload |
歸屬清理:誰註冊的等待,誰消失時一併回收 |
| 適配器關閉 / 重啟 | platform_stop |
該平台掛起的等待全部取消 |
| 同會話被新的等待 / 租約取代 | conflict |
見下方「會話仲裁」 |
| 回覆者被拉黑 / owner 模組被解綁 | revoked |
回覆命中的權限复查:scope 身份維度 + 模組維度 |
| 用戶回覆命中 | —— | 正常路徑,返回回覆事件 |
底層異常為 InteractionCancelled(掛在 InteractionError 異常體系下),
wait_reply 已將其轉換為返回 None;需要原因的呼叫方可直接使用
sdk.interaction.register() 低層 API。
回覆命中的完整判定鏈
一條回覆訊息到達時,交互管理器按以下順序判定(在命令匹配之前執行, 對話連續性優先——即使訊息已被其他高優先級處理器認領,掛起的對話也能完成):
會話鍵命中(精確 user 維度 → 會話級回退)
→ pattern / regex 文本過濾(不匹配則繼續等)
→ validator 校驗(失敗則繼續等)
→ 權限复查(scope 身份維度 + owner 模組維度,失敗則終止等待)
→ 喚醒等待方 + 認領事件(mark_processed)
聲明式多輪:.got() 鏈(2.11+)
@command 返回多輪流控代理,用 .got() 逐步聲明收集步驟——步驟函數按
參數名接收已收集的值(含命令入口參數),類型跟隨 type= / 注解自動解析。
底層編譯到 Conversation:每步一個分支、跳轉自動保存檢查點,重啟後使用者
回覆會從存檔步驟繼續(恢復工廠在裝飾期自動註冊,隨模組卸載自動註銷)。
@command("weather")
async def weather(event):
pass # 入口:首個 .got 的 prompt 會自動發送,無需手動提問
@weather.got("city", prompt="請直接回覆城市名")
async def weather_city(event, city: str):
await event.reply(f"{city}:晴,25℃")
@weather.got("days", prompt="預報幾天?", type=int, retry_prompt="請輸入數字")
async def weather_days(event, city: str, days: int):
await event.reply(f"{city} 未來 {days} 天……")
參數說明
| 參數 | 說明 |
|---|---|
name |
收集值名稱(注入後續步驟函數的參數名;流程內唯一,重複聲明註冊期報錯) |
prompt |
進入該步驟時自動發送的提問 |
timeout |
單步等待超時(秒數或 "90s" / "1h30m" 時長串,預設 60s) |
type |
值類型(int / float / str…;解析失敗自動重發 retry_prompt,最多 max_retries 次) |
validator / pattern / regex |
回覆過濾與校驗(語義與 wait_reply 一致) |
session |
會話級等待(同會話任何人可命中) |
cmdpass |
命令放行三態(預設 /cancel 等命令在等待期間照常執行) |
語義與邊界
- 任一步超時 / 被打斷 → 整條流程結束並清除檢查點(與
wait_reply語義一致); 步驟函數內可隨時event.reply(...)輸出中間結果 - 同一使用者同時只能有一條掛起互動——第二個流程的等待會頂掉前一個
(
InteractionCancelled("conflict"));需要互斥提示請配合 會話租約 - 收集值僅存在於流程內;需要跨重啟攜帶複雜狀態的編排請直接使用
Conversation(
context+branch/goto+ 手動檢查點) @command返回的是代理物件:呼叫行為、__name__、docstring、自定義屬性 與原函數完全一致;command.unregister(代理)自動解包
會話定時器:remind / escalate
把「超時」從回傳值變成可編排的原語。定時器掛在互動會話上, 隨模組卸載 / 適配器關閉自動取消,單會話活躍 remind 上限 5 個。
remind:沒回覆就提醒
@command("ticket")
async def ticket_command(event):
await event.reply("工單已提交,處理結果會在這裡通知")
# 5 分鐘無回覆則溫和催一次;使用者任何回覆都會自動取消它
event.remind(300, "還在嗎?有結果了會第一時間告訴你")
reply = await event.wait_reply(timeout=3600)
...
event.remind(delay, text=None, *, callback=None):到期向當前會話發送text(或執行callback(event),支援同步 / 異步)。強制校驗:text與callback必須二選一(都不給拋ValueError)- 返回
Reminder句柄:reminder.cancel()手動取消、reminder.expired查詢狀態 - 使用者在該會話回覆後自動取消——這正是「提醒」語義: 提醒只在使用者沉默時出現
Conversation內同樣可用:conv.remind(120, "還在考慮嗎?")
escalate:到點必達的升級
event.escalate(1800, lambda e: notify_master(f"工單 30 分鐘未處理:{event.get_command_args()}"))
與 remind 的唯一區別:不被使用者回覆取消——升級動作(通知主人、轉人工)
是「超時必達」承諾,僅手動 cancel() / 模組卸載 / 適配器關閉才取消。
remind |
escalate |
|
|---|---|---|
| 到期行為 | 發文字 / 執行 callback | 執行 callback |
| 使用者回覆 | 自動取消 | 不受影響 |
| 歸屬清理(卸載 / 關平台) | 取消 | 取消 |
| 單會話上限 | 5 | 不限(隨歸屬清理兜底) |
多路等待:expect + select
一句話:expect 只描述期望而不註冊等待,select 綜合掛起多條期望,任一先命中即返回 (下標, 回覆事件),未命中的自動清理。
同時掛起多條期望,先到先得——典型場景:等待管理員審批的同時等待使用者撤回、多人協作投票。
which, reply = await event.select(
event.expect(pattern="同意*", user="10001"),
event.expect(pattern="拒絕*", user="10002"),
event.expect(validator=lambda e: e.get_text() == "擱置", session=True),
timeout=60,
)
if which is None:
await event.reply("60 秒內未收到任何審批結果")
elif which == 0:
await event.reply("已同意")
elif which == 1:
await event.reply("已拒絕")
event.expect(...)構造期望描述(不註冊任何等待):支援pattern/regex/validator/user(限定回覆者)/session(任何人可答)event.select(*expectations, timeout=60):統一註冊 → 任一命中即返回(下標, 回覆事件)→ 未命中的等待自動取消;全部超時返回(None, None)。 強制校驗:至少傳入一條 expectation,否則拋ValueError- 命中的事件已被框架認領(
mark_processed),不會被其他處理器重複消費
{!--< tips >!--}
select 與多線程 asyncio.wait 手工編排相比:期望未命中時自動清理、
命中事件自動認領、權限复查與歸屬清理全部生效——不需要自己管任何 Future。
{!--< /tips >!--}
Note
2.10.1 起 select 為聚合等待:全部期望合併為單條目 + 自定義命中判定,
同鍵多路(如同一 user 掛兩條不同 pattern)不再互相取消,任一路先命中即返回。
回覆文本的判定口徑為 alt_message 优先 + 消息段回退(與命令分發一致)。
边界說明:event.wait_for(...) 直掛在適配器事件總線上,不經過中間件與
detail_type 條件過濾(身份准入由分發入口兜底);需要完整管線的等待請用
wait_reply / select。
會話互斥:acquire / hold / get_owner_of
歸屬權從「資源」走向「會話」——「這個使用者目前正被誰佔用」成為一等查詢。
# 查詢:這個會話正被誰互動?(空閒返回 None)
owner = sdk.interaction.get_owner_of(event)
if owner and owner != "MyModule":
return # 其他模組正在對話中,避免打擾
# 互斥租約:獨佔會話(deny 策略,被佔用返回 None)
lease = sdk.interaction.acquire(event) # 預設 TTL 1 小時,可傳 ttl=
if lease is None:
return # 已被佔用
try:
... # 獨佔互動
finally:
lease.release()
上下文管理器形式(獲取失敗拋 SessionOccupiedError):
with sdk.interaction.hold(event) as lease:
... # 退出自動釋放
租約支援 renew(ttl) 續期;TTL 慢性過期——過期的租約在下次訪問時自動清理。
Conversation.resume() 恢復對話時框架會自動 acquire 租約(見
Conversation 多輪對話的「恢復即接管」)——
恢復的對話天然持有會話,其他模組不會插入。
會話收件箱:event.history
保留策略(7 天 / 條數上限)與運行時覆蓋 API、風險與審計見會話收件箱專題。
每會話近期訊息流的統一記錄(使用者 + 機器人雙方),作為 AI 上下文、 防重複、行為分析類模組的共享事實底座——各模組不再各自存歷史。
messages = await event.history(20) # 當前會話最近 20 條,時間升序
for m in messages:
print(m["role"], ":", m["text"]) # role: "user" / "bot"
- 自動記錄:入站訊息(role=user)+ 機器人出站文字(role=bot)
- 存儲:獨立 SQLite 表,保留策略 = 每會話上限(預設 50)+ 全局 TTL(預設 7 天)
- 寫入方式:記憶體緩衝 + 後台批量落盤(延遲至多 1 秒),查詢介面自動合併未落盤的緩衝行——同進程「讀你的寫」不受影響;正常退出(
sdk.uninit/ 進程退出)自動刷盤。硬崩潰 / 強殺時最近約 1 秒的記錄可能遺失:該底座定位為近期上下文緩存,不適合作為審計級持久化 - 配置:
ErisPulse.transcript = {enabled = true, max_per_session = 50, ttl_hours = 168} - 管理器 API:
sdk.transcript.append() / get() / clear(),aflush()/flush()手動刷盤
消息事務:message_tx
事務內的所有出站發送自動記帳;異常退出時逆序自動撤回已發送的消息
(適配器未實作 delete_message 時跳過,帳本仍正常記錄)。
async with event.message_tx():
await event.reply("正在處理,請稍候")
result = await do_something() # 這裡拋異常 →
await event.reply(f"完成: {result}") # 前面的"處理中"自動撤回
事務外發送不記帳(零開銷);事務內隨時可讀回執帳本,典型用途是自刪機器人
(發出即安排延時撤回)與發送審計:
import asyncio
from ErisPulse.runtime import get_send_receipts
async def delayed_delete(adapter, message_id: str, delay: float):
await asyncio.sleep(delay)
await adapter.delete_message(message_id)
async with event.message_tx():
await event.reply("臨時提示")
for r in get_send_receipts() or []:
# 每條回執含 platform / bot_id / message_id / trace_id
asyncio.create_task(delayed_delete(adapter, r["message_id"], 30))
回執讀取是事務作用域的:僅在 message_tx() 事務內返回非 None,
事務外恆為 None;需要捕獲全部出站(含事務外)請用 message.sending/sent
鉤子(見鏈路追蹤的 trace_id 字段)。
鏈路追蹤:trace-id
每個入站事件自動獲得追蹤 ID(複用 event["id"],缺失則生成),貫穿:
- handler 上下文(
get_current_trace_id()讀取) - 出站發送(
[Send]日誌行附加[trace:...],message.sending/sent鉤子的trace_id字段) - 生命週期鉤子資料(dict 自動補
_trace_id) - 定向事件(
lifecycle.emit(..., to=...))與訊息事務回執
一條訊息被多個模組接力處理時,全鏈路可用同一 ID 串聯(日誌 / 慢查詢 / 審計)。
與其他系統的關係
- 歸屬權:等待 / 租約 / 定時器全部記錄 owner,卸載即回收(歸屬權系統)
- 作用域:回覆命中复查身份 + 模組維度;跨模組呼叫審計走出站維度(作用域)
- Conversation:多輪對話是互動會話之上的分支狀態機(Conversation), 其等待同樣享有本頁全部取消 / 复查 / 归属语义
相關文件
- Conversation 多輪對話 - 分支狀態機、自動檢查點與重啟恢復
- 歸屬權(owner)系統 - 歸屬清理的全景與設計邊界
- 作用域(scope) - 權限复查與出站審計的配置方式
- 模組間通信 - 跨模組呼叫與定向事件