NcatBot 文档

外观

示例代码解析

约 1947 字大约 6 分钟

2025-02-08

NcatBot 是如何运作的？

最小示例

代码

python
# ========= 导入必要模块 ==========
from ncatbot.core import BotClient, GroupMessage, PrivateMessage
from ncatbot.utils.config import config
from ncatbot.utils.logger import get_log

# ========== 设置配置项 ==========
config.set_bot_uin("123456")  # 设置 bot qq 号 (必填)
config.set_root("123456")  # 设置 bot 超级管理员账号 (建议填写)
config.set_ws_uri("ws://localhost:3001")  # 设置 napcat websocket server 地址
config.set_token("")  # 设置 token (napcat 服务器的 token)

# ========== 创建 BotClient ==========
bot = BotClient()

# ========= 注册回调函数 ==========
_log = get_log()

@bot.group_event()
async def on_group_message(msg: GroupMessage):
    _log.info(msg)
    if msg.raw_message == "测试":
        await msg.reply(text="NcatBot 测试成功喵~")

@bot.private_event()
async def on_private_message(msg: PrivateMessage):
    _log.info(msg)
    if msg.raw_message == "测试":
        await bot.api.post_private_msg(msg.user_id, text="NcatBot 测试成功喵~")

# ========== 启动 BotClient==========
if __name__ == "__main__":
    bot.run()

导入必须的模块

python
from ncatbot.core import BotClient
from ncatbot.core.message import GroupMessage, PrivateMessage
from ncatbot.utils.config import config
from ncatbot.utils.logger import get_log

导入部分分为 4 段, 分别是:

  1. 导入 BotClient 类, 用于创建一个 bot 实例, NcatBot 的所有接口和功能都封装在这个类中.
  2. 导入 GroupMessage 和 PrivateMessage 类, 用于类型注解, 方便使用 IDE 的代码补全功能.
  3. 导入 get_log 函数, 用于获取日志实例, 输出日志信息方便调试.
  4. 导入 config 模块, 用于配置 bot 的相关参数.

设置配置项

python
# ========== 设置配置项 ==========
config.set_bot_uin("123456")  # 设置 bot qq 号 (必填)
config.set_root("123456")  # 设置 bot 超级管理员账号 (建议填写)
config.set_ws_uri("ws://localhost:3001")  # 设置 napcat websocket server 地址
config.set_token("")  # 设置 token (napcat 服务器的 token)

请参阅配置项

创建 bot 实例

python
# ========== 创建 bot 实例 ==========
bot = BotClient() # 创建一个 BotClient 实例

注意

一个程序中, 只允许创建一个 BotClient 实例.

注册回调函数

python
# ========= 注册回调函数 ==========
_log = get_log() # 获取日志实例, 输出日志信息方便调试
@bot.group_event()
async def on_group_message(msg: GroupMessage):
    _log.info(msg) # 打印收到的消息到日志中
    if msg.raw_message == "测试":
        await msg.reply("NcatBot 测试成功喵~")

@bot.private_event()
async def on_private_message(msg: PrivateMessage):
    _log.info(msg)
    if msg.raw_message == '测试':
        await bot.api.post_private_msg(msg.user_id, text="NcatBot 测试成功喵~")

使用 decorator @bot.group_event() 和 @bot.private_event() 来注册事件回调函数, 回调函数用于处理与之绑定的事件. 注意, 回调函数必须定义为异步函数, 也就是用 async def 来定义.

回调函数会在相应的事件发生后被调用, 例如这里的例子, 当用户在私聊中发送任意消息时, 都会调用 on_private_message 函数, 并将 msg 作为参数传入.

在 on_private_message 中, 编写了一些逻辑, 这里的逻辑是如果文本为 测试 时, 调用 API 向用户发送一条 NcatBot 测试成功喵~ 的消息.

在 on_group_message 中逻辑相同, 但是直接使用了简化的 API 调用方式来发送信息.

关于回调函数的定义和参数, 请查阅回调函数.

关于能够支持的事件, 请查阅事件上报.

关于调用 API 发送消息, 请查阅API 调用.

运行部分

python
# ========== 启动 BotClient==========
if __name__ == "__main__":
    bot.run()

NcatBot 默认会在同一台电脑上运行 NapCat 服务, 我们也只建议这么做. 了解 NcatBot 和 NapCat 的关系.

如果硬要把 NcatBot 和 NapCat 分开, 查阅使用远端 NapCat 接口.

对初学者的提醒

在 Python 中, 每个模块都有一个特殊的内置变量 __name__. 它的值取决于模块是如何被运行的:

  • 如果模块是被直接运行的 (例如, 你直接运行一个脚本文件), __name__ 的值会被设置为 '__main__'.
  • 如果模块是被其他模块导入的 (例如, 你在其他脚本中用 import 导入了这个模块), __name__ 的值会是模块的名称(通常是文件名, 不带 .py 后缀).

使用 import xxx 或者 from xxx import yyy 时, xxx 文件中的所有代码都会被执行一遍.

例如, 你复制的示例代码就是被 直接运行 的, 而代码中导入的 ncatbot.client 等代码就是被其它模块导入 的.

尽管在这里 if __name__ == '__main__': 并不是必须的, 因为 main.py 一定会被直接运行, 但这不失为一种良好的编程习惯.

NcatBot 生命周期

NcatBot 的生命周期按照时间顺序分为以下几步:

  • 引导
  • 环境检查
  • 连接 NapCat 服务
  • 加载插件
  • 运行
  • 退出

引导

  1. 导入必要的模块
  2. 设置配置项
  3. 创建 BotClient 实例
    1. 检查配置项是否合法, 检查是否已经创建过 BotClient 实例.
    2. 初始化 BotAPI.
    3. 初始化事件总线和内置功能.
    4. 加载功能注册钩子.
    5. 加载权限数据.
  4. 注册回调函数(可选)
  5. 启动 BotClient 实例

以上过程称为启动, 用于启动的代码称作引导程序. 上面的代码就是一个引导程序.

因此, 无论是插件项目还是 BotClient 项目, 都需要运行引导程序来启动.

环境检查

环境检查发生在调用 BotClient.run() 时.

  1. 检查 NcatBot 是否通过 pip 安装, 检查 NcatBot 是否有新版本可用, 在 BotClient.run() 中指定 debug=True 可以跳过检查.
  2. 检查 ws_uri 中指定的 NapCat 服务是否能被连接并且可用, 如果可用直接跳过本部分以及下一部分, 直接进行插件加载.
  3. 检查 NapCat 是否被正确安装, 见 NapCat 是否有新版本可用, 如果没有安装或者有新版本, 则询问是否安装或更新.
  4. 安装或更新 NapCat.(可选)
  5. 配置 NapCat, 自动配置 NapCat 的各项内容, 以便 NcatBot 能正常连接 NapCat 服务. 如果你自行改动了 NapCat 配置, NcatBot 会直接覆盖掉你的修改.

连接 NapCat 服务

  1. 启动 NapCat 服务, Windows 下会询问是否允许 NapCat 对计算机进行修改, 需要同意.
  2. 引导登录(如果之前本地有登录记录, 则会使用快速登录), 需要扫描二维码登录.
  3. 连接 NapCat 服务.

加载插件

  1. 查找工作目录下的 plugins 目录, 读取插件 meta 信息.
  2. 根据插件 meta 中的依赖信息构建加载拓扑图.
  3. 加载每个插件
    1. 加载插件私有可持久化数据(包括配置项).
    2. 调用插件 BasePlugin.on_load 函数, 执行自定义初始化操作.
    3. 事件总线注册插件功能和插件配置项.

运行

  1. 启动 WebSocket, 监听来在 NapCat 的事件并上报. 事件对应的回调函数被调用, 同时事件上报到事件总线.
  2. 处理事件
    • 事件回调函数直接处理事件.
    • 事件进入事件总线, 激活功能函数, 并调用订阅了该事件的所有回调函数
  3. 事件被拦截或者被处理
    • 订阅事件的回调函数可以拦截该事件, 阻止其继续传播.
    • 订阅事件的回调函数可以添加事件的处理结果, 以便和其它部分通信.

退出

按下 Ctrl+C 正常退出后, 进入退出流程, 点 X 关闭属于异常退出, 不会触发退出流程.

  1. 保存权限数据.
  2. 调用 BasePlugin._unload_ 函数, 完成自定义卸载操作.
  3. 保存插件私有可持久化数据(包括配置项).
  4. 关闭 NapCat 服务(可选, 默认不关闭).

版权归属：huan-yp

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

© 2025 NcatBot