跳到主要内容

会话控制

在起步的 weather 插件中，我们使用依赖注入获取了机器人用户发送的地名参数，并根据地名参数进行相应的回复。但是，一问一答的对话模式仅仅适用于简单的对话场景，如果我们想要实现更复杂的对话模式，就需要使用会话控制。

询问并获取用户输入​

在 weather 插件中，我们对于用户未输入地名参数的情况直接回复了 请输入地名 并结束了事件流程。但是，这样用户体验并不好，需要重新输入指令和地名参数才能获取天气回复。我们现在来实现询问并获取用户地名参数的功能。

询问用户​

我们可以使用事件响应器操作中的 got 装饰器来表示当前事件处理流程需要询问并获取用户输入的消息：

@weather.handle()
async def handle_function(location: EventPlainText):
    if location:
        await weather.finish(f"今天{location}的天气是...")

@weather.got("location", prompt="请输入地名")
async def got_location():
    ...

在上面的代码中，我们使用 got 事件响应器操作来向用户发送提示消息 prompt，并等待用户的回复。用户的回复消息将会被作为 location 参数存储于事件响应器状态中。

提示

事件处理函数根据定义的顺序依次执行。

获取用户输入​

在询问以及用户回复之后，我们就可以获取到我们需要的 location 参数了。我们使用 ArgPlainText 依赖注入来获取参数纯文本信息：

from kirami.depends import ArgPlainText

@weather.handle()
async def handle_function(location: EventPlainText):
    if location:
        await weather.finish(f"今天{location}的天气是...")

@weather.got("location", prompt="请输入地名")
async def got_location(location: ArgPlainText):
    await weather.finish(f"今天{location}的天气是...")
天气
KiramiBot Logo
请输入地名
北京
KiramiBot Logo
今天北京的天气是...

在上面的代码中，我们在 got_location 函数中定义了一个依赖注入参数 location，他的值将会是用户回复的消息纯文本信息。获取到用户输入的地名参数后，我们就可以进行天气查询并回复了。

提示

如果想要获取用户回复的消息对象 Message ，可以使用 Arg 依赖注入。

跳过询问​

在上面的代码中，如果用户在输入天气指令时同时提供了地名参数，我们会直接回复天气信息。这部分的逻辑和用户输入后的处理是相同的。如果我们希望在复杂的业务场景中避免代码冗余，我们可以使用事件响应器操作中的 set_arg 来主动设置参数：

from kirami.depends import EventMessage
from nonebot.matcher import Matcher

@weather.handle()
async def handle_function(matcher: Matcher, location: EventMessage):
    if location.extract_plain_text():
        matcher.set_arg("location", location)

@weather.got("location", prompt="请输入地名")
async def got_location(location: ArgPlainText):
    await weather.finish(f"今天{location}的天气是...")
提示

因为 set_arg 的参数值要求为 Message 对象，所以我们需要使用 EventMessage 来获取用户输入的消息对象，而不是使用 EventPlainText 来获取纯文本消息。

注意

设置参数需要使用依赖注入来获取 Matcher 实例以确保上下文正确。

在 location 参数被设置之后，got 事件响应器操作将不再会询问并等待用户的回复，而是直接进入 got_location 函数。

请求重新输入​

在实际的业务场景中，用户的输入可能不符合我们的预期，而结束事件处理流程让用户从头开始也不是一个好体验。这时，我们可以使用 reject 事件响应器操作来请求用户重新输入：

@weather.handle()
async def handle_function(matcher: Matcher, location: EventMessage):
    if location.extract_plain_text():
        matcher.set_arg("location", location)

@weather.got("location", prompt="请输入地名")
async def got_location(location: ArgPlainText):
    if location not in ["北京", "上海"]:
        await weather.reject(f"你想查询的城市 {location} 暂不支持，请重新输入！")
    await weather.finish(f"今天{location}的天气是...")
天气
KiramiBot Logo
请输入地名
广州
KiramiBot Logo
你想查询的城市 广州 暂不支持，请重新输入！
北京
KiramiBot Logo
今天北京的天气是...

在上面的代码中，我们在 got_location 函数中判断用户输入的地名是否在支持的城市列表中，如果不在，则使用 reject 事件响应器操作。

该操作将会向用户发送 reject 参数中的消息，并等待用户回复后，重新执行 got_location 函数。通过 got 和 reject 事件响应器操作，我们实现了类似于循环的执行方式。

注意

与 finish 类似，reject 会在向机器人用户发送消息内容后抛出 RejectedException 异常来暂停事件响应流程，以等待用户的回复。也就是说，在 reject 后面的代码将不会被执行。

更多事件响应器操作​

在之前的章节中，我们已经大致了解了五个事件响应器操作：handle、got、send、finish 和 reject。现在我们来完整地介绍一下这些操作。

事件响应器操作可以分为两大类：交互操作和流程控制操作。我们可以通过交互操作来与用户进行交互，而流程控制操作则可以用来控制事件处理流程的执行。

提示

事件处理流程按照事件处理函数添加顺序执行，已经结束的事件处理函数不可能被恢复执行。

handle​

handle 事件响应器操作是一个装饰器，用于向事件处理流程添加一个事件处理函数。

@matcher.handle()
async def handle_func():
    ...

handle 装饰器支持嵌套操作，即一个事件处理函数可以被添加多次：

@matcher.handle()
@matcher.handle()
async def handle_func():
    # 这个函数会被执行两次
    ...

handle 装饰器拥有简写形式，即 @matcher 等同于 @matcher.handle()：

@matcher
async def handle_func():
    ...

got​

got 事件响应器操作也是一个装饰器，它会在当前装饰的事件处理函数运行之前，中断当前事件处理流程，等待接收一个新的事件。它可以通过 prompt 参数来向用户发送询问消息，然后等待用户的回复消息，贴近对话形式会话。

got 装饰器接受一个参数 key 和一个可选参数 prompt。当会话状态中不存在 key 对应的消息时，会向用户发送 prompt 参数的消息，并等待用户回复。prompt 参数的类型和 send 事件响应器操作的参数类型一致。

在事件处理函数中，可以通过依赖注入的方式来获取接收到的消息，参考：Arg、ArgStr、ArgPlainText。

@matcher.got("key", prompt="请输入...")
async def got_func(key: Arg):
    ...

got 装饰器支持与 got 和 receive 装饰器嵌套操作，即一个事件处理函数可以在接收多个事件或消息后执行：

@matcher.got("key1", prompt="请输入key1...")
@matcher.got("key2", prompt="请输入key2...")
@matcher.receive("key3")
async def got_func(key1: Arg, key2: Arg, key3: Event = useReceived("key3")):
    ...

receive​

receive 事件响应器操作也是一个装饰器，它会在当前装饰的事件处理函数运行之前，中断当前事件处理流程，等待接收一个新的事件。与 got 不同的是，receive 不会向用户发送询问消息，并且等待一个用户事件。可以接收的事件类型取决于会话更新。

receive 装饰器接受一个可选参数 id，用于标识当前需要接收的事件，如果不指定，则默认为空 ""。

在事件处理函数中，可以通过依赖注入的方式来获取接收到的事件，参考：Received、LastReceived。

@matcher.receive("id")
async def receive_func(event: Event = useReceived("id")):
    ...

receive 装饰器支持与 got 和 receive 装饰器嵌套操作，即一个事件处理函数可以在接收多个事件或消息后执行：

@matcher.receive("key1")
@matcher.got("key2", prompt="请输入key2...")
@matcher.got("key3", prompt="请输入key3...")
async def receive_func(key1: Event = Received("key1"), key2: Message = useArg(), key3: Message = useArg()):
    ...

send​

send 事件响应器操作用于向用户发送一条消息。

send 操作接受一个参数 message 和其他任何协议适配器接受的参数。message 参数类型可以是字符串、消息序列、消息段。

提示

这个操作等同于使用 bot.send(event, message, **kwargs)，但不需要自行传入 event。

@matcher.handle()
async def _():
    await matcher.send("Hello world!")

finish​

向用户发送一条消息（可选），并立即结束整个处理流程。

参数与 send 相同。

@matcher.handle()
async def _():
    await matcher.finish("Hello world!")
    # 下面的代码不会被执行

reject​

向用户发送一条消息（可选），立即结束当前事件处理函数，等待接收一个新的事件后再次执行当前事件处理函数。

reject 可以用于拒绝当前 receive 接收的事件或 got 接收的参数。通常在用户回复不符合格式或标准，需要重新输入，或者用于循环进行用户交互。

参数与 send 相同。

@matcher.got("arg")
async def _(arg: ArgPlainText):
    if not is_valid(arg):
        await matcher.reject("Invalid arg!")

reject_arg​

向用户发送一条消息（可选），立即结束当前事件处理函数，等待接收一个新的消息后再次执行当前事件处理函数。

reject_arg 用于拒绝指定 got 接收的参数，通常在嵌套装饰器时使用。

reject_arg 操作接受一个 key 参数以及可选的 prompt 参数。prompt 参数与 send 相同。

@matcher.got("a")
@matcher.got("b")
async def _(a: ArgPlainText, b: ArgPlainText):
    if a not in b:
        await matcher.reject_arg("a", "Invalid a!")

reject_receive​

向用户发送一条消息（可选），立即结束当前事件处理函数，等待接收一个新的事件后再次执行当前事件处理函数。

reject_receive 用于拒绝指定 receive 接收的事件，通常在嵌套装饰器时使用。

reject_receive 操作接受一个可选的 id 参数以及可选的 prompt 参数。id 参数默认为空 ""，prompt 参数与 send 相同。

@matcher.receive("a")
@matcher.receive("b")
async def _(a: Event = useReceived("a"), b: Event = useReceived("b")):
    if a.get_user_id() != b.get_user_id():
        await matcher.reject_receive("a")

pause​

向用户发送一条消息（可选），立即结束当前事件处理函数，等待接收一个新的事件后进入下一个事件处理函数。

参数与 send 相同。

@matcher.handle()
async def _():
    if need_confirm:
        await matcher.pause("请在两分钟内确认执行")

@matcher.handle()
async def _():
    ...

skip​

立即结束当前事件处理函数，进入下一个事件处理函数。

通常在依赖注入中使用，用于跳过当前事件处理函数的执行。

from kirami.depends import depends

@depends
async def dependency():
    matcher.skip()

@matcher.handle()
async def _(check=dependency):
    # 这个函数不会被执行

stop_propagation​

阻止事件向更低优先级的事件响应器传播。

from kirami.matcher import Matcher

@foo.handle()
async def _(matcher: Matcher):
    matcher.stop_propagation()
警告

stop_propagation 操作是实例方法，需要先通过依赖注入获取事件响应器实例再进行调用。

get_arg​

获取一个 got 接收的参数。

get_arg 操作接受一个 key 参数和一个可选的 default 参数。当参数不存在时，将返回 default 或 None。

from kirami.matcher import Matcher

@matcher.handle()
async def _(matcher: Matcher):
    key = matcher.get_arg("key", default=None)

set_arg​

设置 / 覆盖一个 got 接收的参数。

set_arg 操作接受一个 key 参数和一个 value 参数。请注意，value 参数必须是消息序列对象，如需存储其他数据请使用会话状态。

from kirami.matcher import Matcher

@matcher.handle()
async def _(matcher: Matcher):
    matcher.set_arg("key", Message("value"))

get_receive​

获取一个 receive 接收的事件。

get_receive 操作接受一个 id 参数和一个可选的 default 参数。当事件不存在时，将返回 default 或 None。

from kirami.matcher import Matcher

@matcher.handle()
async def _(matcher: Matcher):
    event = matcher.get_receive("id", default=None)

get_last_receive​

获取最近的一个 receive 接收的事件。

get_last_receive 操作接受一个可选的 default 参数。当事件不存在时，将返回 default 或 None。

from kirami.matcher import Matcher

@matcher.handle()
async def _(matcher: Matcher):
    event = matcher.get_last_receive(default=None)

set_receive​

设置 / 覆盖一个 receive 接收的事件。

set_receive 操作接受一个 id 参数和一个 event 参数。请注意，event 参数必须是事件对象，如需存储其他数据请使用会话状态。

from kirami.matcher import Matcher

@matcher.handle()
async def _(matcher: Matcher):
    matcher.set_receive("key", Event())

get_argot​

获取指定的暗语内容。

get_argot 操作接受一个 key 参数和一个可选的 default 参数。当暗语不存在时，将返回 default 或 None。

from kirami.matcher import Matcher

@matcher.handle()
async def _(matcher: Matcher):
    argot = matcher.get_argot("key", default=None)
© 2024 KiramiBot. All rights reserved.

内容目录

编辑此页