138 lines
9.7 KiB
Markdown
138 lines
9.7 KiB
Markdown
---
|
||
name: create-scheduled-task
|
||
description: "创建当前微信会话中的提醒或定时任务。当用户说“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。
|
||
|
||
## 脚本参数
|
||
|
||
```text
|
||
--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 分钟后提醒：
|
||
|
||
```bash
|
||
python3 scripts/create_scheduled_task.py --name '喝水提醒' --schedule-type delay_once --delay-minutes 10 --content '提醒：喝水'
|
||
```
|
||
|
||
5 分钟后在当前群聊 @ 指定群友：
|
||
|
||
```bash
|
||
python3 scripts/create_scheduled_task.py --name '晚饭提醒' --schedule-type delay_once --delay-minutes 5 --mention '又双叒叕' --content '该吃晚饭了🍚'
|
||
```
|
||
|
||
每天同时 @ 多名群友：
|
||
|
||
```bash
|
||
python3 scripts/create_scheduled_task.py --name '打卡提醒' --schedule-type daily --time 09:00 --mentions '["张三","李四"]' --content '记得打卡'
|
||
```
|
||
|
||
每天在当前群聊 @所有人：
|
||
|
||
```bash
|
||
python3 scripts/create_scheduled_task.py --name '全员打卡提醒' --schedule-type daily --time 09:00 --mention-all --content '请大家记得打卡'
|
||
```
|
||
|
||
每周一和周三提醒：
|
||
|
||
```bash
|
||
python3 scripts/create_scheduled_task.py --name '周会提醒' --schedule-type weekly --time 09:30 --weekdays '[1,3]' --content '提醒：参加周会'
|
||
```
|
||
|
||
法定工作日生成动态内容：
|
||
|
||
```bash
|
||
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 个任务；群主、群管理员和后台管理员不受此配额限制。
|