NcatBot 文档

外观

开发指南

约 3009 字大约 10 分钟

2025-03-25

NcatBot 的几种开发范式

主动模式（原先叫嵌入模式）

主动模式下，进程的管理权限由你持有。使用 BotClient.run_blocking() 方法启动，该方法会返回一个 BotAPI 实例，通过该实例可以调用 NcatBot 提供的接口。退出时需要使用 BotClient.exit() 方法通知 NcatBot 完成退出操作。再结束进程。

主动模式下，NcatBot 就是一个普通的第三方模块，你可以按照任何你喜欢的方式布局你的项目。

插件模式

插件模式下，进程的管理权限由 NcatBot-PluginSystem 持有。使用 BotClient.run() 方法启动，调用后进程控制权被转交。启动后可以使用 Ctrl+C 正常退出。

插件项目是 NcatBot 的核心, 也是 NcatBot 的主要开发范式. 插件项目有一定的目录结构要求和命名规范要求. 与之对应的, 插件项目具有便利的功能支持和丰富的社区生态, 通过插件项目, 可以开发出功能强大, 分发容易的 QQ 机器人.

一些澄清

主动模式和插件模式唯一的区别是控制权所属。主动模式下，只要调用了 BotClient.run_blocking() 方法，也会加载工作目录下 plugins/ 中的插件。NcatBot 及其插件被抽象为一个 BotClient 实例。

从实际项目快速了解

学习路径

插件模式

主动模式

文档导航

1. 快速开始

1. 快速开始: 了解如何快速上手 NcatBot.

1.1. Linux 安装: Linux 安装 NcatBot.

1.2. Windows 安装: Windows 安装 NcatBot.

1.3. MacOS 安装(暂不提供官方支持): MacOS 安装 NcatBot.

1.4. Windows 一键安装: Windows 下载 .exe 文件安装 NcatBot.

1.5 极简安装指南: 给熟练的同学快速上手 NcatBot.

2. 开发指南: 了解如何基于 NcatBot 开发 QQ 机器人.

3. 安装和使用插件: 基于 NcatBot 开发的 QQ 机器人通常以插件的形式发布, 了解如何安装和使用插件.

2. 基本开发

1. 插件模式最小示例: 插件模式最小示例和代码解析。

2. 主动模式最小示例: 主动模式最小示例和代码解析.

3. NcatBot 生命周期: 了解 NcatBot 的运行生命周期.

4. 配置项: 介绍 NcatBot 的配置项, 了解可自定义的内容.

5. 主动模式开发: 主动模式开发介绍。

3. 事件处理

1. 回调函数: 了解 NcatBot 如何处理事件, 了解 NcatBot 向回调函数传递的的事件参数.

2. 事件上报: 了解 NcatBot 可以监听哪些 QQ 事件. 以及如何获取这些事件的有关信息

3. 消息解析: 特别了解如何解析消息, 以及如何获取消息的详细信息.

4. API 参考

1. API 调用: 了解 NcatBot 的 API 调用方式.

2. 主要 API 说明: 了解如何使用 NcatBot 的主要 API, 例如如何发送消息和文件等.

3. 其它 API 说明: 了解如何使用 NcatBot 的其它 API, 例如如何获取群成员信息, 通过加群申请等.

5. 杂项

1. 认识 NcatBot: 了解 NcatBot 社区和历史.

2. 使用远端 napcat 接口: NcatBot 如何使用位于另外一台计算机上的 NapCat 接口.

3. 日志: NcatBot 的日志系统主要用于调试, 如果遇到问题需要求助, 请附上日志文件.

4. 轻松上云: NcatBot 与 IDC 服务商有合作, 利用合作服务商的云服务, 可以轻松且经济地部署 NcatBot 上云.

5. CLI: NcatBot-CLI 用于管理 NcatBot 的插件, 了解如何使用 NcatBot-CLI 以便于开发 NcatBot 插件.

6. 术语表: 了解 NcatBot 的术语.

7. AI+NcatBot: 如何使用 AI 高效开发 NcatBot。

6. 开发 NcatBot 插件

1. 了解 NcatBot 插件: 对 NcatBot 插件的基本了解.

2. 插件的加载和卸载: 插件的生命周期始于加载, 终于卸载, 了解 NcatBot 插件的加载卸载过程.

3. 插件的交互系统:

  • 事件的发布和订阅: 插件可以监听广义事件, 即 QQ 事件和插件事件. 插件也可以发布自定义事件. 了解事件如何被发布、订阅和处理.
  • 注册功能: 插件能够注册自定义功能, 功能是对事件及其处理的上层抽象, 通过功能可以更高效的设计 QQ Bot.
  • 权限系统: 权限系统用于决定每个特定功能能被哪些用户和群聊使用, 让你的插件更加安全.
  • 内置功能: NcatBot 内置了多个功能以方便插件开发, 了解如何使用这些功能.

4. 插件高级功能:

  • 内置可持久化数据: NcatBot 插件系统可以持久化数据, 使用内置可持久化数据可以方便的长期保存 Bot 运行时数据.
  • 依赖其它插件: 插件可以依赖其它插件, 以便构建更加强大的插件.
  • 依赖第三方 Python 库: 插件可以依赖第三方 Python 库, 以便使用第三方库提供的功能.
  • 私有工作目录: NcatBot 禁止插件进行 os.chdir 切换目录操作, 使用私有工作目录上下文可以方便的进行文件和路径操作.
  • 定时任务: NcatBot 插件可以注册定时任务, 让你的 Bot 提醒你上早八吧.

5. 发布你的插件: NcatBot 提供插件的快速分发和快速部署方案, 了解如何发布你的插件以便用户能够便捷使用. 6. 个人插件: 在确保只有个人使用需求时，可以忽略一些插件模式的限制。

7. 常见问题

1. 安装时常见问题: 安装或者首次运行 NcatBot 时能够遇到的常见问题.

2. 运行时常见问题: (非首次)运行时可能遇到的问题.

3. 开发时常见问题: 进行开发或者功能测试时可能遇到的文件.

8. 实际项目参考

综合教程项目:

1. 简单 BotClient 项目: BotClient 项目的示例.

2. LLM_API 插件项目: 插件项目示例————LLM_API.

版权归属：huan-yp

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

© 2025 NcatBot