定时任务
Elftia 的定时任务系统（Cron）让你可以按计划自动执行重复性工作，支持桌面通知提醒和 AI Agent 自动执行任务两种动作类型，并可将结果推送到 Channel 消息渠道。
使用场景
- 每天上午 9 点让 AI 汇总最新技术新闻
- 每隔 30 分钟检查某个 API 的状态并通知你
- 在指定时间发送一次性提醒
- 定期让 AI Agent 执行数据分析并将结果推送到 Discord 或 Telegram
- 每周一早上自动生成本周工作计划
创建定时任务
操作步骤
- 打开 Cron 管理页面（从侧边栏或导航菜单进入）
- 点击 创建任务 按钮
- 填写任务信息：
- 任务名称 — 为任务取一个描述性名称
- 描述（可选） — 详细说明任务目的
- 调度方式 — 选择执行频率（见下方调度类型说明）
- 动作类型 — 选择通知或 Agent 执行
- 消息内容 — 通知文本或 Agent 提示词
- （可选）配置 Channel 推送
- （可选）选择 Agent 使用的 LLM 提供商和模型
- 点击 保存
调度类型
Elftia 支持三种调度方式，覆盖从简单到复杂的各种定时需求。
Cron 表达式
使用标准的 5 字段 cron 表达式精确控制执行时间。
格式： 分 时 日 月 周
| 字段 | 范围 | 特殊字符 |
|---|---|---|
| 分钟 | 0-59 | * , - / |
| 小时 | 0-23 | * , - / |
| 日期 | 1-31 | * , - / |
| 月份 | 1-12 | * , - / |
| 星期 | 0-7（0 和 7 均为周日） | * , - / |
常用示例：
| 表达式 | 含义 |
|---|---|
0 9 * * * | 每天上午 9:00 |
30 8 * * 1-5 | 工作日上午 8:30 |
0 */2 * * * | 每 2 小时整点 |
0 9 1 * * | 每月 1 日上午 9:00 |
0 9 * * 1 | 每周一上午 9:00 |
*/15 * * * * | 每 15 分钟 |
0 9,18 * * * | 每天 9:00 和 18:00 |
特殊字符说明：
| 字符 | 说明 | 示例 |
|---|---|---|
* | 匹配所有值 | * * * * * 每分钟 |
, | 列出多个值 | 0,30 * * * * 每小时的 0 分和 30 分 |
- | 范围 | 0 9-17 * * * 9 点到 17 点的每小时整点 |
/ | 步长 | */10 * * * * 每 10 分钟 |
:::tip 界面辅助 创建任务时，界面提供了可视化的调度模式选择器，包括每日、工作日、每周、每月、每小时等预设模式，无需手动编写 cron 表达式。选择预设模式后，系统自动生成对应的 cron 表达式。 :::
间隔执行（every）
以固定间隔重复执行任务。
格式： 数字 + 单位
| 单位 | 符号 | 示例 |
|---|---|---|
| 秒 | s | 30s — 每 30 秒 |
| 分钟 | m | 5m — 每 5 分钟 |
| 小时 | h | 1h — 每 1 小时 |
| 天 | d | 3d — 每 3 天 |
行为说明：
- 间隔从上次执行完成时间开始计算
- 应用重启后，系统会从上次记录的执行时间恢复计时，不会立即触发
一次性执行（at）
在指定的精确时间执行一次任务，执行后自动禁用。
格式： ISO 8601 日期时间字符串
示例： 2026-04-15T09:00:00
行为说明：
- 任务在到达指定时间后的下一个检查周期内触发（检查间隔为 30 秒）
- 执行完成后任务自动切换为禁用状态
- 已过期的一次性任务不会被触发
动作类型
通知（notify）
发送桌面系统通知。
- 任务触发时弹出桌面通知，显示任务名称和消息内容
- 需要系统允许应用发送通知
- 可在 Elftia 的通知设置中启用或禁用桌面通知
Agent 执行（agent）
触发 AI Agent 执行指定的提示词任务。
- 任务触发时，系统将消息内容作为提示词发送给 AI Agent
- Agent 会执行提示词中的指令并生成响应
- 响应内容会被记录在执行历史中（最多保留前 2000 个字符）
- 如果任务没有配置 Channel，执行结果会通过桌面通知展示（可通过
notifyOnComplete控制）
配置 LLM 提供商
Agent 任务可以指定使用的 LLM 提供商和模型：
| 配置项 | 说明 |
|---|---|
| 提供商 (providerId) | 选择执行任务的 LLM 提供商 |
| 模型 (model) | 选择具体的 AI 模型 |
如不指定，将使用当前默认的提供商和模型。
Channel 推送
定时任务支持将执行结果推送到外部消息渠道（如 Discord、Telegram 等）。
配置步骤
- 在创建或编辑任务时，启用 Channel 推送
- 选择目标 Channel（需要先在 Channel 管理中配置）
- 填写目标 Chat ID（Channel 内的群组或频道 ID）
- Agent 执行完毕后，会自动将结果发送到指定的 Channel
行为说明
- 配置了 Channel 的 Agent 任务，提示词中会包含 Channel 信息
- Agent 被指示使用
channel_sendMCP 工具将结果发送到目标 Channel - 没有配置 Channel 的 Agent 任务仅在本地执行，结果通过桌面通知展示
执行历史
每个任务的执行历史会自动记录，每个任务最多保留最近 200 条记录。
历史记录字段
| 字段 | 说明 |
|---|---|
| 时间戳 | 执行开始的时间 |
| 状态 | ok（成功）或 error（失败） |
| 耗时 | 执行持续时间（毫秒） |
| 错误信息 | 失败时的错误描述 |
| Agent 响应 | Agent 任务的回复内容（最多 2000 字符） |
查看历史
- 在 Cron 管理页面点击某个任务
- 展开任务详情面板
- 查看执行历史标签页
任务管理
暂停 / 恢复
- 点击任务的开关按钮可以暂停或恢复任务
- 暂停后任务不会被触发，直到重新启用
立即执行
- 点击任务的立即运行按钮，手动触发一次执行
- 不影响任务的正常调度计划
- 如果任务正在执行中，重复点击不会创建并发执行
编辑
- 点击任务进入编辑模式
- 可以修改名称、描述、调度方式、动作类型和 Channel 配置
- 修改后下次执行时间会自动重新计算
删除
- 删除任务会同时清除其执行历史记录
- 删除操作不可撤销
状态事件广播
定时任务在执行过程中会广播状态事件到前端界面：
| 状态 | 说明 |
|---|---|
running | 任务开始执行 |
success | 任务执行成功 |
error | 任务执行失败 |
界面会实时更新任务状态指示器，方便你了解后台任务的运行情况。
系统行为
| 行为 | 说明 |
|---|---|
| 轮询间隔 | 每 5 秒重新加载任务配置 |
| 检查间隔 | 每 30 秒检查一次调度时间 |
| Cron 去重 | 同一分钟内同一 cron 任务只触发一次 |
| 并发控制 | 同一任务不会并发执行 |
| 数据存储 | 任务配置存储在 jobs.json，历史记录存储在 runs/ 目录 |
常见问题
| 问题 | 解决方案 |
|---|---|
| 任务没有按时执行 | 确认任务处于启用状态，检查调度表达式是否正确 |
| Cron 表达式无效 | 使用界面提供的可视化调度模式，或参考上方的表达式示例 |
| Agent 任务执行失败 | 检查 LLM 提供商配置是否正确，确认 API Key 有效 |
| Channel 推送没有收到消息 | 确认 Channel 配置正确，检查 Chat ID 是否有效 |
| 一次性任务没有触发 | 确认指定的时间未过期，时间需要使用 ISO 格式 |
| 历史记录被截断 | 系统自动保留最近 200 条记录，更早的记录会被清除 |
| 应用重启后间隔任务立即触发 | 正常情况下不会立即触发，系统会从上次执行时间恢复计时 |