插件结构
约 1186 字大约 4 分钟
2026-03-19
manifest.toml 清单文件、目录布局、基类选择和插件属性详解。
目录
标准目录布局
一个 NcatBot 插件的最小结构只需两个文件:
plugins/
└── my_plugin/
├── manifest.toml # 插件清单(必须)
└── main.py # 入口文件(必须)带资源文件的完整布局:
plugins/
└── my_plugin/
├── manifest.toml # 插件清单
├── main.py # 入口文件
├── resources/ # 静态资源(图片、文件等)
│ ├── logo.png
│ └── template.txt
├── utils.py # 辅助模块
└── models.py # 数据模型示例参考:examples/qq/04_bot_api/ 包含
resources/目录。
所有插件放在 plugins/ 目录下(可通过 config.yaml 的 plugin.plugins_dir 配置),框架启动时自动扫描加载。
manifest.toml 详解
每个插件必须在根目录下有一个 manifest.toml 文件,框架通过它识别和管理插件。
最小示例
name = "hello_world"
version = "1.0.0"
main = "main.py"完整示例
name = "external_api"
version = "1.0.0"
main = "main.py"
entry_class = "ExternalAPIPlugin"
author = "NcatBot"
description = "外部 API 集成 — HTTP 请求、配置管理、错误处理"
[dependencies]
some_plugin = ">=1.0.0" # 依赖其他插件
[pip_dependencies]
aiohttp = ">=3.8.0" # pip 依赖字段说明
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
name | str | ✅ | — | 插件唯一标识符,全局不可重复 |
version | str | ✅ | — | 语义化版本号(如 "1.0.0") |
main | str | ✅ | — | 入口文件名(带或不带 .py 后缀) |
entry_class | str | ❌ | 自动发现 | 插件类名;省略时框架自动查找第一个 BasePlugin 子类 |
author | str | ❌ | "Unknown" | 作者 |
description | str | ❌ | "" | 插件描述 |
dependencies | Dict[str, str] | ❌ | {} | 依赖的其他插件,格式:插件名 = "版本约束" |
pip_dependencies | Dict[str, str] | ❌ | {} | pip 依赖,格式:包名 = "版本约束" |
依赖声明
插件依赖:在 [dependencies] 中声明对其他插件的依赖,框架会自动按拓扑排序加载:
[dependencies]
rbac = ">=1.0.0" # 依赖 rbac 插件 1.0.0 或更高版本
config_manager = ">=0.5.0"pip 依赖:在 [pip_dependencies] 中声明 Python 包依赖,框架在加载时自动检查并提示安装:
[pip_dependencies]
aiohttp = ">=3.8.0"
beautifulsoup4 = ">=4.12.0"依赖解析的详细机制参见 高级主题 — 插件依赖管理。
插件基类
NcatBot 提供两个插件基类:
BasePlugin vs NcatBotPlugin
| 特性 | BasePlugin | NcatBotPlugin |
|---|---|---|
| 生命周期 | ✅ on_load() / on_close() | ✅ |
| 事件处理器注册 | ✅ @registrar.on_*() | ✅ |
| Bot API 访问 | ✅ self.api | ✅ |
| 配置持久化 | ❌ | ✅ ConfigMixin |
| 数据持久化 | ❌ | ✅ DataMixin |
| 权限管理 | ❌ | ✅ RBACMixin |
| 定时任务 | ❌ | ✅ TimeTaskMixin |
| 事件流 | ❌ | ✅ EventMixin |
推荐使用 NcatBotPlugin——它继承了所有 Mixin 能力,开箱即用:
from ncatbot.plugin import NcatBotPlugin
class MyPlugin(NcatBotPlugin):
name = "my_plugin"
version = "1.0.0"NcatBotPlugin 的 MRO(方法解析顺序)
class NcatBotPlugin(BasePlugin, EventMixin, TimeTaskMixin, RBACMixin, ConfigMixin, DataMixin):
passMRO 决定了 Mixin 钩子的执行顺序:
- 加载:EventMixin → TimeTaskMixin → RBACMixin → ConfigMixin → DataMixin
- 卸载:EventMixin → TimeTaskMixin → RBACMixin → ConfigMixin → DataMixin
各 Mixin 的详细 API 参见 Mixin 能力体系。
类属性与注入属性
插件元数据(子类定义)
class MyPlugin(NcatBotPlugin):
# -------- 必须定义 --------
name = "my_plugin" # 插件唯一标识
version = "1.0.0" # 版本号
# -------- 可选 --------
author = "Your Name" # 作者
description = "描述" # 插件描述
dependencies = {} # 插件依赖(同 manifest.toml)类属性中的
name/version必须与manifest.toml一致。
运行时注入属性
框架在加载插件时自动注入以下属性,可在 on_load() 及之后使用:
| 属性 | 类型 | 说明 |
|---|---|---|
self.workspace | Path | 插件工作目录(自动创建) |
self.api | BotAPIClient | Bot API 客户端,用于发送消息、群管理等 |
self.services | ServiceManager | 服务管理器,访问系统服务 |
self._dispatcher | AsyncEventDispatcher | 底层事件分发器(通常不直接使用) |
self._plugin_loader | PluginLoader | 插件加载器实例 |
self._manifest | PluginManifest | 插件清单数据 |
self._debug | bool | 是否为调试模式 |
便捷方法
# 获取其他插件实例
other = self.get_plugin("other_plugin_name")
# 列出所有已加载插件
names = self.list_plugins()
# 读取调试标志
if self.debug:
LOG.debug("调试模式")多文件插件组织
当插件逻辑较复杂时,可以拆分为多个文件:
plugins/
└── my_complex_plugin/
├── manifest.toml
├── main.py # 入口:导入并组合各模块
├── handlers.py # 事件处理器
├── services.py # 业务逻辑
└── models.py # 数据模型main.py(入口文件)中导入其他模块:
from ncatbot.plugin import NcatBotPlugin
from ncatbot.core import registrar
from ncatbot.event.qq import GroupMessageEvent
# 相对导入同目录下的模块
from .services import MyService
from .models import UserData
class MyComplexPlugin(NcatBotPlugin):
name = "my_complex_plugin"
version = "1.0.0"
async def on_load(self):
self.service = MyService()
@registrar.on_group_command("查询")
async def on_query(self, event: GroupMessageEvent, keyword: str):
result = await self.service.search(keyword)
await event.reply(result)框架会将插件根目录(
plugins/)添加到sys.path,因此每个插件文件夹相当于一个 Python 包。详细的跨插件导入机制参见 高级主题 — 跨插件交互。
下一步
- 生命周期 — 了解
on_load()/on_close()在整个加载流程中的位置 - 事件处理 — 学习用装饰器注册事件处理器
- Mixin 能力体系 — 使用配置、数据、权限、定时任务等 Mixin
版权所有
版权归属:huan-yp
