task-management

name	task-management
description	后台任务和定时任务管理指南，支持异步执行和定时调度。
homepage
metadata	{"finchbot":{"emoji":"📋","requires":{}}}

任务管理

FinchBot 支持两种任务类型：后台任务 和 定时任务。

一、后台任务

后台任务由独立的子代理执行，拥有完整的工具集，最多执行 15 次迭代。

使用场景

• 长时间运行的分析任务
• 需要多步骤执行的复杂操作
• 不需要立即结果的任务

工具列表

工具	说明
start_background_task	启动后台任务
check_task_status	检查任务状态
get_task_result	获取任务结果
cancel_task	取消任务
list_background_tasks	列出所有任务

使用示例

# 启动后台任务
启动一个后台任务，分析项目代码结构并生成报告

# 检查状态
检查任务 abc123 的状态

# 获取结果
获取任务 abc123 的结果

# 列出任务
列出所有后台任务

# 取消任务
取消任务 abc123

任务状态

状态	说明
pending	等待执行
running	正在执行
completed	已完成
failed	执行失败
cancelled	已取消

最佳实践

1. 提供清晰的任务描述：详细说明要执行的任务，子代理会根据描述执行
2. 使用标签：为任务添加标签便于识别
3. 定期检查状态：长时间任务建议定期检查状态
4. 及时取消：不需要的任务及时取消释放资源

---

二、定时任务

定时任务支持三种调度模式，可在指定时间自动执行。

调度模式

模式	参数	说明	示例
间隔任务	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

最佳实践

1. 选择合适的调度模式：

   • 固定间隔 → every_seconds
   • 固定时间点 → cron_expr
   • 一次性提醒 → at

2. 使用有意义的任务名称：便于识别和管理

3. 指定时区：Cron 任务建议指定时区，避免时区问题

4. 及时清理：不再需要的任务及时删除

---

三、任务执行结果通知

定时任务和后台任务执行完成后，结果会自动注入到当前会话：

• 定时任务：显示 "🔔 定时任务通知" 面板
• 后台任务：显示 "🔔 后台任务完成" 面板

Agent 可以读取这些通知并继续处理。