# 任务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/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/lib/db.ts](file://src/lib/db.ts)
- [src/lib/types.ts](file://src/lib/types.ts)
- [src/hooks/use-cron-tasks.ts](file://src/hooks/use-cron-tasks.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. [附录](#附录)

## 简介
本文件为“计划任务API接口”的权威技术文档，覆盖任务管理的HTTP接口定义、请求与响应格式、CRUD与批量操作、状态管理、配置校验、权限与安全机制、版本与错误处理规范，并提供客户端集成示例与最佳实践。该系统通过定时引擎驱动任务执行，支持心跳检查、代理执行、技能执行与自定义提示等动作类型。

## 项目结构
- API层：Next.js 路由处理器，位于 src/app/api 下，分别提供任务列表、单个任务、立即执行、执行历史与引擎启停等接口。
- 执行层：cron 引擎与执行器，负责解析Cron表达式、调度执行、记录执行结果与会话。
- 数据层：SQLite 数据库，包含任务表、执行记录表、会话与消息表等。
- 类型与工具：统一的数据模型、Cron解析器、数据库初始化与迁移逻辑。

```mermaid
graph TB
subgraph "API 层"
RT["/api/cron-tasks<br/>GET/POST"]
RID["/api/cron-tasks/[id]<br/>GET/PATCH/DELETE"]
REXEC["/api/cron-tasks/[id]/execute<br/>POST"]
REXECS["/api/task-executions<br/>GET/POST"]
RENG["/api/cron-engine<br/>GET/POST"]
end
subgraph "执行层"
ENG["CronEngine<br/>定时调度"]
EXE["Executor<br/>任务执行"]
PARSE["CronParser<br/>表达式匹配"]
end
subgraph "数据层"
DB["SQLite 数据库<br/>cron_tasks / task_executions / sessions / messages"]
end
RT --> DB
RID --> DB
REXEC --> EXE
REXECS --> DB
RENG --> ENG
ENG --> PARSE
ENG --> EXE
EXE --> 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/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)

## 核心组件
- 任务管理API：提供任务的创建、查询、更新、删除与立即执行。
- 执行历史API：提供按任务或工作区过滤的执行记录查询与手动写入。
- 定时引擎API：提供引擎启停与运行状态查询。
- 执行引擎与执行器：解析Cron表达式、调度执行、生成会话与消息、记录执行结果。
- 数据库与类型：统一的任务、执行记录、会话与消息数据模型及初始化/迁移逻辑。

章节来源
- [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)
- [src/app/api/task-executions/route.ts:5-75](file://src/app/api/task-executions/route.ts#L5-L75)
- [src/app/api/cron-engine/route.ts:4-29](file://src/app/api/cron-engine/route.ts#L4-L29)
- [src/lib/cron/engine.ts:16-106](file://src/lib/cron/engine.ts#L16-L106)
- [src/lib/cron/executor.ts:26-47](file://src/lib/cron/executor.ts#L26-L47)
- [src/lib/db.ts:117-147](file://src/lib/db.ts#L117-L147)
- [src/lib/types.ts:162-211](file://src/lib/types.ts#L162-L211)

## 架构总览
系统采用“API层-执行层-数据层”分层设计。API层接收HTTP请求并调用执行层；执行层通过Cron引擎与执行器完成任务调度与执行；数据层以SQLite存储任务、执行记录、会话与消息。

```mermaid
sequenceDiagram
participant C as "客户端"
participant API as "API 路由"
participant ENG as "CronEngine"
participant EXE as "Executor"
participant DB as "SQLite"
C->>API : "POST /api/cron-tasks"
API->>DB : "插入任务记录"
API-->>C : "201 + 新建任务"
C->>API : "POST /api/cron-engine"
API->>ENG : "启动引擎"
API-->>C : "{running : true}"
loop 每60秒
ENG->>DB : "查询启用的任务"
ENG->>ENG : "匹配Cron表达式"
ENG->>EXE : "执行任务"
EXE->>DB : "写入执行记录/会话"
EXE-->>ENG : "返回状态与结果"
end
```

图表来源
- [src/app/api/cron-tasks/route.ts:23-52](file://src/app/api/cron-tasks/route.ts#L23-L52)
- [src/app/api/cron-engine/route.ts:11-29](file://src/app/api/cron-engine/route.ts#L11-L29)
- [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-147](file://src/lib/db.ts#L135-L147)

## 详细组件分析

### 任务管理API
- 列表查询
  - 方法与路径：GET /api/cron-tasks
  - 查询参数：workspace_id（可选）
  - 返回：任务数组（包含心跳任务与按时间排序）
- 创建任务
  - 方法与路径：POST /api/cron-tasks
  - 请求体字段：name、schedule、action、action_type、agent_name、skill_name、workspace_id、enabled、config
  - 默认值与处理：未提供字段使用默认值；config为对象时序列化为字符串；enabled默认开启；自动启动引擎（若尚未运行）
  - 响应：201 + 新建任务
- 获取单个任务
  - 方法与路径：GET /api/cron-tasks/[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被置为真时自动启动引擎
  - 响应：更新后的任务
- 删除任务
  - 方法与路径：DELETE /api/cron-tasks/[id]
  - 限制：心跳任务不可删除
  - 响应：{ ok: true }

请求/响应示例（字段说明）
- 请求体字段
  - name：任务名称
  - schedule：Cron 表达式（分钟 小时 日 月 星期）
  - action：执行动作描述或内容
  - action_type：动作类型（run-agent、run-skill、custom-prompt）
  - agent_name：代理名称（run-agent时必填）
  - skill_name：技能名称（run-skill时必填）
  - workspace_id：工作区ID（建议提供）
  - enabled：是否启用（布尔）
  - config：JSON字符串或对象（通知渠道、检查清单路径等）
- 响应体字段
  - 包含任务表所有字段（如created_at、updated_at、last_run_at、last_run_result等）

章节来源
- [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/lib/types.ts:162-201](file://src/lib/types.ts#L162-L201)

### 立即执行任务API
- 方法与路径：POST /api/cron-tasks/[id]/execute
- 功能：触发指定任务的即时执行（例如心跳的“立即检查”）
- 流程：查询任务 -> 执行任务 -> 记录执行与任务最后运行信息 -> 返回状态与结果摘要
- 错误处理：任务不存在返回404；执行异常返回500

```mermaid
sequenceDiagram
participant C as "客户端"
participant API as "执行路由"
participant DB as "SQLite"
participant EXE as "Executor"
C->>API : "POST /api/cron-tasks/{id}/execute"
API->>DB : "查询任务"
DB-->>API : "任务记录"
API->>EXE : "executeTask(task)"
EXE->>DB : "写入执行记录/会话"
EXE-->>API : "状态与结果"
API-->>C : "{status,result,sessionId}"
```

图表来源
- [src/app/api/cron-tasks/[id]/execute/route.ts](file://src/app/api/cron-tasks/[id]/execute/route.ts#L11-L39)
- [src/lib/cron/executor.ts:26-47](file://src/lib/cron/executor.ts#L26-L47)
- [src/lib/db.ts:135-147](file://src/lib/db.ts#L135-L147)

章节来源
- [src/app/api/cron-tasks/[id]/execute/route.ts](file://src/app/api/cron-tasks/[id]/execute/route.ts#L11-L39)

### 执行历史API
- 列表查询
  - 方法与路径：GET /api/task-executions
  - 查询参数：task_id（精确查询）、workspace_id（工作区过滤，支持心跳任务）、limit（1~500，默认20）、offset（默认0）、type（heartbeat/cron）、status（ok/alert/error）
  - 返回：按执行时间倒序的执行记录数组
- 手动写入
  - 方法与路径：POST /api/task-executions
  - 请求体：task_id（必填）、task_name、result、status、session_id
  - 响应：201 + 新建记录

```mermaid
flowchart TD
Start(["请求进入"]) --> Parse["解析查询参数"]
Parse --> Cond{"是否有 task_id ?"}
Cond --> |是| ByTask["按任务ID查询"]
Cond --> |否| Build["构建多条件WHERE"]
Build --> Join["关联任务表过滤"]
ByTask --> Limit["分页限制"]
Join --> Limit
Limit --> Return["返回执行记录"]
```

图表来源
- [src/app/api/task-executions/route.ts:5-49](file://src/app/api/task-executions/route.ts#L5-L49)

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

### 定时引擎API
- 运行状态查询
  - 方法与路径：GET /api/cron-engine
  - 响应：{ running: boolean }
- 启停控制
  - 方法与路径：POST /api/cron-engine
  - 请求体：{ action: "start"|"stop" }
  - 响应：{ running: boolean }

```mermaid
sequenceDiagram
participant C as "客户端"
participant API as "引擎路由"
participant ENG as "CronEngine"
C->>API : "GET /api/cron-engine"
API->>ENG : "isRunning()"
API-->>C : "{running}"
C->>API : "POST /api/cron-engine {action : 'start'|'stop'}"
API->>ENG : "start()/stop()"
API-->>C : "{running : true|false}"
```

图表来源
- [src/app/api/cron-engine/route.ts:4-29](file://src/app/api/cron-engine/route.ts#L4-L29)
- [src/lib/cron/engine.ts:40-42](file://src/lib/cron/engine.ts#L40-L42)

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

### 执行引擎与执行器
- Cron引擎
  - 单例：全局缓存，按需自动启动（存在启用任务时）
  - 调度周期：每60秒扫描一次
  - 并发控制：正在执行的任务ID集合去重
  - 任务类型：心跳任务与普通任务；普通任务执行后可能自动禁用（一次性任务）
- 执行器
  - 支持动作类型：心跳、运行代理、运行技能、自定义提示
  - 工作区解析：优先使用任务配置的工作区ID，心跳任务回退到最近打开的工作区
  - 会话与消息：为每次执行创建会话与消息记录，便于在聊天界面查看
  - 通知：可选通过IM通道发送通知

```mermaid
classDiagram
class CronEngine {
-timer
-running
-executingTasks
+start()
+stop()
+isRunning() bool
-tick()
-runTask(task)
}
class Executor {
+executeTask(task) TaskResult
-executeHeartbeat(task) TaskResult
-executeRunAgent(task) TaskResult
-executeRunSkill(task) TaskResult
-executeCustomPrompt(task) TaskResult
-runAgentTask(prompt,user,ws,title) Promise
-notifyIm(channel,msg) Promise
}
CronEngine --> Executor : "调度执行"
```

图表来源
- [src/lib/cron/engine.ts:16-106](file://src/lib/cron/engine.ts#L16-L106)
- [src/lib/cron/executor.ts:26-306](file://src/lib/cron/executor.ts#L26-L306)

章节来源
- [src/lib/cron/engine.ts:16-106](file://src/lib/cron/engine.ts#L16-L106)
- [src/lib/cron/executor.ts:26-306](file://src/lib/cron/executor.ts#L26-L306)
- [src/lib/cron/cron-parser.ts:7-20](file://src/lib/cron/cron-parser.ts#L7-L20)

### 数据模型与数据库
- 任务表（cron_tasks）：包含任务ID、名称、Cron表达式、动作、动作类型、代理/技能名称、工作区ID、启用状态、心跳标记、配置、最后运行时间与结果、创建/更新时间。
- 执行记录表（task_executions）：包含执行ID、任务ID、任务名、结果、状态、会话ID、执行时间；外键关联任务表。
- 会话与消息表：用于持久化每次执行产生的会话与消息，供UI展示。

```mermaid
erDiagram
CRON_TASKS {
text id PK
text name
text schedule
text action
text action_type
text agent_name
text skill_name
text workspace_id
integer enabled
integer is_heartbeat
text config
text last_run_at
text last_run_result
text created_at
text updated_at
}
TASK_EXECUTIONS {
text id PK
text task_id FK
text task_name
text result
text status
text session_id
text executed_at
}
SESSIONS {
text id PK
text title
text workspace
text model
text status
text created_at
text updated_at
}
MESSAGES {
text id PK
text session_id FK
text role
text content
text created_at
}
CRON_TASKS ||--o{ TASK_EXECUTIONS : "产生"
SESSIONS ||--o{ MESSAGES : "包含"
```

图表来源
- [src/lib/db.ts:117-147](file://src/lib/db.ts#L117-L147)

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

## 依赖关系分析
- API路由依赖数据库访问与执行引擎/执行器。
- 执行引擎依赖Cron解析器与执行器。
- 执行器依赖工作区文件系统读取、IM桥接与会话消息持久化。
- 前端通过React Hook与API交互，实现任务列表、编辑、执行与历史查看。

```mermaid
graph LR
A["use-cron-tasks.ts"] --> B["/api/cron-tasks/*"]
A --> C["/api/cron-tasks/[id]/execute"]
D["schedule-view.tsx"] --> A
B --> E["db.ts"]
C --> F["executor.ts"]
F --> E
G["cron-engine.ts"] --> F
G --> H["cron-parser.ts"]
```

图表来源
- [src/hooks/use-cron-tasks.ts:47-115](file://src/hooks/use-cron-tasks.ts#L47-L115)
- [src/components/views/schedule-view.tsx:160-187](file://src/components/views/schedule-view.tsx#L160-L187)
- [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]/execute/route.ts](file://src/app/api/cron-tasks/[id]/execute/route.ts#L1-L40)
- [src/lib/db.ts:1-499](file://src/lib/db.ts#L1-L499)
- [src/lib/cron/executor.ts:1-306](file://src/lib/cron/executor.ts#L1-L306)
- [src/lib/cron/engine.ts:1-121](file://src/lib/cron/engine.ts#L1-L121)
- [src/lib/cron/cron-parser.ts:1-57](file://src/lib/cron/cron-parser.ts#L1-L57)

章节来源
- [src/hooks/use-cron-tasks.ts:47-115](file://src/hooks/use-cron-tasks.ts#L47-L115)
- [src/components/views/schedule-view.tsx:160-187](file://src/components/views/schedule-view.tsx#L160-L187)
- [src/lib/cron/engine.ts:108-120](file://src/lib/cron/engine.ts#L108-L120)

## 性能考量
- 调度频率：引擎每60秒扫描一次，避免频繁IO。
- 并发控制：正在执行的任务ID集合去重，防止重复执行。
- 分页查询：执行历史支持limit/offset，建议前端分页加载。
- 数据库优化：WAL模式、外键约束、索引（执行记录按任务与时间排序）。
- 一次性任务：引擎在执行后自动禁用，减少后续无效调度。

章节来源
- [src/lib/cron/engine.ts:21-62](file://src/lib/cron/engine.ts#L21-L62)
- [src/app/api/task-executions/route.ts:10-12](file://src/app/api/task-executions/route.ts#L10-L12)
- [src/lib/db.ts:22-23](file://src/lib/db.ts#L22-L23)
- [src/lib/db.ts:146-146](file://src/lib/db.ts#L146-L146)

## 故障排查指南
- 常见错误码
  - 400：请求体无效、缺少必要字段、不支持的动作参数
  - 404：任务不存在
  - 500：执行异常
- 排查步骤
  - 确认Cron表达式格式正确（分钟 小时 日 月 星期），参考解析器支持的语法。
  - 检查任务配置中的工作区ID与动作类型是否匹配（代理/技能名称是否存在）。
  - 查看执行历史接口返回的status与result，定位失败原因。
  - 若心跳任务无法删除，确认是否为内置心跳任务。
- 建议
  - 在开发阶段使用“立即执行”接口快速验证任务配置。
  - 对于一次性任务，确认Cron表达式的日/月字段是否为具体数值。

章节来源
- [src/app/api/cron-tasks/[id]/execute/route.ts](file://src/app/api/cron-tasks/[id]/execute/route.ts#L35-L38)
- [src/app/api/cron-tasks/[id]/route.ts](file://src/app/api/cron-tasks/[id]/route.ts#L60-L61)
- [src/lib/cron/cron-parser.ts:7-20](file://src/lib/cron/cron-parser.ts#L7-L20)
- [src/app/api/task-executions/route.ts:51-75](file://src/app/api/task-executions/route.ts#L51-L75)

## 结论
本API体系提供了完整的计划任务生命周期管理能力，涵盖任务CRUD、批量查询、状态控制、立即执行与历史追踪，并通过定时引擎与执行器实现可靠的任务调度与执行。配合前端视图组件，用户可在可视化界面中便捷地配置与监控任务。

## 附录

### API定义与规范
- 版本管理
  - 当前API为Next.js路由风格，未显式版本号；建议在网关或反向代理层进行版本化路由（如 /v1/cron-tasks）。
- 错误处理与响应码
  - 400：请求体无效、缺少必要字段、动作参数非法
  - 404：资源不存在（任务）
  - 500：内部执行错误
- 权限与安全
  - 当前路由未实现鉴权/授权逻辑；建议在网关或中间件层增加认证与基于工作区的访问控制。
- 数据安全
  - 配置字段为JSON字符串存储，注意敏感信息不应明文存放；建议在业务层进行脱敏与加密。

章节来源
- [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-L53)
- [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:51-75](file://src/app/api/task-executions/route.ts#L51-L75)
- [src/app/api/cron-engine/route.ts:11-29](file://src/app/api/cron-engine/route.ts#L11-L29)

### 使用示例与客户端集成
- 前端集成要点
  - 使用React Hook封装任务列表、创建、更新、删除与执行。
  - 通过API路由获取任务与执行历史，结合本地状态管理。
  - 心跳任务的“立即检查”按钮直接调用立即执行接口。
- 示例流程（前端）
  - 获取任务：GET /api/cron-tasks?workspace_id=xxx
  - 创建任务：POST /api/cron-tasks（携带name、schedule、action_type等）
  - 更新任务：PATCH /api/cron-tasks/{id}（仅传入需要变更的字段）
  - 删除任务：DELETE /api/cron-tasks/{id}
  - 立即执行：POST /api/cron-tasks/{id}/execute
  - 查看历史：GET /api/task-executions?task_id=xxx&limit=20

章节来源
- [src/hooks/use-cron-tasks.ts:47-115](file://src/hooks/use-cron-tasks.ts#L47-L115)
- [src/components/views/schedule-view.tsx:170-195](file://src/components/views/schedule-view.tsx#L170-L195)

### 最佳实践
- Cron表达式
  - 使用可视化界面生成表达式，避免手写错误。
  - 一次性任务使用“日/月”为具体数值的表达式，便于引擎自动禁用。
- 配置管理
  - 将通知渠道、检查清单路径等配置放入config字段，便于维护。
- 监控与告警
  - 关注执行历史的状态（ok/alert/error），及时处理异常。
- 性能优化
  - 控制任务数量与执行频率，避免并发冲突。
  - 对高频查询使用分页与过滤参数。

章节来源
- [src/components/views/schedule-view.tsx:26-49](file://src/components/views/schedule-view.tsx#L26-L49)
- [src/lib/cron/engine.ts:84-89](file://src/lib/cron/engine.ts#L84-L89)
- [src/app/api/task-executions/route.ts:10-12](file://src/app/api/task-executions/route.ts#L10-L12)