koishi

Koishi

Koishi 是一个在 Node.js 环境下运行，基于 CoolQ 和 CQHTTP 的 QQ 机器人框架。

它的名字和图标来源于东方 Project 中的角色古明地恋（Komeiji Koishi）。

特性

开箱即用的 CLI

Koishi 高度配置化的 CLI 命令可以让你无需写代码就搭建属于你的机器人。与此同时，CLI 还配备了丰富和人性化的提示，进一步提高调试体验。

参见：快速上手 / 配置文件

功能强大的 API

Koishi 的 API 包括下面几个部分：

• Receiver：将收到的信息转化为事件进行分发，且同时支持 HTTP 和 WebSocket
• Sender：完美契合 CQHTTP API 的一套异步发送器，同样支持 HTTP 和 WebSocket
• Middleware：支持异步操作的中间件系统，可以让你高效地处理每一条信息
• Context：用上下文描述了机器人可能的运行环境，让你得以对不同的群进行不同的处理
• Plugin：将逻辑以插件的形式封装，可以实现更好的模块化和配置化
• Command：Koishi 的核心功能之一，使用链式调用轻松创建指令，同时提供了大量的实用特性
• Database：内置的数据库系统，但并不依赖具体的数据库实现，无论何种数据库都可以在 Koishi 中使用

每一个部分都经过了精心的编写，可以让你轻松实现任何需求。

参见：API 文档

丰富的生态系统

Koishi 在编写时，也同样编写了大量的官方插件作为补充。它们有些 Koishi 的基础功能，有些则为 Koishi 的使用提供了许多便利。更重要的是，这数十个插件都可以作为 Koishi 插件开发的极好示范。

参见：官方插件

多机器人支持

Koishi 原生地支持了多机器人开发，同时为这些机器人之间互通数据、共用服务器、保证数据安全提供了原生的解决方案，这有助于在保持高性能的同时，将腾讯风控造成的影响降低到最小。

参见：多机器人开发

类型与单元测试

Koishi 在开发时借助了下面的工具：

• 使用 TypeScript 编写
• 使用 Jest 进行单元测试
• 使用 Eslint 进行代码风格检查
• 使用 Codecov 进行覆盖率检测
• 使用 GitHub Actions 进行持续集成

这保证了其代码的正确性和可读性。

对比

特性	koishi 1.3.0	cqhttp 1.2.0	cq-websocket 2.0.2	lemon-bot 0.6.0	@ionjs/core 0.6.5
依赖数量	22 / 10	62	37	65	73
HTTP	✔️	✔️	❌	✔️	✔️
WebSocket	✔️	❌	✔️	❌	❌
反向 WebSocket	❌	❌	❌	❌	❌
监听器	✔️	✔️	✔️	❌	✔️
上下文	✔️	❌	❌	✔️	✔️
中间件	✔️	❌	❌	❌	✔️
命令行	✔️	❌	❌	❌	❌
指令	✔️	❌	❌	✔️	❌

注：依赖数量如果表示为 X/Y，则 X 表示命令行工具依赖数量， Y 表示核心库依赖数量。

安装

# 进入文件夹
cd my-bot

# 安装 Koishi
npm i koishi -g

# 初始化配置文件
koishi init

# 运行你的 Bot
koishi run

现在可以对你的机器人说话了：

> echo hello world
< hello world

注意: Koishi 要求您的 Node.js 的版本不小于 10，CQHTTP 的版本不小于 3.0。过低的 CQHTTP 版本将不会支持 Koishi 的某些功能。因此，我们建议您保持较新的 CQHTTP 版本以确保所有功能可用。

完整的文档在 这里。

更新日志

参见 releases。

贡献

如果想对 Koishi 做出贡献，可以参考下面的指南：

向本项目提交代码

1. Fork 本项目并下载到你的本地
2. 提交代码
3. 从你的分支发起 PR 到 master 分支

完善 Koishi 的文档

与上面类似，但是针对的是 这个项目。

开发 Koishi 插件

我们欢迎开发 Koishi 插件并发布到 NPM 供大家使用。如果愿意的话我们也会邀请插件开发者成为 Koishi 团队成员。

编写基于 Koishi 的机器人

我们欢迎编写基于 Koishi 的机器人。如果有得意的作品也可以告诉我们，我们将在未来提供专门用于展示社区机器人的地方。

支持项目作者