ByteNoteByteNote
字

字节笔记本

2026年3月22日

Koishi - 跨平台聊天机器人框架

#开源工具

本文介绍 Koishi，一个跨平台、可扩展、高性能的聊天机器人框架，支持 QQ、Telegram、Discord、飞书等主流聊天平台，拥有超过 3000 个社区插件，让开发者在几分钟内即可搭建属于自己的聊天机器人。

项目简介

Koishi 是一个用 TypeScript 编写的跨平台聊天机器人框架，它的名字和图标设计来源于东方 Project 中的角色古明地恋 (Komeiji Koishi)。这个名字既象征着聊天机器人的主题，也蕴含了开发者为之倾注的热爱与热情。

作为一个经过长达四年持续迭代的成熟项目，Koishi 已经发展出了丰富的插件生态和与之匹配的健壮系统框架。无论你的目标是构建大型交互应用还是轻量级的辅助机器人，Koishi 都能提供最佳的实践方案。项目在 GitHub 上已获得超过 5500 颗 Star，拥有 295 个 Fork，发布了 201 个版本，社区活跃度极高。

Koishi 的核心定位是降低聊天机器人开发的门槛，同时为高级开发者提供强大的扩展能力。它通过可视化的控制台、丰富的插件市场和完善的文档体系，让非技术人员也能快速搭建和管理聊天机器人。

核心特性

开箱即用的控制台

Koishi 提供了高度便利的 Web 控制台，让用户无需任何编程基础就能在几分钟内搭建自己的聊天机器人：

  • 在线插件市场：提供插件浏览、搜索和一键安装功能，即使没有任何编程基础的用户也能轻松在控制台中下载安装插件
  • 多平台支持：支持 QQ、Telegram、Discord、飞书等主流聊天平台，支持多账户管理和跨平台数据互通
  • 远程管理：随时随地通过控制面板监控机器人运行状态、控制机器人行为，甚至直接上号聊天

丰富的插件生态

Koishi 拥有超过 3000 个官方和社区插件，覆盖了机器人开发的方方面面：

  • 平台支持：各聊天平台的适配器插件
  • 数据存储：数据库连接、ORM、缓存等插件
  • 资源管理：图片、文件等资源的存储与访问
  • 网页控制台：控制台扩展和自定义面板
  • 状态管理：用户数据、群组数据等状态管理方案
  • 业务功能：签到、抽卡、问答、游戏等各类业务功能插件

专为开发者打造

Koishi 为插件开发者准备了众多专业功能，使得在各种复杂需求中构建规模化解决方案成为可能：

  • 完整的类型支持：Koishi 完全基于 TypeScript 开发，拥有顶级的类型定义和代码提示，在编写代码时甚至无需频繁查看文档
  • 单元测试覆盖：所有核心功能均通过单元测试验证，既确保了框架的可靠性，也为开发者提供了一套测试插件和定位问题的最佳实践
  • 模块热重载：开发 Koishi 插件时，只需保存文件即可触发热重载，无需频繁重启机器人，如同前端开发一样丝滑顺畅

跨平台兼容

Koishi 的跨平台架构设计使其能够同时对接多种聊天平台，实现消息的统一处理和数据的跨平台互通。开发者只需编写一次业务逻辑代码，即可部署到多个聊天平台上运行，极大地提升了开发效率。

技术栈

Koishi 的核心技术栈包括：

  • 语言：TypeScript（占代码库 99.8%）与少量 JavaScript
  • 运行时：Node.js
  • 包管理：Yarn（通过 yarn workspaces 管理多包仓库）
  • 代码质量：ESLint 代码检查、NYC 代码覆盖率统计
  • 构建工具：自定义的 yakumo 构建系统
  • 许可证：MIT License
  • 代码仓库：Monorepo 架构，包含 packages 和 plugins 两个主要目录

安装指南

Koishi 的安装方式非常灵活，支持多种部署方案：

方式一：使用包管理器安装

推荐使用 Node.js 包管理器全局安装 Koishi：

bash
npm install -g koishi

方式二：使用 Docker 部署

对于需要生产环境部署的用户，可以使用 Docker 容器化部署：

bash
docker pull koishijs/koishi

方式三：从源码安装

开发者可以从 GitHub 克隆仓库，通过以下步骤构建：

bash
git clone https://github.com/koishijs/koishi.git
cd koishi
yarn install
yarn build

快速开始

启动控制台

安装完成后，通过以下命令启动 Koishi 控制台：

bash
koishi

Koishi 会自动打开浏览器并进入控制台界面。首次使用时，系统会引导你完成基础配置。

配置聊天平台适配器

在控制台的插件市场中选择并安装对应平台的适配器插件：

  • QQ 平台：安装对应的 OneBot 适配器
  • Telegram：安装 Telegram 适配器并填入 Bot Token
  • Discord：安装 Discord 适配器并配置 Bot 凭据
  • 飞书：安装飞书适配器并完成授权

安装功能插件

通过控制台的插件市场，可以搜索并安装各种功能插件。安装后通常需要简单的配置即可使用，部分插件还提供了可视化的配置界面。

开发自定义插件

对于有开发需求的用户，可以通过以下步骤创建自定义插件：

typescript
import { Context, Schema } from 'koishi'

export const name = 'my-plugin'
export const usage = '我的自定义插件'

export function apply(ctx: Context) {
  ctx.command('hello', '打招呼')
    .action(() => '你好，世界！')
}

将插件代码保存后，Koishi 的热重载机制会自动加载新插件，无需手动重启。

使用示例

构建群聊管理机器人

利用 Koishi 的插件生态，可以快速搭建一个功能完善的群聊管理机器人。通过组合关键词过滤、自动回复、成员管理等功能插件，实现群组的自动化管理。

搭建知识问答系统

结合 Koishi 的命令系统和数据存储插件，可以构建一个知识库问答机器人。用户可以通过对话的方式查询知识库内容，机器人根据关键词匹配返回相关信息。

开发互动游戏

Koishi 的事件系统和消息处理能力非常适合开发聊天互动游戏。社区中已有大量游戏类插件可供参考，如抽卡模拟、文字冒险、群组小游戏等。

多平台同步机器人

利用 Koishi 的跨平台能力，开发者可以编写一次逻辑代码，让机器人同时在 QQ、Telegram、Discord 等多个平台上运行，实现消息的统一处理和用户数据的跨平台互通。

项目链接

开源工具
上一篇

FastGPT - 基于 LLM 的 AI 知识库问答平台

下一篇

Koishi - 跨平台聊天机器人框架

分享: