# 计划任务API

<cite>
**本文档引用的文件**
- [src/app/api/cron-tasks/route.ts](file://src/app/api/cron-tasks/route.ts)
- [src/app/api/cron-tasks/[id]/route.ts](file://src/app/api/cron-tasks/[id]/route.ts)
- [src/app/api/cron-tasks/[id]/execute/route.ts](file://src/app/api/cron-tasks/[id]/execute/route.ts)
- [src/app/api/task-executions/route.ts](file://src/app/api/task-executions/route.ts)
- [src/app/api/cron-engine/route.ts](file://src/app/api/cron-engine/route.ts)
- [src/lib/db.ts](file://src/lib/db.ts)
- [src/lib/cron/engine.ts](file://src/lib/cron/engine.ts)
- [src/lib/cron/executor.ts](file://src/lib/cron/executor.ts)
- [src/lib/cron/cron-parser.ts](file://src/lib/cron/cron-parser.ts)
- [src/hooks/use-cron-tasks.ts](file://src/hooks/use-cron-tasks.ts)
- [src/hooks/use-task-executions.ts](file://src/hooks/use-task-executions.ts)
- [src/lib/types.ts](file://src/lib/types.ts)
- [src/components/views/schedule-view.tsx](file://src/components/views/schedule-view.tsx)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件为 Forge 计划任务 API 的详细参考文档，覆盖以下内容：
- RESTful 接口：任务的创建、读取、更新、删除与立即执行
- 执行历史查询接口：支持按任务、工作区、类型与状态过滤
- 任务配置参数：cron 表达式、任务名称、描述、执行参数等
- 执行状态跟踪、失败重试机制与执行日志记录
- 任务调度最佳实践与性能优化建议
- 监控、告警配置与故障排除指南

## 项目结构
计划任务相关的核心文件组织如下：
- API 路由层：负责 HTTP 请求处理与响应
- 数据库层：负责任务与执行历史的持久化
- 调度引擎：负责周期性检查与触发任务
- 执行器：负责具体任务的执行逻辑（代理、技能、自定义提示）
- 前端 Hook 与视图：提供 CRUD 操作与执行历史展示

```mermaid
graph TB
subgraph "前端"
UI["ScheduleView 组件<br/>任务列表/心跳/历史"]
Hooks["useCronTasks / useTaskExecutions<br/>数据钩子"]
end
subgraph "API 层"
RTasks["/api/cron-tasks<br/>GET/POST"]
RTasksId["/api/cron-tasks/[id]<br/>GET/PATCH/DELETE"]
RTasksExec["/api/cron-tasks/[id]/execute<br/>POST"]
RExec["/api/task-executions<br/>GET/POST"]
REngine["/api/cron-engine<br/>GET/POST"]
end
subgraph "业务逻辑"
Engine["CronEngine<br/>定时检查/触发"]
Executor["Executor<br/>执行器"]
Parser["CronParser<br/>匹配表达式"]
end
subgraph "数据存储"
DB["SQLite 数据库<br/>cron_tasks / task_executions / sessions"]
end
UI --> Hooks
Hooks --> RTasks
Hooks --> RTasksId
Hooks --> RTasksExec
Hooks --> RExec
Hooks --> REngine
RTasks --> DB
RTasksId --> DB
RTasksExec --> Executor
RExec --> DB
REngine --> Engine
Engine --> Parser
Engine --> Executor
Engine --> DB
Executor --> DB
```

**图表来源**
- [src/app/api/cron-tasks/route.ts:1-53](file://src/app/api/cron-tasks/route.ts#L1-L53)
- [src/app/api/cron-tasks/[id]/route.ts](file://src/app/api/cron-tasks/[id]/route.ts#L1-L66)
- [src/app/api/cron-tasks/[id]/execute/route.ts](file://src/app/api/cron-tasks/[id]/execute/route.ts#L1-L40)
- [src/app/api/task-executions/route.ts:1-76](file://src/app/api/task-executions/route.ts#L1-L76)
- [src/app/api/cron-engine/route.ts:1-30](file://src/app/api/cron-engine/route.ts#L1-L30)
- [src/lib/cron/engine.ts:1-121](file://src/lib/cron/engine.ts#L1-L121)
- [src/lib/cron/executor.ts:1-306](file://src/lib/cron/executor.ts#L1-L306)
- [src/lib/cron/cron-parser.ts:1-57](file://src/lib/cron/cron-parser.ts#L1-L57)
- [src/lib/db.ts:117-147](file://src/lib/db.ts#L117-L147)

**章节来源**
- [src/app/api/cron-tasks/route.ts:1-53](file://src/app/api/cron-tasks/route.ts#L1-L53)
- [src/app/api/cron-tasks/[id]/route.ts](file://src/app/api/cron-tasks/[id]/route.ts#L1-L66)
- [src/app/api/cron-tasks/[id]/execute/route.ts](file://src/app/api/cron-tasks/[id]/execute/route.ts#L1-L40)
- [src/app/api/task-executions/route.ts:1-76](file://src/app/api/task-executions/route.ts#L1-L76)
- [src/app/api/cron-engine/route.ts:1-30](file://src/app/api/cron-engine/route.ts#L1-L30)
- [src/lib/db.ts:117-147](file://src/lib/db.ts#L117-L147)

## 核心组件
- 任务表（cron_tasks）：存储任务元数据、状态与配置
- 执行历史表（task_executions）：记录每次执行的结果、状态与会话
- 调度引擎（CronEngine）：每分钟扫描启用的任务，匹配 cron 表达式后触发执行
- 执行器（Executor）：根据任务类型（代理、技能、自定义提示）执行并可通知 IM
- 前端 Hook：封装 CRUD 与执行历史查询，提供用户界面交互

**章节来源**
- [src/lib/db.ts:117-147](file://src/lib/db.ts#L117-L147)
- [src/lib/cron/engine.ts:1-121](file://src/lib/cron/engine.ts#L1-L121)
- [src/lib/cron/executor.ts:1-306](file://src/lib/cron/executor.ts#L1-L306)
- [src/hooks/use-cron-tasks.ts:1-116](file://src/hooks/use-cron-tasks.ts#L1-L116)
- [src/hooks/use-task-executions.ts:1-98](file://src/hooks/use-task-executions.ts#L1-L98)

## 架构总览
下图展示了从 API 到数据库与调度引擎的整体流程：

```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "API 路由"
participant Engine as "CronEngine"
participant Exec as "Executor"
participant DB as "数据库"
Client->>API : "POST /api/cron-tasks"
API->>DB : "插入 cron_tasks"
DB-->>API : "返回新任务"
API-->>Client : "201 Created + 任务"
Client->>API : "POST /api/cron-tasks/[id]/execute"
API->>Exec : "executeTask(task)"
Exec->>DB : "写入 task_executions"
Exec->>DB : "更新 cron_tasks.last_run_*"
API-->>Client : "执行结果"
Engine->>DB : "查询启用任务"
Engine->>Engine : "匹配 cron 表达式"
Engine->>Exec : "executeTask(task)"
Exec->>DB : "写入 task_executions"
Exec->>DB : "更新 cron_tasks.last_run_*"
```

**图表来源**
- [src/app/api/cron-tasks/route.ts:23-52](file://src/app/api/cron-tasks/route.ts#L23-L52)
- [src/app/api/cron-tasks/[id]/execute/route.ts](file://src/app/api/cron-tasks/[id]/execute/route.ts#L11-L39)
- [src/lib/cron/engine.ts:44-105](file://src/lib/cron/engine.ts#L44-L105)
- [src/lib/cron/executor.ts:26-47](file://src/lib/cron/executor.ts#L26-L47)
- [src/lib/db.ts:135-144](file://src/lib/db.ts#L135-L144)

## 详细组件分析

### 1) 任务 CRUD 与立即执行 API
- GET /api/cron-tasks
  - 功能：列出所有任务，支持按工作区过滤；同时包含全局心跳任务
  - 查询参数：workspace_id（可选）
  - 返回：任务数组（包含名称、cron 表达式、动作类型、代理/技能名、工作区、启用状态、配置等）

- POST /api/cron-tasks
  - 功能：创建新任务
  - 请求体字段：name、schedule、action、action_type、agent_name、skill_name、workspace_id、enabled、config
  - 默认值：未提供时自动填充默认值；首次创建会尝试启动调度引擎

- GET /api/cron-tasks/[id]
  - 功能：按 ID 获取单个任务
  - 返回：任务对象或 404

- PATCH /api/cron-tasks/[id]
  - 功能：更新任务部分字段
  - 允许字段：name、schedule、action、action_type、agent_name、skill_name、workspace_id、enabled、config、last_run_at、last_run_result
  - 更新时间：自动写入 updated_at
  - 启用时行为：若 enabled=true，尝试启动调度引擎

- DELETE /api/cron-tasks/[id]
  - 功能：删除任务
  - 特殊限制：心跳任务不可删除
  - 返回：删除成功

- POST /api/cron-tasks/[id]/execute
  - 功能：立即执行指定任务
  - 行为：调用执行器，记录执行历史，更新任务最近运行信息
  - 返回：状态与结果摘要（截断），以及会话 ID

**章节来源**
- [src/app/api/cron-tasks/route.ts:6-52](file://src/app/api/cron-tasks/route.ts#L6-L52)
- [src/app/api/cron-tasks/[id]/route.ts](file://src/app/api/cron-tasks/[id]/route.ts#L5-L65)
- [src/app/api/cron-tasks/[id]/execute/route.ts](file://src/app/api/cron-tasks/[id]/execute/route.ts#L11-L39)

### 2) 执行历史查询 API
- GET /api/task-executions
  - 功能：分页查询执行历史
  - 查询参数：
    - task_id：按任务过滤
    - workspace_id：按工作区过滤（含心跳任务）
    - type：heartbeat 或 cron
    - status：ok、alert、error
    - limit：1–500，默认 20
    - offset：默认 0
  - 返回：按执行时间倒序的历史记录数组

- POST /api/task-executions
  - 功能：手动上报一次执行记录
  - 请求体字段：task_id、task_name、result、status、session_id
  - 自动更新：对应任务的 last_run_at 与 last_run_result

**章节来源**
- [src/app/api/task-executions/route.ts:5-75](file://src/app/api/task-executions/route.ts#L5-L75)

### 3) 调度引擎控制 API
- GET /api/cron-engine
  - 功能：查询引擎运行状态
  - 返回：running（布尔）

- POST /api/cron-engine
  - 功能：启动或停止引擎
  - 请求体：action（start 或 stop）
  - 返回：新的运行状态

**章节来源**
- [src/app/api/cron-engine/route.ts:4-29](file://src/app/api/cron-engine/route.ts#L4-L29)

### 4) 数据模型与类型
- 任务表（cron_tasks）
  - 关键列：id、name、schedule、action、action_type、agent_name、skill_name、workspace_id、enabled、is_heartbeat、config、last_run_at、last_run_result、created_at、updated_at
  - 约束：action_type 枚举（run-agent、run-skill、custom-prompt）

- 执行历史表（task_executions）
  - 关键列：id、task_id、task_name、result、status（ok/alert/error）、session_id、executed_at
  - 外键：task_id 引用 cron_tasks(id)（级联删除）

- 类型定义（CronTask、TaskExecution、TaskActionType、TaskExecutionStatus）
  - 定义于类型文件中，用于前端与后端的数据契约

**章节来源**
- [src/lib/db.ts:117-147](file://src/lib/db.ts#L117-L147)
- [src/lib/types.ts:162-221](file://src/lib/types.ts#L162-L221)

### 5) 调度引擎与执行器
- CronEngine
  - 启动策略：进程启动时若存在启用任务则自动启动
  - 执行周期：每分钟 tick 一次
  - 并发控制：同一任务在执行期间跳过重复触发
  - 一次性任务：当 cron 表达式包含特定日期/月份时，执行后自动禁用该任务
  - 结果记录：无论成功或失败均写入执行历史，并更新任务最后运行信息

- Executor
  - 心跳任务：读取工作区中的 HEARTBEAT.md，执行清单并根据结果发送 IM 通知
  - 代理任务：加载指定代理的提示文件，执行用户消息并可通知 IM
  - 技能任务：加载指定技能的提示文件，执行用户消息并可通知 IM
  - 自定义提示：直接执行用户提供的 action 文本
  - 会话管理：每次执行创建独立会话，便于在聊天界面查看

- CronParser
  - 支持格式：分钟 小时 日期 月份 星期
  - 支持语法：*、N、N-M、N,M、*/N、范围/步进

**章节来源**
- [src/lib/cron/engine.ts:16-121](file://src/lib/cron/engine.ts#L16-L121)
- [src/lib/cron/executor.ts:26-306](file://src/lib/cron/executor.ts#L26-L306)
- [src/lib/cron/cron-parser.ts:7-57](file://src/lib/cron/cron-parser.ts#L7-L57)

### 6) 前端集成与最佳实践
- useCronTasks
  - 提供任务列表、心跳任务、创建、更新、删除、立即执行与刷新
  - 自动映射数据库行到前端类型

- useTaskExecutions
  - 分页加载执行历史，支持按类型与状态过滤
  - 内置分页偏移与“加载更多”能力

- ScheduleView
  - 可视化频率选择器（一次性、分钟、小时、日、周、月）
  - 心跳任务配置（检查间隔、通知渠道、HEARTBEAT.md 编辑）
  - 执行历史表格与筛选器

**章节来源**
- [src/hooks/use-cron-tasks.ts:47-116](file://src/hooks/use-cron-tasks.ts#L47-L116)
- [src/hooks/use-task-executions.ts:30-98](file://src/hooks/use-task-executions.ts#L30-L98)
- [src/components/views/schedule-view.tsx:26-70](file://src/components/views/schedule-view.tsx#L26-L70)

## 依赖关系分析

```mermaid
classDiagram
class CronTask {
+string id
+string name
+string schedule
+string action
+TaskActionType actionType
+string agentName
+string skillName
+string workspaceId
+boolean enabled
+boolean isHeartbeat
+Record~string,string~ config
+string lastRunAt
+string lastRunResult
+string createdAt
+string updatedAt
}
class TaskExecution {
+string id
+string taskId
+string taskName
+string result
+TaskExecutionStatus status
+string sessionId
+string executedAt
}
class CronEngine {
+start() void
+stop() void
+isRunning() boolean
-tick() void
-runTask(task) void
}
class Executor {
+executeTask(task) Promise~TaskResult~
}
class CronParser {
+matchesCron(expr, date) boolean
}
CronTask --> TaskExecution : "产生执行历史"
CronEngine --> CronTask : "扫描/触发"
CronEngine --> Executor : "执行"
Executor --> CronTask : "读取配置"
CronEngine --> CronParser : "匹配表达式"
```

**图表来源**
- [src/lib/types.ts:185-211](file://src/lib/types.ts#L185-L211)
- [src/lib/cron/engine.ts:16-121](file://src/lib/cron/engine.ts#L16-L121)
- [src/lib/cron/executor.ts:26-47](file://src/lib/cron/executor.ts#L26-L47)
- [src/lib/cron/cron-parser.ts:7-20](file://src/lib/cron/cron-parser.ts#L7-L20)

**章节来源**
- [src/lib/types.ts:162-221](file://src/lib/types.ts#L162-L221)
- [src/lib/cron/engine.ts:1-121](file://src/lib/cron/engine.ts#L1-L121)
- [src/lib/cron/executor.ts:1-306](file://src/lib/cron/executor.ts#L1-L306)
- [src/lib/cron/cron-parser.ts:1-57](file://src/lib/cron/cron-parser.ts#L1-L57)

## 性能考虑
- 调度频率
  - 引擎每分钟检查一次，建议 cron 表达式粒度控制在分钟级及以上，避免过于频繁的任务导致资源竞争
- 并发与去重
  - 引擎内部使用集合记录正在执行的任务 ID，避免重复触发；执行器创建独立会话，减少跨任务干扰
- 数据库写入
  - 执行历史与任务更新采用批量原子写入，建议控制单次执行输出长度，避免超长 result 影响查询性能
- 分页与过滤
  - 执行历史查询支持 limit/offset 与多条件过滤，建议前端设置合理上限（最大 500），并结合类型与状态筛选
- 一次性任务
  - 引擎检测特定日期/月份的 cron 表达式后自动禁用，避免无效重复执行

[本节为通用性能建议，不直接分析具体文件]

## 故障排除指南
- 无法创建/更新任务
  - 检查请求体字段是否符合要求；PATCH 仅允许部分字段更新
  - 若 enabled 字段变更，确认调度引擎已启动
- 任务未触发
  - 确认任务已启用且 cron 表达式有效；检查调度引擎运行状态
  - 若为一次性任务，确认日期/月份是否已过期
- 执行历史为空
  - 使用 task_id 或 workspace_id 参数过滤；检查 type 与 status 过滤条件
  - 确认 limit/offset 设置是否过大
- 心跳任务无通知
  - 检查心跳任务配置中的通知渠道与绑定；确认 IM 渠道连接状态
- 手动上报执行记录
  - 确保 task_id 存在；status 应为 ok/alert/error；必要时更新任务的 last_run_at

**章节来源**
- [src/app/api/cron-tasks/route.ts:23-52](file://src/app/api/cron-tasks/route.ts#L23-L52)
- [src/app/api/cron-tasks/[id]/route.ts](file://src/app/api/cron-tasks/[id]/route.ts#L13-L54)
- [src/app/api/cron-tasks/[id]/execute/route.ts](file://src/app/api/cron-tasks/[id]/execute/route.ts#L11-L39)
- [src/app/api/task-executions/route.ts:5-75](file://src/app/api/task-executions/route.ts#L5-L75)
- [src/lib/cron/engine.ts:44-105](file://src/lib/cron/engine.ts#L44-L105)

## 结论
Forge 的计划任务系统通过清晰的 API 设计、可靠的调度引擎与完善的执行历史记录，提供了从任务配置到执行监控的完整闭环。配合前端可视化界面与 IM 通知，能够满足日常巡检、自动化执行与问题告警等场景需求。建议在生产环境中合理规划 cron 表达式、控制执行输出长度，并利用执行历史与筛选功能进行持续监控。

[本节为总结性内容，不直接分析具体文件]

## 附录

### A. 任务配置参数说明
- 名称与描述
  - name：任务显示名称
  - action：任务描述或执行说明
- 调度与执行
  - schedule：cron 表达式（分钟 小时 日期 月份 星期）
  - action_type：执行类型（run-agent、run-skill、custom-prompt）
  - agent_name/skill_name：分别对应代理/技能名称
  - workspace_id：工作区标识，心跳任务可回退到最近打开的工作区
  - enabled：是否启用
  - is_heartbeat：是否为心跳任务（系统内置）
  - config：JSON 字符串，常用键包括 check_interval、notify_channel、checklist_path
- 状态与时间
  - last_run_at/last_run_result：最近一次执行时间与结果摘要
  - created_at/updated_at：创建与更新时间

**章节来源**
- [src/lib/db.ts:117-133](file://src/lib/db.ts#L117-L133)
- [src/lib/types.ts:185-201](file://src/lib/types.ts#L185-L201)
- [src/lib/cron/executor.ts:14-18](file://src/lib/cron/executor.ts#L14-L18)

### B. 执行状态与日志
- 状态枚举：ok、alert、error
- 日志记录：
  - 执行历史表记录每次执行的 task_id、task_name、result、status、session_id、executed_at
  - 任务表记录 last_run_at 与 last_run_result
- 会话关联：每次执行创建独立会话，可在聊天界面查看执行详情

**章节来源**
- [src/lib/db.ts:135-144](file://src/lib/db.ts#L135-L144)
- [src/lib/types.ts:203-211](file://src/lib/types.ts#L203-L211)
- [src/lib/cron/executor.ts:202-253](file://src/lib/cron/executor.ts#L202-L253)

### C. 最佳实践与建议
- cron 表达式
  - 避免过于密集的分钟级任务；尽量错峰执行
  - 一次性任务使用特定日期/月份表达式，执行后自动禁用
- 通知与告警
  - 心跳任务建议开启通知渠道；确保 IM 渠道已正确绑定
- 监控与维护
  - 定期检查执行历史与任务状态；对异常状态及时处理
  - 控制执行输出长度，避免影响查询性能

[本节为通用建议，不直接分析具体文件]