# 迁移历史运行记录

`POST` `/api/agent/schedule/importExecution`

把已迁入本平台的一轮历史对话，登记为某个已存在定时任务的一次历史运行，用于从其它系统迁移存量定时任务后补齐执行历史。本接口不调用模型、不消耗额度、不触发任务执行，也不会改变任务的调度计划和下次触发时间。

**两阶段迁移流程**：
1. 先调用「会话」模块的「导入一问一答会话」或「导入完整会话轨迹」接口迁入历史对话，从响应的 messageMappings 中取出目标轮次的 assistantMessageId；
2. 再调用本接口，用该 assistantMessageId 关联到已存在的 taskId 上。服务端会据此推导用户消息、会话和智能体，无需重复传入。

**时间口径**：所有时间均为北京时间，格式 yyyy-MM-dd HH:mm:ss（亦兼容ISO的T分隔符与省略秒两种等价写法，不接受毫秒和时区偏移），取值须不早于 2000-01-01 00:00:00 且不晚于当前时间。startedAt 到 completedAt 的区间必须覆盖本轮已导入消息及其片段的时间，本接口不会反向改写消息时间。执行历史列表的展示时间和排序取 createdAt，**需要还原源端历史顺序时务必显式传入 createdAt**，不传时会落到首次迁入的时间。

**幂等与冲突**：本接口按本地助手消息幂等，同一条助手消息重复调用不会产生第二条运行记录，重放时返回原有记录且 created 为 false。若该消息已被其它运行占用、与已有记录冲突或对应记录已删除，返回 409 冲突。注意第一阶段的会话导入接口本身并不幂等，请求超时后请先查询目标会话确认是否已导入，不要无条件重试。

**迁移进来的运行是只读的**：迁入的记录会出现在执行历史中，可以查询、可以随任务删除，但不支持暂停、恢复、终止、重试和补充输入，也不支持订阅事件流。

## 请求参数

### 请求头参数

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

### 请求体（JSON）

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| taskId | integer | 是 | 已存在的定时任务ID，任务必须属于当前操作主体且未删除；已暂停的任务也可以关联历史运行 |
| assistantMessageId | integer | 是 | 会话导入接口返回的本地助手消息ID，取自 messageMappings 中对应轮次的 assistantMessageId。服务端据此推导本轮的用户消息、所属会话和智能体，无需额外传入 |
| status | string | 是 | 历史运行的终态，仅支持已结束的状态，不接受执行中或等待中的状态（大小写不敏感）。
- COMPLETED：执行完成
- FAILED：执行失败
- CANCELLED：执行取消 |
| startedAt | string | 是 | 真实执行开始时间，北京时间，格式 yyyy-MM-dd HH:mm:ss。须不早于 2000-01-01 00:00:00 且不晚于当前时间，并且要早于或等于本轮已导入消息及其片段的最早时间 |
| completedAt | string | 是 | 真实结束、失败或取消时间，格式与时区同 startedAt。不能早于 startedAt，并且要晚于或等于本轮已导入消息及其片段的最晚时间 |
| createdAt | string | 否 | 源端记录创建时间，北京时间，格式 yyyy-MM-dd HH:mm:ss。执行历史列表的展示时间和排序都取这个时间，需要还原源端历史顺序时务必显式传入；不传时取首次迁入的时间，幂等重放会保留首次值 |
| updatedAt | string | 否 | 源端记录更新时间，北京时间，格式 yyyy-MM-dd HH:mm:ss。与 createdAt 各自独立选填，两者都显式传入时要求 createdAt 不晚于 updatedAt；不传时取首次迁入的时间，幂等重放会保留首次值 |
| rounds | integer | 否 | 已知的真实循环步骤数。不传时保留已有值，没有已有值时记为0；服务端不会按导入轮数推测 |
| tokenUsage | TokenUsageRequest | 否 | 已知的历史Token用量。整体选填，传入非空对象时 totalTokens 必填，也可只传总量；未传的细分项保留助手消息已有统计，没有统计时记为0。重复导入不会累加 |
|     totalTokens | integer | 是 | 总Token数。tokenUsage 对象整体选填，但传入非空对象时本字段必填 |
|     promptTokens | integer | 否 | 输入Token数。与 completionTokens 同时传入时，两者之和必须等于 totalTokens |
|     completionTokens | integer | 否 | 输出Token数 |
|     cachedTokens | integer | 否 | 缓存Token数，属于输入用量的子集，不重复计入总量 |
|     reasoningTokens | integer | 否 | 推理Token数，属于输出用量的子集，不重复计入总量 |
| model | string | 否 | 历史运行使用的模型名称。助手消息上已有模型时以已有值为准，两处都传时必须一致；都没有时为空 |
| errorCode | string | 否 | 源端的失败或取消错误码，仅在 status 为 FAILED、CANCELLED 时可传；status 为 COMPLETED 时不接受任何错误信息 |
| errorMessage | string | 否 | 源端的失败或取消原因，仅在 status 为 FAILED、CANCELLED 时可传；status 为 COMPLETED 时不接受任何错误信息。不传时原因记为未知 |

## 响应

### 200

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | ImportTaskExecutionResponse | 响应数据 |
|     runId | integer | 本平台为这条历史运行分配的运行ID |
|     requestId | string | 服务端按本地消息锚点生成的稳定请求ID，不是源端的执行ID；同一条助手消息重复导入会得到相同的值 |
|     taskId | integer | 关联的定时任务ID |
|     sessionId | integer | 从助手消息推导出的会话ID |
|     agentId | integer | 从关联会话推导出的智能体ID |
|     userMessageId | integer | 关联的本地用户消息ID |
|     assistantMessageId | integer | 关联的本地助手消息ID |
|     status | string | 已登记的运行终态，可能取值：COMPLETED、FAILED、CANCELLED |
|     created | boolean | 本次是否首次创建运行记录。true表示新建，false表示同一条助手消息已经迁移过、本次按幂等重放返回原有记录 |
| 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处理 |