跳转到主要内容
YumeBot 使用注解式 API，只需在方法上添加注解即可自动注册监听器。

​
概述

在插件类中定义 suspend 方法，使用注解标记为监听器： 
class MyPlugin : Plugin() {
    @OnGroupMessage
    @GroupKeyword("你好")
    @Priority(100)
    suspend fun onHello(event: OB11GroupMessage) {
        // 处理消息
    }
}
无需手动注册，框架会自动扫描并注册所有带注解的方法。

​
群消息监听器

​
@OnGroupMessage

监听群聊消息事件。 
@OnGroupMessage
@GroupKeyword("搜索")
@Priority(100)
suspend fun onSearch(event: OB11GroupMessage) {
    val query = event.rawMessage.removePrefix("搜索").trim()
    
    val reply = message {
        text("搜索结果：$query")
    }.build()
    
    messageApi?.sendGroupMessage(event.groupId, reply, name)
}

​
事件对象

​
OB11GroupMessage
data class
群消息事件对象

​
群消息过滤器

匹配包含指定关键词的消息（任一匹配即触发）
@GroupKeyword("你好", "hello", "hi")
suspend fun onGreeting(event: OB11GroupMessage) {
    // 消息包含"你好"、"hello"或"hi"时触发
}
消息内容完全匹配
@GroupExact("ping", ignoreCase = true)
suspend fun onPing(event: OB11GroupMessage) {
    // 消息完全是"ping"时触发（不区分大小写）
}
消息以指定前缀开头
@GroupStartsWith("/cmd")
suspend fun onCommand(event: OB11GroupMessage) {
    // 消息以"/cmd"开头时触发
}
使用正则表达式匹配
@GroupRegex("^/\\w+\\s+.*")
suspend fun onComplexCommand(event: OB11GroupMessage) {
    // 匹配 "/命令 参数" 格式
}
只处理指定群的消息
@FromGroup(123456789, 987654321)
suspend fun onSpecificGroup(event: OB11GroupMessage) {
    // 只在指定群触发
}
只处理指定用户的消息
@FromUserInGroup(111111111, 222222222)
suspend fun onSpecificUser(event: OB11GroupMessage) {
    // 只处理这些用户的消息
}

​
组合过滤器

// AND 逻辑（默认）：所有条件都满足
@OnGroupMessage
@GroupKeyword("搜索")
@FromGroup(123456789)
suspend fun onSearch(event: OB11GroupMessage) {
    // 必须在指定群且包含"搜索"关键词
}

// OR 逻辑：任一条件满足
@OnGroupMessage
@GroupKeyword("查询", "搜索")
@FilterMode(FilterCombineMode.OR)
suspend fun onQuery(event: OB11GroupMessage) {
    // "查询"或"搜索"都会触发
}

​
私聊消息监听器

​
@OnPrivateMessage

监听私聊消息事件。 
@OnPrivateMessage
@PrivateKeyword("帮助")
@Priority(100)
suspend fun onHelp(event: OB11PrivateMessage) {
    val help = message {
        text("可用命令列表：\n")
        text("- 帮助：显示此消息\n")
        text("- 状态：查看运行状态")
    }.build()
    
    messageApi?.sendPrivateMessage(event.userId, help, name)
}

​
事件对象

​
OB11PrivateMessage
data class
私聊消息事件对象

​
私聊过滤器

// 关键词
@PrivateKeyword("帮助", "help")

// 精确匹配
@PrivateExact("status", ignoreCase = true)

// 前缀匹配
@PrivateStartsWith("/")

// 正则表达式
@PrivateRegex("^\\d{6}$")  // 匹配6位数字

// 指定用户
@FromUser(123456789)

​
通知事件监听器

​
@OnNotice

监听各类通知事件（加群、退群、禁言等）。 
@OnNotice
@Priority(100)
suspend fun onNotice(event: NoticeEvent) {
    when (event) {
        is GroupIncreaseNotice -> {
            // 新成员加群
            val welcome = message {
                at(event.userId)
                text(" 欢迎加入本群！")
            }.build()
            messageApi?.sendGroupMessage(event.groupId, welcome, name)
        }
        
        is GroupDecreaseNotice -> {
            // 成员退群
            logger.info("用户 ${event.userId} 离开了群 ${event.groupId}")
        }
        
        is GroupBanNotice -> {
            // 群禁言
            val action = if (event.subType == GroupBanSubType.BAN) "禁言" else "解禁"
            logger.info("群 ${event.groupId} 用户 ${event.userId} 被${action}")
        }
        
        is GroupRecallNotice -> {
            // 消息撤回
            logger.info("群 ${event.groupId} 消息 ${event.messageId} 被撤回")
        }
    }
}

​
常见通知事件

GroupIncreaseNotice

群成员增加（新人加群）

GroupDecreaseNotice

群成员减少（退群/被踢）

GroupBanNotice

群禁言/解禁

GroupAdminNotice

管理员变动

GroupRecallNotice

消息撤回

GroupUploadNotice

群文件上传

FriendAddNotice

好友添加

FriendRecallNotice

好友消息撤回

​
请求事件监听器

​
@OnRequest

监听加好友、加群请求事件。 
@OnRequest
@Priority(100)
suspend fun onRequest(event: RequestEvent) {
    when (event) {
        is FriendRequest -> {
            // 好友请求
            logger.info("收到好友请求：${event.userId}")
            
            // 自动同意
            friendApi?.setFriendAddRequest(
                flag = event.flag,
                approve = true,
                remark = "自动通过"
            )
        }
        
        is GroupRequest -> {
            // 加群请求
            when (event.subType) {
                GroupRequestSubType.ADD -> {
                    // 申请加群
                    logger.info("用户 ${event.userId} 申请加入群 ${event.groupId}")
                }
                GroupRequestSubType.INVITE -> {
                    // 邀请入群
                    logger.info("收到群 ${event.groupId} 的邀请")
                    // 自动同意邀请
                    groupApi?.setGroupAddRequest(event.flag, approve = true)
                }
            }
        }
    }
}

​
请求事件类型

有人添加机器人为好友
data class FriendRequest(
    val userId: Long,      // 请求者 QQ 号
    val comment: String,   // 验证消息
    val flag: String       // 请求标识（用于同意/拒绝）
)
加群申请或邀请入群
data class GroupRequest(
    val groupId: Long,                  // 群号
    val userId: Long,                   // 请求者 QQ 号
    val comment: String,                // 验证消息/邀请理由
    val flag: String,                   // 请求标识
    val subType: GroupRequestSubType   // ADD(申请) 或 INVITE(邀请)
)

​
元事件监听器

​
@OnMeta

监听心跳、生命周期等元事件。 
@OnMeta
@Priority(100)
suspend fun onMeta(event: MetaEvent) {
    when (event) {
        is OB11HeartbeatEvent -> {
            // 心跳事件（定期推送）
            logger.debug("心跳：在线=${event.status.online}")
        }
        
        is OB11LifeCycleEvent -> {
            // 生命周期事件
            logger.info("生命周期：${event.subType}")
        }
    }
}
元事件推送频繁，建议使用 logger.debug() 而非 logger.info()

​
优先级

​
@Priority

设置监听器执行顺序，数字越大越先执行。 
@OnGroupMessage
@Priority(200)  // 高优先级
suspend fun adminCommand(event: OB11GroupMessage) {
    // 管理员命令，优先处理
}

@OnGroupMessage
@Priority(100)  // 普通优先级
suspend fun normalCommand(event: OB11GroupMessage) {
    // 普通命令
}

@OnGroupMessage
@Priority(0)    // 低优先级（默认）
suspend fun logger(event: OB11GroupMessage) {
    // 日志记录，最后执行
}
建议优先级分配：
  • 管理员命令：200+
  • 重要功能：100-199
  • 普通功能：50-99
  • 日志记录：0-49

​
返回值控制

监听器方法返回 EventHandleResult 控制事件传播： 
import plus.yumeyuka.yumebot.core.EventHandleResult

@OnGroupMessage
@Priority(100)
suspend fun checkBlacklist(event: OB11GroupMessage): EventHandleResult {
    if (event.userId in blacklist) {
        // 阻止事件继续传播
        return EventHandleResult.STOP_PROPAGATION
    }
    
    // 继续传播给其他监听器
    return EventHandleResult.CONTINUE
}
​
EventHandleResult.CONTINUE
enum
继续传播事件到下一个监听器
​
EventHandleResult.STOP_PROPAGATION
enum
停止事件传播，后续监听器不会收到此事件
​
EventHandleResult.CANCEL
enum
取消事件（与 STOP_PROPAGATION 相同）

​
完整示例

​
多功能群助手

package plugins.assistant

import plus.yumeyuka.yumebot.plugin.Plugin
import plus.yumeyuka.yumebot.plugin.annotations.*
import plus.yumeyuka.yumebot.protocol.message.OB11GroupMessage
import plus.yumeyuka.yumebot.protocol.event.*
import plus.yumeyuka.yumebot.api.message.message

class AssistantPlugin : Plugin() {
    override val id = "com.example.assistant"
    override val name = "群助手"
    override val version = "1.0.0"
    override val author = "YumeBot"
    override val description = "多功能群助手"
    
    // 问候功能
    @OnGroupMessage
    @GroupKeyword("你好", "hi", "hello")
    @Priority(100)
    suspend fun onGreeting(event: OB11GroupMessage) {
        val reply = message {
            at(event.sender.userId)
            text(" 你好呀！有什么可以帮助你的吗？")
        }.build()
        messageApi?.sendGroupMessage(event.groupId, reply, name)
    }
    
    // 时间查询
    @OnGroupMessage
    @GroupStartsWith("/time")
    @Priority(100)
    suspend fun onTimeQuery(event: OB11GroupMessage) {
        val now = java.time.LocalDateTime.now()
        val formatter = java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")
        
        val reply = message {
            text("当前时间：${now.format(formatter)}")
        }.build()
        messageApi?.sendGroupMessage(event.groupId, reply, name)
    }
    
    // 新人欢迎
    @OnNotice
    @Priority(100)
    suspend fun onNewMember(event: NoticeEvent) {
        if (event is GroupIncreaseNotice) {
            val welcome = message {
                at(event.userId)
                text(" 欢迎加入本群！\n")
                text("发送 /help 查看可用命令")
            }.build()
            messageApi?.sendGroupMessage(event.groupId, welcome, name)
        }
    }
    
    // 自动同意好友请求
    @OnRequest
    @Priority(100)
    suspend fun onFriendRequest(event: RequestEvent) {
        if (event is FriendRequest) {
            friendApi?.setFriendAddRequest(event.flag, approve = true)
            logger.info("已同意好友请求：${event.userId}")
        }
    }
}

​
最佳实践

重要监听器设置更高优先级，确保先执行
过滤器可以减少不必要的处理，提升性能
监听器内部应该捕获异常，避免影响其他监听器
使用协程处理耗时操作，不要阻塞事件处理
在 @OnNotice 和 @OnRequest 中使用 when 区分事件类型

​
相关链接

消息 API

学习如何发送和构建消息

协议事件

了解所有事件类型详情

过滤器注解

查看所有可用的过滤器注解

插件开发

完整的插件开发指南