NcatBot 文档

外观

注册功能

约 1039 字大约 3 分钟

2025-03-27

使用功能

功能是对事件发布和处理的进一步封装, 使用功能可以方便快捷的接入 NcatBot 的权限管理机制.

功能的运作对象是消息事件, 只有群聊和私聊消息事件才会进行下面的判定.

体现在实际使用中, 直接私聊 Bot 或者在任何一个 Bot 所在的群聊中发送满足条件的消息即可触发功能.

功能的触发条件

触发功能要经过两个阶段：

  1. 权限判定：收到消息后, 对于每个功能会先进行权限判定. 消息来源(包括用户 QQ 号和所在群聊群号)会同时参与权限判定，两者必须都具有权限才会触发。功能在注册时会分配好权限节点, 只有被授权了权限节点的来源才能通过权限判定。
  2. 触发判定: 如果权限判定通过, 则会进行触发判定。触发判定的逻辑由功能注册者决定。请继续阅读本页。

注册功能

注册功能需要在插件==加载时==进行.

以下函数用于注册功能:

def register_user_func(
        self,
        name: str,
        handler: Callable[[BaseMessage], Any],
        filter: Callable = None,
        prefix: str = None,
        regex: str = None,
        permission_raise: bool = False,
        description: str = "",
        usage: str = "",
        examples: List[str] = None,
        tags: List[str] = None,
        metadata: Dict[str, Any] = None,
):
def register_admin_func(...)

register_default_func (3.8.x 起弃用)

注册一个默认功能, 如果一条消息没有触发默认功能所在插件的任何其它功能, 也没有触发内置功能, 则会触发默认功能.

  • handler: 功能处理函数, 接受一个 BaseMessage 类型的参数, 必须定义为异步函数.
  • permission: 功能权限, 默认为 user 级别 (user 级别的所有权限节点初始时自动分配给每个用户). 其它支持的填写如下:
    • user 或者 PermissionGroup.USER.value: 用户级别.
    • admin 或者 PermissionGroup.ADMIN.value: 管理员级别.
    • root 或者 PermissionGroup.ROOT.value: 超级管理员级别.

register_user_func

注册一个用户功能, 如果能满足触发条件则触发该功能.

  • name: 功能名称, 用于建立权限结构, 该功能的权限节点为 <plugin_name>.<name>. 功能.
  • handler: 功能处理函数, 接受一个 BaseMessage 类型的参数, .
  • filter: 自定义过滤函数, 接受一个 BaseMessage 类型的参数, 返回布尔值表示是否触发功能. 如果为 None 则不进行过滤.注意:自定义过滤函数需为同步函数
  • prefix: 前缀匹配字符串, 如果消息以该前缀开头则触发功能. 例如 prefix="/help" 会匹配以 "/help" 开头的消息.
  • regex: 正则表达式字符串, 如果消息匹配该正则表达式则触发功能. 例如 regex="\d*" 会匹配包含任意数量数字的消息. 可以使用 Python 的 re 模块支持的所有正则表达式语法.
  • description: 功能描述, 用于帮助文档.
  • permission_raise: 是否针对群聊提权, 如果 user_id (消息发送者 QQ 号) 为 admin 级别及以上权限, 则临时提升消息来源群聊的权限为 root. 私聊被分在一个特殊的群组, 权限为 root.
  • usage: 使用说明, 用于帮助文档.
  • examples: 使用示例列表, 用于帮助文档.
  • tags: 功能标签列表, 用于功能分类.
  • metadata: 额外元数据字典, 可以存储任意自定义数据.

注意: filter, prefix, regex 三个参数可以组合使用, 组合时需要同时满足所有条件才会触发功能. 如果都为 None 则该功能会被每条消息触发(不推荐).

register_admin_func

注册一个管理员功能, 如果能满足触发条件则触发该功能, 其它同上.

内置功能

参考内置功能

例子

LLM_API 插件

版权归属：NNNH

许可证：署名 4.0 国际 (CC-BY-4.0)

© 2025 NcatBot