qqbot-cron

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

QQ Bot 智能提醒

QQ Bot Smart Reminder

让 AI 帮用户设置、管理定时提醒，支持私聊和群聊。

Let AI help users set up and manage timed reminders, supporting private chats and group chats.

⛔ 最重要的一条规则（读三遍）

⛔ The Most Important Rule (Read Three Times)

调用 cron 工具时，payload.kind 必须是
"agentTurn"
。绝对不能用
"systemEvent"
！
systemEvent
只会在 AI 会话里插入一条文本，用户根本收不到 QQ 消息。只有
agentTurn
+
deliver: true
+
channel: "qqbot"
+
to
才能真正把消息发到 QQ。

When calling the cron tool, payload.kind must be
"agentTurn"
. Never use
"systemEvent"
!
systemEvent
will only insert a text into the AI session, and users will never receive the QQ message. Only
agentTurn
+
deliver: true
+
channel: "qqbot"
+
to
can truly send messages to QQ.

🤖 AI 决策指南

🤖 AI Decision Guide

时间确认规则

Time Confirmation Rules

设置提醒前，先确认当前系统时间（查看上下文中的时间信息，或执行
date
）。纯相对时间（"5分钟后"、"1小时后"）可以跳过确认，直接算
Date.now() + 延迟毫秒
。

Before setting a reminder, confirm the current system time (check time information in the context, or execute
date
). Pure relative time ("remind me in 5 minutes", "remind me in 1 hour") can skip confirmation, directly calculate as
Date.now() + delay milliseconds
.

用户意图识别

User Intention Recognition

用户说法	意图	cron 工具 action
"5分钟后提醒我喝水"	创建一次性提醒	`add` （schedule.kind=at）
"每天8点提醒我打卡"	创建周期提醒	`add` （schedule.kind=cron）
"我有哪些提醒"	查询	`list`
"取消喝水提醒"	删除	`remove`
"修改提醒时间"	删除+重建	`remove` → `add`
"提醒我" (无时间)	需追问	询问具体时间

User's Statement	Intention	cron Tool Action
"Remind me to drink water in 5 minutes"	Create one-time reminder	`add` (schedule.kind=at)
"Remind me to clock in at 8 every day"	Create periodic reminder	`add` (schedule.kind=cron)
"What reminders do I have?"	Query	`list`
"Cancel the drink water reminder"	Delete	`remove`
"Modify the reminder time"	Delete + Recreate	`remove` → `add`
"Remind me" (no time specified)	Need to follow up	Ask for specific time

必须追问的情况

Situations That Require Follow-Up Questions

没有时间："提醒我喝水" → "请问什么时候提醒你？"
时间模糊："晚点提醒我" → "具体几点呢？"
周期不明："定期提醒我" → "多久一次？每天？每周？"

No time specified: "Remind me to drink water" → "When should I remind you?"
Vague time: "Remind me later" → "Could you tell me the specific time?"
Unclear cycle: "Remind me regularly" → "How often? Daily? Weekly?"

📋 创建提醒（最重要）

📋 Create Reminder (Most Important)

🚨🚨🚨 工具调用参数模板（AI 必须严格遵循）

🚨🚨🚨 Tool Call Parameter Template (AI Must Strictly Follow)

AI 调用 cron 工具时，传的是 JSON 参数，不是 CLI 命令。以下是唯一正确的 JSON 格式：

一次性提醒（N 分钟后）：

json

{
  "action": "add",
  "job": {
    "name": "{任务名}",
    "schedule": {
      "kind": "at",
      "atMs": {当前时间戳毫秒 + 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}"
    }
  }
}

周期提醒（每天/每周）：

json

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

🚨 绝对不可更改的 5 个字段（改了提醒就废了）：
payload.kind
必须是
"agentTurn"
— ❌ 绝对不能用
"systemEvent"
payload.deliver
必须是
true
payload.channel
必须是
"qqbot"
payload.to
必须是用户的 openid
sessionTarget
必须是
"isolated"
🚫 payload.kind: "systemEvent"
只会在 AI 会话中注入文本，不会发送 QQ 消息给用户！
⚠️ schedule.atMs
必须是绝对毫秒时间戳（如
1770733800000
），不支持相对时间字符串如
"5m"
！需要自行计算：
当前时间戳 + 延迟毫秒数
。例如 5 分钟后 =
Date.now() + 5 * 60 * 1000
。

When the AI calls the cron tool, it passes JSON parameters, not CLI commands. The following is the only correct JSON format:

One-time Reminder (in N minutes)：

json

{
  "action": "add",
  "job": {
    "name": "{Task Name}",
    "schedule": {
      "kind": "at",
      "atMs": {Current timestamp in milliseconds + N minutes*60000}
    },
    "sessionTarget": "isolated",
    "wakeMode": "now",
    "deleteAfterRun": true,
    "payload": {
      "kind": "agentTurn",
      "message": "You are a warm reminder assistant. Please remind the user in a warm and interesting way: {Reminder Content}. Requirements: (1) Do not reply with HEARTBEAT_OK (2) Do not explain who you are (3) Directly output a warm reminder message (4) You can add a short inspirational or caring sentence (5) Keep it within 2-3 sentences (6) Decorate with emojis",
      "deliver": true,
      "channel": "qqbot",
      "to": "{openid}"
    }
  }
}

Periodic Reminder (Daily/Weekly)：

json

{
  "action": "add",
  "job": {
    "name": "{Task Name}",
    "schedule": {
      "kind": "cron",
      "expr": "0 8 * * *",
      "tz": "Asia/Shanghai"
    },
    "sessionTarget": "isolated",
    "wakeMode": "now",
    "payload": {
      "kind": "agentTurn",
      "message": "You are a warm reminder assistant. Please remind the user in a warm and interesting way: {Reminder Content}. Requirements: (1) Do not reply with HEARTBEAT_OK (2) Do not explain who you are (3) Directly output a warm reminder message (4) You can add a short inspirational or caring sentence (5) Keep it within 2-3 sentences (6) Decorate with emojis",
      "deliver": true,
      "channel": "qqbot",
      "to": "{openid}"
    }
  }
}

🚨 5 Fields That Must Not Be Changed (If changed, the reminder will fail):
payload.kind
must be
"agentTurn"
— ❌ Never use
"systemEvent"
payload.deliver
must be
true
payload.channel
must be
"qqbot"
payload.to
must be the user's openid
sessionTarget
must be
"isolated"
🚫 payload.kind: "systemEvent"
will only inject text into the AI session, not send QQ messages to users!
⚠️ schedule.atMs
must be an absolute millisecond timestamp (e.g.,
1770733800000
), relative time strings like
"5m"
are not supported! You need to calculate it yourself:
Current timestamp + delay milliseconds
. For example, in 5 minutes =
Date.now() + 5 * 60 * 1000
.

查询提醒

Query Reminders

使用 cron 工具

action: "list"

查询。

Use the cron tool with

action: "list"

to query.

删除提醒

Delete Reminders

使用 cron 工具

action: "remove"

jobId

。

Use the cron tool with

action: "remove"

jobId

💬 用户交互模板

💬 User Interaction Template

创建提醒后的反馈要简洁友好，不要啰嗦

Feedback after creating a reminder should be concise and friendly, not verbose

创建成功反馈（推荐简洁版）

Feedback for Successful Creation (Recommended Concise Version)

一次性提醒：

⏰ 好的，{时间}后提醒你{提醒内容}~

周期提醒：

⏰ 收到，{周期描述}提醒你{提醒内容}~

One-time Reminder：

⏰ Got it, I'll remind you to {Reminder Content} after {Time}~

Periodic Reminder：

⏰ Received, I'll remind you to {Reminder Content} {Cycle Description}~

查询提醒反馈

Feedback for Querying Reminders

📋 你的提醒：

1. ⏰ {提醒名} - {时间}
2. 🔄 {提醒名} - {周期}

说"取消xx提醒"可删除~

📋 Your reminders:

1. ⏰ {Reminder Name} - {Time}
2. 🔄 {Reminder Name} - {Cycle}

Say "cancel xx reminder" to delete it~

无提醒时反馈

Feedback When No Reminders Exist

📋 目前没有提醒哦~

说"5分钟后提醒我xxx"试试？

📋 You have no reminders at the moment~

Try saying "Remind me to xxx in 5 minutes"?

删除成功反馈

Feedback for Successful Deletion

✅ 已取消"{提醒名称}"

✅ "{Reminder Name}" has been canceled

⏱️ 时间格式

⏱️ Time Format

一次性提醒（schedule.kind = "at"）

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

⚠️
schedule.atMs
只接受绝对毫秒时间戳，需要自己计算！

用户说法	计算方式
5分钟后	`Date.now() + 5 * 60 * 1000`
半小时后	`Date.now() + 30 * 60 * 1000`
1小时后	`Date.now() + 60 * 60 * 1000`
明天早上8点	先确认当前日期，计算目标时间的毫秒时间戳

⚠️
schedule.atMs
only accepts absolute millisecond timestamps, you need to calculate it yourself!

User's Statement	Calculation Method
In 5 minutes	`Date.now() + 5 * 60 * 1000`
In half an hour	`Date.now() + 30 * 60 * 1000`
In 1 hour	`Date.now() + 60 * 60 * 1000`
Tomorrow at 8 AM	First confirm the current date, then calculate the millisecond timestamp of the target time

周期提醒（schedule.kind = "cron"）

Periodic Reminder (schedule.kind = "cron")

必须加

"tz": "Asia/Shanghai"

用户说法	schedule.expr
每天早上8点	`"0 8 * * *"`
每天晚上10点	`"0 22 * * *"`
每个工作日早上9点	`"0 9 * * 1-5"`
每周一早上9点	`"0 9 * * 1"`
每周末上午10点	`"0 10 * * 0,6"`
每小时整点	`"0 * * * *"`

Must add

"tz": "Asia/Shanghai"

User's Statement	schedule.expr
Every day at 8 AM	`"0 8 * * *"`
Every day at 10 PM	`"0 22 * * *"`
Every workday 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 * * * *"`

📌 参数说明

📌 Parameter Description

工具调用 job 对象必填字段

Required Fields for Tool Call job Object

字段	说明	示例
`job.name`	任务名	`"喝水提醒"`
`job.schedule.kind`	`"at"` 或 `"cron"`	`"at"`
`job.schedule.atMs`	绝对毫秒时间戳（不支持 `"5m"` ！）	`1770734100000`
`job.sessionTarget`	必须 `"isolated"`	`"isolated"`
`job.wakeMode`	推荐 `"now"`	`"now"`
`job.payload.kind`	必须 `"agentTurn"` （❌ 不能用 `"systemEvent"` ）	`"agentTurn"`
`job.payload.message`	以 `[直接输出]` 开头	`"[直接输出] 💧 喝水时间到！"`
`job.payload.deliver`	必须 `true`	`true`
`job.payload.channel`	必须 `"qqbot"`	`"qqbot"`
`job.payload.to`	用户 openid	从系统消息获取
`job.deleteAfterRun`	一次性任务必须 `true`	`true`

Field	Description	Example
`job.name`	Task name	`"Drink Water Reminder"`
`job.schedule.kind`	`"at"` or `"cron"`	`"at"`
`job.schedule.atMs`	Absolute millisecond timestamp (does not support `"5m"` !)	`1770734100000`
`job.sessionTarget`	Must be `"isolated"`	`"isolated"`
`job.wakeMode`	Recommended `"now"`	`"now"`
`job.payload.kind`	Must be `"agentTurn"` (❌ Cannot use `"systemEvent"` )	`"agentTurn"`
`job.payload.message`	Starts with `[Direct Output]`	`"[Direct Output] 💧 It's time to drink water!"`
`job.payload.deliver`	Must be `true`	`true`
`job.payload.channel`	Must be `"qqbot"`	`"qqbot"`
`job.payload.to`	User's openid	Obtained from system messages
`job.deleteAfterRun`	Must be `true` for one-time tasks	`true`

payload.message 暖心提醒模板

Warm Reminder Template for payload.message

💡 payload.message
是一个 prompt，告诉 AI 以暖心方式生成提醒。每次触发时 AI 会自由发挥，生成不重复的、有温度的提醒消息。

统一模板（把

{提醒内容}

替换成具体事项）：

你是一个暖心的提醒助手。请用温暖、有趣的方式提醒用户：{提醒内容}。要求：(1) 不要回复HEARTBEAT_OK (2) 不要解释你是谁 (3) 直接输出一条暖心的提醒消息 (4) 可以加一句简短的鸡汤或关怀的话 (5) 控制在2-3句话以内 (6) 用emoji点缀

效果举例（每次触发内容都不同）：

喝水提醒 →

💧 嘿，该喝水啦～身体是革命的本钱，水是身体的燃料！

开会提醒 →

📅 会议时间到～带上你的好想法，闪亮登场吧！

吃饭提醒 →

🍜 干饭时间到！再忙也要好好吃饭，你值得被善待～

打卡提醒 →

🌅 新的一天，记得打卡哦～每一天都是新的开始！

为什么用 prompt 而不是固定文本？

固定文本太死板，每次都一样，像机器人
用 prompt 让 AI 自由发挥，每次提醒都暖心且不重复

💡 payload.message
is a prompt that tells the AI to generate reminders in a warm way. Each trigger will allow the AI to play freely, generating warm and unique reminder messages every time.

Unified Template (Replace

{Reminder Content}

with specific items):

You are a warm reminder assistant. Please remind the user in a warm and interesting way: {Reminder Content}. Requirements: (1) Do not reply with HEARTBEAT_OK (2) Do not explain who you are (3) Directly output a warm reminder message (4) You can add a short inspirational or caring sentence (5) Keep it within 2-3 sentences (6) Decorate with emojis

Effect Examples (Content varies each time it is triggered):

Drink water reminder →

💧 Hey, it's time to drink water~ The body is the capital of revolution, and water is the fuel of the body!

Meeting reminder →

📅 It's meeting time~ Bring your great ideas and shine on stage!

Meal reminder →

🍜 It's meal time! No matter how busy you are, you should eat well. You deserve to be treated well~

Clock-in reminder →

🌅 It's a new day, remember to clock in~ Every day is a new start!

Why use a prompt instead of fixed text?

Fixed text is too rigid and repetitive, like a robot
Using a prompt allows the AI to play freely, making each reminder warm and unique

🎯 使用场景示例

🎯 Usage Scenario Examples

场景1：一次性提醒

Scenario 1: One-time Reminder

用户: 5分钟后提醒我喝水

AI 调用 cron 工具（假设当前时间戳为 1770734000000）:

json

{
  "action": "add",
  "job": {
    "name": "喝水提醒",
    "schedule": { "kind": "at", "atMs": 1770734300000 },
    "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}"
    }
  }
}

atMs
= 当前时间戳 + 5 * 60 * 1000 = 1770734000000 + 300000 = 1770734300000

AI 回复:

⏰ 好的，5分钟后提醒你喝水~

User: Remind me to drink water in 5 minutes

AI Calls cron Tool (Assuming current timestamp is 1770734000000):

json

{
  "action": "add",
  "job": {
    "name": "Drink Water Reminder",
    "schedule": { "kind": "at", "atMs": 1770734300000 },
    "sessionTarget": "isolated",
    "wakeMode": "now",
    "deleteAfterRun": true,
    "payload": {
      "kind": "agentTurn",
      "message": "You are a warm reminder assistant. Please remind the user in a warm and interesting way: It's time to drink water. Requirements: (1) Do not reply with HEARTBEAT_OK (2) Do not explain who you are (3) Directly output a warm reminder message (4) You can add a short inspirational or caring sentence (5) Keep it within 2-3 sentences (6) Decorate with emojis",
      "deliver": true,
      "channel": "qqbot",
      "to": "{openid}"
    }
  }
}

atMs
= Current timestamp + 5 * 60 * 1000 = 1770734000000 + 300000 = 1770734300000

AI Reply:

⏰ Got it, I'll remind you to drink water in 5 minutes~

场景2：每日周期提醒

Scenario 2: Daily Periodic Reminder

用户: 每天早上8点提醒我打卡

AI 调用 cron 工具:

json

{
  "action": "add",
  "job": {
    "name": "打卡提醒",
    "schedule": { "kind": "cron", "expr": "0 8 * * *", "tz": "Asia/Shanghai" },
    "sessionTarget": "isolated",
    "wakeMode": "now",
    "payload": {
      "kind": "agentTurn",
      "message": "[直接输出] 🌅 打卡时间到！",
      "deliver": true,
      "channel": "qqbot",
      "to": "{openid}"
    }
  }
}

周期任务不加
deleteAfterRun

AI 回复:

⏰ 收到，每天早上8点提醒你打卡~

User: Remind me to clock in at 8 AM every day

AI Calls cron Tool:

json

{
  "action": "add",
  "job": {
    "name": "Clock-in Reminder",
    "schedule": { "kind": "cron", "expr": "0 8 * * *", "tz": "Asia/Shanghai" },
    "sessionTarget": "isolated",
    "wakeMode": "now",
    "payload": {
      "kind": "agentTurn",
      "message": "[Direct Output] 🌅 It's time to clock in!",
      "deliver": true,
      "channel": "qqbot",
      "to": "{openid}"
    }
  }
}

Do not add
deleteAfterRun
for periodic tasks

AI Reply:

⏰ Received, I'll remind you to clock in at 8 AM every day~

场景3：工作日提醒

Scenario 3: Workday Reminder

用户: 工作日下午6点提醒我写日报

AI 调用 cron 工具:

json

{
  "action": "add",
  "job": {
    "name": "日报提醒",
    "schedule": { "kind": "cron", "expr": "0 18 * * 1-5", "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}"
    }
  }
}

AI 回复:

⏰ 收到，工作日下午6点提醒你写日报~

User: Remind me to write the daily report at 6 PM on workdays

AI Calls cron Tool:

json

{
  "action": "add",
  "job": {
    "name": "Daily Report Reminder",
    "schedule": { "kind": "cron", "expr": "0 18 * * 1-5", "tz": "Asia/Shanghai" },
    "sessionTarget": "isolated",
    "wakeMode": "now",
    "payload": {
      "kind": "agentTurn",
      "message": "You are a warm reminder assistant. Please remind the user in a warm and interesting way: It's time to write the daily report. Requirements: (1) Do not reply with HEARTBEAT_OK (2) Do not explain who you are (3) Directly output a warm reminder message (4) You can add a short inspirational or caring sentence (5) Keep it within 2-3 sentences (6) Decorate with emojis",
      "deliver": true,
      "channel": "qqbot",
      "to": "{openid}"
    }
  }
}

AI Reply:

⏰ Received, I'll remind you to write the daily report at 6 PM on workdays~

场景4：会议提醒

Scenario 4: Meeting Reminder

用户: 3分钟后提醒我开会

AI 调用 cron 工具（假设当前时间戳为 1770734000000）:

json

{
  "action": "add",
  "job": {
    "name": "开会提醒",
    "schedule": { "kind": "at", "atMs": 1770734180000 },
    "sessionTarget": "isolated",
    "wakeMode": "now",
    "deleteAfterRun": true,
    "payload": {
      "kind": "agentTurn",
      "message": "[直接输出] 📅 开会时间到！",
      "deliver": true,
      "channel": "qqbot",
      "to": "{openid}"
    }
  }
}

atMs
= 当前时间戳 + 3 * 60 * 1000

AI 回复:

⏰ 好的，3分钟后提醒你开会~

User: Remind me to attend a meeting in 3 minutes

AI Calls cron Tool (Assuming current timestamp is 1770734000000):

json

{
  "action": "add",
  "job": {
    "name": "Meeting Reminder",
    "schedule": { "kind": "at", "atMs": 1770734180000 },
    "sessionTarget": "isolated",
    "wakeMode": "now",
    "deleteAfterRun": true,
    "payload": {
      "kind": "agentTurn",
      "message": "[Direct Output] 📅 It's meeting time!",
      "deliver": true,
      "channel": "qqbot",
      "to": "{openid}"
    }
  }
}

atMs
= Current timestamp + 3 * 60 * 1000

AI Reply:

⏰ Got it, I'll remind you to attend the meeting in 3 minutes~

场景5：群组提醒

Scenario 5: Group Reminder

用户（群聊）: 每天早上9点提醒大家站会

AI 调用 cron 工具:

json

{
  "action": "add",
  "job": {
    "name": "站会提醒",
    "schedule": { "kind": "cron", "expr": "0 9 * * 1-5", "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": "group:{group_openid}"
    }
  }
}

群组使用
"group:{group_openid}"
格式

User (in group chat): Remind everyone to have a standup meeting at 9 AM every day

AI Calls cron Tool:

json

{
  "action": "add",
  "job": {
    "name": "Standup Meeting Reminder",
    "schedule": { "kind": "cron", "expr": "0 9 * * 1-5", "tz": "Asia/Shanghai" },
    "sessionTarget": "isolated",
    "wakeMode": "now",
    "payload": {
      "kind": "agentTurn",
      "message": "You are a warm reminder assistant. Please remind the user in a warm and interesting way: It's time for the standup meeting. Requirements: (1) Do not reply with HEARTBEAT_OK (2) Do not explain who you are (3) Directly output a warm reminder message (4) You can add a short inspirational or caring sentence (5) Keep it within 2-3 sentences (6) Decorate with emojis",
      "deliver": true,
      "channel": "qqbot",
      "to": "group:{group_openid}"
    }
  }
}

Use the format
"group:{group_openid}"
for groups

场景6：查询提醒

Scenario 6: Query Reminders

用户: 我有哪些提醒？

AI 调用 cron 工具：

{ "action": "list" }

AI 回复（根据返回结果）:

📋 你的提醒：

1. ⏰ 喝水提醒 - 3分钟后
2. 🔄 打卡提醒 - 每天08:00

说"取消xx提醒"可删除~

User: What reminders do I have?

AI Calls cron Tool:

{ "action": "list" }

AI Reply (Based on returned results):

📋 Your reminders:

1. ⏰ Drink Water Reminder - In 3 minutes
2. 🔄 Clock-in Reminder - Every day at 08:00

Say "cancel xx reminder" to delete it~

场景7：取消提醒

Scenario 7: Cancel Reminder

用户: 取消打卡提醒

AI 执行:

先用
```
{ "action": "list" }
```
找到对应任务 ID
再用
```
{ "action": "remove", "jobId": "{id}" }
```
删除

AI 回复:

✅ 已取消"打卡提醒"

User: Cancel the clock-in reminder

AI Executes:

First use
```
{ "action": "list" }
```
to find the corresponding task ID
Then use
```
{ "action": "remove", "jobId": "{id}" }
```
to delete it

AI Reply:

✅ "Clock-in Reminder" has been canceled

⚙️ 消息发送说明

⚙️ Message Sending Instructions

定时提醒（cron add）

Timed Reminders (cron add)

定时提醒只能发送主动消息，因为：

提醒执行时，原始 message_id 通常已超过 1 小时有效期

┌─────────────────────┐
│ 定时任务触发         │
└──────────┬──────────┘
           ↓
┌─────────────────────┐
│ AI 通过 agentTurn   │
│ 在隔离会话中执行     │
└──────────┬──────────┘
           ↓
┌─────────────────────┐
│ deliver=true 投递    │
│ channel="qqbot"     │
│ to="{openid}"       │
└──────────┬──────────┘
           ↓
    ✅ 用户收到提醒

Timed reminders can only send proactive messages, because:

When the reminder is executed, the original message_id usually exceeds the 1-hour validity period

┌─────────────────────┐
│ Timed task triggered │
└──────────┬──────────┘
           ↓
┌─────────────────────┐
│ AI executes via agentTurn │
│ in an isolated session │
└──────────┬──────────┘
           ↓
┌─────────────────────┐
│ Deliver with deliver=true │
│ channel="qqbot"     │
│ to="{openid}"       │
└──────────┬──────────┘
           ↓
    ✅ User receives the reminder

即时回复

Instant Reply

即时消息发送支持被动回复（如果 message_id 有效）：

                ┌─────────────────────┐
                │ 发送即时消息         │
                └──────────┬──────────┘
                           ↓
         ┌──────────────────────────────┐
         │ message_id 在 1 小时内有效？ │
         └──────────────────────────────┘
               ↓                ↓
              是               否
               ↓                ↓
    ┌───────────────┐  ┌─────────────────┐
    │ 被动消息回复   │  │ 发送主动消息     │
    │ (引用原消息)   │  │ (直接发送)      │
    └───────────────┘  └─────────────────┘

Instant message sending supports passive replies (if message_id is valid):

                ┌─────────────────────┐
                │ Send instant message │
                └──────────┬──────────┘
                           ↓
         ┌──────────────────────────────┐
         │ Is message_id valid within 1 hour? │
         └──────────────────────────────┘
               ↓                ↓
              Yes              No
               ↓                ↓
    ┌───────────────┐  ┌─────────────────┐
    │ Passive reply │  │ Send proactive message │
    │ (Quote original message) │  │ (Send directly)      │
    └───────────────┘  └─────────────────┘

⚠️ 重要限制

⚠️ Important Limitations

限制	说明
message_id 有效期	1 小时内有效，超时自动降级
回复次数限制	同一 message_id 最多回复 4 次
主动消息权限	⚠️ QQ 机器人需要申请主动消息权限，否则定时提醒会发送失败
主动消息限制	只能发给与机器人交互过的用户（24小时内）
消息内容	`payload.message` 不能为空

Limitation	Description
message_id validity period	Valid within 1 hour, automatically downgrades after timeout
Reply limit	Maximum 4 replies per message_id
Proactive message permission	⚠️ QQ Bot needs to apply for proactive message permission, otherwise timed reminders will fail to send
Proactive message restriction	Can only be sent to users who interacted with the bot within 24 hours
Message content	`payload.message` cannot be empty

⚠️ 主动消息权限说明

⚠️ Proactive Message Permission Description

定时提醒功能依赖主动消息能力，但 QQ 官方默认不授予此权限。

常见错误：

错误码
```
40034102
```
："主动消息失败, 无权限"
这表示机器人没有主动消息权限

解决方案：

登录 QQ 开放平台
进入机器人开发-沙箱管理，消息列表配置中添加自己。

💡 临时替代方案：在没有主动消息权限前，可以让用户使用"回复"方式获得即时提醒，而非定时提醒。

The timed reminder function relies on proactive message capability, but QQ official does not grant this permission by default.

Common Errors:

Error code
```
40034102
```
: "Failed to send proactive message, no permission"
This means the bot does not have proactive message permission

Solution:

Log in to QQ Open Platform
Enter Bot Development - Sandbox Management, add yourself in the message list configuration.

💡 Temporary Alternative: Before obtaining proactive message permission, let users use the "reply" method to get instant reminders instead of timed reminders.

📝 消息模板

📝 Message Templates

场景	触发时输出	Emoji
喝水	喝水时间到啦！	💧 🚰
打卡	早上好，打卡时间到！	🌅 ✅
会议	开会时间到！	📅 👥
休息	该休息一下了~	😴 💤
日报	下班前别忘了写日报哦~	📝 ✍️
运动	运动时间到！	🏃 💪
吃药	该吃药了~	💊 🏥
生日	今天是xx的生日！	🎂 🎉

Scenario	Output When Triggered	Emoji
Drink water	It's time to drink water!	💧 🚰
Clock in	Good morning, it's time to clock in!	🌅 ✅
Meeting	It's meeting time!	📅 👥
Rest	It's time to take a break~	😴 💤
Daily report	Don't forget to write the daily report before getting off work~	📝 ✍️
Exercise	It's exercise time!	🏃 💪
Take medicine	It's time to take medicine~	💊 🏥
Birthday	Today is xx's birthday!	🎂 🎉

🔧 用户标识

🔧 User Identification

类型	格式	来源
用户 openid	`B3EA9A1d-2D3c-5CBD-...`	系统消息自动提供
群组 openid	`group:FeC1ADaf-...`	系统消息自动提供
message_id	`ROBOT1.0_xxx`	系统消息自动提供

💡 这些信息在系统消息中格式如：
当前用户 openid: B3EA9A1d-...
当前消息 message_id: ROBOT1.0_...

Type	Format	Source
User openid	`B3EA9A1d-2D3c-5CBD-...`	Automatically provided by system messages
Group openid	`group:FeC1ADaf-...`	Automatically provided by system messages
message_id	`ROBOT1.0_xxx`	Automatically provided by system messages

💡 This information is in the system message in the following format:
Current user openid: B3EA9A1d-...
Current message message_id: ROBOT1.0_...