hibikier

# 真寻Bot插件基本标准

# 简介

统一插件标准的好处：
- 自动生成帮助
- 自动生成配置项
- 自动生成插件开关
- 避免了修改插件单独配置文件的麻烦
- 没有重写matcher，利于增删额外插件
普通插件应该包含：
- __zx_plugin_name__：插件名
- __plugin_usage__：用法
- __plugin_des__：简介
- __plugin_cmd__：命令
- __plugin_settings__ ：插件通用设置
有主动发送消息的被动插件（不需要命令调用的插件，如定时任务，hook等）应该包含：
- __plugin_task__：为你提供一个或多个开关
以下作为额外添加选项：
- __plugin_type__：插件帮助分类（被动类插件不需要）
- __plugin_version__：插件版本
- __plugin_author__：插件作者
- __plugin_cd_limit__：插件cd限制
- __plugin_block_limit__：插件阻塞限制
- __plugin_count_limit__: 插件每日调用次数限制
- __plugin_resources__: 资源管理
- __plugin_configs__: 插件配置

已支持 PluginMetaData

_\_plugin_meta_\_ = PluginMetadata(
    name="测试插件",                    # __zx_plugin_name__
    description="测试插件元信息",       # __plugin_des__
    usage="无法使用",                   # __plugin_usage__
    config=Config,                      # __plugin_configs__
    extra={
        "author": "NoneBot",             # 'author' -> __plugin_author__
        "version": "0.1.0",             # 'version' -> __plugin_version__ : meta数据中的version仅修改插件文件部分，对于Config文件必定修改
        },        
)

1
2
3
4
5
6
7
8
9
10

# __zx_plugin_name__

类型：str
说明：
插件名称，为插件普通帮助的展示内容，基本所有模块都必须有 __zx_plugin_name__
通过在__zx_plugin_name__中添加 [Admin] [Superuser] [Hidden] 控制初始化帮助时插件的分类
基本为以下四类：
- ``：默认，即没有以下三种分类，作为普通插件
- [Admin]：纯管理员插件
- [Superuser]：纯超级用户插件
- [Hidden]：隐藏的插件，一般是不需要命令调用的插件

__zx_plugin_name__ = "色图"
__zx_plugin_name__ = "管理员操作 [Admin]"
__zx_plugin_name__ = "超级用户操作 [Superuser]"
__zx_plugin_name__ = "自动检测群员数量 [Hidden]"

1
2
3
4

# __plugin_usage__

类型：str
说明：
插件帮助说明示例：

"""
usage:
    有什么用处？
    指令：
        ...
        示例：...
""".strip()

1
2
3
4
5
6
7

# __plugin_superuser_usage__

类型：str
说明：
当非 [Superuser] 插件含有超级用户的功能时，在该属性中编写超级用户的额外帮助
帮助写法与 __plugin_usage__ 一致

# __plugin_des__

类型：str
说明：
插件简介，不建议太长，详细介绍可以写在usage中，主要在详细帮助中显示

# __plugin_cmd__

类型：List[str]
说明：
插件指令，相同功能的插件指令请使用/分离，如果是超级用户的功能，请在命令后添加[_superuser]
示例：

# 发送 ‘我的签到’ 和 ‘好感度’ 效果相同
__plugin_cmd__ = ["我的签到/好感度", "好感度排行", "清空好感度 [_superuser]"]

1
2

# __plugin_settings__

类型：Dict[str, Union[str, int]]
说明：
插件的通用设置，普通插件与纯管理员插件会有所不同
示例：

# 普通插件，以下除cmd外为默认值
__plugin_settings__ = {
    "level": 5,             # 群权限等级，请不要设置为1或999，若无特殊情况请设置为5
    "default_status": True,     # 进群时的默认开关状态
    "limit_superuser": False,   # 开关插件的限制是否限制超级用户
    "cmd": ["b封面", 'B封面'],   # 命令别名，主要用于帮助和开关
    "cost_gold": 0,             # 该功能需要花费的金币
}
#"cmd"第一个值会被作为功能调用统计的显示选项，开关方面：开启b封面=开启B封面=开启cover
#"__zx_plugin_name__"不需要额外写入，在bot启动时会自动将"__zx_plugin_name__"导入对应的"cmd"

# 只填写需要的部分，其他默认
__plugin_settings__ = {
    "level": 5,             # 群权限等级，请不要设置为1或9，若无特殊情况请设置为5
    "cmd": ["b封面", 'B封面'],   # 命令别名，主要用于帮助和开关
}

# 再简化一点
__plugin_settings__ = {
    "cmd": ["b封面", 'B封面'],   # 命令别名，主要用于帮助和开关
}

# 管理员插件
__plugin_settings__ = {
    "admin_level": 1,       # 管理员等级，建议设置在5及以下，敏感操作设置在5以上
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# __plugin_task__

类型：Dict[str, Union[str, str]]
说明：
为你提供一个或多个开关，主要用于被动类插件的开关
示例：

# 定义开关
__plugin_task__ = {
    "名称": "开关中文名",
    "abcd": "统计开关",
    "...": "..."
}

# 使用被动技能控制页面的方法（推荐！
# 使用最最基本的控制：在插件中设置（不推荐

# 导入管理器
from utils.manager import group_manager

# 下方法为最最基本的插件控制
async def _(...):
    if await group_manager.check_group_task_status(event.group_id, "名称"):
        ...
    if await group_manager.check_group_task_status(event.group_id, "abcd"):
        ...

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# __plugin_type__

类型：Tuple[Union[str, int]]
说明：
为普通插件分类，当没有__plugin_type__时，将统一放置普通功能分类中
相同分类的插件在帮助图片中将会统合在一起
示例：

# 定义格式：
# 排列：无或0时：横向排列，1：列项排序(当你的__plugin_cmd__指令很多，建议使用 1)
__plugin_type__ = (分类名称, 详细帮助中的排列)
# 创建一个`工具`的分类
__plugin_type__ = ('工具',)
# 创建一个`原神相关`的分类，并在详细功能中命令以列向排列显示
__plugin_type__ = ('原神相关', 1)

1
2
3
4
5
6
7

# __plugin_version__

类型：Union[float, int]
说明：
插件版本，将作为插件自动更新的依照

# __plugin_author__

类型：str
说明：
插件作者

# __plugin_cd_limit__

类型：Dict[str, Optional[Union[int, str]]]
说明：
插件cd限制

# 以下为默认值
__plugin_cd_limit__ = {
    "cd": 5,                # 限制 cd 时长
    "check_type": "all",    # 'private'/'group'/'all'，限制私聊/群聊/全部
    "limit_type": "user",   # 监听对象，以user_id或group_id作为键来限制，'user'：用户id，'group'：群id
    "rst": None,            # 回复的话，为None时不回复，可以添加[at]，[uname]，[nickname]来对应艾特，用户群名称，昵称系统昵称
    "status": true          # 此限制的开关状态
}

# 可以只添加需要的内容，其他选用默认值
__plugin_cd_limit__ = {
    "cd": 10,
    "rst": "冷静点，别冲了！"
}
# 甚至全部使用默认值
__plugin_cd_limit__ = {}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# __plugin_block_limit__

类型：Dict[str, Optional[str]]
说明：
插件阻塞限制

# 以下为默认值
__plugin_block_limit__ = {
    "check_type": "all",    # 'private'/'group'/'all'，限制私聊/群聊/全部
    "limit_type": "user",   # 监听对象，以user_id或group_id作为键来限制，'user'：用户id，'group'：群id
    "rst": None,            # 回复的话，为None时不回复，可以添加[at]，[uname]，[nickname]来对应艾特，用户群名称，昵称系统昵称
    "status": true          # 此限制的开关状态
}
# 可以只添加需要的内容，其他选用默认值
__plugin_block_limit__ = {
    "rst": "你正在冲！"
}
# 甚至全部使用默认值
__plugin_block_limit__ = {}

1
2
3
4
5
6
7
8
9
10
11
12
13

# __plugin_count_limit__

类型：Dict[str, Optional[Union[int, str]]]
说明：
插件每日调用次数限制

# 以下为默认值
__plugin_count_limit__ = {
    "max_count": 5,    # 每日次数限制数量
    "limit_type": "user",   # 监听对象，以user_id或group_id作为键来限制，'user'：用户id，'group'：群id
    "rst": None,            # 回复的话，为None时不回复，可以添加[at]，[uname]，[nickname]来对应艾特，用户群名称，昵称系统昵称
    "status": true          # 此限制的开关状态
}
# 可以只添加需要的内容，其他选用默认值
__plugin_count_limit__ = {
    "max_count": 10,
    "rst": "你今天没得冲了！"
}
# 甚至全部使用默认值
__plugin_count_limit__ = {}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# __plugin_resource__

类型：Dict[Union[str, Path], Union[str, Path]]
说明：
将插件目录下资源移动要指定文件夹并记录保存，在插件删除后自动删除对应资源文件

# 提供示例
__plugin_resources__ = {
    "cases": IMAGE_PATH
    }