定时执行任务

​

概述

定时任务让 Qoder CLI 在指定时间自动运行一个提示词或斜杠命令。你可以安排任务在未来某个时间点运行一次，也可以按照日历计划周期性地重复运行。它适合定时巡检、周期性报告、按计划触发的自动化等场景。

定时任务分两种：

• 一次性任务（one-shot）：在下一个匹配时间触发一次，然后自动删除。
• 周期任务（recurring）：按 Cron 计划反复触发，直到被删除或自动过期。

​

创建定时任务

在交互式会话中，用自然语言描述时间和要做的事，Qoder 就会为你创建定时任务。例如：

每天早上 9 点检查一次 CI 状态并汇总
每周一上午 10 点生成上周的提交摘要
2 月 28 日下午 2:30 提醒我发布版本

Qoder 会把你的描述解析成 Cron 表达式并创建任务。任务使用标准 5 字段 Cron 表达式（分钟、小时、日、月、星期），基于运行 CLI 的本地时区解释。

如果你想按固定时间间隔重复（例如”每 5 分钟”），使用更简单的 /loop，见 重复执行任务（/loop）。

​

Cron 表达式

定时任务使用 5 字段 Cron 表达式：

┌───────── 分钟 (0-59)
│ ┌─────── 小时 (0-23)
│ │ ┌───── 日 (1-31)
│ │ │ ┌─── 月 (1-12)
│ │ │ │ ┌─ 星期 (0-6，0=周日)
│ │ │ │ │
* * * * *

支持的字段语法：通配符 *、单值 N、步进 */N、区间 N-M、列表 N,M,...。星期字段中 7 会被当作周日（等同 0）。

不支持 L、W、?、名称别名（如 MON），也不含秒级字段。

示例：

Cron	含义
*/5 * * * *	每 5 分钟
0 * * * *	每小时整点
0 9 * * *	每天上午 9:00
30 14 28 2 *	2 月 28 日下午 2:30（当年一次）
0 10 * * 1	每周一上午 10:00
0 9 * * 1-5	工作日上午 9:00

所有时间都按运行 CLI 的本地时区解释。例如 0 9 * * * 表示 CLI 所在时区的每天 9 点。

​

保存位置与持久化

定时任务的持久化行为分两种：

• 持久化任务：写入项目根目录的 <project>/.qoder/scheduled_tasks.json，进程重启后仍然存在。
• 会话内任务：只保存在内存中，当前会话结束后消失。

保存到磁盘的任务在文件里以任务列表形式存储，每个任务包含 id、cron 表达式、prompt、创建时间等字段。

​

运行限制

定时任务有以下限制：

• 任务数量上限：最多 50 个任务。达到上限后需要先删除已有任务才能创建新任务。
• 周期任务自动过期：周期任务在创建后 7 天 自动过期，除非更早被删除。需要长期运行的任务需重新创建。
• 最小粒度：由于不含秒级字段，最小调度粒度是 1 分钟。
• 单进程驱动：同一项目目录由文件锁保证只有一个进程驱动调度，避免重复触发。

为了避免大量任务在同一时刻集中触发，调度器会为触发时间加入少量抖动：周期任务按下一周期长度的一小部分（最多 15 分钟）向后延迟；一次性任务在对齐到 30 分钟边界（整点和半点）时最多提前约 90 秒触发。

​

查看与删除

在会话中可以让 Qoder 列出当前的定时任务，或按 id 删除某个任务。例如：

列出所有定时任务
删除定时任务 <id>

创建任务时，Qoder 会返回该任务的 id，删除时用这个 id 指定要取消的任务。

​

错过的任务

如果 CLI 在某个任务本应触发的时间没有运行（例如进程当时未启动），该任务会被识别为”错过”。启动时 Qoder 会把错过的任务提示给你，便于你决定是否补跑或调整计划。

完整的字段、限制值和保存格式见 定时任务参考。