插件结构

约 1211 字大约 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/03_rich_message/ 包含 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 依赖

取自 examples/common/06_external_api/manifest.toml。

字段说明

字段	类型	必填	默认值	说明
`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):
    pass

MRO 决定了 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

版权所有

版权归属：MI

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

通用

QQ

Bilibili

GitHub

通用

QQ