开发指南
约 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
实例。
从实际项目快速了解
学习路径
- 阅读你操作系统的安装方式.
- 阅读对应的最小示例.
- 阅读回调函数部分, 了解回调函数参数的数据格式.
- 阅读事件上报, 了解能够监听和处理的事件类型.
- 阅读API 调用, 了解如何调用 NcatBot 提供的 API.
- 阅读AI+NcatBot,了解如何正确使用 AI 开发基于 NcatBot 的项目。
- 阅读开发技巧,提高你的开发效率。
插件模式
主动模式
文档导航
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