定时任务

概述

定时任务（Cron Jobs）允许你配置 Agent 定期自动执行重复性工作，无需手工干预。适用场景包括：

• 每日代码审查
• 每周安全扫描
• 每月依赖更新检查
• 定时日志分析和报告生成

定时任务由 Agent 本身通过 MCP 工具创建和管理，而不是由 Sink 直接调度。Agent 可以在任务执行期间设置、修改或取消定时任务。

了解定时任务

Task 与 Cron Job 的关系

• Task：单次 Agent 工作会话（如一次代码审查）
• Cron Job：重复执行的任务定义（如每天运行代码审查）

Cron Job 的每一次执行都对应一个独立的 Task。系统会在预定时间自动创建新 Task，并使用相同的 Profile 启动 Agent。

Cron 表达式

定时任务使用标准的 Cron 表达式格式（5 字段）：

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

Cron 表达式示例

通配符说明

创建定时任务

通过 Agent 创建

Agent 可以在任务执行期间通过 MCP 工具创建定时任务：

请为我创建一个定时任务：
- 名称："Daily Code Review"
- Cron 表达式：0 2 * * * （每天凌晨 2 点）
- 描述：每天自动审查代码变更

Agent 会：

1. 验证 Cron 表达式的有效性
2. 注册定时任务到系统
3. 在指定时间自动触发

调度参数

Sink 提供了两种 cron 模式，每种模式有不同的参数：

通知模式（cron_set）

在预定时间向当前任务发送消息。

• scheduleId：调度的唯一标识符。允许字符：字母数字、_ 和 -。最大 64 字符。示例：daily-reminder
• Cron 表达式：标准 5 字段 cron 表达式（见上文）
• message：每次触发时发送到该任务收件箱的文本消息
• enabled（可选）：是否立即启用调度。默认为 true

生成模式（cron_spawn）

在预定时间创建新的子任务。

• scheduleId：调度的唯一标识符。命名规则与通知模式相同
• Cron 表达式：标准 5 字段 cron 表达式（见上文）。最小间隔：5 分钟
• prompt：每次触发时生成的子任务需要完成的工作描述
• enabled（可选）：是否立即启用调度。默认为 true
• concurrency（可选）：控制上一次调用仍在运行时的行为：
  • serial（默认）— 如果上一个子任务仍在活跃，则跳过本次触发
  • parallel — 每次触发都创建新任务
• profileId（可选）：生成的子任务使用哪个 Profile
• executionMode（可选）：生成的子任务的执行模式，individual 或 team
• managed（可选）：生成的子任务是否在托管模式下运行（默认为 false）
• configOverrides（可选）：对生成的子任务 Profile 的逐配置项值覆盖

查看已创建的定时任务

在任务详情页面的”定时任务”标签中，你可以看到：

• 任务名称：定时任务的标识
• Cron 表达式：执行时间表
• 创建时间：何时创建的
• 最后执行时间：上次运行的时间
• 下次执行时间：下次运行的预期时间
• 状态：启用/禁用

管理定时任务

暂停定时任务

如果需要暂时停止某个定时任务，可以在 Web UI 中禁用它：

1. 打开包含该定时任务的 Task
2. 找到”定时任务”标签
3. 选择要禁用的任务
4. 点击”禁用”按钮

禁用后不会自动执行，但配置会保留。

重新启用定时任务

1. 在”定时任务”标签中选择已禁用的任务
2. 点击”启用”按钮

任务会按照原定时间表恢复执行。

修改定时任务

系统不支持直接修改定时任务的参数。如需更改时间表或消息内容，请先删除再重新创建：

1. 让 Agent 删除现有定时任务（cron_remove）
2. 让 Agent 用新参数重新创建定时任务（cron_set 或 cron_spawn）

例如：

删除定时任务 "Daily Code Review"，然后创建一个新的：
- 新的 Cron 表达式：0 10 * * 1-5 （改为工作日上午 10 点）

删除定时任务

如果不再需要某个定时任务，可以删除它：

1. 在”定时任务”标签中选择要删除的任务
2. 点击”删除”按钮
3. 确认删除

删除后该定时任务将不会再执行。

定时任务的执行

自动执行流程

当定时任务触发时：

1. 创建新 Task
   • 系统自动创建新的 Task 实例
   • Task 使用与原始任务相同的 Profile 和配置
   • Task 的描述会包含”自动执行”标记
2. 启动 Agent
   • Agent 按照 Profile 定义的系统提示启动
   • Agent 自动加载相同的指令文件和配置
3. 执行工作
   • Agent 执行分配的工作
   • 你仍然可以实时监控进度
   • 需要权限时 Agent 仍会询问
4. 任务完成
   • Agent 完成工作并生成报告
   • Task 进入终态

查看执行历史

点击定时任务的”历史”选项，可以看到所有过去的执行记录：

• 执行时间
• 任务 ID
• 执行状态（成功/失败/进行中）
• 运行时长
• 生成的报告

常见场景

场景 1：每日代码审查

定时任务配置：
- 名称：Daily Code Review
- Profile：Code Reviewer
- Cron：0 2 * * *
- 描述：每天凌晨 2 点自动审查新代码，检查质量和正确性问题

步骤：
1. Agent 自动启动
2. 读取最近 24 小时的代码变更
3. 执行安全分析
4. 生成审计报告
5. 发送通知或邮件

场景 2：每周依赖检查

定时任务配置：
- 名称：Weekly Dependency Audit
- Profile：Dependency Analyzer
- Cron：0 0 * * 0
- 描述：每周日午夜检查依赖更新和安全补丁

步骤：
1. 扫描所有依赖版本
2. 检查已知漏洞数据库
3. 识别可用的安全更新
4. 生成升级建议报告

场景 3：月度报告生成

定时任务配置：
- 名称：Monthly Summary
- Profile：Report Generator
- Cron：0 9 1 * *
- 描述：每月 1 号上午 9 点生成汇总报告

步骤：
1. 收集上月的数据和指标
2. 分析趋势和变化
3. 生成详细报告
4. 发送给相关团队

定时任务的最佳实践

1. 合理设置执行时间

• 避免高峰时段：在非办公时间执行，避免影响其他工作
• 考虑时区：明确 cron 时间在哪个时区执行
• 避免冲突：不要让多个定时任务在同一时间运行（除非必要）

2. 设置监控和告警

• 定期检查”执行历史”
• 发现失败时及时调查
• 考虑让 Agent 在失败时发送通知

3. 定期审查

• 每月检查定时任务列表，删除不再需要的
• 根据实际需要调整执行时间
• 验证 Agent 的执行质量

4. 资源考虑

• 并发执行的定时任务数受限于 settings.json 中的 agentLifecycle.maxConcurrent
• 避免定时任务消耗过多资源
• 监控系统资源使用情况
• 每个任务最多可包含 32 个定时调度（MAX_CRON_SCHEDULES）
• spawn 调度的最小间隔为 5 分钟（更密集的表达式最多每 5 分钟触发一次）

5. 日志和报告

• 让 Agent 为每次执行生成详细日志
• 保留执行历史供后续审查
• 定期导出报告存档

故障排除

定时任务没有按时执行

可能原因：

• Cron 表达式不正确
• 系统处于维护或停机状态
• 表达式间隔短于 5 分钟（spawn 调度有速率限制，最小间隔为 5 分钟；更密集的表达式最多每 5 分钟触发一次）
• 并发槽位已满，新 Task 排队等待

检查步骤：

1. 验证 Cron 表达式语法（可用在线 cron 工具检查）
2. 检查系统是否在线
3. 确认表达式间隔不少于 5 分钟（spawn 速率限制）
4. 查看”并发任务”数量是否达到上限

定时任务执行失败

可能原因：

• Agent 遇到错误
• 所需的数据或工具不可用
• Profile 配置不适合定期执行

调查步骤：

1. 在”执行历史”中查看失败的 Task
2. 读取 Task 的详细日志和错误信息
3. 手动运行一次测试 Task，看是否能重现问题
4. 修改 Profile 或指令后，编辑定时任务并重新启用

定时任务创建成功但未显示

可能原因：

• 浏览器缓存
• 定时任务在其他标签页中创建
• 权限限制

解决方案：

1. 刷新页面（F5）
2. 检查其他打开的标签页中是否存在该任务
3. 验证你有权限查看该 Task 的定时任务

后续步骤

• 管理 Profile：为定时任务选择合适的 Profile
• 配置网关：调整系统并发设置
• 快速开始：创建第一个任务并了解工作流程