Koishi机器人开发

Koishi - 创建跨平台、可扩展、高性能的机器人
本篇文章，将开始手把手介绍Koishi机器人开发的流程和细节

安装和配置插件

Koishi 的一个核心特性是强大的控制台。控制台是一个对用户友好的图形界面，封装了 Koishi 的绝大多数功能：

1.安装、卸载和更新插件
2.启用、停用和配置插件
3.管理指令、数据库、输出文本
4.在模拟和真实环境下聊天
5.状态监控、数据统计
6.查看日志
本节中我们将以 echo 插件为例来演示插件的安装与配置。
echo 插件注册了一个名为 echo 的指令，调用此指令可以将输入原样输出给用户。

认识控制台

在你成功安装了模板项目或启动器后，控制台将自动打开。
控制台的界面主要分为两部分，左侧是活动栏，用来切换右边的界面，右边默认打开的是仪表盘页面。
在宽屏设备的下方还有一个状态栏，主要用来显示机器人的运行状态。

在之后的几节里，我们会逐一介绍各界面的功能和使用。

安装插件

前往「插件市场」页面，你将在这里看到所有可下载的插件。
在搜索框中输入 echo，找到我们想要的插件，点击「添加」按钮，然后在弹出的对话框中点击「安装」。
等待片刻，插件就已经安装成功了。

启用和停用插件

Koishi 不会自动启用刚刚安装的插件，你需要手动配置并启用。
前往「插件配置」页面，左侧栏中列出了已配置的各种插件。
其中黑色字体显示的是正在运行的插件，而灰色字体则对应尚未运行的插件。

我们可以看到此时 echo 插件的名字是灰色的，这表明它并未处于运行状态。
echo 插件没有可配置的项目，因此右侧的详情页是空白的。
我们可以直接点击右上角的「启用插件」按钮，看到「启用成功」的提示信息，这表明 echo 插件就已经处于运行状态了。

要停用 echo 插件同样很简单。点击右上角的「停用插件」按钮，插件便会停止运行。
停用插件既不会删除插件的代码，也不会删除插件的配置，你可以随时重新启用它。

配置插件

虽然 echo 插件没有需要配置的地方，但更复杂的插件则通常会提供各种配置项，允许使用者控制插件的行为。下图展示了 novelai 插件的配置界面。

在这个界面中，我们可以看到许多配置项。其中你需要注意：
必选但尚未填入的配置项会在左侧呈现 红色 的提示条，只有正确填写配置才能启动插件。
已修改但未保存的配置项会在左侧呈现 紫色 的提示条，点击「启用插件」或「保存配置」按钮后会保存配置；
如果你想撤销这些改动，可以在配置名称旁的小三角处呼出菜单，选择「撤销更改」使该配置恢复到上次保存时的状态。

第一次对话

安装完了 Koishi 并体验了插件市场，想必你已经等不及体验 Koishi 的功能了。现在就让我们立即开始与机器人的第一次对话吧！

在沙盒中模拟对话

在控制台中前往「沙盒」页面，在这里我们可以模拟与机器人的对话。

首先点击屏幕左上角的「添加用户」来创建一个虚拟用户 (通常第一位虚拟用户的名字会是 Alice)，此时屏幕右侧会出现空白的聊天界面。
点击屏幕下方的对话框，输入「help」，并按回车键发送。
你会立即在聊天界面中看到机器人的回复，列出了包括 echo 和 help 在内的所有可用的指令，这便是 help 这个内置指令的功能。

可以看到，这里的 echo 就是我们刚刚安装的插件，它的功能是将用户的输入原样返回。
让我们现在尝试一下：输入「echo 你好」，并按回车键发送。你会看到机器人的回复是「你好」。

如果想要模拟群聊，我们可以创建更多的用户，并在聊天界面顶部点击切换到「群聊模式」。这样，你就可以通过在左侧栏切换并控制多个虚拟用户与机器人聊天了。如果你要体验的是下棋一类的多人交互插件，这会非常有用。

除此以外，如果某些指令需要一定的 权限等级，你也可以切换到「用户设置」中进行调整。

接入真实聊天平台

仅仅是在沙盒中对话是远远不够的。我们需要将机器人接入到真实的聊天平台中，才能让它真正地为我们服务。
我们在前文中已经以大家常用的QQ为例，接入了最新版NT架构的QQ聊天平台。

下面是官方维护的适配器列表：
钉钉
Discord
KOOK
飞书
LINE
邮件
Matrix
QQ
Slack
Telegram
微信公众号
企业微信
WhatsApp
Zulip

其中，常用的适配器插件已经预装在了 Koishi 中，你可以在插件配置中的 adapter 分组中找到它们。
如果没有看到你想要的平台，你也可以在插件市场中搜索并安装更多适配器插件。

一个 Koishi 应用可以同时接入多个聊天平台的多个账号。
每个账号对应一份插件配置，你可以参考 添加更多插件 中的方法添加新的插件配置。
由于同一平台内接入的多个机器人共享了相同的用户数据。
因此，你可以非常方便地在多个机器人之间切换以实现负载均衡。

不同平台的接入方式与难度存在较大的差异。对于不同的平台，
你需要做好相应的准备工作。这些工作可能包括在平台内注册开发者账号、准备一台部署到公网的服务器等等。
你可以在各个适配器插件的文档中找到详细的指引。

好消息是，Koishi 的大部分功能都不依赖特定的聊天平台。
因此在进行准备工作的同时，你完全可以阅读本文档的后续部分，并在沙盒中体验并学习 Koishi 的功能。

对比沙盒与真实环境

事实上，大多数机器人框架都没有提供沙盒功能，或是倾向于用户在真实环境中进行体验。
你可能会有疑惑：为什么 Koishi 要推荐使用沙盒功能呢？因此我们列出了沙盒的几点优势。

首先，沙盒可以让你快速地了解插件的效果，而不需要在真实环境中进行大量的测试。
想象一下，你刚刚安装了一个陌生的插件，你并不知道应该如何使用它，也不知道它的效果是什么。
最糟糕的情况下，一旦插件的某些功能触发了机器人的敏感行为，你的真实账号还存在被封禁的风险。
而沙盒则可以让你在不用担心这些问题的情况下，快速地了解插件的功能。

其次，如果你是插件的开发者而非使用者，沙盒功能的意义则更大了：得益于 Koishi 的热重载机制，每次修改插件源码后，你只需要按下保存，即可立即在沙盒中体验修改后的效果。
这允许你在任何设备上进行快速的迭代开发，而根本不需要准备真实环境的账号。

当然，沙盒并不能代替真实的聊天环境，有些插件的效果可能无法在沙盒中体验。因此，我们推荐你在沙盒中体验插件的基础功能，而在真实环境中进行更加深入的测试。