跳到主要内容

定时任务

Elftia 的定时任务系统(Cron)让你可以按计划自动执行重复性工作,支持桌面通知提醒和 AI Agent 自动执行任务两种动作类型,并可将结果推送到 Channel 消息渠道。

使用场景​

  • 每天上午 9 点让 AI 汇总最新技术新闻
  • 每隔 30 分钟检查某个 API 的状态并通知你
  • 在指定时间发送一次性提醒
  • 定期让 AI Agent 执行数据分析并将结果推送到 Discord 或 Telegram
  • 每周一早上自动生成本周工作计划

创建定时任务​

操作步骤​

  1. 打开 Cron 管理页面(从侧边栏或导航菜单进入)
  2. 点击 创建任务 按钮
  3. 填写任务信息:
    • 任务名称 — 为任务取一个描述性名称
    • 描述(可选) — 详细说明任务目的
    • 调度方式 — 选择执行频率(见下方调度类型说明)
    • 动作类型 — 选择通知或 Agent 执行
    • 消息内容 — 通知文本或 Agent 提示词
  4. (可选)配置 Channel 推送
  5. (可选)选择 Agent 使用的 LLM 提供商和模型
  6. 点击 保存

调度类型​

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)​

以固定间隔重复执行任务。

格式: 数字 + 单位

单位符号示例
秒s30s — 每 30 秒
分钟m5m — 每 5 分钟
小时h1h — 每 1 小时
天d3d — 每 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 等)。

配置步骤​

  1. 在创建或编辑任务时,启用 Channel 推送
  2. 选择目标 Channel(需要先在 Channel 管理中配置)
  3. 填写目标 Chat ID(Channel 内的群组或频道 ID)
  4. Agent 执行完毕后,会自动将结果发送到指定的 Channel

行为说明​

  • 配置了 Channel 的 Agent 任务,提示词中会包含 Channel 信息
  • Agent 被指示使用 channel_send MCP 工具将结果发送到目标 Channel
  • 没有配置 Channel 的 Agent 任务仅在本地执行,结果通过桌面通知展示

执行历史​

每个任务的执行历史会自动记录,每个任务最多保留最近 200 条记录。

历史记录字段​

字段说明
时间戳执行开始的时间
状态ok(成功)或 error(失败)
耗时执行持续时间(毫秒)
错误信息失败时的错误描述
Agent 响应Agent 任务的回复内容(最多 2000 字符)

查看历史​

  1. 在 Cron 管理页面点击某个任务
  2. 展开任务详情面板
  3. 查看执行历史标签页

任务管理​

暂停 / 恢复​

  • 点击任务的开关按钮可以暂停或恢复任务
  • 暂停后任务不会被触发,直到重新启用

立即执行​

  • 点击任务的立即运行按钮,手动触发一次执行
  • 不影响任务的正常调度计划
  • 如果任务正在执行中,重复点击不会创建并发执行

编辑​

  • 点击任务进入编辑模式
  • 可以修改名称、描述、调度方式、动作类型和 Channel 配置
  • 修改后下次执行时间会自动重新计算

删除​

  • 删除任务会同时清除其执行历史记录
  • 删除操作不可撤销

状态事件广播​

定时任务在执行过程中会广播状态事件到前端界面:

状态说明
running任务开始执行
success任务执行成功
error任务执行失败

界面会实时更新任务状态指示器,方便你了解后台任务的运行情况。

系统行为​

行为说明
轮询间隔每 5 秒重新加载任务配置
检查间隔每 30 秒检查一次调度时间
Cron 去重同一分钟内同一 cron 任务只触发一次
并发控制同一任务不会并发执行
数据存储任务配置存储在 jobs.json,历史记录存储在 runs/ 目录

常见问题​

问题解决方案
任务没有按时执行确认任务处于启用状态,检查调度表达式是否正确
Cron 表达式无效使用界面提供的可视化调度模式,或参考上方的表达式示例
Agent 任务执行失败检查 LLM 提供商配置是否正确,确认 API Key 有效
Channel 推送没有收到消息确认 Channel 配置正确,检查 Chat ID 是否有效
一次性任务没有触发确认指定的时间未过期,时间需要使用 ISO 格式
历史记录被截断系统自动保留最近 200 条记录,更早的记录会被清除
应用重启后间隔任务立即触发正常情况下不会立即触发,系统会从上次执行时间恢复计时

相关链接​

  • Agent — 了解 Agent 系统,Agent 是定时任务的执行引擎
  • Channel — 配置消息推送渠道
  • 聊天 — 在对话中使用 AI 功能