一个用于针对简化 mirai 插件开发的前置插件。它通过注解驱动的方式，大幅减少了编写消息监听和权限校验的重复代码。 最新版本请查看上面展示的maven版本!
- 自动化消息监听: 使用
@EventComponent和@MessageAuthorize自动化注册监听器。 - 编译期优化 (KSP): 支持使用 KSP 在编译期生成注册代码，消除运行时反射开销，提升启动速度。
- 多维度权限系统: 针对用户 (Friend)、群 (Group)、群成员 (GroupMember)、群管理 (GroupAdmin) 提供独立权限控制。
- 权限分组与继承: 权限通过分组管理，支持组间继承。
- 灵活的消息匹配: 支持文本、正则、以及自定义逻辑匹配。
- 指令前缀支持: 全局或局部配置指令触发前缀。
- 轻量化: 移除外部依赖，减少插件体积。
在 settings.gradle.kts 中添加仓库：
dependencyResolutionManagement {
repositories {
// 壶言私服 - 国内加速镜像代理 (推荐)
maven("https://nexus.chahuyun.cn/repository/maven-public/")
// KSP 插件与常规依赖来源 (备用)
google()
mavenCentral()
}
}在子项目的 build.gradle.kts 中添加插件和依赖：
plugins {
// 启用 KSP（可选；版本需与 Kotlin 版本匹配）
id("com.google.devtools.ksp") version "1.9.20-1.0.14"
}
dependencies {
// 核心库（下游只需要依赖 HuYanAuthorize 即可使用 AuthorizeServer/PermUtil/注解等所有能力）
compileOnly("cn.chahuyun:HuYanAuthorize:$authVersion")
// 启用 KSP 编译期加速 (可选，需要同时引入上面的 ksp 插件)
ksp("cn.chahuyun:HuYanAuthorize-ksp:$authVersion")
}在插件的 onEnable 方法中：
override fun onEnable() {
// 注册本插件的消息监听包
// - 默认 useKsp = false：走反射注册（无需 KSP 处理器）
// - 若你启用了 KSP：建议 useKsp = true（强制仅使用 KSP 生成的注册器，避免重复订阅）
AuthorizeServer.registerEvents(this, "your.package.name", useKsp = true)
}创建一个带有 @EventComponent 注解的类，并在方法上使用 @MessageAuthorize：
@EventComponent
class MyListener {
@MessageAuthorize(text = ["你好"])
suspend fun onHello(event: MessageEvent) {
event.subject.sendMessage("你好啊！")
}
@MessageAuthorize(
text = ["admin"],
userPermissions = ["admin_code"] // 需要拥有 admin_code 权限
)
suspend fun onAdmin(event: MessageEvent) {
event.subject.sendMessage("管理员你好！")
}
}AuthorizeServer 是功能入口类（原 PermissionServer 已弃用，但仍保留向下兼容）。
registerEvents(plugin, packageName, exceptionHandle, prefix, useKsp)
扫描指定包下所有带有 @EventComponent 的类并自动注册监听器。
其中 useKsp 的语义：
useKsp = false（默认）：使用反射注册监听器。useKsp = true：强制使用 KSP 生成的注册器（若未生成对应注册器会直接报错，便于快速发现“没启用 KSP/没重新构建”问题）。
重要：
useKsp不会“传递到下游插件”。它只是你当前插件在运行时选择“用 KSP 注册/用反射注册”的开关。 下游只有在自己的工程里启用了com.google.devtools.ksp并添加ksp("cn.chahuyun:HuYanAuthorize-ksp:...")时，才应该传useKsp = true。
registerPermissions(plugin, vararg perms)
预定义插件所需的权限码。
本插件支持使用 KSP (Kotlin Symbol Processing) 来替换运行时的反射扫描。
- 启动速度: 避免在插件启动时扫描大量的 Class 注解。
- 混淆安全: 直接生成代码调用，不受 R8/Proguard 混淆影响。
- 性能: 消除反射调用 (Method.invoke) 的额外开销。
- 在项目
build.gradle.kts的plugins块中引入com.google.devtools.ksp。 - 在
dependencies块中添加ksp("cn.chahuyun:HuYanAuthorize-ksp:版本号")。 - 在你的插件
onEnable中调用AuthorizeServer.registerEvents(..., useKsp = true)。 - 无需修改业务代码: KSP 会在编译时为每个
@EventComponent类生成XXX_AuthorizeRegistrar，运行时通过ServiceLoader自动发现并注册。
说明：项目内部使用多模块用于工程维护，对下游发布仍是
cn.chahuyun:HuYanAuthorize（核心）与cn.chahuyun:HuYanAuthorize-ksp（处理器）。
| 属性 | 类型 | 说明 |
|---|---|---|
text |
Array<String> |
匹配文本。正则模式下取第一条。 |
messageMatching |
Enum |
匹配方式：TEXT(默认), REGULAR, CUSTOM。 |
messageConversion |
Enum |
转换方式：MIRAI_CODE(默认), CONTENT, JSON。 |
userPermissions |
Array<String> |
用户需拥有的权限码。 |
groupPermissions |
Array<String> |
群需拥有的权限码。 |
userInGroupPermissionsAssociation |
Enum |
用户与群权限的关联逻辑：AND(默认), OR。 |
priority |
EventPriority |
监听优先级。 |
concurrency |
ConcurrencyKind |
并发处理方式。 |
为了提供最佳的开发体验，我们计划推出配套的 IntelliJ IDEA 插件。目前该插件仍在路线图中，尚未正式发布。
- [未实现] 消除未使用警告: 自动识别
@MessageAuthorize标记的方法为程序入口点，不再提示 "Method is never used"。 - [未实现] 权限码自动补全: 在注解中输入权限码时，提供智能提示。
- [未实现] 正则校验: 在编写
@MessageAuthorize正则规则时，实时进行语法检查。 - [未实现] 侧边栏导航 (Gutter Icons): 在监听方法侧边显示图标，点击可快速跳转或查看配置。
在配套插件发布前，下游开发者可以通过以下方式手动消除 IDEA 的未使用方法警告：
- 手动添加入口点 (Entry Point):
- 打开 IDEA 设置:
Editor->Inspections。 - 找到
JVM languages->Unused declaration。 - 在右侧点击
Entry Points标签页 ->Annotations...。 - 点击
+号并输入:cn.chahuyun.authorize.MessageAuthorize。
- 打开 IDEA 设置:
- 项目级共享 (推荐):
- 在 IDEA 中将检查配置文件 (Inspection Profile) 的
Scheme改为Project。 - 将
.idea/inspectionProfiles/Project_Default.xml提交到 Git 仓库，这样所有下游开发者克隆项目后都将自动获得该配置。
- 在 IDEA 中将检查配置文件 (Inspection Profile) 的
| 指令 | 作用 | 示例 |
|---|---|---|
+perm (组名) [code] |
创建/修改权限组并添加权限 | +perm 管理组 admin |
+global (@用户) (组名) |
将用户加入全局权限组 | +global 123456 管理组 |
+member (@用户) (组名) |
将群成员加入权限组 | +member @小明 成员组 |
=perm [组名] |
查询权限组信息 | =perm |