permdesc.md

权限配置文档

概述

权限配置文件使用 YAML 格式，每个文件在本插件中被称为一个名称空间。不同名称空间里可以有同名的权限组，同一个名称空间下的权限组名必须唯一。

本插件会从插件配置项flexperm_base指定的路径（默认为permissions目录）加载权限配置，这个目录下每个.yml文件对应一个名称空间，文件名（不含扩展名）就是这个名称空间的名字。本插件也会加载其他插件注册时指定的预设权限配置，这种情况下，配置文件会被加载到与插件同名的名称空间，无关于文件名。

每个文件的顶层对象应为字典类型，键为权限组名，值为权限组的描述。权限组名一般应为字符串。对于group和user名称空间，默认适配器的用户ID或群号可以使用整数，其他适配器需要用格式为<适配器名小写>:<用户ID/群号>的字符串。

权限组的描述应为字典类型，可以包含两个字段——permissions和inherits。两个字段都为可选，若未提供，则等价于设为空列表。

权限描述

每个权限组的描述中，permissions字段指定该组包含的权限描述，应为列表，元素应为字符串。每个元素是一项权限描述。

权限描述由两部分组成，中间没有分隔符。

第一部分指定是授予还是撤销权限。默认为授予，减号（-）代表撤销。

第二部分指定要授予或撤销的权限项目。包含由点（.）分隔的若干段，每段可以包含字母、数字和下划线，且不应以数字开头。最后一段也可以是单独一个星号（*）。若最后一段是星号，则指定具体权限及其所有子权限，否则单独指定具体权限。例如：

权限描述	含义
a.b	授予a.b权限
-c.d	撤销c.d权限
e.*	授予e及其所有子权限，如e.a、e.b.c等
-f.g.*	撤销f.g及其所有子权限

说明：授予一个权限时不会自动授予其路径上的权限，如权限描述a.b.c只会授予a.b.c权限，而不会同时授予a和a.b两个权限。撤销同理。

需要授予全部权限时，由于星号在 YAML 语法中有特殊意义，权限描述须写为"*"。其他情况下可以不加引号。

继承

每个权限组的描述中，inherits字段指定本权限组继承的权限组，应为列表，元素应为字符串。每个元素标识一个其他权限组。

权限组标识可以包含一个冒号，冒号前为目标权限组的名称空间，冒号后为权限组名；也可以不包含冒号，代表当前名称空间，整个字符串为权限组名。

权限判断逻辑

对于每个权限组，首先检查指定权限在本权限组的permissions字段中是否被授予或撤销。若存在授予或撤销，则作为本组的检查结果（既被授予又被撤销时视为撤销）。若既未授予也未撤销，则递归地检查继承的组。在本组直接继承的所有组中，若某个组的检查结果为撤销，则本组检查结果也为撤销；若都没有撤销，且某个组的检查结果为授予，则本组检查结果也为授予；否则，检查无结果。

对于一个事件，本插件会依次检查下列权限组，以第一个有结果的为准。如果都无结果，则视为事件没有所需权限。

• user:<事件所属用户ID>
• global:superuser，如果用户是 bot 的超级用户
• global:anyone
• global:group_admin，如果事件来自群聊，且用户是群管理员（不含群主）
• global:group_owner，如果事件来自群聊，且用户是群主
• group:<事件所属群号>，如果事件来自群聊
• global:group，如果事件来自群聊
• global:private，如果事件来自私聊

默认权限组

本插件在global名称空间提供了六个默认组，定义如下：

anyone: {}
private: {}
group: {}
group_admin: {}

group_owner:
  inherits:
    - global:group_admin

superuser:
  permissions:
    - flexperm.*

前四个组均为空，后两个组各自带有一项默认设置。手动创建配置文件时需要把这两项设置加进去，除非需要改变对应的行为。