im-reminder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

IM 定时提醒

IM Scheduled Reminder

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

Cross-platform scheduled reminder skill that ensures accurate time triggering and message delivery. Configured via cron job to ensure messages are sent to the original channel where the user requested the reminder, avoiding the NO_REPLY issue.

适用场景

Application Scenarios

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

User requests scheduled reminders (e.g., "Remind me to attend the meeting in 5 minutes")
User requests recurring tasks (e.g., "Remind me to drink water every hour")
Need to trigger the Agent to perform operations and reply to users at a specified time

固定字段

Fixed Fields

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

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

The following fields have fixed values in all tasks and cannot be modified:

Field	Fixed Value	Description
`enabled`	`true`	Must be true, otherwise the task will not execute
`sessionTarget`	`"isolated"`	Create an independent session for each trigger
`payload.kind`	`"agentTurn"`	Trigger type is Agent turn
`payload.deliver`	`true`	Ensure messages are sent to external channels

动态字段

Dynamic Fields

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

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

The following fields need to be automatically populated based on the current session context:

Field	Description
`payload.channel`	Current channel type, obtained from runtime context (e.g., `feishu` )
`payload.to`	Required, target user ID of the current channel, obtained from session context; missing this will cause message delivery failure

调度方式

Scheduling Methods

一次性定时（at）

One-time Schedule (at)

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

json

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

atMs

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

Trigger once at the specified time, suitable for scenarios like "Remind me after X minutes".

json

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

atMs

is the Unix timestamp (in milliseconds) of the target trigger time.

周期性定时（every）

Recurring Schedule (every)

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

json

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

everyMs

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

Trigger repeatedly at fixed intervals, suitable for scenarios like "Remind me every X minutes".

json

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

everyMs

is the interval in milliseconds (e.g., 60000 = 1 minute).

Cron 表达式定时（cron）

Cron Expression Schedule (cron)

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

json

"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 * *`

Schedule using standard cron expressions, suitable for calendar-based regular scenarios like "Remind me at 7 AM every day".

json

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

expr

is a standard 5-field cron expression with the following format:

┌───────────── Minute (0-59)
│ ┌───────────── Hour (0-23)
│ │ ┌───────────── Day (1-31)
│ │ │ ┌───────────── Month (1-12)
│ │ │ │ ┌───────────── Week (0-6, 0=Sunday)
│ │ │ │ │
* * * * *

Common expressions:

Scenario	Expression
7 AM every day	`0 7 * * *`
12 PM every day	`0 12 * * *`
9 AM on workdays	`0 9 * * 1-5`
10 AM every Monday	`0 10 * * 1`
9 AM on the 1st of every month	`0 9 1 * *`

完整示例

Complete Examples

示例一：一次性提醒

Example 1: One-time Reminder

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

json

{
  "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"
      }
    }
  ]
}

Trigger at the specified time and end after execution.

json

{
  "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": "The reply content is test2",
        "deliver": true,
        "channel": "feishu",
        "to": "ou_XXXXXXXXXXX"
      }
    }
  ]
}

示例二：周期性提醒

Example 2: Recurring Reminder

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

json

{
  "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"
      }
    }
  ]
}

Trigger at fixed intervals and continue execution.

json

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

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

Example 3: Cron Expression Scheduled Reminder

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

json

{
  "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"
      }
    }
  ]
}

Scheduled via cron expression, suitable for calendar-based recurring tasks.

json

{
  "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 Detection

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

Get channel type: Obtain from the runtime
```
channel
```
property (e.g.,
```
feishu
```
)
Get user ID: Obtain from the current session or message context (e.g.,
```
ou_xxxx
```
)
Always auto-detect: Use the original channel where the request was initiated; do not hardcode

消息内容指南

Message Content Guidelines

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

Avoid plain text messages; include instructions for the Agent to generate responses
Use complete instruction sentences to ensure the Agent produces visible replies after processing

实现步骤

Implementation Steps

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

Detect the current channel type and user ID
Convert the user's time request into a timestamp (milliseconds) or interval milliseconds
Build the complete job configuration (fixed fields + dynamic fields)
Call the API to create the scheduled task
Confirm successful creation and notify the user

常见坑点

Common Pitfalls

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

Wrong Practice	Correct Practice
Hardcoding channel and to	Auto-detect from current context
Setting `sessionTarget` to `main`	Must set to `isolated`
Missing or setting `deliver` to `false`	Must set to `true`
Missing or setting `enabled` to `false`	Must explicitly set to `true`
Missing or empty `payload.to`	Must fill in, otherwise messages cannot be delivered