NcatBot 文档

外观

插件模式启动

约 484 字大约 2 分钟

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 模式和热重载。

方式二：CLI 创建插件

方式三：手动创建

1. 项目结构

my-bot/
├── config.yaml
└── 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. 启动

ncatbot dev     # 开发模式：debug 日志 + 热重载
# 或
ncatbot run     # 生产模式

提示

如需自定义启动逻辑（异步编排、多适配器代码传参等），可创建 main.py 手动启动，参见 非插件模式。

插件模式 vs 非插件模式

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

延伸阅读

版权归属：MI

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

© 2025-2026 NcatBot