# 定时任务

定时任务（Cron）是 JiuwenSwarm 中实现自动化执行的重要机制。

---

## 概念科普

### 什么是定时任务

**定时任务（Cron Job）** 是一种按照预设时间计划自动执行任务的机制。在 JiuwenSwarm 中，定时任务可以让 Agent 在指定时间自动执行特定操作，并将结果推送到指定频道。

**核心能力：**

| 能力 | 说明 |
|------|------|
| **定时执行** | 按照 Cron 表达式定义的时间计划自动触发 |
| **自然语言描述** | 用自然语言描述任务内容，Agent 自动理解执行 |
| **多频道推送** | 结果可推送到 Web、飞书、微信等频道 |
| **自动唤醒** | 提前唤醒 Agent 做准备，确保准时执行 |
| **Team/SwarmFlow** | 支持多 Agent 协作，适合复杂任务（见 [§6](#6-team-模式与-swarmflow多智能体定时任务)） |

**典型应用场景：**

- 📅 **每日提醒**：每天固定时间发送工作提醒、健康提醒等
- 📊 **周期汇总**：定期汇总数据、生成日报/周报
- 🔄 **定时检查**：定时检查系统状态、监控任务进度
- 📢 **消息推送**：定时向指定频道推送消息或通知
- 🤝 **协作任务**：Team 模式下多 Agent 协作完成复杂分析任务

### Cron 表达式原理

Cron 表达式是定义定时任务执行时间规则的标准格式。

**基本格式：**

```
分 时 日 月 周
```

| 字段 | 取值范围 | 说明 |
|------|----------|------|
| 分 | 0-59 | 分钟 |
| 时 | 0-23 | 小时 |
| 日 | 1-31 | 日期 |
| 月 | 1-12 | 月份 |
| 周 | 0-6 | 星期（0=周日） |

**特殊字符：**

| 字符 | 说明 | 示例 |
|------|------|------|
| `*` | 任意值 | `* * * * *` = 每分钟 |
| `,` | 列举多个值 | `0,30 * * * *` = 每小时的第0和第30分钟 |
| `-` | 范围 | `0 9-17 * * *` = 9点到17点每小时 |
| `/` | 间隔 | `*/15 * * * *` = 每15分钟 |

**常用表达式示例：**

| 表达式 | 含义 |
|--------|------|
| `0 9 * * *` | 每天早上 9:00 |
| `30 18 * * *` | 每天下午 18:30 |
| `0 9 * * 1` | 每周一早上 9:00 |
| `0 9,18 * * *` | 每天 9:00 和 18:00 |
| `*/30 * * * *` | 每 30 分钟 |
| `0 0 * * *` | 每天凌晨 0:00 |

### 定时任务与心跳的区别

JiuwenSwarm 提供了两种自动化机制：**定时任务**和**心跳**。详细对比请参考 [心跳教程](心跳.md)。

| 对比项 | 定时任务 (Cron) | 心跳 (Heartbeat) |
|--------|-----------------|------------------|
| **触发方式** | 按固定时间计划触发 | 按固定间隔周期触发 |
| **时间定义** | 使用 Cron 表达式（如每天9点） | 使用间隔时间（如每5分钟） |
| **适用场景** | 有明确时间点的任务（日报、提醒、协作分析） | 持续性检查、状态监控 |
| **配置方式** | 配置 Cron 表达式 | 配置心跳间隔 |
| **执行精度** | 精确到指定时间点 | 按间隔周期执行 |

---

## 快速上手

### 通过 Web 界面创建

**操作步骤：**

1. 打开 JiuwenSwarm Web 界面，在左侧导航栏点击「**工作**」
2. 在工作页面左侧子面板中，点击「**定时任务**」
3. 进入定时任务管理页面，点击「**创建**」按钮
4. 填写任务配置表单：

![定时任务页面](../assets/images/current-ui/11-定时任务页面.png)

| 配置项 | 说明 | 示例 |
|--------|------|------|
| **任务名称** | 任务名称（唯一标识） | `daily_reminder` |
| **cron表达式** | Cron 表达式 | `0 9 * * *`（每天9点） |
| **时区** | 任务执行时区 | `Asia/Shanghai`（默认） |
| **状态** | 任务状态 | 启用/停用 |
| **描述** | 任务内容描述 | 生成今日工作提醒 |
| **唤醒偏移秒数** | 提前唤醒秒数 | `0`（默认，不提前唤醒） |
| **推送频道** | 结果推送频道 | `web`、`feishu`、`wechat`、`wecom`、`whatsapp`、`telegram` 等 |
| **执行模式** | Agent 执行模式 | `agent.plan`（默认） |
| **项目目录** | 任务归属的项目工作目录（绝对路径） | `/home/user/my-project`；不填则默认取当前会话所在项目 |

4. 点击 **「创建」**，任务将自动生效

**项目归属说明：**

定时任务创建后自动归属到指定 `project_dir` 对应的项目（匹配不到可见项目则归默认项目）。后续可以在项目视图下按项目维度管理定时任务及其执行会话。

**存储位置：**

定时任务配置保存在：
```
~/.jiuwenswarm/agent/home/cron_jobs.json
```

### 通过对话创建

当 Agent 具备 `cron_create_job` 工具能力时，您可以直接通过自然语言对话创建定时任务。

![通过对话创建定时任务](../assets/images/current-ui/20-定时任务-创建页.png)

**示例对话：**

```
用户：帮我创建一个定时任务，每天早上9点提醒我喝水。
```

Agent 会自动：
1. 解析时间意图 → `cron_expr: "0 9 * * *"`
2. 理解任务内容 → `description: "提醒喝水"`
3. 确定推送频道 → `targets: "web"`
4. 调用工具创建任务

> **提示**：通过对话创建任务时，Agent 会根据上下文自动推断合理的默认值，如时区、频道等。

---

## 定时任务执行

### 执行过程

到固定时间触发定时任务后，对话页面会返回一个执行中的对话。

**执行流程：**

1. **触发时刻**：到达 Cron 表达式定义的时间点
2. **Agent 唤醒**：根据 `wake_offset_seconds` 提前唤醒 Agent
3. **任务执行**：Agent 开始执行任务描述中的内容
4. **结果推送**：执行完成后，结果推送到指定频道

**执行状态：**

| 状态 | 说明 |
|------|------|
| **待执行** | 任务已创建，等待触发时间 |
| **执行中** | Agent 正在执行任务 |
| **已完成** | 任务执行完毕，结果已推送 |
| **执行失败** | 任务执行过程中出现错误 |

### 查看执行结果

定时任务执行完毕的返回结果可以在对话页面查看

![定时任务执行](../assets/images/current-ui/10-工作页面-完整.png)

上图展示了定时任务触发后的执行过程。

![定时任务执行2](../assets/images/current-ui/10-工作页面-完整.png)

上图展示了定时任务执行完成后的结果展示。
---

## 定时任务管理

创建后任务可以在前端页面进行以下操作：

| 操作 | 说明 |
|------|------|
| **立即执行** | 手动触发任务立即执行一次，返回 `{accepted, run_id, session_id}`，可通过 `session_id` 跳转到执行会话 |
| **预览** | 查看任务配置详情（含 `project_id` 归属项目、`last_session_id` 最近执行会话） |
| **停用** | 暂停任务，不再自动触发 |
| **更新** | 修改任务配置（含更新 `project_dir` 变更归属项目） |
| **删除** | 删除任务 |

### 任务与执行会话的双向关联

定时任务执行后会自动创建执行会话，可通过以下字段双向跳转：

| 字段 | 位置 | 说明 |
|------|------|------|
| `project_id` | CronJob | 任务归属的项目 ID |
| `last_session_id` | CronJob | 最近一次执行产生的会话 ID（未执行过为 `null`） |
| `cron_id` | SessionInfo | 会话来源的定时任务 ID（普通会话为空串） |

- 从任务跳转会话：通过 `cron.job.get` 返回的 `last_session_id`
- 从会话反查任务：通过 `project.get_cron_sessions` 按 `cron_id` 过滤
- 项目视图聚合：`project.get_sessions`（普通会话）+ `project.get_cron_sessions`（cron 会话）互斥分工

---

## 案例实践

### 每日工作提醒

**场景描述：** 每天早上 9 点自动生成工作提醒，推送到 Web 界面。

**配置步骤：**

1. 创建定时任务，对话框输入：
```每天早上 9 点自动生成今日工作提醒，包括：1) 待办事项列表 2) 重要日程提醒 3) 天气信息```

![工作提醒定时任务执行1](../assets/images/current-ui/10-工作页面-完整.png)

2. 创建成功后，每天 9:00 Agent 会自动执行并推送结果

**数据获取说明：** 待办、日程等由 Agent 从 `agent/memory/` 记忆文件中读取（来自日常对话写入）；天气等通过搜索工具获取。记忆里没有的内容，提醒中通常不会出现。


**执行效果：**

![工作提醒定时任务执行2](../assets/images/current-ui/10-工作页面-完整.png)

```
📋 今日工作提醒（2026年5月20日 星期三）
1️⃣ 待办事项列表
当前暂无待办事项。

2️⃣ 重要日程提醒
今日暂无重要日程安排。

3️⃣ 天气信息
今日天气：

- 🌫️ 天气状况：阴天
- 🌡️ 气温：16℃ ~ 25℃
- 💨 风向风力：东风，微风
- 📍 地区：北京

未来三天预报：

- 5月21日（周四）：多云转小雨，16℃ ~ 24℃，南风微风
- 5月22日（周五）：中雨转阴，17℃ ~ 23℃，南风微风
- 5月23日（周六）：多云，19℃ ~ 28℃，西南风微风

温馨提示：

- 今日阴天，气温适中，建议穿着轻薄外套
- 明后两天有降雨，请提前准备雨具
- 周末天气转好，适合户外活动
- 祝您工作顺利！如有新的待办事项或日程安排，随时告诉我。
```

---

## 常见问题

### Q1: 定时任务没有按时执行怎么办？

**排查步骤：**

1. 检查任务是否启用（`enabled: true`）
2. 检查 Cron 表达式是否正确
3. 检查时区设置是否正确
4. 检查 JiuwenSwarm 服务是否在运行
5. 查看日志文件确认是否有错误

### Q2: 如何修改已创建的定时任务？

在 Web 界面的定时任务列表中，点击任务右侧的 **「编辑」** 按钮，修改配置后保存即可。修改后调度器会自动更新。

### Q3: 定时任务的结果会保存吗？

定时任务执行的结果会：
- 推送到指定频道（Web/飞书等）
- 作为会话历史保存在对应的会话文件中
- 可通过会话管理查看历史执行记录

### Q4: wake_offset_seconds 是什么作用？

`wake_offset_seconds` 定义了提前唤醒 Agent 的时间（默认 `0`，即不提前唤醒）。例如设置为 `300`（5分钟）时：
- 任务设定 9:00 执行
- `wake_offset_seconds: 300`（5分钟）
- Agent 会在 8:55 开始准备，确保 9:00 准时执行

### Q5: 定时任务支持哪些推送频道？

目前支持的频道：
- `web` - Web 界面
- `feishu` - 飞书
- `wechat` - 微信
- `wecom` - 企业微信
- `whatsapp` - WhatsApp
- `telegram` - Telegram

---

## 6. Team 模式与 SwarmFlow（多智能体定时任务）

除默认的单 Agent 模式外，定时任务现已支持 **Team 模式**，可在到点时启动多智能体协作，并可选走 **SwarmFlow** 工作流（详见 [Agent Team 使用指南](AgentTeam.md)、[TUI 使用 SwarmFlow 指南](TUI使用SwarmFlow指南.md)）。

#### 6.1 支持的执行模式（`mode`）

| `mode` | 说明 |
|---|---|
| `agent.fast` | **默认**。单 Agent 快速执行，适合简单提醒、查询类任务 |
| `agent` / `agent.plan` / `plan` | 单 Agent 规划或推理后执行 |
| `team` | 多 Agent Team 协作；可触发 SwarmFlow |
| `team.plan` | Team + 规划类协作 |
| `code.team` | 编码向 Team 协作 |

TUI / Web 创建任务时可传 `mode=`；前端通过 `cron.job.meta` 拉取当前支持的 mode 列表与默认超时配置。

#### 6.2 创建示例

```text
# 每周一 9 点，Team 协作生成对比报告（结果推送到 TUI）
/cron add name=模型周报 cron_expr="0 9 * * 1" description="对比 GLM 与 DeepSeek 近期能力并输出 Markdown 报告" mode=team targets=tui

# 简单提醒仍用默认 agent.fast
/cron add name=喝水提醒 cron_expr="0 30 8 * * *" description="提醒用户喝水" targets=tui
```

可选 **`timeout_seconds`**（60～259200 秒）覆盖单次执行超时：

| 模式 | 默认超时 |
|---|---|
| `agent.fast` 等普通模式 | 600 秒（10 分钟） |
| `team` / `team.plan` / `code.team` | 1200 秒（20 分钟） |

```text
/cron add name=长报告 cron_expr="0 9 * * 1" description="..." mode=team timeout_seconds=3600 targets=tui
```

#### 6.3 执行与推送行为（与单 Agent 任务的区别）

**执行路径**

- 普通模式（非 Team）：经 `__cron__` 通道、**非流式** unary 调用 Agent，session 为 `cron_{时间戳}_{job_id}`。
- Team 模式：**流式**调用 AgentServer（`mode=team`），同样使用独立 session `cron_{时间戳}_{job_id}`，**不绑定**创建任务时的 TUI `session_id`。

**为何使用独立 session**

- 创建任务时仍会记录 `session_id`（主要用于飞书等 IM 推送路由）。
- Team 执行 deliberately 使用 `cron_*` session，避免关闭创建者 TUI 窗口时，`cancel_agent_sessions_on_disconnect` 误取消仍在运行的 Team 定时流。
- **代价**：执行过程中 **不会** 在创建者 TUI 窗口实时展示 SwarmFlow / Team 成员进度（事件带 `cron_*` session，当前窗口不会订阅）。

**结果推送**

所有 `targets`（`web`、`tui`、飞书、钉钉、企业微信等）共用同一套 `_push_to_targets` 推送逻辑，正文格式如下：

| 场景 | 推送正文格式 |
|---|---|
| **正常完成** | `{Agent 返回正文}`（不拼接任务名前缀，也无 `[cron]` 前缀） |
| **执行失败 / 超时 / 无有效报告等** | 以 `[cron]` 开头的状态文案（如 `[cron] 任务执行失败: …`），不拼接任务名前缀 |
| **执行中占位** | `{任务名} 正在执行中，结果稍后补发（push_at=…）` |

各频道差异主要在 **路由**，不在正文格式：

- **`web`**：推到 Web 聊天面板；占位消息可通过 `payload.cron.is_placeholder` 与正式结果关联替换。
- **`tui`**：故意不绑定 `session_id`，Gateway **广播**到所有已连接 TUI 窗口；若完成瞬间无 TUI 在线，广播可能丢失。
- **飞书 / 钉钉 / 企业微信等 IM**：优先使用创建任务时绑定的 `session_id` 与 `metadata` 路由到对应会话；群聊创建的任务可走 IMOutboundPipeline 路由决策。

请保持 Gateway 运行；也可通过 `/cron show` 或 Web 定时任务面板查看任务配置。

**结束判定（Team）**

Gateway 与 AgentServer 共用 `jiuwenswarm/common/cron_team_completion.py` 中的逻辑，避免以下误判：

- Leader 中间回复、占位话术被当成最终报告；
- Harness 委派尚未完成（仍有 open `team.task` 或成员 busy）时提前结束；
- SwarmFlow 未完成时因 Leader  interim `chat.final` 提前结束。

仅当满足对应场景的结构化完成信号（如 workflow `completed` + Leader 最终报告、或 Harness 侧 Leader final 且无未完成任务）才结束流并写入 `result_text`。

#### 6.4 相关实现位置（开发者）

| 模块 | 职责 |
|---|---|
| `gateway/cron/scheduler.py` | 调度 wake/push；Team 流式消费与超时；`_format_cron_broadcast_text` 格式化推送 |
| `gateway/cron/models.py` | `mode` / `timeout_seconds` 校验与默认值 |
| `common/cron_team_completion.py` | Team 轮次结束判定共享状态机 |
| `server/runtime/agent_adapter/team_helpers.py` | Cron Team 首轮/后续流、提前结束 background stream |
| `channels/tui/.../cron.ts` | `/cron` 子命令与 `mode`、`timeout_seconds` 参数 |

更完整的 Slash 参数说明见 [Slash 命令表 — `/cron`](Slash命令表.md#cron定时任务管理)。

---

## 相关链接

- [心跳机制](心跳.md) - 了解心跳与定时任务的区别
- [频道配置](频道.md) - 配置消息推送频道
- [任务规划](任务规划.md) - 了解任务管理机制
- [对话教程](智能体.md) - 了解对话功能

---

*文档版本：v1.0*  
*适用对象：JiuwenClaw 用户*  
*最后更新：2026-05-05*