koishi插件开发指南

欢迎学习 Koishi 插件开发指南！

Koishi 是一个基于 Node.js 的 QQ 机器人框架，它提供了丰富的插件系统，允许开发者快速构建自己的机器人应用。下面是一个简单的插件示例：

module.exports = (ctx) => {
  ctx.command('hello', '打招呼').action(({ session }) => {
    return session.send('Hello World!')
  })
}

这是一个最基本的插件，它注册了一个 `hello` 命令，当用户输入 `hello` 时，机器人会回复 `Hello World!`。

接下来，我们来详细了解如何开发 Koishi 插件。

### 安装 Koishi

首先，我们需要安装 Koishi。可以通过 npm 来安装，执行以下命令：

npm install koishi

### 创建插件

创建一个新的 Koishi 插件非常简单，只需要创建一个 JavaScript 文件，比如 `my-plugin.js`，然后将上述示例代码复制到文件中即可。在 Koishi 启动时，Koishi 会自动加载所有的插件并注册它们。

### 插件基础结构

插件基本结构如下：

module.exports = (ctx) => {
  // 插件代码
}

插件是一个函数，它接受一个参数 `ctx`，该参数包含了许多有用的信息，比如命令注册、消息发送等等。

### 注册命令

Koishi 提供了一个 `ctx.command()` 方法来注册命令。该方法接受两个参数：命令名和命令描述，例如：

ctx.command('hello', '打招呼')

该方法返回一个 `Command` 实例，你可以调用其 `.action()` 方法来设置命令执行时的操作，例如：

ctx.command('hello', '打招呼').action(({ session }) => {
  return session.send('Hello World!')
})

在上述代码中，我们设置了 `hello` 命令的执行操作为发送 `Hello World!` 消息。

### 处理消息

Koishi 提供了一个 `ctx.middleware()` 方法来注册消息处理函数。该方法接受一个函数作为参数，该函数需要返回一个布尔值或 Promise，代表是否继续执行下游的处理函数。

例如，以下代码可以回复用户发送的消息：

ctx.middleware(async (session, next) => {
  if (session.content === 'hello') {
    await session.send('Hi there!')
    // 中止后续处理函数
    return false
  }
  // 继续执行下游的处理函数
  return next()
})

在上述代码中，我们判断用户发送的消息是否为 `hello`，如果是，我们发送一条回复消息 `Hi there!`，并中止后续处理函数。如果不是，我们调用 `next()` 函数，继续执行下游的处理函数。

### 发送消息

Koishi 提供了一个 `session.send()` 方法来发送消息。该方法接受一个字符串作为参数，代表要发送的消息内容。

以下是一个发送消息的示例代码：

ctx.middleware(async (session, next) => {
  // 回复消息
  await session.send('Hello World!')
  // 继续执行下游的处理函数
  return next()
})

### 接收消息

Koishi 提供了一个 `ctx.receiver` 对象来接收消息。该对象包含多个事件，你可以监听这些事件来处理用户发送的消息。

例如，以下代码可以监听用户发送的私聊消息，并回复一条消息：

ctx.receiver.on('message.private', async (session) => {
  await session.send('Hello World!')
})

在上述代码中，我们使用 `ctx.receiver.on()` 方法来监听 `message.private` 事件，该事件代表用户发送的私聊消息。当事件发生时，我们回复一条消息 `Hello World!`。

### 插件配置

Koishi 插件支持配置项。你可以通过 `ctx.plugin.config` 属性来访问插件的配置项，例如：

module.exports = (ctx) => {
  const config = ctx.plugin.config

  ctx.command(config.command, '打招呼').action(({ session }) => {
    return session.send(config.message)
  })
}

module.exports.defaultConfig = {
  command: 'hello',
  message: 'Hello World!',
}

在上述代码中，我们通过 `ctx.plugin.config` 属性来获取插件的配置项。我们设置了两个配置项：`command` 和 `message`。

### 插件生命周期

Koishi 插件的生命周期包含以下三个阶段：

- `created`：插件被创建时。
- `attached`：插件被附加到机器人实例时。
- `detached`：插件从机器人实例中分离时。

你可以通过监听 `created`、`attached` 和 `detached` 事件来执行相应的操作。例如，以下代码可以在插件被创建时输出一条日志：

module.exports = (ctx) => {
  console.log('My plugin created.')
}

module.exports.lifecycle = {
  created: () => {
    console.log('My plugin created lifecycle.')
  },
  attached: () => {
    console.log('My plugin attached lifecycle.')
  },
  detached: () => {
    console.log('My plugin detached lifecycle.')
  },
}

在上述代码中，我们通过 `console.log()` 方法输出了一些日志。我们还设置了一个 `lifecycle` 对象来监听插件生命周期事件。当插件被创建时，我们输出了一条日志 `My plugin created lifecycle.`。

### 总结

本文介绍了如何开发 Koishi 插件，包括命令注册、消息处理、消息发送、插件配置、插件生命周期等内容。希望对你有所帮助！