量子猫🐱 Quantcat (注解API)

quantcat 模块定义了一些注解, 以及服务这些注解的配套内容。这些注解的作用便是用于简化事件的监听、处理以及匹配的。 quantcat 模块仅提供定义和一部分基础的、默认的实现。

quantcat 是一种“标准”, 没有具体的注解解析实现。

事件监听 @Listener

@Listener 注解标记在一个函数上, 用来声明此函数将会被解析为一个事件处理器。

@Listener
suspend fun listen1(event: Event) {
    // ...
}

@Listener
suspend fun Event.listen2() {
    // ...
}

@Listener
public void listen1(Event event) {
    // ...
}

// 👇 支持 [[[CollectableReactivelyResult|basic-event-listener.html#CollectableReactivelyResult]]] 中所述的异步/响应式结果。
//    如果返回响应式结果, 记得添加对应的 [[[kotlinx-coroutines-xxx|https://github.com/Kotlin/kotlinx.coroutines/blob/master/reactive/README.md]]] 依赖。

@Listener
public CompletableFuture<?> listen2(Event event) {
    return ...
}

@Listener
public Mono<?> listen3(Event event) {
    return ...
}

一个被标记了 @Listener 的函数, 它的参数、返回值等内容会被解析, 然后最终被处理为一个 EventListener, 进而被使用。其中：

参数中, Event 类型的参数会被视为本次事件监听的目标类型。如果没有, 则视为监听所有类型的事件。建议只有一个 Event 类型的参数。
参数中, 一些可知的类型的参数可以自动填充：
- EventListenerContext
- EventContext
- Event 或某个子类型 (上一条所述)
- EventListener

事件过滤 @Filter

@Filter 配合 @Listener, 用于简化对文本的匹配和一些已知的样板信息的匹配。

@Listener
@Filter("你好")
suspend fun listen1(event: Event) {
    // ...
}

@Listener
@Filter(targets = [Filter.Targets(bots = ["bot-id-123"])])
suspend fun listen2(event: Event) {
    // ...
}

@Listener
@Filter("你好")
public void listen1(Event event) {
    // ...
}

@Listener
@Filter(targets = {@Filter.Targets(bots = "bot-id-123")})
public void listen2(Event event) {
    // ...
}

如上所示, 函数 listen1 将会用"你好"进行正则匹配, 只有一个消息事件 MessageEvent 中的文本消息符合这个正则, 才会进入此处理器。

函数 listen2 则会判断 BotEvent 中的 bot 是否能将 "bot-id-123" 视为自己, 如果可以才会进入此处理器。

下面会列举 @Filter 中详细的属性列表。

@Filter:

value

String, 要进行文字匹配的值。匹配方式由 matchType 决定。

matchType

MatchType 枚举, value 的匹配逻辑, 默认为 REGEX_MATCHES。

TEXT_EQUALS: 文本全等匹配
TEXT_EQUALS_IGNORE_CASE: 文本忽略大小写的全等匹配
TEXT_STARTS_WITH: 文本开头匹配
TEXT_ENDS_WITH: 文本结尾匹配
TEXT_CONTAINS: 文本包含匹配
REGEX_MATCHES: 正则匹配
REGEX_CONTAINS: 正则 find 匹配

mode

FilterMode, 代表当前这个注解被解析后所产生的“过滤器”的实现模式。默认为 IN_LISTENER。

INTERCEPTOR: 将 Filter 中的逻辑作为对应的事件处理器的专属拦截器 EventInterceptor 注册。使用此模式则可以通过优先级的控制来使其与其他拦截器之间的关系（例如全局注册的拦截器）。
IN_LISTENER: 作为一段逻辑注入到事件处理器的前置中。由于最终执行逻辑是与事件处理器的逻辑“融为一体”的, 所以使用此模式时, Filter 所产生的逻辑始终会在所有拦截器之后执行。

priority

Int, 优先级。根据 mode 的不同, 分别代表作为拦截器时的优先级或与其他 IN_LISTENER 逻辑之间的优先级。默认为 PriorityConstant.DEFAULT。

targets

Filter.Targets 数组, 后续介绍。默认为空。

ifNullPass

Boolean, 如果消息的纯文本内容 plainText 为 null, 是否直接放行。默认为 false 。此参数只有当 value 不为空的时候有效。

@Filter.Targets:

components: String 数组, 对 Component 进行匹配。如果事件为 ComponentEvent, 则只有 component.id 在此列表中时才会放行。
bots: String 数组, 对 Bot 进行匹配。如果事件为 BotEvent, 则只有 Bot.id 在此列表中时才会放行。
actors: String 数组, 对 Actor 进行匹配。如果事件为 ActorEvent, 则只有 Actor.id 在此列表中时才会放行。
authors: String 数组, 对消息发送者进行匹配。如果事件为 MessageEvent, 则只有 MessageEvent.authorId 在此列表中才会放行。
chatRooms: String 数组, 对事件的 ChatRoom 进行匹配。如果事件为 ChatRoomEvent, 则只有 ChatRoomEvent.content.id 在此列表中才会放行。
organizations: String 数组, 对事件的 Organization 进行匹配。如果事件为 OrganizationEvent, 则只有 OrganizationEvent.content.id 在此列表中才会放行。
groups: String 数组, 对事件的 ChatGroup 进行匹配。如果事件为 ChatGroupEvent, 则只有 ChatGroupEvent.content.id 在此列表中才会放行。
guilds: String 数组, 对事件的 Guild 进行匹配。如果事件为 GuildEvent, 则只有 GuildEvent.content.id 在此列表中才会放行。
contacts: String 数组, 对事件的 Contact 进行匹配。如果事件为 ContactEvent, 则只有 ContactEvent.content.id 在此列表中才会放行。
ats: String 数组, 对消息事件中 At 进行匹配。如果事件为 MessageEvent,
则只有 MessageEvent.messageContent.messages 中存在 At 消息且包含任意 at 目标时才会放行。
atBot: Boolean ，对消息事件中 At 进行匹配。如果事件为 MessageEvent，则只有 MessageEvent.messageContent.messages 中存在 At 消息且 id 属于事件 bot 时才会放行。

@FilterValue 参数提取器

配合 @Filter 使用，当你使用正则类型的匹配方式进行文本匹配时，你可以使用参数提取来便捷的提取出匹配通过内容的某些值。例如：

@Filter("name: (?<name>.+), age: (?<age>\\d+)")
suspend fun Event.listen(
  @FilterValue("name") name: String, 
  @FilterValue("age") age: Int) {
    // ...
}

@Filter("name: {{name}}, age: {{age,\\d+}}")
suspend fun Event.listen(
  @FilterValue("name") name: String, 
  @FilterValue("age") age: Int) {
    // ...
}

@Filter("name: (?<name>.+), age: (?<age>\\d+)")
public void listen(
  Event event,
  @FilterValue("name") String name, 
  @FilterValue("age") int age) {
    // ...
}

@Filter("name: {{name}}, age: {{age,\\d+}}")
public void listen(
  Event event,
  @FilterValue("name") String name, 
  @FilterValue("age") int age) {
    // ...
}

20 September 2025