wechat-robot-skills/skills/create-scheduled-task/SKILL.md

name	description
create-scheduled-task	创建当前微信会话中的提醒或定时任务。当用户说“X 分钟后提醒我/群友/所有人 Y”“过一会提醒我”“每天/每周/工作日几点提醒我”“帮我设个提醒”或“创建一个……定时任务”时使用。支持一次性延时、每日、每周和中国法定工作日任务，可在群聊中真正 @ 指定成员或 @所有人，也支持按时生成 AI 内容。

创建定时任务

通过 scripts/create_scheduled_task.py 调用机器人客户端的定时任务接口。自动从当前会话环境变量推导创建人和发送目标，不要求用户提供微信 ID。

执行流程

1. 从用户原话中提取任务名称、执行规则、发送内容，以及要 @ 创建人、指定群成员、所有人还是不 @。
2. 缺少执行时间或发送内容时，只追问缺失项，不运行脚本。
3. 按下表选择调度类型和参数。
4. 在本 Skill 目录执行 scripts/create_scheduled_task.py，且不要在真实请求中传 --dry-run。
5. 仅在脚本返回 ok: true 后确认创建成功。回复任务名称、执行规则、下一次执行时间、提醒内容、发送位置和实际 @ 对象。以返回的 task.mention 为准：all 说明会 @所有人，custom 列出 display_names，creator 说明会 @ 创建人，none 说明不 @ 任何人。
6. 脚本失败时立即向用户反馈原始错误含义，不得声称任务已创建。

调度规则

用户表达	--schedule-type	必需参数
“10 分钟后提醒我喝水”“10 分钟提醒我喝水”	delay_once	--delay-minutes 10
“2 小时后提醒我开会”	delay_once	--delay-hours 2
“明天 08:00 提醒我”且距离现在不超过 24 小时	delay_once	--run-at 'YYYY-MM-DD HH:mm'
“每天 08:00 提醒我”	daily	--time 08:00
“每周一、周三 09:30 提醒我”	weekly	--time 09:30 --weekdays '[1,3]'
“每个中国法定工作日 09:00 提醒我”	cn_workday	--time 09:00

遵守以下语义：

• 将星期一到星期日映射为 1 到 7。
• 将“工作日”解释为中国法定工作日，包括法定调休补班；用户明确说“周一到周五”时改用 weekly 和 [1,2,3,4,5]。
• 将缺少“后”但结构为“X 分钟提醒我 Y”的表达解释为 X 分钟后。
• 使用 Asia/Shanghai 时区。每日、每周和法定工作日时间必须是零补齐的 HH:mm。
• 中国法定工作日可用年份取决于客户端内置日历。当前配套客户端只包含 2026 年数据；创建 cn_workday 任务时提醒用户它在 2027 年前需要随客户端补充日历数据，否则跨年后无法继续计算下一次执行时间。
• 一次性延时必须在 1 秒到 24 小时之间。超过 24 小时的绝对一次性提醒不受后端支持。
• 后端不支持每月、每年、原始 Cron 表达式或“每隔 X 分钟”这类间隔循环。遇到这些请求时说明限制，并请用户改成支持的规则，不要伪造近似任务。
• “创建一个定时任务”但没有给出明确规则或内容时，先追问，不要猜测。

内容规则

• 对普通提醒使用 --content。默认把“提醒我喝水”整理为面向用户的 提醒：喝水，但用户给出精确文案时保持原文。
• 真正的 @ 由 --mention/--mentions/--mention-all 单独配置，不要在正文中拼接普通文本 @昵称 或 @所有人。若正文只是以被提醒人的名字作称呼（如“张三，该吃饭了”），通常把 --content 整理为“该吃饭了”，避免客户端自动添加 @张三 后重复人名；用户明确要求保留精确正文时除外。
• 对“每天生成一份早报”这类动态内容使用 --ai-prompt，不要把普通固定提醒升级为 AI 任务。
• 可以同时传 --content 和 --ai-prompt；执行时先发送固定文本，再发送 AI 结果。
• 至少传 --content 或 --ai-prompt 之一。
• 任务名应简短、可识别，不超过 100 个字符；固定文本不超过 500 个字符。

群成员 @ 规则

• “提醒我……”或用户没有指定被 @ 人时，不传任何 mention 参数。脚本会为群聊显式保存创建人的微信 ID；私聊会显式保存空数组。
• “提醒这位群友 张三……”“到点 @ 张三……”或其他明确点名表达，按用户原话提取群昵称或备注并传 --mention '张三'。
• 指定多人时重复传 --mention，或使用 --mentions '["张三","李四"]'。脚本会按群备注、群昵称依次匹配并去重。
• 用户明确说“@所有人”“提醒全体成员”“通知群里所有人”时传 --mention-all。不要把“所有人”当成员昵称查询，也不要在正文里拼接普通文本。
• 用户明确说“不要 @ 人”“只发消息”时传 --no-mention。不要用它替代缺省行为。
• --mention-all、--no-mention 和指定成员参数三种模式互斥。
• --mention 只允许用于当前群聊。不要让用户提供或猜测微信 ID；脚本会通过客户端查询当前群内未退群成员并保存真实微信 ID。
• 找不到成员或同一优先级匹配到多人时，脚本会在创建任务前失败。向用户说明需要更准确、唯一的完整群备注或昵称，不要退回为 @ 创建人，也不要只把名字拼进正文。
• 固定文本和 AI 内容同时存在时，只在第一条固定文本中 @；只有 AI 内容时在 AI 回复中 @。

会话目标

脚本自动读取以下环境变量：

• ROBOT_FROM_WX_ID：当前私聊好友 ID 或当前群聊 ID。
• ROBOT_SENDER_WX_ID：当前消息发送人 ID。
• ROBOT_WECHAT_CLIENT_PORT：机器人客户端端口。

私聊中把当前好友作为创建人和发送目标。群聊中把当前发言人作为创建人、当前群聊作为发送目标。因此任务始终发回当前会话，不会私聊群成员。每个发送目标都显式保存 mention_wechat_ids：群聊里的“提醒我”保存创建人 ID，明确指定成员时保存成员 ID，--mention-all 保存 notify@all，传 --no-mention 或私聊任务时保存空数组。成功回复必须按脚本实际返回说明，不能笼统声称总会 @ 创建人。不要让用户提供或猜测这些 ID。

脚本参数

--name <任务名>                                  必填
--schedule-type <delay_once|daily|weekly|cn_workday> 必填
--content <固定提醒文本>                         与 --ai-prompt 至少一个
--ai-prompt <动态内容提示词>                     与 --content 至少一个
--time <HH:mm>                                   daily/weekly/cn_workday 必填
--weekdays <JSON数组或逗号列表>                  weekly 必填，1=周一，7=周日
--mention <当前群成员昵称或备注>                 可选，可重复；指定真正 @ 的成员
--mentions <字符串JSON数组>                      可选；一次指定多个真正 @ 的成员
--mention-all                                    可选；真正 @ 当前群所有人
--no-mention                                     可选；明确不 @ 任何人，不能与其他 mention 参数同用
--delay-seconds <整数>                           delay_once 四选一
--delay-minutes <整数>                           delay_once 四选一
--delay-hours <整数>                             delay_once 四选一
--run-at <YYYY-MM-DD HH:mm[:ss]>                 delay_once 四选一，须在未来 24 小时内
--dry-run                                        仅供开发校验，真实创建时禁止使用

调用示例

10 分钟后提醒：

python3 scripts/create_scheduled_task.py --name '喝水提醒' --schedule-type delay_once --delay-minutes 10 --content '提醒：喝水'

5 分钟后在当前群聊 @ 指定群友：

python3 scripts/create_scheduled_task.py --name '晚饭提醒' --schedule-type delay_once --delay-minutes 5 --mention '又双叒叕' --content '该吃晚饭了🍚'

每天同时 @ 多名群友：

python3 scripts/create_scheduled_task.py --name '打卡提醒' --schedule-type daily --time 09:00 --mentions '["张三","李四"]' --content '记得打卡'

每天在当前群聊 @所有人：

python3 scripts/create_scheduled_task.py --name '全员打卡提醒' --schedule-type daily --time 09:00 --mention-all --content '请大家记得打卡'

每周一和周三提醒：

python3 scripts/create_scheduled_task.py --name '周会提醒' --schedule-type weekly --time 09:30 --weekdays '[1,3]' --content '提醒：参加周会'

法定工作日生成动态内容：

python3 scripts/create_scheduled_task.py --name '工作日早报' --schedule-type cn_workday --time 08:30 --ai-prompt '生成今天的简短早报，直接给出可发送给用户的正文。'

调用 execute_skill_script 时，将以上命令中脚本路径之后的部分放入 args。

成功与失败处理

• 成功 JSON 包含 task.id、task.schedule_summary、task.next_run_time、task.target_type 和 task.mention。使用这些实际返回值回复，不要只复述用户输入或根据创建人猜测 @ 对象。
• 接口业务错误会以“创建定时任务失败：……”返回。说明可操作的原因，例如发送目标不存在、任务数量达到上限、AI 配置缺失或调度器未初始化。
• 创建接口不是幂等接口。发生超时、连接中断、无效响应，或错误中含“任务已保存，但刷新调度器失败”时，任务可能已经入库；明确告知用户先到定时任务列表核对，禁止自动重试，以免创建重复任务。
• 普通好友和普通群成员最多创建 5 个任务；群主、群管理员和后台管理员不受此配额限制。