这里是 TaskScheduler 的服务首页。访问根域名先看系统定位、接入方式、参数结构和 API 文档； 正式对接时，统一使用 这一组 HTTP 接口创建、更新、启停和删除定时任务。 任务到点后，系统会按照你提供的 notifyHTTPParam 回调业务服务，再由业务服务完成 AI 执行、 知识库检索、通知下发或结果回写。
TaskScheduler 不是业务工作流编排平台，也不是 AI 执行引擎。 它更适合做你系统里的“定时任务基础设施层”：统一接收任务定义、维护未来执行计划、定时回调业务服务，并记录调度过程中的关键结果。
通过 HTTP 统一创建、修改、启用、停用和删除定时任务，不同业务系统只需要维护自己的 app 名称与回调协议。
把单次时间戳或 cron 表达式展开为未来执行计划，避免业务侧自己处理多种调度语法和迁移逻辑。
到点后按照 notifyHTTPParam 发起回调，真正的 AI 生成、知识检索、机器人通知都由你的业务服务完成。
适合和 AI 助手、自动化工作台、通知系统联动，把执行状态、错误原因和响应内容再次回写到业务侧。
下面这条链路就是系统的标准用法：业务系统负责创建与承接回调，TaskScheduler 负责稳定触发与调度基础能力。
业务系统调用 /create_timer，提交 app、调度时间和 notifyHTTPParam。
调度器解析 executeAt 或 cron，生成未来执行计划，并可通过 enable/disable 接口控制是否生效。
任务到期后，系统会用你提供的方法、请求头和请求体向业务服务发起 HTTP 回调，真正执行业务动作。
业务系统可结合 reportUrl 回写执行结果，把状态、错误原因、请求体和响应体收敛回自己的业务链路。
根域名用于人工查看说明页，正式 API 使用统一前缀；而真正的业务执行 URL 由调用方在创建任务时自行提供。
如果你是第一次接入，这一节最关键。核心要理解三个对象：任务本身、业务回调参数，以及业务侧回写结果时的约定字段。
| app | 业务系统标识，用来隔离不同调用方的任务空间。 |
|---|---|
| name | 任务名称，建议写成业务可读文本，方便排查和审计。 |
| executeAt | 单次任务时间戳；传这个时，服务端会自动标准化为一次性 cron。 |
| cron | 推荐的正式调度字段，支持 5 段、6 段和 7 段格式。 |
| timerId | 更新、启用、停用、删除时使用的主键 ID。 |
| method | 当前主要按 POST 使用，便于传 JSON 负载。 |
|---|---|
| url | 到点后真正要被调用的业务接口地址。 |
| header | 回调时附带的请求头，例如 Content-Type、签名头、业务密钥头。 |
| body | 回调请求体，通常是业务系统预先序列化好的 JSON 字符串。 |
{
"code": 0,
"message": "ok",
"data": {},
"date_time": "2026-03-19T20:00:00+08:00"
}
建议你在 notifyHTTPParam.body 中预先放入业务系统自己的 scheduleTaskId、签名密钥和 reportUrl，这样回调和回写就能闭环关联到同一条业务任务。
复杂业务编排、AI Prompt 执行、知识库读取、机器人通知、业务鉴权等逻辑，建议都放在你自己的业务服务中，不要塞进调度系统本体。
这部分专门解释调度器真实会怎么调用你的业务服务。当前实现非常明确：按 notifyHTTPParam 原样发起 HTTP POST，请求头和请求体都由调用方提供；回调结束后，如果请求体里带有 scheduleTaskId、secret 和 reportUrl，系统还会自动补一轮结果回写。
| Method | 当前执行器按 POST 方式发起业务回调。 |
|---|---|
| Header | 使用 notifyHTTPParam.header 中的键值对原样透传。 |
| Body | 使用 notifyHTTPParam.body 作为请求体；通常建议传 JSON 字符串。 |
| Timeout | 当前 HTTP 客户端默认超时约 5 秒，业务接口不宜做过长阻塞。 |
| Response | 响应体会被按 JSON 解析，建议你的业务回调接口始终返回结构化 JSON。 |
| Trace | 若 body 中带有 scheduleTaskId，会记录 callback_request、callback_response 等追踪阶段。 |
{
"notifyHTTPParam": {
"method": "POST",
"url": "https://your-business.example.com/api/job/run",
"header": {
"Content-Type": "application/json",
"X-App-Key": "your-app-key"
},
"body": "{\"jobType\":\"daily-summary\",\"tenantId\":\"team-a\"}"
}
}
{
"notifyHTTPParam": {
"method": "POST",
"url": "https://ai.example.com/v1/workspace/schedule/execute",
"header": {
"Content-Type": "application/json",
"X-Schedule-Secret": "demo-secret"
},
"body": "{\"scheduleTaskId\":\"abc123\",\"secret\":\"demo-secret\",\"reportUrl\":\"https://ai.example.com/v1/workspace/schedule/report\"}"
}
}
{
"scheduleTaskId": "abc123",
"schedulerTimerId": 9527,
"runAt": 1773925200,
"status": "success",
"reason": "",
"requestBody": "{\"scheduleTaskId\":\"abc123\",\"secret\":\"demo-secret\",\"reportUrl\":\"https://ai.example.com/v1/workspace/schedule/report\"}",
"responseBody": "{\"code\":0,\"message\":\"ok\"}",
"secret": "demo-secret"
}
下面展示当前首页建议对外公开的全部接口。页面中的路径全部按正式前缀 /api/xtimer/* 展示。
创建一个新的定时器，适用于单次任务和循环任务。生产系统通常先创建，再立即启用。
| app | 必填，业务系统名称。 |
|---|---|
| name | 必填，定时器名称。 |
| executeAt | 可选，单次任务时间戳。 |
| cron | 可选，循环或一次性 cron。和 `executeAt` 至少传一个。 |
| notifyHTTPParam | 必填，触发时要调用的业务回调信息。 |
更新已有任务的名称、执行时间、cron 表达式或回调参数。适合编辑已存在的任务定义。
| app | 必填，业务系统名称。 |
|---|---|
| timerId | 必填，要更新的 timer ID。 |
| name | 可选，更新后的名称。 |
| executeAt | 可选，新的单次执行时间。 |
| cron | 可选，新的 cron 表达式。 |
| notifyHTTPParam | 可选，新的回调配置。 |
重新启用一个已经停用的任务，并恢复未来执行计划。通常用于草稿发布或临时停用后的恢复。
| app | 必填，业务系统名称。 |
|---|---|
| timerId | 必填，要启用的 timer ID。 |
停用一个已启用任务，并清理未来尚未执行的调度计划。适合暂停或下线业务任务。
| app | 必填，业务系统名称。 |
|---|---|
| timerId | 必填，要停用的 timer ID。 |
删除任务主记录。若任务仍在运行中，系统会先执行停用与清理，再删除主记录。
| app | 必填，业务系统名称。 |
|---|---|
| timerId | 必填，要删除的 timer ID。 |
用于联调或演示回调链路是否畅通。它不是生产业务闭环中的正式执行入口，正式执行仍然依赖业务系统自己的回调地址。
这部分给的是最贴近业务接入的示例：一个循环 AI 任务，一个单次执行任务，再加一份结果回写字段示例。
curl -X POST '/create_timer' \
-H 'Content-Type: application/json' \
-d '{
"app": "go-ai-office",
"name": "每天早上汇总日报",
"cron": "0 9 * * *",
"notifyHTTPParam": {
"method": "POST",
"url": "https://ai.example.com/v1/workspace/schedule/execute",
"header": {
"Content-Type": "application/json",
"X-Schedule-Secret": "demo-secret"
},
"body": "{\"scheduleTaskId\":\"abc123\",\"secret\":\"demo-secret\",\"reportUrl\":\"https://ai.example.com/v1/workspace/schedule/report\"}"
}
}'
{
"app": "go-ai-office",
"name": "2026-03-19 21:00 执行一次",
"executeAt": 1773925200,
"notifyHTTPParam": {
"method": "POST",
"url": "https://ai.example.com/v1/workspace/schedule/execute",
"header": {
"Content-Type": "application/json",
"X-Schedule-Secret": "demo-secret"
},
"body": "{\"scheduleTaskId\":\"abc123\",\"secret\":\"demo-secret\",\"reportUrl\":\"https://ai.example.com/v1/workspace/schedule/report\"}"
}
}
{
"scheduleTaskId": "abc123",
"schedulerTimerId": 9527,
"runAt": 1773925200,
"status": "success",
"reason": "",
"requestBody": "...",
"responseBody": "...",
"secret": "demo-secret"
}