task-management git:20260303.c69e59dA

Immutable. This exact content is served forever at /api/v1/blob/29c09355ce083abd.

---
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 可以读取这些通知并继续处理。