# 查询任务详情

`GET` `/api/agent/schedule/detail`

根据任务ID查询任务详情，包含任务的基本信息和执行历史。

返回的任务信息使用两个独立字段描述状态，二者结合才能完整反映一个任务的状态：

**taskStatus（任务开关状态）**：由调用方主动控制，暂停或恢复任务时改变。
- ENABLED：启用中，任务处于生效状态，会按配置的触发规则自动执行
- DISABLED：已暂停，任务配置保留，但不再触发执行，可随时恢复

**scheduleState（实时调度状态）**：由系统根据任务的实际调度情况实时计算，反映此刻任务在做什么。
- SCHEDULED：等待执行，任务已排入调度计划，将在 nextExecutionTime 指定时间触发
- RUNNING：执行中，任务已被触发，正在运行
- NOT_SCHEDULED：无后续执行计划，任务被暂停，或一次性任务已执行完毕

**常见状态组合**：
- ENABLED + SCHEDULED：正常运行中，等待下次触发
- ENABLED + RUNNING：正在执行本次任务
- ENABLED + NOT_SCHEDULED：一次性任务已执行完成，无后续计划
- DISABLED + NOT_SCHEDULED：任务已暂停，恢复后将重新排入调度计划

展示建议：以 scheduleState 作为任务的主展示状态，taskStatus 用于渲染「暂停 / 恢复」操作按钮的开关态。对于一次性任务，执行完成后 taskStatus 仍为 ENABLED，但已不会再次触发，此时应依据 scheduleState 判断任务是否还有后续执行计划。

**触发类型（triggerType）**：
- ONE_TIME：一次性任务，在指定时间执行一次，执行后不再触发
- RECURRING：周期性任务，从起始时间开始按固定时间间隔重复执行
- CRON：Cron 表达式任务，按标准 Cron 表达式定义的时间规则执行

**响应中 triggerConfig 的时间口径**：
triggerConfig 以 JSON 字符串返回，其中 executeTime、startTime 为北京时间，格式 yyyy-MM-dd HH:mm:ss，与创建/修改时传入的时间口径一致，也与同一响应中的 nextExecutionTime、createdAt 保持一致。
历史上该字段曾以 UTC 的 ISO-8601（如 2026-09-07T16:00:00Z）返回，如果您解析了这两个时间字段，请按北京时间解析，不要再当作 UTC 处理；仅透传或展示该字段的调用方不受影响。

身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

## 请求参数

### 请求头参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-Principal-Id | integer | 否 | 身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。 |

### Query 参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| taskId | integer | 是 | 任务ID，必填 |

## 响应

### 200

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | TaskDetail | 响应数据 |
|     task | TaskInfo | - |
|         id | integer | - |
|         sessionId | integer | - |
|         agentId | integer | - |
|         taskName | string | - |
|         description | string | - |
|         triggerType | string | 触发类型。ONE_TIME：一次性任务，在指定时间执行一次，执行后不再触发；RECURRING：周期性任务，从起始时间开始按固定时间间隔重复执行；CRON：Cron 表达式任务，按标准 Cron 表达式定义的时间规则执行 |
|         triggerConfig | string | - |
|         taskStatus | string | 任务开关状态，由调用方主动控制，暂停或恢复任务时改变。ENABLED：启用中，任务处于生效状态，会按配置的触发规则自动执行；DISABLED：已暂停，任务配置保留，但不再触发执行，可随时恢复。建议将该字段用于渲染「暂停 / 恢复」操作按钮的开关态 |
|         deliveryChannel | string | - |
|         scheduleState | string | 实时调度状态，由系统根据任务的实际调度情况实时计算，反映此刻任务在做什么。SCHEDULED：等待执行，任务已排入调度计划，将在 nextExecutionTime 指定时间触发；RUNNING：执行中，任务已被触发，正在运行；NOT_SCHEDULED：无后续执行计划，任务被暂停，或一次性任务已执行完毕。建议将该字段作为任务的主展示状态 |
|         nextExecutionTime | string | 下次触发时间，北京时间，格式 yyyy-MM-dd HH:mm:ss。scheduleState 为 NOT_SCHEDULED 时任务无后续执行计划，该字段为空 |
|         totalExecutionCount | integer | - |
|         createdAt | string | - |
|         payload | string | - |
|     executionHistory | array | - |
|         runId | integer | - |
|         taskId | integer | - |
|         taskName | string | - |
|         sessionId | integer | - |
|         requestId | string | - |
|         executionTime | string | - |
|         status | string | - |
|         rounds | integer | - |
|         totalTokens | integer | - |
|         durationMs | integer | - |
|         errorCode | string | - |
|         errorMessage | string | - |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 400

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 500

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |