> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 定时执行任务

# 概述

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

定时任务分两种：

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

# 创建定时任务

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

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

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

如果你想按固定时间间隔重复（例如"每 5 分钟"），使用更简单的 `/loop`，见 [重复执行任务（/loop）](https://docs.qoder.com/zh/cli/03-使用QoderCLI/02-任务自动化/loop.md)。

# Cron 表达式

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

```text theme={null}
┌───────── 分钟 (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 删除某个任务。例如：

```text theme={null}
列出所有定时任务
删除定时任务 <id>
```

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

# 错过的任务

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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.