定时任务调度智体 API 文档

概述

定时任务调度智体是一个基于自然语言指令的任务调度系统，支持通过AI解析自然语言指令创建定时任务，并自动执行任务。系统提供完整的任务管理功能，包括任务创建、列表查询、取消、状态查询以及定时检查器管理。

基础信息

基础URL

/rtagent/task_scheduler/

请求方式

所有API均支持 GET 和 POST 方法

通用请求头

Content-Type: application/x-www-form-urlencoded

通用响应格式

{
    "ret": true/false,
    "msg": "操作结果描述",
    "data": {} // 具体数据，根据接口不同而变化
}

通用参数

参数名	类型	必填	说明
user_id	string	是	用户ID，用于标识用户身份
s_id	string	否	会话ID，用于关联会话上下文

API端点列表

任务管理API

调度定时任务
列出所有任务
取消任务
获取任务状态

定时检查器管理API

配置定时检查器
启动定时检查器
停止定时检查器
获取检查器状态

任务管理API

调度定时任务

端点: /rtagent/task_scheduler/schedule

功能: 通过自然语言指令创建定时任务

请求参数:

参数名	类型	必填	说明	示例
user_id	string	是	用户ID	"user123"
s_id	string	否	会话ID	"session_abc"
instruction	string	是	自然语言任务指令	"每天上午10点提醒我开会"

自然语言指令示例:

"每天上午10点提醒我开会"
"每周一上午9点发送周报"
"每月1号凌晨2点备份数据库"
"每小时的第30分钟检查系统状态"
"明天下午3点提醒我打电话给客户"
"从现在开始，每隔2小时检查一次邮件，到明天晚上8点结束"
"每周一、三、五上午10点发送日报，执行10次后停止"

响应成功示例:

{
    "ret": true,
    "msg": "定时任务调度成功",
    "data": {
        "task_id": "plantask_1691234567890_abc123def",
        "schedule_type": "daily",
        "cron_expression": "0 0 10 * * *",
        "next_run": "根据调度规则计算"
    }
}

响应失败示例:

{
    "ret": false,
    "msg": "任务指令不能为空"
}

列出所有任务

端点: /rtagent/task_scheduler/list

功能: 获取用户的所有定时任务列表

请求参数:

参数名	类型	必填	说明	示例
user_id	string	否	用户ID（为空则返回所有用户的任务）	"user123"

响应成功示例:

{
    "ret": true,
    "data": {
        "tasks": [
            {
                "task_id": "plantask_1691234567890_abc123def",
                "task_description": "每天上午10点提醒我开会",
                "schedule_type": "daily",
                "cron_expression": "0 0 10 * * *",
                "created_at": "2023-08-05T10:00:00.000Z",
                "active": true
            },
            {
                "task_id": "plantask_1691234567891_xyz789ghi",
                "task_description": "每周一上午9点发送周报",
                "schedule_type": "weekly",
                "cron_expression": "0 0 9 * * 1",
                "created_at": "2023-08-04T15:30:00.000Z",
                "active": false
            }
        ],
        "total": 2
    }
}

取消任务

端点: /rtagent/task_scheduler/cancel

功能: 取消指定的定时任务

请求参数:

参数名	类型	必填	说明	示例
user_id	string	是	用户ID	"user123"
task_id	string	是	任务ID	"plantask_1691234567890_abc123def"

响应成功示例:

{
    "ret": true,
    "msg": "任务已取消"
}

响应失败示例:

{
    "ret": false,
    "msg": "任务不存在"
}

获取任务状态

端点: /rtagent/task_scheduler/status

功能: 获取指定任务的详细状态信息

请求参数:

参数名	类型	必填	说明	示例
task_id	string	是	任务ID	"plantask_1691234567890_abc123def"

响应成功示例:

{
    "ret": true,
    "data": {
        "task_id": "plantask_1691234567890_abc123def",
        "task_description": "每天上午10点提醒我开会",
        "schedule_type": "daily",
        "cron_expression": "0 0 10 * * *",
        "active": true,
        "created_at": "2023-08-05T10:00:00.000Z",
        "last_executed": "2023-08-06T10:00:00.000Z",
        "next_run": "根据调度规则计算"
    }
}

定时检查器管理API

配置定时检查器

端点: /rtagent/task_scheduler/checker/configure

功能: 配置定时任务检查器的参数

请求参数:

参数名	类型	必填	说明	默认值	取值范围
interval	integer	否	检查间隔（毫秒）	60000	30000-300000
enabled	boolean	否	是否启用检查器	true	true/false
immediate_start	boolean	否	是否立即开始检查	true	true/false

响应成功示例:

{
    "ret": true,
    "msg": "定时检查配置已更新",
    "data": {
        "enabled": true,
        "interval": 60000,
        "minInterval": 30000,
        "maxInterval": 300000,
        "immediateStart": true,
        "lastCheckTime": "2023-08-06T10:00:00.000Z",
        "checkCount": 15
    }
}

启动定时检查器

端点: /rtagent/task_scheduler/checker/start

功能: 启动定时任务检查器

请求参数: 无

响应成功示例:

{
    "ret": true,
    "msg": "定时检查器已启动",
    "data": {
        "enabled": true,
        "interval": 60000,
        "intervalFormatted": "60秒",
        "minInterval": 30000,
        "maxInterval": 300000,
        "immediateStart": true,
        "lastCheckTime": "2023-08-06T10:00:00.000Z",
        "checkCount": 15,
        "isRunning": true,
        "nextCheckIn": 60000
    }
}

停止定时检查器

端点: /rtagent/task_scheduler/checker/stop

功能: 停止定时任务检查器

请求参数: 无

响应成功示例:

{
    "ret": true,
    "msg": "定时检查器已停止",
    "data": {
        "enabled": true,
        "interval": 60000,
        "intervalFormatted": "60秒",
        "minInterval": 30000,
        "maxInterval": 300000,
        "immediateStart": true,
        "lastCheckTime": "2023-08-06T10:00:00.000Z",
        "checkCount": 15,
        "isRunning": false,
        "nextCheckIn": null
    }
}

获取检查器状态

端点: /rtagent/task_scheduler/checker/status

功能: 获取定时检查器的当前状态

请求参数: 无

响应成功示例:

{
    "ret": true,
    "data": {
        "enabled": true,
        "interval": 60000,
        "intervalFormatted": "60秒",
        "minInterval": 30000,
        "maxInterval": 300000,
        "immediateStart": true,
        "lastCheckTime": "2023-08-06T10:00:00.000Z",
        "checkCount": 15,
        "isRunning": true,
        "nextCheckIn": 45000
    }
}

数据结构说明

任务数据结构

{
    "task_id": "plantask_1691234567890_abc123def",
    "user_id": "user123",
    "s_id": "session_abc",
    "task_description": "任务描述",
    "schedule_type": "daily",
    "schedule_value": "10:30",
    "cron_expression": "0 30 10 * * *",
    "end_time": 1691234567890,
    "max_executions": 10,
    "execution_count": 3,
    "created_at": "2023-08-05T10:00:00.000Z",
    "active": true,
    "status": "scheduled",
    "last_executed": "2023-08-06T10:30:00.000Z",
    "last_result": {},
    "failure_count": 0,
    "ai_analysis": {
        "reason": "cron表达式匹配当前时间",
        "should_complete_after_execution": false,
        "analyzed_at": "2023-08-06T10:29:55.000Z",
        "analysis_summary": "基于cron表达式的自动匹配"
    }
}

字段说明:

字段名	类型	说明
task_id	string	任务唯一标识符
user_id	string	创建任务的用户ID
s_id	string	会话ID
task_description	string	任务描述（不含定时信息）
schedule_type	string	调度类型：hourly/daily/weekly/monthly/cron/once
schedule_value	string	调度值（如："10:30"）
cron_expression	string	cron表达式（如："0 30 10 * * *"）
end_time	integer	任务结束时间戳（毫秒）
max_executions	integer	最大执行次数
execution_count	integer	已执行次数
created_at	string	创建时间（ISO格式）
active	boolean	是否活跃
status	string	任务状态：scheduled/executed/completed/cancelled/failed/expired
last_executed	string	上次执行时间
last_result	object	上次执行结果
failure_count	integer	失败次数
ai_analysis	object	AI分析结果
job	object	调度任务对象（内部使用）

定时检查器配置

{
    "enabled": true,
    "interval": 60000,
    "minInterval": 30000,
    "maxInterval": 300000,
    "immediateStart": true,
    "lastCheckTime": "2023-08-06T10:00:00.000Z",
    "checkCount": 15,
    "isRunning": true,
    "nextCheckIn": 45000
}

字段说明:

字段名	类型	说明
enabled	boolean	是否启用定时检查
interval	integer	检查间隔（毫秒）
minInterval	integer	最小检查间隔（毫秒）
maxInterval	integer	最大检查间隔（毫秒）
immediateStart	boolean	是否立即开始检查
lastCheckTime	string	上次检查时间
checkCount	integer	检查次数统计
isRunning	boolean	检查器是否正在运行
nextCheckIn	integer	距离下次检查的毫秒数

自然语言指令格式

支持的调度类型

一次性任务
- "明天下午3点提醒我开会"
- "2023年12月25日早上8点发送圣诞祝福"
- "1小时后提醒我休息"
每日任务
- "每天上午9点打卡"
- "每天晚上10点备份数据"
- "每日凌晨2点清理缓存"
每周任务
- "每周一上午10点开周会"
- "每周五下午5点发送周报"
- "每周三、周六晚上8点健身提醒"
每月任务
- "每月1号凌晨0点生成月报"
- "每月15号上午9点发工资提醒"
- "每月最后一天下午6点结算"
每小时任务
- "每小时的第30分钟检查系统"
- "每小时的0分0秒记录日志"
- "每小时执行一次数据同步"

时间限定词

系统支持以下时间限定词：

结束时间限定
- "到12月31日结束"
- "截止到今天晚上8点"
- "执行到明天早上"
执行次数限定
- "只执行3次"
- "最多执行10次"
- "执行5次后停止"
组合限定
- "每天上午9点提醒，执行7天后停止"
- "每小时检查一次，到今晚12点结束"
- "每周一提醒，共提醒4次"

指令解析示例

自然语言指令	解析结果
"每天上午10点提醒我开会"	schedule_type: daily, schedule_value: 10:00
"每周一上午9点发送周报，执行4周"	schedule_type: weekly, max_executions: 4
"每小时的第15分钟检查邮件，到今晚8点结束"	schedule_type: hourly, end_time: 今晚8点
"明天下午3点打电话给客户"	schedule_type: once, max_executions: 1
"每月1号凌晨2点备份，执行12次"	schedule_type: monthly, max_executions: 12

错误码说明

通用错误码

错误码	说明	可能原因
400	请求参数错误	缺少必要参数或参数格式错误
401	权限不足	用户无权操作该任务
404	资源不存在	任务ID不存在
500	服务器内部错误	系统内部异常

特定错误信息

任务调度相关
- "任务指令不能为空"：instruction参数为空
- "无法解析定时任务指令"：AI无法解析自然语言指令
- "保存任务计划失败"：文件系统写入失败
- "任务不存在"：指定的task_id不存在
- "无权取消此任务"：用户ID与任务创建者不匹配
定时检查器相关
- "配置定时检查器失败"：配置参数验证失败
- "启动定时检查器失败"：检查器启动过程中出错
- "停止定时检查器失败"：检查器停止过程中出错
系统状态相关
- "API应用未初始化"：系统未正确初始化
- "API端点不存在"：请求的API路径不存在

使用注意事项

任务限制
- 所有任务默认有30天的最大执行期限（防止无限循环）
- 一次性任务必须设置结束时间或最大执行次数
- 任务失败超过3次会自动停用
性能考虑
- 定时检查器默认每分钟检查一次
- 可配置检查间隔（30秒-5分钟）
- 建议根据任务数量调整检查频率
存储说明
- 任务数据存储在 task_scheduler_agent/plan/ 目录
- 已完成/取消的任务移动到 task_scheduler_agent/timeout/ 目录
- 所有数据以JSON格式存储
安全性
- 用户只能操作自己创建的任务
- 所有API调用需要user_id参数
- 建议在生产环境中添加额外的认证机制

🧩 定时任务

🗂️ 技能一览

定时任务

定时任务调度智体 API 文档

概述

目录

基础信息

基础URL

请求方式

通用请求头

通用响应格式

通用参数

API端点列表

任务管理API

定时检查器管理API

任务管理API

调度定时任务

列出所有任务

取消任务

获取任务状态

定时检查器管理API

配置定时检查器

启动定时检查器

停止定时检查器

获取检查器状态

数据结构说明

任务数据结构

定时检查器配置

自然语言指令格式

支持的调度类型

时间限定词

指令解析示例

错误码说明

通用错误码

特定错误信息

使用注意事项