NcatBot 文档

外观

NcatBot 生命周期

约 974 字大约 3 分钟

2025-02-08

简介

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

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

引导

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

以上过程称为引导，用于引导的代码称作引导程序。

插件模式引导

主动模式引导

环境检查

环境检查发生在调用 BotClient.run() 或者 BotClient.run_blocking() 时，包含以下步骤：

  1. 检查 NcatBot 安装：检查 NcatBot 是否通过 pip 安装。如果开启了 NcatBot 更新检查，则额外检查 NcatBot 是否有新版本可用，如果有新版本则提醒用户更新。
  2. 检查 NapCat 服务： 检查 ws_uri 中指定的 NapCat 服务是否能被连接并且可用, 如果可用则跳过环境检查、 NapCat 启动、引导登录，进入确认登录。
  3. 检查 NapCat 安装：NapCat 是否被正确安装。
  4. 安装或更新 NapCat：如果 NapCat 未安装，则安装 NapCat。如果开启了 NapCat 更新检查且 NapCat 有新版本可用, 则在用户确认后更新 NapCat。
  5. 配置 NapCat： 自动配置 NapCat 的各项内容, 以便 NcatBot 能正常连接 NapCat 服务. 如果你自行改动了 NapCat 配置, NcatBot 会直接覆盖掉你的修改.

连接 NapCat 服务

  1. 启动 NapCat 服务：Linux 通过命令行启动无感启动 NapCat。Windows 下会询问是否允许 NapCat 对计算机进行修改, 需要同意后才能启动。
  2. 引导登录：如果之前本地有登录记录，则会使用快速登录。否则需要扫描终端的二维码登录。
  3. 确认登录：通过 NapCat WebUI 接口确认登录结果，如果登录信息不一致，则终止运行并提醒。
  4. 连接 NapCat 服务：使用 WebSocket 协议连接到 NapCat 服务。

加载插件

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

运行

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

退出

注意

点 X 关闭属于异常退出, 不会触发退出流程。

插件模式按下 Ctrl+C 正常退出，或者主动模式调用对应 BotClient 实例的 exit 方法, 进入退出流程。

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

版权归属：huan-yp

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

© 2025 NcatBot