tomevault-io 任务管理
FinchBot 支持两种任务类型：后台任务 和 定时任务。
一、后台任务
后台任务由独立的子代理执行，拥有完整的工具集，最多执行 15 次迭代。
使用场景
- 长时间运行的分析任务
- 需要多步骤执行的复杂操作
- 不需要立即结果的任务
工具列表
| 工具 | 说明 |
|---|---|
start_background_task |
启动后台任务 |
check_task_status |
检查任务状态 |
get_task_result |
获取任务结果 |
cancel_task |
取消任务 |
list_background_tasks |
列出所有任务 |
使用示例
# 启动后台任务
启动一个后台任务，分析项目代码结构并生成报告
# 检查状态
检查任务 abc123 的状态
# 获取结果
获取任务 abc123 的结果
# 列出任务
列出所有后台任务
# 取消任务
取消任务 abc123
任务状态
| 状态 | 说明 |
|---|---|
pending |
等待执行 |
running |
正在执行 |
completed |
已完成 |
failed |
执行失败 |
cancelled |
已取消 |
最佳实践
- 提供清晰的任务描述：详细说明要执行的任务，子代理会根据描述执行
- 使用标签：为任务添加标签便于识别
- 定期检查状态：长时间任务建议定期检查状态
- 及时取消：不需要的任务及时取消释放资源
二、定时任务
定时任务支持三种调度模式，可在指定时间自动执行。
调度模式
| 模式 | 参数 | 说明 | 示例 |
|---|---|---|---|
| 间隔任务 | every_seconds |
每 N 秒执行一次 | every_seconds=3600（每小时） |
| Cron 表达式 | cron_expr |
精确时间调度 | cron_expr="0 9 * * *"（每天 9:00） |
| 一次性任务 | at |
指定时间执行后删除 | at="2025-01-15T10:30:00" |
工具列表
| 工具 | 说明 |
|---|---|
create_cron |
创建定时任务 |
list_crons |
列出所有定时任务 |
get_cron_status |
获取任务详情 |
toggle_cron |
启用/禁用任务 |
run_cron_now |
立即执行任务 |
delete_cron |
删除任务 |
Cron 表达式格式
┌───────────── 分钟 (0-59)
│ ┌───────────── 小时 (0-23)
│ │ ┌───────────── 日期 (1-31)
│ │ │ ┌───────────── 月份 (1-12)
│ │ │ │ ┌───────────── 星期 (0-6, 0=周日)
│ │ │ │ │
* * * * *
常用 Cron 示例
| 表达式 | 说明 |
|---|---|
0 9 * * * |
每天 9:00 |
0 9 * * 1-5 |
工作日 9:00 |
*/30 * * * * |
每 30 分钟 |
0 0 * * * |
每天午夜 |
0 9 1 * * |
每月 1 日 9:00 |
时区支持
Cron 表达式支持 IANA 时区：
# 上海时区（东八区）
create_cron(name="早报", message="发送每日早报", cron_expr="0 9 * * *", tz="Asia/Shanghai")
# 纽约时区（西五区）
create_cron(name="晚报", message="发送每日晚报", cron_expr="0 17 * * *", tz="America/New_York")
使用示例
# 创建间隔任务（每小时检查一次）
创建定时任务"健康检查"，每小时执行一次，内容是检查系统状态
# 创建 Cron 任务（每天早上 9 点）
创建定时任务"早报"，每天 9 点执行，使用上海时区，内容是生成并发送每日早报
# 创建一次性任务
创建定时任务"提醒"，在 2025-01-15T10:30:00 执行，内容是提醒我参加会议
# 列出所有任务
列出所有定时任务
# 立即执行
立即执行定时任务 abc123
# 禁用任务
禁用定时任务 abc123
# 删除任务
删除定时任务 abc123
最佳实践
选择合适的调度模式：
- 固定间隔 →
every_seconds - 固定时间点 →
cron_expr - 一次性提醒 →
at
- 固定间隔 →
使用有意义的任务名称：便于识别和管理
指定时区：Cron 任务建议指定时区，避免时区问题
及时清理：不再需要的任务及时删除
三、任务执行结果通知
定时任务和后台任务执行完成后，结果会自动注入到当前会话：
- 定时任务：显示 "🔔 定时任务通知" 面板
- 后台任务：显示 "🔔 后台任务完成" 面板
Agent 可以读取这些通知并继续处理。
Source: xt765/FinchBot — distributed by TomeVault.