Core模块困难

字数统计:1.2k 字

阅读时长:4 分钟

class SVList

class SV

服务注册器

def __init__(
        self,
        name: str = '',
        pm: int = 6,
        priority: int = 5,
        enabled: bool = True,
        area: Literal['GROUP', 'DIRECT', 'ALL'] = 'ALL',
        black_list: List = [],
        white_list: List = [],
):

参数	类型	默认值	注释
name	str	无	服务的名称，代表这一组功能的统称
pm	int	6	用户权限（0=主人，2=群主，3=管理员，6=普通）
priority	int	5	响应优先级，数字越小越先执行
enabled	bool	True	启用状态
area	Literal['GROUP', 'DIRECT', 'ALL']	ALL	作用范围
black_list	list	[]	黑名单列表
white_list	list	[]	白名单列表

同一 name 的 SV 是单例，多次创建会返回同一个实例，可跨文件共享。

触发器通用参数

所有 on_xxx 装饰器都支持以下通用参数：

参数	类型	默认值	说明
block	bool	False	匹配后阻止事件继续传递给其他触发器
to_me	bool	False	是否必须 @ 机器人才触发
prefix	bool	True	是否应用插件全局前缀
to_ai	str	""	非空时自动注册为 AI 工具（详见 触发器文档）

method on_fullmatch

def on_fullmatch(self, keyword: Union[str, Tuple[str, ...]], block: bool = False, to_ai: str = "", ...)

全字匹配消息。只有当消息内容完全等于预设关键词时触发。

method on_prefix

def on_prefix(self, keyword: Union[str, Tuple[str, ...]], block: bool = False, to_ai: str = "", ...)

匹配消息前缀。消息内容以预设关键词开头时触发，且必须包含后续参数（仅发送关键词本身不会触发）。

method on_suffix

def on_suffix(self, keyword: Union[str, Tuple[str, ...]], block: bool = False, to_ai: str = "", ...)

匹配消息后缀。消息内容以预设关键词结尾时触发。

method on_keyword

def on_keyword(self, keyword: Union[str, Tuple[str, ...]], block: bool = False, to_ai: str = "", ...)

关键词匹配。消息内容中包含预设关键词时触发。

method on_command

def on_command(self, keyword: Union[str, Tuple[str, ...]], block: bool = False, to_ai: str = "", ...)

命令匹配。消息内容以预设关键词开头时触发，与 on_prefix 不同的是，即使后面没有跟任何参数也会触发。简单理解：on_command = on_fullmatch + on_prefix。

method on_regex

def on_regex(self, regex: str, block: bool = False, to_ai: str = "", ...)

正则表达式匹配。消息内容符合正则表达式模式时触发。匹配结果可通过 ev.regex_dict（命名分组）和 ev.regex_group（位置分组）获取。

method on_file

def on_file(self, suffix: str = "", block: bool = False, ...)

文件消息触发器。用户上传文件时触发，可指定文件后缀过滤（如 "png"、"json"）。

method on_message

def on_message(self, block: bool = False, ...)

消息触发器。接收到任意消息时触发，适合用作消息日志记录或全局处理。慎用，可能影响性能。

value SL

服务列表。是一个SVList对象。

---

class Plugins

插件级配置类，定义整个插件的前缀、权限等共享设置。一个 Plugins 下可以有多个 SV 实例。

class Plugins(
    name: str = '',
    pm: int = 6,
    priority: int = 5,
    enabled: bool = True,
    area: Literal['GROUP', 'DIRECT', 'ALL', 'SV'] = 'SV',
    black_list: List[str] = [],
    white_list: List[str] = [],
    prefix: List[str] | str = [],
    force_prefix: List[str] = [],
    disable_force_prefix: bool = False,
    allow_empty_prefix: bool | None = None,
)

参数	类型	默认值	说明
name	str	''	插件名称，必须与目录名一致
pm	int	6	权限等级（0=主人，2=群主，3=管理员，6=普通）
priority	int	5	优先级
enabled	bool	True	是否启用
area	Literal	'SV'	作用范围
force_prefix	List[str]	[]	插件作者自定义强制前缀（不会写入 config.json）
prefix	List[str] | str	[]	用户自定义前缀
allow_empty_prefix	bool | None	None	是否允许无前缀触发
disable_force_prefix	bool	False	是否禁用强制前缀

示例：

from gsuid_core.sv import Plugins

Plugins(
    name="MyGameUID",
    force_prefix=["mygame", "游戏"],
    allow_empty_prefix=False,
    alias=["mygame"],
)

Plugins vs SV 的关系：

• Plugins 是插件级配置，定义整个插件的前缀、权限等共享设置
• SV 是服务模块级配置，定义单个功能模块的触发器和权限
• 一个 Plugins 下可以有多个 SV 实例
• SV 创建时会自动查找同名 Plugins 实例，继承其前缀配置

---

启动钩子

on_core_start_before

def on_core_start_before(
    func: Optional[Callable] = None,
    /,
    priority: int = 0,
):

注册在 WS 服务启动之前执行的钩子函数。用于数据库迁移、全局变量加载等必须在连接建立前完成的操作。

参数	类型	默认值	说明
func	Callable	None	钩子函数（由装饰器自动传入）
priority	int	0	优先级，数字越小越先执行

from gsuid_core.server import on_core_start_before

@on_core_start_before
async def my_before_hook():
    # 必须在 WS 连接前完成的操作
    ...

@on_core_start_before(priority=5)
async def my_before_hook_with_priority():
    ...

on_core_start

def on_core_start(
    func: Optional[Callable] = None,
    /,
    priority: int = 0,
):

注册在 WS 服务启动之后作为后台任务异步执行的钩子函数。适合网络请求、模型下载等耗时操作。

参数	类型	默认值	说明
func	Callable	None	钩子函数（由装饰器自动传入）
priority	int	0	优先级，数字越小越先执行

from gsuid_core.server import on_core_start

@on_core_start
async def my_hook():
    # 耗时的初始化操作，不影响 WS 连接
    ...