NcatBot 文档

外观

插件模式最小示例

约 775 字大约 3 分钟

2025-02-08

源代码

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

# ========== 创建 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(bt_uin="123456")

代码分析

导入必须的模块

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

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

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

创建 bot 实例

python
# ========== 创建 bot 实例 ==========
bot = BotClient() # 创建一个 BotClient 实例
_log = get_log() # 获取日志实例, 输出日志信息方便调试

注意

NcatBot 要求, 一个独立的进程只能创建唯一一个 BotClient 实例.

注册回调函数(可选)

python
# ========= 注册回调函数 ==========
@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 测试成功喵~")

@bot.group_event()
async def on_group_message(msg: GroupMessage):
    _log.info(msg) # 打印收到的消息到日志中
    if msg.raw_message == "测试":
        await msg.reply("NcatBot 测试成功喵~")

在函数前面添加 @bot.group_event() 或 @bot.private_event() 来注册回调函数。

回调函数会在相应的事件发生后被调用, 回调函数的参数包含了对应事件的信息。这里，当 Bot 收到私聊的消息时，会调用 on_private_message 函数, 并且将收到的消息作为参数传入。

在 on_private_message 中, 可以自行编写逻辑。 在这里，如果文本是 测试, 则调用 API 向用户发送一条 NcatBot 测试成功喵~ 的消息。

在 on_group_message，直接使用了简化的 API 调用方式来发送信息.

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

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

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

运行

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

执行 bot.run() 时，会在工作目录下 plugins/ 中查找并加载插件。bot.run() 会阻塞整个线程，直到 Ctrl+C 触发退出流程退出整个进程。

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

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

了解 NcatBot 生命周期

版权归属：huan-yp

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

© 2025 NcatBot