scheduled-task

name	scheduled_task
description	当用户需要创建、管理、查询定时任务时使用。帮助用户设置定期执行的自动化任务，如每日汇总、定期检查、周期性分析等。

定时任务管理 Scheduled Task Management

Overview

定时任务管理功能允许用户创建、查询、修改和删除定时执行的自动化任务。系统会按照设定的时间规则自动执行任务，并将结果保存到文件中。

适用场景：

• 每日/每周数据汇总和报告
• 定期系统监控和健康检查
• 周期性数据备份和清理
• 自动化的重复性工作
• 一次性的延时任务

核心功能

1. 创建定时任务 (Create)

用户可以通过 ScheduledTaskManager 工具创建定时任务。

调度类型：

• cron - 使用 cron 表达式定义复杂的时间规则

  格式: "分 时 日 月 周"
  示例:
  - "0 9 * * *"      每天9点
  - "0 */2 * * *"    每2小时
  - "0 9 * * 1-5"    工作日9点
  - "30 14 1 * *"    每月1号14:30
  

• interval - 固定时间间隔（秒）

  示例:
  - "3600"    每小时
  - "86400"   每天
  - "1800"    每30分钟
  

• datetime - 一次性任务（ISO 8601格式）

  示例:
  - "2026-04-10T14:30:00"  在2026年4月10日14:30执行一次
  

示例对话：

用户: 请帮我创建一个每天早上9点的数据汇总任务

助手: 好的，我来为您创建一个每日数据汇总的定时任务。

[调用 ScheduledTaskManager 工具]
{
  "operation": "create",
  "task_name": "每日数据汇总",
  "prompt": "请汇总昨天的数据分析结果，包括：1) 用户活跃度 2) 系统性能指标 3) 异常事件统计",
  "schedule_type": "cron",
  "schedule_config": "0 9 * * *",
  "task_description": "每天早上9点自动生成前一天的数据汇总报告"
}

✅ 定时任务创建成功！
任务ID: task_abc12345
下次执行: 2026-04-10T09:00:00

2. 查询任务列表 (List)

查看当前用户的所有定时任务。

示例对话：

用户: 我有哪些定时任务？

助手: [调用 ScheduledTaskManager 工具]
{
  "operation": "list"
}

共有 3 个定时任务：

- **每日数据汇总** (task_abc12345)
  - 状态: enabled
  - 调度: cron - 0 9 * * *
  - 下次执行: 2026-04-10T09:00:00
  - 执行次数: 15

- **系统监控** (task_def67890)
  - 状态: enabled
  - 调度: interval - 3600
  - 下次执行: 2026-04-09T20:30:00
  - 执行次数: 48

3. 查看任务详情 (Get)

查看特定任务的完整配置信息。

示例：

{
  "operation": "get",
  "task_id": "task_abc12345"
}

4. 删除任务 (Delete)

删除不再需要的定时任务。

示例对话：

用户: 删除那个系统监控任务

助手: [调用 ScheduledTaskManager 工具]
{
  "operation": "delete",
  "task_id": "task_def67890"
}

✅ 任务已删除: task_def67890

5. 启用/禁用任务 (Toggle)

暂时禁用或重新启用任务，而不删除它。

示例：

{
  "operation": "toggle",
  "task_id": "task_abc12345",
  "enabled": false
}

6. 查看执行历史 (Get Results)

查看任务的执行历史记录，包括成功/失败状态、执行时长等。

示例：

{
  "operation": "get_results",
  "task_id": "task_abc12345",
  "limit": 10
}

7. 查看输出文件 (Get Outputs)

获取任务生成的输出文件列表。每次任务执行都会生成一个 Markdown 格式的输出文件。

示例：

{
  "operation": "get_outputs",
  "task_id": "task_abc12345",
  "limit": 10
}

8. 读取输出内容 (Read Output)

读取特定输出文件的完整内容。

示例：

{
  "operation": "read_output",
  "file_path": "/path/to/outputs/task_abc12345/20260409_090000.md"
}

任务执行机制

1. 自动执行 - 定时任务管理器在后台运行，按照设定的时间规则自动触发任务
2. 独立会话 - 每个任务在执行时使用独立的 DrSaiAssistant 实例，避免干扰
3. 结果保存 - 执行结果自动保存为 Markdown 文件，便于查看和分享
4. 错误处理 - 执行失败会记录错误信息，并支持重试机制

输出文件位置：

<base_dir>/scheduled_tasks/outputs/<task_id>/<timestamp>.md

输出文件格式：

# 定时任务执行结果

**任务名称:** 每日数据汇总
**任务ID:** task_abc12345
**执行时间:** 2026-04-09 09:00:00
**用户ID:** [e-mail]
**会话ID:** thread_xyz

---

## 执行内容

请汇总昨天的数据分析结果...

---

## 执行结果

[助手生成的汇总报告内容]

最佳实践

1. 合理设置调度时间

• 避开高峰期 - 不要将所有任务都设置在整点（如 9:00、10:00）
• 考虑执行时长 - 确保任务间隔足够长，避免任务堆积
• 时区注意 - cron 表达式使用服务器本地时区

2. 明确任务描述

创建任务时，在 prompt 字段中清晰描述：

• 具体要做什么
• 需要哪些数据
• 输出格式要求

3. 监控任务状态

定期检查：

• 任务是否正常执行（get_results）
• 是否有错误（查看 error_count）
• 输出是否符合预期（read_output）

4. 及时清理

• 删除不再需要的任务
• 禁用临时不需要的任务（而不是删除）
• 定期清理旧的输出文件

常见问题

Q: 任务没有按时执行？

• 检查任务状态是否为 enabled
• 验证 next_run 时间是否正确
• 查看系统日志是否有错误

Q: 如何停止正在运行的任务？

• 将任务状态设置为 disabled
• 正在运行的任务会完成当前执行，之后不再触发

Q: 执行结果保存在哪里？

• 使用 get_outputs 查看输出文件列表
• 使用 read_output 读取具体文件内容
• 文件位置: <base_dir>/scheduled_tasks/outputs/<task_id>/

Q: cron 表达式怎么写？

格式: 分 时 日 月 周

* * * * *
│ │ │ │ │
│ │ │ │ └─ 周几 (0-6, 0=周日)
│ │ │ └─── 月份 (1-12)
│ │ └───── 日期 (1-31)
│ └─────── 小时 (0-23)
└───────── 分钟 (0-59)

特殊符号:
* - 任意值
*/n - 每n个单位
n-m - 范围
n,m - 列举

使用指南

作为智能体助手

当用户提到以下需求时，应该使用定时任务功能：

✅ 应该使用：

• "每天..."、"每周..."、"定期..."
• "帮我设置一个自动..."
• "能不能定时..."
• "我想让系统自动..."

❌ 不应该使用：

• 一次性的立即执行任务（直接执行即可）
• 需要实时响应的任务（应使用其他机制）
• 需要用户交互的任务（定时任务不支持交互）

作为用户

创建任务时应明确：

1. 任务名称 - 简短清晰
2. 执行内容 - 具体描述要做什么
3. 时间规则 - 选择合适的调度类型
4. 预期结果 - 说明期望的输出

技术细节

• 并发控制 - 同一任务不会同时运行多个实例
• 超时保护 - 默认 300 秒超时，可自定义
• 错误重试 - 最多重试 3 次
• 状态持久化 - 任务配置保存到 JSON 文件
• 日志记录 - 完整的执行日志

---

需要帮助？ 随时询问如何创建或管理定时任务！