NcatBot 文档

外观

插件模式启动

约 387 字大约 1 分钟

2026-03-19

创建插件目录 + manifest.toml + NcatBotPlugin 子类 — 推荐的正式项目启动方式，支持配置持久化、权限控制、定时任务和热重载。

前提条件

方式一：使用 CLI 快速初始化

mkdir my-bot && cd my-bot
ncatbot init          # 交互式生成 config.yaml + 模板插件
ncatbot run           # 启动 Bot

ncatbot init 会生成完整的项目结构，包括一个可运行的模板插件。

开发时使用 ncatbot dev 代替 ncatbot run，自动开启 debug 模式和热重载。

方式二：手动创建

1. 项目结构

my-bot/
├── config.yaml
├── main.py              # 入口文件
└── plugins/
    └── hello_world/     # 插件目录
        ├── manifest.toml
        └── plugin.py

2. manifest.toml

name = "hello_world"
version = "1.0.0"
main = "plugin.py"
entry_class = "HelloWorldPlugin"
author = "你的名字"
description = "最小可运行插件"

[dependencies]
pip_dependencies = []

3. plugin.py

from ncatbot.plugin import NcatBotPlugin
from ncatbot.core import registrar
from ncatbot.event.qq import GroupMessageEvent
from ncatbot.utils import get_log

LOG = get_log("HelloWorld")

class HelloWorldPlugin(NcatBotPlugin):
    name = "hello_world"
    version = "1.0.0"

    async def on_load(self):
        LOG.info("HelloWorld 插件已加载！")

    async def on_close(self):
        LOG.info("HelloWorld 插件已卸载。")

    @registrar.on_group_command("hello", ignore_case=True)
    async def on_group_hello(self, event: GroupMessageEvent):
        await event.reply(text="Hello from plugin!")

4. main.py

from ncatbot.app import BotClient

bot = BotClient()

if __name__ == "__main__":
    bot.run()

5. 启动

python main.py

插件模式 vs 非插件模式

能力非插件模式插件模式
配置持久化（ConfigMixin）❌✅
数据存储（DataMixin）❌✅
权限控制（RBACMixin）❌✅
定时任务（TimeTaskMixin）❌✅
热重载❌✅
依赖管理❌✅

延伸阅读

版权归属：huan-yp

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

© 2025 NcatBot