qqbot-cron

QQ Bot scheduled reminders

⚠️ Mandatory rules

When the user mentions any request involving delay or scheduling, such as "remind", "alarm", "schedule", "in X minutes/hours", "every day at X o'clock", "call me", etc., you must call the cron tool, and absolutely must not reply only in natural language saying "OK, I will remind you"!

You have no memory or background thread, and verbally promising "I will remind you then" is invalid—only calling the cron tool can actually register a scheduled task.

Core rules

payload.kind must be "agentTurn", and absolutely must not use "systemEvent"！ systemEvent only injects text within the AI session, and the user will not receive a QQ message.

5 unchangeable fields：

Field	Fixed value	Reason
`payload.kind`	`"agentTurn"`	`systemEvent` will not send a QQ message
`payload.deliver`	`true`	otherwise it will not be delivered
`payload.channel`	`"qqbot"`	QQ channel identifier
`payload.to`	user openid	get from context
`sessionTarget`	`"isolated"`	isolate the session to avoid pollution

schedule.atMs must beabsolute millisecond timestamp(such as 1770733800000), relative strings such as "5m" are not supported. Calculation method:当前时间戳ms + 延迟毫秒。

Parameter template

One-time reminder (schedule.kind = "at")

{
  "action": "add",
  "job": {
    "name": "{任务名}",
    "schedule": { "kind": "at", "atMs": "{当前时间戳ms + N*60000}" },
    "sessionTarget": "isolated",
    "wakeMode": "now",
    "deleteAfterRun": true,
    "payload": {
      "kind": "agentTurn",
      "message": "你是一个暖心的提醒助手。请用温暖、有趣的方式提醒用户：{提醒内容}。要求：(1) 不要回复HEARTBEAT_OK (2) 不要解释你是谁 (3) 直接输出一条暖心的提醒消息 (4) 可以加一句简短的鸡汤或关怀的话 (5) 控制在2-3句话以内 (6) 用emoji点缀",
      "deliver": true,
      "channel": "qqbot",
      "to": "{openid}"
    }
  }
}

Recurring reminder (schedule.kind = "cron")

{
  "action": "add",
  "job": {
    "name": "{任务名}",
    "schedule": { "kind": "cron", "expr": "0 8 * * *", "tz": "Asia/Shanghai" },
    "sessionTarget": "isolated",
    "wakeMode": "now",
    "payload": {
      "kind": "agentTurn",
      "message": "你是一个暖心的提醒助手。请用温暖、有趣的方式提醒用户：{提醒内容}。要求：(1) 不要回复HEARTBEAT_OK (2) 不要解释你是谁 (3) 直接输出一条暖心的提醒消息 (4) 可以加一句简短的鸡汤或关怀的话 (5) 控制在2-3句话以内 (6) 用emoji点缀",
      "deliver": true,
      "channel": "qqbot",
      "to": "{openid}"
    }
  }
}

Recurring taskdo not add deleteAfterRun. Group chat to format is "group:{group_openid}"。

cron expression quick reference

Scenario	expr
Every day at 8 AM	`"0 8 * * *"`
Every day at 10 PM	`"0 22 * * *"`
Weekdays at 9 AM	`"0 9 * * 1-5"`
Every Monday at 9 AM	`"0 9 * * 1"`
Every weekend at 10 AM	`"0 10 * * 0,6"`
Every hour on the hour	`"0 * * * *"`

Recurring reminders must add "tz": "Asia/Shanghai"。

Query and delete

Query：{ "action": "list" }
Delete: first list find jobId, then { "action": "remove", "jobId": "{id}" }
Modify: delete and recreate

AI decision guide

User wording	action	schedule.kind
"Remind me to drink water in 5 minutes"	`add`	`at`
"Remind me to clock in every day at 8"	`add`	`cron`
"What reminders do I have"	`list`	—
"Cancel the drink water reminder"	`remove`	—
"Change the reminder time"	`remove` → `add`	—
"Remind me" (no time)	Need to ask follow-up	—

Pure relative times ("in 5 minutes", "in 1 hour") can be calculated directly without confirmation. When the time is vague or missing, ask a follow-up.

Reply template

One-time:⏰ 好的，{时间}后提醒你{内容}~
Recurring:⏰ 收到，{周期}提醒你{内容}~
Query with no results:📋 目前没有提醒哦~ 说"5分钟后提醒我xxx"试试？
Delete successful:✅ 已取消"{名称}"