IM 定时提醒

跨平台定时提醒技能，保证准确的时间触发和消息送达。通过 cron job 配置，确保消息发送到用户请求提醒的原始频道，避免 NO_REPLY 问题。

适用场景

用户请求定时提醒（如"5 分钟后提醒我开会"）
用户请求周期性任务（如"每小时提醒我喝水"）
需要在指定时间触发 Agent 执行操作并回复用户

固定字段

以下字段在所有任务中取值固定，不可更改：

字段	固定值	说明
`enabled`	`true`	必须为 true，否则任务不会执行
`sessionTarget`	`"isolated"`	每次触发创建独立会话
`payload.kind`	`"agentTurn"`	触发类型为 Agent 回合
`payload.deliver`	`true`	确保消息发送到外部频道

动态字段

以下字段需根据当前会话上下文自动填充：

字段	说明
`payload.channel`	当前频道类型，从运行时上下文获取（如 `feishu`）
`payload.to`	必填，当前频道目标用户 ID，从会话上下文获取，缺失会导致消息无法送达

调度方式

一次性定时（at）

在指定时间点触发一次，适用于"X 分钟后提醒我"这类场景。

"schedule": {
  "kind": "at",
  "atMs": 1770449700000
}

atMs 为目标触发时间的 Unix 时间戳（毫秒）。

周期性定时（every）

按固定间隔重复触发，适用于"每隔 X 分钟提醒我"这类场景。

"schedule": {
  "kind": "every",
  "everyMs": 60000
}

everyMs 为触发间隔的毫秒数（如 60000 = 1 分钟）。

Cron 表达式定时（cron）

使用标准 cron 表达式调度，适用于"每天早上 7 点提醒我"这类基于日历规律的场景。

"schedule": {
  "kind": "cron",
  "expr": "0 7 * * *"
}

expr 为标准五位 cron 表达式，格式如下：

┌───────────── 分钟 (0-59)
│ ┌───────────── 小时 (0-23)
│ │ ┌───────────── 日 (1-31)
│ │ │ ┌───────────── 月 (1-12)
│ │ │ │ ┌───────────── 星期 (0-6，0=周日)
│ │ │ │ │
* * * * *

常用表达式：

场景	表达式
每天早上 7 点	`0 7 * * *`
每天中午 12 点	`0 12 * * *`
工作日早上 9 点	`0 9 * * 1-5`
每周一早上 10 点	`0 10 * * 1`
每月 1 号上午 9 点	`0 9 1 * *`

完整示例

示例一：一次性提醒

在指定时间点触发，执行一次后结束。

{
  "version": 1,
  "jobs": [
    {
      "id": "0dd466ae-d52a-448f-ad01-2fc719f1f48c",
      "name": "test2",
      "description": "test2",
      "enabled": true,
      "schedule": {
        "kind": "at",
        "atMs": 1770449700000
      },
      "sessionTarget": "isolated",
      "wakeMode": "next-heartbeat",
      "payload": {
        "kind": "agentTurn",
        "message": "回复内容是test2",
        "deliver": true,
        "channel": "feishu",
        "to": "ou_XXXXXXXXXXX"
      }
    }
  ]
}

示例二：周期性提醒

每隔固定时间触发一次，持续执行。

{
  "version": 1,
  "jobs": [
    {
      "id": "50f53ed1-4ad6-4ed2-9984-fdd4eba1fdab",
      "name": "测试1",
      "description": "测试1",
      "enabled": true,
      "schedule": {
        "kind": "every",
        "everyMs": 60000
      },
      "sessionTarget": "isolated",
      "wakeMode": "next-heartbeat",
      "payload": {
        "kind": "agentTurn",
        "message": "回复这是测试1",
        "deliver": true,
        "channel": "feishu",
        "to": "ou_XXXXXXXXXXX"
      }
    }
  ]
}

示例三：Cron 表达式定时提醒

按 cron 表达式调度，适用于基于日历规律的周期性任务。

{
  "version": 1,
  "jobs": [
    {
      "id": "0ec68ffa-07b2-4ca6-93ee-75edd26b4b74",
      "name": "cron",
      "description": "cron",
      "enabled": true,
      "schedule": {
        "kind": "cron",
        "expr": "0 7 * * *"
      },
      "sessionTarget": "isolated",
      "wakeMode": "next-heartbeat",
      "payload": {
        "kind": "agentTurn",
        "message": "cron",
        "deliver": true,
        "channel": "feishu",
        "to": "ou_XXXXXXXXXXX"
      }
    }
  ]
}

频道检测

获取频道类型：从运行时 channel 属性获取（如 feishu）
获取用户 ID：从当前会话或消息上下文获取（如 ou_xxxx）
始终自动检测：使用发起请求的原始频道，不要硬编码

消息内容指南

避免纯文本消息，需要包含让 Agent 生成响应的指令
使用完整的指令句，确保 Agent 处理后产生可见回复

实现步骤

检测当前频道类型和用户 ID
将用户的时间请求转换为时间戳（毫秒）或间隔毫秒数
构建完整的 job 配置（固定字段 + 动态字段）
调用 API 创建定时任务
确认创建成功，告知用户

常见坑点

错误做法	正确做法
硬编码 channel 和 to	从当前上下文自动检测
`sessionTarget` 设为 `main`	必须设为 `isolated`
`deliver` 缺失或设为 `false`	必须设为 `true`
`enabled` 缺失或设为 `false`	必须显式设为 `true`
`payload.to` 缺失或为空	必须填写，否则消息无法送达

im-reminder