计划任务

计划任务(Task) 是 Kotori 提供的一个重要功能，用于在指定的时间执行特定的操作。它基于 cron 表达式实现定时任务的调度，可以用来执行诸如定时提醒、数据备份、定期清理等自动化操作。

注册计划任务

通过 ctx.task() 注册一个计划任务，该方法支持两种方式传入参数：

1. 简单方式：直接传入 cron 表达式字符串和回调函数
2. 配置对象方式：传入一个选项对象和回调函数

基本用法

最简单的使用方式是直接传入 cron 表达式和回调函数：

ctx.task('0 0 * * *', () => {
  // 每天 00:00 执行
  console.log('每天凌晨触发的任务')
})

上述代码注册了一个每天零点执行的任务。cron 表达式 0 0 * * * 表示在每天的 00:00 执行回调函数。

移除任务

ctx.task() 方法的返回值是一个用于移除该任务的函数：

const dispose = ctx.task('*/30 * * * *', () => {
  console.log('每30分钟执行一次')
})

// 移除任务
dispose()

高级配置

如果需要更详细的配置，可以传入一个配置对象：

ctx.task(
  {
    cron: '0 8 * * *',
    timeZone: 'Asia/Shanghai',
    start: true
  },
  () => {
    console.log('每天北京时间 8:00 执行')
  }
)

配置对象支持以下选项：

• cron: cron 表达式字符串（必填）
• timeZone: 时区设置，默认为系统时区
• start: 是否在注册后立即启动任务，默认为 true

Cron 表达式

Cron 表达式由 6 个或 7 个由空格分隔的字段组成：

┬ ┬ ┬ ┬ ┬ ┬
│ │ │ │ │ │
│ │ │ │ │ └ 星期几 (0 - 7) (0 或 7 都代表星期日)
│ │ │ │ └───── 月份 (1 - 12)
│ │ │ └────────── 日期 (1 - 31)
│ │ └─────────────── 小时 (0 - 23)
│ └──────────────────── 分钟 (0 - 59)
└───────────────────────── 秒 (0 - 59, 可选)

常用的 cron 表达式示例：

• * * * * * - 每分钟执行
• 0 * * * * - 每小时开始时执行
• 0 0 * * * - 每天零点执行
• 0 8 * * * - 每天早上 8 点执行
• 0 0 * * 0 - 每周日零点执行
• 0 0 1 * * - 每月 1 日零点执行

使用示例

定时报时

// 每分钟的第30秒执行
ctx.task('30 * * * * *', async (ctx) => {
  ctx.boardcast()

  await Promise.all(
    Array.from(ctx[Symbols.bot].values()).map((apis) =>
      Array.from(apis.values()).map(async (api) =>
        (await api.getGroupList()).map(({ groupId }) => api.sendGroupMsg('每分钟的第 30 秒执行', groupId))
      )
    )
  )
})

这个例子创建了一个每分钟的第 30 秒执行的任务，并向所有当前 Kotori 的所有实例的所有群聊广播消息。

工作日提醒

// 工作日的下午3点执行
ctx.task('0 15 * * 1-5', () => {
  // 其实用外部或者内部的 ctx 都是一样的
  ctx.logger.debug('该下班了！')
})

这个例子演示了如何创建一个在工作日（周一至周五）下午 3 点执行的任务。任务会向指定的群组发送下班提醒。cron 表达式 0 15 * * 1-5 中的 1-5 表示周一到周五。

通过计划任务，你可以轻松实现各种定时自动化操作，比如：

• 定时发送提醒消息
• 每日数据统计
• 定期清理缓存
• 节日祝福
• 自动备份

结合其他功能，计划任务可以让你的机器人更加智能和自动化。记住在设置计划任务时要注意时区设置，以确保任务在预期的时间执行。同时也要考虑任务的执行频率，避免过于频繁的任务影响系统性能。