NcatBot 文档

外观

主动模式开发

约 918 字大约 3 分钟

2025-04-06

从 3.7.0 版本后, NcatBot 对嵌入开发的支持更加完善，使用 BotClient 类可以方便的将 Ncatbot 作为模块嵌入到你的 Python 项目中.

为了避免歧义，嵌入模式称为主动模式。

适用场景

对 NcatBot 插件功能依赖一般

目前的插件生态情况, 基本都可以用这个办法.

推荐以阻塞启动模式启动.

非阻塞模式下, NcatBot 需要手动调用退出函数来退出 NcatBot 以保证可持久化数据的完整性.

对 NcatBot 插件功能依赖非常强

如果你的项目高度依赖 NcatBot 插件的完善功能, 推荐以插件模式启动, 让 NcatBot 引导程序来管理插件, 你的项目作为守护进程运行.

你需要注意, Ncatbot 在接受 Ctrl+C 信号时, 进入退出流程, 你可能需要捕获这些信号以便你的项目也能正常退出.

阻塞启动模式(推荐)

BotClient 对象提供 run_blocking 方法以阻塞模式启动 NcatBot. NcatBot 启动完成后, 会返回一个 BotAPI 对象, 该对象提供 NcatBot 的所有接口.

同时提供 exit 方法以正常退出 NcatBot, exit 方法不会退出进程, 你可以继续做你的事情.

from ncatbot.core import BotClient

bot = BotClient()
api = bot.run_blocking(bt_uin="123456", root="1234567") # 启动 NcatBot, NcatBot 接口可用时返回 API 实例
api.post_private_msg_sync(12345678, "你好") # 此时 NcatBot 已经启动完成, 可以正常使用接口
bot.exit()
print("退出")

非阻塞启动模式

BotClient 对象提供 run_non_blocking 方法以非阻塞模式启动 NcatBot.

非阻塞启动的 NcatBot 没有完全准备好, 需要通过以下方式确保其正常运行.

提前引导 + sleep

启动 NcatBot 需要一定时间.

推荐先用引导程序完成一次启动引导, 不要关闭启动的 NapCat 服务. 接着再以非阻塞模式. 此时 NcatBot 将启动快速引导模式, 大约 sleep 10 秒后, NcatBot 就会进入正常运行模式.

此时所有接口均可用.

import time

from ncatbot.core import BotClient

bot = BotClient()
bot.run_non_blocking(bt_uin="123456", root="123456") # 在这里指定 QQ 运行参数, 可以替代全局变量 config
time.sleep(10) # 等待 NcatBot 启动完成

api.post_private_msg_sync(123456, "你好") # 此时 NcatBot 已经启动完成, 可以正常使用接口

STARTUP_EVENT 回调函数 + 锁

BotClient 对象提供针对 startup_event 事件的回调函数, 以在 NcatBot 接口可用发.

可以通过全局加锁的方式来精确地在 NcatBot 接口可用时执行你的代码.

from ncatbot.core import BotClient
from threading import Lock


lock = Lock()
lock.acquire() # 全局加锁

bot = BotClient()
bot.add_startup_handler(lambda: lock.release()) # 在 NcatBot 接口可用时, 释放全局锁
api = bot.run_non_blocking(bt_uin="123456", root="123456")
# 这里可以做点别的事情
lock.acquire() # 等待 NcatBot 启动完成
api.post_private_msg_sync(123456, "你好") # 此时 NcatBot 已经启动完成, 可以正常使用接口

引导模式

使用正常的 NcatBot 引导程序, 添加一个 startup 回调函数来引导你的项目启动.

你的项目必须以守护进程的形式在另一个线程运行.

from ncatbot.core import BotClient, BotAPI
from threading import Thread

def start_my_app(api:BotAPI):
    print("start my app")
    api.post_private_msg_sync("1234", "你好主动模式")

def start_my_app_warp():
    th = Thread(
        target=lambda api=bot.api:start_my_app(api),
        daemon=True,
    ) # 守护模式在另一个线程运行
    th.start()

bot = BotClient()
bot.add_startup_handler(start_my_app_warp) # NcatBot 启动时调用该回调函数
bot.run(bt_uin="1234", root="1234")

提醒

注意, 如果你需要同步调用 NcatBot 的 API, 请使用 xxx_xxx_sync 系列函数. 没有 _sync 后缀的函数都是异步函数.

版权归属：huan-yp

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

© 2025 NcatBot