快速入门
约 1255 字大约 4 分钟
2026-03-19
5 分钟跑通你的第一个 NcatBot 插件。
目录
环境准备
| 依赖 | 要求 | 说明 |
|---|---|---|
| Python | ≥ 3.12 | python --version 验证 |
| uv | 最新版 | 推荐的包管理器,安装指南 |
| NapCat | 最新版 | QQ 协议端,NcatBot 会自动下载安装 |
提示
如果你还没有 uv,也可以直接用 pip。NapCat 在首次运行时会自动下载配置。
asyncio 速查
NcatBot 是一个 异步框架,插件中的事件处理器都是异步函数。如果你不熟悉 Python 异步编程,这里是 5 个核心概念:
import asyncio
# 1. async def 定义协程函数
async def greet(name: str) -> str:
return f"Hello, {name}"
# 2. await 等待协程完成并获取结果
async def main():
result = await greet("World")
print(result) # Hello, World
# 3. asyncio.create_task() 并发执行多个协程
async def main():
task1 = asyncio.create_task(greet("A"))
task2 = asyncio.create_task(greet("B"))
results = await asyncio.gather(task1, task2)
# 4. async for 异步迭代
async def consume(stream):
async for item in stream:
print(item)
# 5. async with 异步上下文管理器
async def use_resource():
async with some_resource() as res:
await res.do_something()在 NcatBot 中,你只需记住:
- 事件处理器用
async def定义 - 调用 API 时用
await(如await event.reply("hello")) - 框架负责运行事件循环,你不需要手动调用
asyncio.run()
安装 NcatBot
# 推荐:使用 uv
uv add ncatbot5
# 或者:使用 pip
pip install ncatbot5验证安装:
python -c "import ncatbot; print(ncatbot.__version__)"准备配置文件
在项目根目录创建 config.yaml:
# 必填:你的 QQ 号
bot_uin: '123456789'
# 可选:超级管理员 QQ 号
root: '123456'
# 适配器配置(NapCat 连接)
adapters:
- type: napcat
platform: qq
enabled: true
config:
ws_uri: ws://localhost:3001
ws_token: napcat_ws
# 插件配置
plugin:
plugins_dir: plugins # 插件目录
load_plugin: true # 是否加载插件将
bot_uin替换为你的实际 QQ 号。其他配置项保持默认即可,完整配置说明参见 配置管理指南。
启动 Bot
创建入口文件 main.py:
from ncatbot.app import BotClient
bot = BotClient()
if __name__ == "__main__":
bot.run()bot.run() 会依次完成:
- 加载
config.yaml配置 - 启动 NapCat(首次运行自动下载安装)
- 建立 WebSocket 连接
- 扫描
plugins/目录,加载所有插件 - 开始监听事件
编写第一个插件
1. 创建插件目录
plugins/
└── hello_world/
├── manifest.toml
└── main.py2. 编写 manifest.toml
每个插件必须有一个 manifest.toml 清单文件,声明插件的基本信息:
name = "hello_world"
version = "1.0.0"
main = "main.py"
entry_class = "HelloWorldPlugin"
author = "NcatBot"
description = "最小可运行插件 — 演示基础生命周期与消息回复"| 字段 | 必填 | 说明 |
|---|---|---|
name | ✅ | 插件唯一标识 |
version | ✅ | 语义化版本号 |
main | ✅ | 入口文件名 |
entry_class | ❌ | 插件类名(省略则自动发现) |
author | ❌ | 作者 |
description | ❌ | 插件描述 |
完整字段说明参见 插件结构 — manifest.toml 详解。
3. 编写 main.py
from ncatbot.core import registrar
from ncatbot.event.qq import GroupMessageEvent, PrivateMessageEvent
from ncatbot.plugin import NcatBotPlugin
from ncatbot.utils import get_log
LOG = get_log("HelloWorld")
class HelloWorldPlugin(NcatBotPlugin):
name = "hello_world"
version = "1.0.0"
author = "NcatBot"
description = "最小可运行插件 — 回复 hello"
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_hello(self, event: GroupMessageEvent):
"""收到群消息 'hello' 时回复"""
await self.api.qq.post_group_msg(event.group_id, text="Hello, World! 👋")
@registrar.on_group_command("hi", ignore_case=True)
async def on_hi(self, event: GroupMessageEvent):
"""用 event.reply() 快速回复(自动引用 + @发送者 + 文字)"""
await event.reply(text="你好呀!这是通过 event.reply() 发送的快速回复 🎉")
@registrar.on_private_command("hello", ignore_case=True)
async def on_private_hello(self, event: PrivateMessageEvent):
"""收到私聊消息 'hello' 时回复"""
await event.reply(text="你好!这是来自 HelloWorld 插件的私聊回复 👋")关键概念解读
| 元素 | 说明 |
|---|---|
NcatBotPlugin | 插件基类,内置了配置、数据、权限、定时任务等 Mixin 能力 |
on_load() | 插件加载时调用——在这里注册事件处理器、初始化数据 |
on_close() | 插件卸载时调用——在这里做清理工作 |
@registrar.on_group_command("hello") | 注册群命令处理器:当群消息内容为 "hello" 时触发 |
@registrar.on_private_command("hello") | 注册私聊命令处理器 |
event: GroupMessageEvent | 事件实体,包含消息内容、发送者、群号等信息 |
event.reply(text="...") | 便捷回复:自动引用原消息 + @发送者 |
self.api.qq.post_group_msg(group_id, text="...") | 直接调用 API 发送群消息 |
get_log("name") | 获取日志实例 |
运行与测试
# 启动 Bot
python main.py启动后:
- 在群里发送
hello→ 收到 "Hello, World! 👋" - 在群里发送
hi→ 收到引用回复 + @你 + "你好呀!..." - 私聊 Bot 发送
hello→ 收到私聊回复
如果看到日志 HelloWorld 插件已加载!,说明插件加载成功。
下一步
恭喜!你已经成功运行了第一个 NcatBot 插件。接下来推荐阅读:
版权所有
版权归属:huan-yp
