后端即时通讯【免费下载链接】nonebot2跨平台 Python 异步聊天机器人框架 / Asynchronous multi-platform chatbot framework written in Python项目地址https://gitcode.com/gh_mirrors/no/nonebot2点击查看免费下载NoneBot2 通过nonebot.plugin.model模块定义了插件系统的两大核心数据模型——PluginMetadata插件元信息由插件作者声明与Plugin插件运行时信息由框架在加载时构建。本文以 官方 API 文档 为骨架结合仓库源码与测试用例逐字段讲解两者的含义、格式约定与实际用法帮助你正确编写插件元信息、理解嵌套插件机制并掌握通过id_、module_name等标识在运行时定位插件的能力。模块定位插件信息的两个层面nonebot.plugin.model是 NoneBot2 插件体系的信息模型层它只负责定义数据结构不负责加载逻辑。加载流程由nonebot.plugin.managerPluginManager、PluginFinder、PluginLoader与nonebot.plugin.loadload_plugin、load_plugins等接口完成而本模块中的两个dataclass类则是整个流程的产物容器PluginMetadata作者声明的信息通过模块级变量__plugin_meta__提供给框架Plugin框架构建的信息在模块执行前由PluginLoader创建并挂载为模块属性__plugin__。两者配合构成了 nonebot/plugin/model.py 的完整定义。PluginMetadata插件作者声明的元信息PluginMetadata是一个dataclass(eqFalse)数据类包含 8 个字段与 1 个方法。插件作者通常在插件模块顶部创建其实例并赋值给__plugin_meta__例如仓库测试插件 tests/plugins/metadata.pyfrom pydantic import BaseModel from nonebot.adapters import Adapter from nonebot.plugin import PluginMetadata class Config(BaseModel): custom: str class FakeAdapter(Adapter): ... __plugin_meta__ PluginMetadata( name测试插件, description测试插件元信息, usage无法使用, typeapplication, homepagehttps://nonebot.dev, configConfig, supported_adapters{~onebot.v11, plugins.metadata:FakeAdapter}, extra{author: NoneBot}, )必填字段字段类型说明namestr插件名称descriptionstr插件功能介绍usagestr插件使用方法三个字段均为str且是构造PluginMetadata时必须提供的参数无默认值其余字段均可省略。它们通常会被插件商店、帮助系统等消费用于向用户展示这个插件是什么、怎么用。可选字段字段类型默认值说明typestr \| NoneNone插件类型用于商店分类homepagestr \| NoneNone插件主页configtype[BaseModel] \| NoneNone插件配置项模型pydanticBaseModel子类supported_adaptersset[str] \| NoneNone插件支持的适配器模块路径集合extradict[Any, Any]{}插件额外信息可自由扩展其中extra使用field(default_factorydict)保证每次实例化都得到独立字典避免 dataclass 可变默认值的陷阱。config字段接收一个 pydantic 模型类而非实例配合 get_plugin_config 可以从全局配置中解析出插件专属配置对象。supported_adapters 的格式约定supported_adapters是插件作者声明本插件兼容哪些适配器的集合格式为module[:Adapter]并有两条关键约定~是nonebot.adapters.的缩写如~onebot.v11等价于nonebot.adapters.onebot.v11None即不声明该字段表示支持所有适配器。每条声明可细分为两种形态仅模块路径~onebot.v11此时默认取该模块的Adapter类模块路径 冒号 适配器类名plugins.metadata:FakeAdapter用于指定非默认命名的适配器类。该格式在 nonebot/plugin/model.py 的 docstring 中有明确定义。get_supported_adapters()把字符串解析为适配器类PluginMetadata.get_supported_adapters()是唯一的方法用于获取当前已安装的插件支持适配器类列表返回set[type[Adapter]] | None。其实现nonebot/plugin/model.py逻辑如下def get_supported_adapters(self) - set[Type[Adapter]] | None: if self.supported_adapters is None: return None adapters set() for adapter in self.supported_adapters: with contextlib.suppress(ModuleNotFoundError, AttributeError): adapters.add( resolve_dot_notation(adapter, Adapter, nonebot.adapters.) ) return adapters若supported_adapters为None直接返回None表示全适配器支持否则对集合中每条字符串调用resolve_dot_notation(adapter, Adapter, nonebot.adapters.)即以nonebot.adapters.为默认前缀解析点分割路径并取出名为Adapter的属性使用contextlib.suppress(ModuleNotFoundError, AttributeError)静默跳过适配器未安装或属性不存在的条目——这意味着未安装的适配器会被自动过滤返回的集合只包含当前环境中真实可用的适配器类。从源码结构可以推断该方法的典型使用场景是框架在加载插件后将插件元信息中的适配器声明解析为实际类用于适配器层面的兼容性判断。Plugin框架构建的插件运行时信息Plugin同样是dataclass(eqFalse)但它不是由插件作者创建而是由PluginLoader.exec_module在模块执行前通过_new_plugin构造nonebot/plugin/manager.py# create plugin before executing plugin _new_plugin(self.name, module, self.manager) setattr(module, __plugin__, plugin)随后模块代码执行完毕后框架读取__plugin_meta__并回填到plugin.metadatametadata: PluginMetadata | None getattr(module, __plugin_meta__, None) plugin.metadata metadata因此对插件作者而言Plugin是只读的运行时视图可通过nonebot.get_plugin(plugin_id)、nonebot.get_loaded_plugins()等接口获取见 nonebot/plugin/init.py。字段一览字段类型说明namestr插件名称NoneBot 使用文件/文件夹名称作为插件名称moduleModuleType插件模块对象module_namestr点分割模块路径managerPluginManager导入该插件的插件管理器matcherset[type[Matcher]]插件加载时定义的Matcher集合parent_pluginPlugin \| None父插件嵌套插件场景下非Nonesub_pluginsset[Plugin]子插件集合metadataPluginMetadata \| None插件元信息注意matcher的默认值为field(default_factoryset)。从源码结构看当插件模块顶层代码调用on_command、on_message等注册函数创建 Matcher 时它们会被自动登记到当前插件即_current_plugin上下文变量指向的Plugin的matcher集合中。id_插件的索引标识id_是一个只读propertynonebot/plugin/model.pyproperty def id_(self) - str: return ( f{self.parent_plugin.id_}:{self.name} if self.parent_plugin else self.name )顶层插件id_就是插件名称如export嵌套子插件id_为父插件id:子插件名称如nested:nested_subplugin。该标识是nonebot.get_plugin()等接口的查找键且保证全局唯一——若出现重复_new_plugin会抛出RuntimeError(Plugin ... already exists!)nonebot/plugin/init.py。源码验证嵌套插件与标识解析仓库测试 tests/plugins/nested/init.py 演示了嵌套插件的构建方式父插件plugins.nested通过PluginManager(search_path[...])声明子插件目录随后加载plugins.nested.plugins.nested_subplugin。对应的 tests/test_plugin/test_get.py 验证了标识解析规则plugin.id_ nested:nested_subplugin子插件标识为父插件 id 冒号 子插件名plugin.module_name plugins.nested.plugins.nested_subplugin模块路径保留完整点分割形式get_plugin_by_module_name(plugins.nested.utils)能通过子模块名反查父插件nested——该函数会逐级向上切割模块名进行匹配nonebot/plugin/init.py。另外PluginManager._prepare_plugins会跳过以_开头的模块nonebot/plugin/manager.py仓库中的 tests/plugins/_hidden.py内含pytest.fail(should not be imported)正是用于验证该行为——以_开头的文件不会被当作插件加载。实战要点如何正确编写与读取插件信息声明元信息在插件模块顶层定义__plugin_meta__ PluginMetadata(...)必填name、description、usage需要商店分类时填type需要声明适配器兼容性时填supported_adapters自定义信息放入extra。适配器声明格式~onebot.v11或nonebot.adapters.onebot.v11均可需要指定非默认类名时用module:AdapterClass不声明该字段即代表全适配器支持。运行时取用通过nonebot.get_plugin(插件id)获取Plugin读取.metadata获得作者声明的元信息通过get_loaded_plugins()遍历全部已加载插件get_available_plugin_names()则返回包含未加载插件在内的全部可用标识nonebot/plugin/init.py。嵌套插件注意子插件id_一定带父插件前缀若插件目录结构会嵌套务必用get_plugin时携带完整父:子标识。关联阅读PluginManager 与加载流程理解Plugin的manager字段如何驱动加载PluginMetadata 源码、加载实现、加载接口适配器基类 Adapterget_supported_adapters()返回值所引用的类型Matcher 定义Plugin.matcher集合中的元素类型赞分享后端即时通讯【免费下载链接】nonebot2跨平台 Python 异步聊天机器人框架 / Asynchronous multi-platform chatbot framework written in Python项目地址https://gitcode.com/gh_mirrors/no/nonebot2点击查看免费下载相关推荐NoneBot2 插件数据库开发指南使用 nonebot-plugin-orm 实现模型、迁移与依赖注入NoneBot2 插件数据库开发指南使用 nonebot plugin orm 实现模型、迁移与依赖注入 本篇指南围绕 NoneBot2 生态中的数据库支持插后端即时通讯Omi Plugin SDK 深度解析Omi 插件 Webhook 数据模型的 Python 共享层Omi Plugin SDK 深度解析Omi 插件 Webhook 数据模型的 Python 共享层 导读 omi plugin sdk 是 Omi 开源仓库人工智能AI 应用语音移动开发后端桌面应用智能硬件MCP 服务30分钟上手GPTeam多智能体协作模拟的终极入门教程30分钟上手GPTeam多智能体协作模拟的终极入门教程 GPTeamGitHub 加速计划是一个开源的多智能体模拟系统它利用GPT 4创建多个智能体通上一篇Wand-Enhancer 免费完整指南解锁Pro功能与手机远程操控设置下一篇纸质文档一键变电子档OpenNoteScanner自动边缘检测与透视校正技术揭秘创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
NoneBot2 插件数据模型深度解析：PluginMetadata 与 Plugin 源码级指南
后端即时通讯【免费下载链接】nonebot2跨平台 Python 异步聊天机器人框架 / Asynchronous multi-platform chatbot framework written in Python项目地址https://gitcode.com/gh_mirrors/no/nonebot2点击查看免费下载NoneBot2 通过nonebot.plugin.model模块定义了插件系统的两大核心数据模型——PluginMetadata插件元信息由插件作者声明与Plugin插件运行时信息由框架在加载时构建。本文以 官方 API 文档 为骨架结合仓库源码与测试用例逐字段讲解两者的含义、格式约定与实际用法帮助你正确编写插件元信息、理解嵌套插件机制并掌握通过id_、module_name等标识在运行时定位插件的能力。模块定位插件信息的两个层面nonebot.plugin.model是 NoneBot2 插件体系的信息模型层它只负责定义数据结构不负责加载逻辑。加载流程由nonebot.plugin.managerPluginManager、PluginFinder、PluginLoader与nonebot.plugin.loadload_plugin、load_plugins等接口完成而本模块中的两个dataclass类则是整个流程的产物容器PluginMetadata作者声明的信息通过模块级变量__plugin_meta__提供给框架Plugin框架构建的信息在模块执行前由PluginLoader创建并挂载为模块属性__plugin__。两者配合构成了 nonebot/plugin/model.py 的完整定义。PluginMetadata插件作者声明的元信息PluginMetadata是一个dataclass(eqFalse)数据类包含 8 个字段与 1 个方法。插件作者通常在插件模块顶部创建其实例并赋值给__plugin_meta__例如仓库测试插件 tests/plugins/metadata.pyfrom pydantic import BaseModel from nonebot.adapters import Adapter from nonebot.plugin import PluginMetadata class Config(BaseModel): custom: str class FakeAdapter(Adapter): ... __plugin_meta__ PluginMetadata( name测试插件, description测试插件元信息, usage无法使用, typeapplication, homepagehttps://nonebot.dev, configConfig, supported_adapters{~onebot.v11, plugins.metadata:FakeAdapter}, extra{author: NoneBot}, )必填字段字段类型说明namestr插件名称descriptionstr插件功能介绍usagestr插件使用方法三个字段均为str且是构造PluginMetadata时必须提供的参数无默认值其余字段均可省略。它们通常会被插件商店、帮助系统等消费用于向用户展示这个插件是什么、怎么用。可选字段字段类型默认值说明typestr \| NoneNone插件类型用于商店分类homepagestr \| NoneNone插件主页configtype[BaseModel] \| NoneNone插件配置项模型pydanticBaseModel子类supported_adaptersset[str] \| NoneNone插件支持的适配器模块路径集合extradict[Any, Any]{}插件额外信息可自由扩展其中extra使用field(default_factorydict)保证每次实例化都得到独立字典避免 dataclass 可变默认值的陷阱。config字段接收一个 pydantic 模型类而非实例配合 get_plugin_config 可以从全局配置中解析出插件专属配置对象。supported_adapters 的格式约定supported_adapters是插件作者声明本插件兼容哪些适配器的集合格式为module[:Adapter]并有两条关键约定~是nonebot.adapters.的缩写如~onebot.v11等价于nonebot.adapters.onebot.v11None即不声明该字段表示支持所有适配器。每条声明可细分为两种形态仅模块路径~onebot.v11此时默认取该模块的Adapter类模块路径 冒号 适配器类名plugins.metadata:FakeAdapter用于指定非默认命名的适配器类。该格式在 nonebot/plugin/model.py 的 docstring 中有明确定义。get_supported_adapters()把字符串解析为适配器类PluginMetadata.get_supported_adapters()是唯一的方法用于获取当前已安装的插件支持适配器类列表返回set[type[Adapter]] | None。其实现nonebot/plugin/model.py逻辑如下def get_supported_adapters(self) - set[Type[Adapter]] | None: if self.supported_adapters is None: return None adapters set() for adapter in self.supported_adapters: with contextlib.suppress(ModuleNotFoundError, AttributeError): adapters.add( resolve_dot_notation(adapter, Adapter, nonebot.adapters.) ) return adapters若supported_adapters为None直接返回None表示全适配器支持否则对集合中每条字符串调用resolve_dot_notation(adapter, Adapter, nonebot.adapters.)即以nonebot.adapters.为默认前缀解析点分割路径并取出名为Adapter的属性使用contextlib.suppress(ModuleNotFoundError, AttributeError)静默跳过适配器未安装或属性不存在的条目——这意味着未安装的适配器会被自动过滤返回的集合只包含当前环境中真实可用的适配器类。从源码结构可以推断该方法的典型使用场景是框架在加载插件后将插件元信息中的适配器声明解析为实际类用于适配器层面的兼容性判断。Plugin框架构建的插件运行时信息Plugin同样是dataclass(eqFalse)但它不是由插件作者创建而是由PluginLoader.exec_module在模块执行前通过_new_plugin构造nonebot/plugin/manager.py# create plugin before executing plugin _new_plugin(self.name, module, self.manager) setattr(module, __plugin__, plugin)随后模块代码执行完毕后框架读取__plugin_meta__并回填到plugin.metadatametadata: PluginMetadata | None getattr(module, __plugin_meta__, None) plugin.metadata metadata因此对插件作者而言Plugin是只读的运行时视图可通过nonebot.get_plugin(plugin_id)、nonebot.get_loaded_plugins()等接口获取见 nonebot/plugin/init.py。字段一览字段类型说明namestr插件名称NoneBot 使用文件/文件夹名称作为插件名称moduleModuleType插件模块对象module_namestr点分割模块路径managerPluginManager导入该插件的插件管理器matcherset[type[Matcher]]插件加载时定义的Matcher集合parent_pluginPlugin \| None父插件嵌套插件场景下非Nonesub_pluginsset[Plugin]子插件集合metadataPluginMetadata \| None插件元信息注意matcher的默认值为field(default_factoryset)。从源码结构看当插件模块顶层代码调用on_command、on_message等注册函数创建 Matcher 时它们会被自动登记到当前插件即_current_plugin上下文变量指向的Plugin的matcher集合中。id_插件的索引标识id_是一个只读propertynonebot/plugin/model.pyproperty def id_(self) - str: return ( f{self.parent_plugin.id_}:{self.name} if self.parent_plugin else self.name )顶层插件id_就是插件名称如export嵌套子插件id_为父插件id:子插件名称如nested:nested_subplugin。该标识是nonebot.get_plugin()等接口的查找键且保证全局唯一——若出现重复_new_plugin会抛出RuntimeError(Plugin ... already exists!)nonebot/plugin/init.py。源码验证嵌套插件与标识解析仓库测试 tests/plugins/nested/init.py 演示了嵌套插件的构建方式父插件plugins.nested通过PluginManager(search_path[...])声明子插件目录随后加载plugins.nested.plugins.nested_subplugin。对应的 tests/test_plugin/test_get.py 验证了标识解析规则plugin.id_ nested:nested_subplugin子插件标识为父插件 id 冒号 子插件名plugin.module_name plugins.nested.plugins.nested_subplugin模块路径保留完整点分割形式get_plugin_by_module_name(plugins.nested.utils)能通过子模块名反查父插件nested——该函数会逐级向上切割模块名进行匹配nonebot/plugin/init.py。另外PluginManager._prepare_plugins会跳过以_开头的模块nonebot/plugin/manager.py仓库中的 tests/plugins/_hidden.py内含pytest.fail(should not be imported)正是用于验证该行为——以_开头的文件不会被当作插件加载。实战要点如何正确编写与读取插件信息声明元信息在插件模块顶层定义__plugin_meta__ PluginMetadata(...)必填name、description、usage需要商店分类时填type需要声明适配器兼容性时填supported_adapters自定义信息放入extra。适配器声明格式~onebot.v11或nonebot.adapters.onebot.v11均可需要指定非默认类名时用module:AdapterClass不声明该字段即代表全适配器支持。运行时取用通过nonebot.get_plugin(插件id)获取Plugin读取.metadata获得作者声明的元信息通过get_loaded_plugins()遍历全部已加载插件get_available_plugin_names()则返回包含未加载插件在内的全部可用标识nonebot/plugin/init.py。嵌套插件注意子插件id_一定带父插件前缀若插件目录结构会嵌套务必用get_plugin时携带完整父:子标识。关联阅读PluginManager 与加载流程理解Plugin的manager字段如何驱动加载PluginMetadata 源码、加载实现、加载接口适配器基类 Adapterget_supported_adapters()返回值所引用的类型Matcher 定义Plugin.matcher集合中的元素类型赞分享后端即时通讯【免费下载链接】nonebot2跨平台 Python 异步聊天机器人框架 / Asynchronous multi-platform chatbot framework written in Python项目地址https://gitcode.com/gh_mirrors/no/nonebot2点击查看免费下载相关推荐NoneBot2 插件数据库开发指南使用 nonebot-plugin-orm 实现模型、迁移与依赖注入NoneBot2 插件数据库开发指南使用 nonebot plugin orm 实现模型、迁移与依赖注入 本篇指南围绕 NoneBot2 生态中的数据库支持插后端即时通讯Omi Plugin SDK 深度解析Omi 插件 Webhook 数据模型的 Python 共享层Omi Plugin SDK 深度解析Omi 插件 Webhook 数据模型的 Python 共享层 导读 omi plugin sdk 是 Omi 开源仓库人工智能AI 应用语音移动开发后端桌面应用智能硬件MCP 服务30分钟上手GPTeam多智能体协作模拟的终极入门教程30分钟上手GPTeam多智能体协作模拟的终极入门教程 GPTeamGitHub 加速计划是一个开源的多智能体模拟系统它利用GPT 4创建多个智能体通上一篇Wand-Enhancer 免费完整指南解锁Pro功能与手机远程操控设置下一篇纸质文档一键变电子档OpenNoteScanner自动边缘检测与透视校正技术揭秘创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考