# 导入完整会话轨迹

`POST` `/api/session/importTrace`

将OpenAI Chat Completions messages格式的JSON文件导入为会话，支持system、user、assistant、tool消息，以及reasoning_content、tool_calls、tool_call_id和多模态content。文件必须是JSON格式且不超过20MB，顶层可直接使用messages数组，也可使用包含messages字段的JSON对象。bizKey命中时追加、未命中时新建；仅传sessionId时追加到指定会话；两者都不传时新建；两者都传时bizKey优先。追加时principalId和agentId必须与目标会话一致，正在执行或等待权限确认的会话不允许追加。需要还原历史时间线时，可在文件内每条消息上增加可选字段messageTime（格式yyyy-MM-dd HH:mm:ss，亦兼容message_time写法，另兼容ISO的T分隔符与省略秒两种等价写法）；时间必须按消息顺序单调不减、不能晚于当前时间、不能早于2000-01-01，追加导入时本批次最早时间不能早于目标会话已有最后一条消息的时间，违反时直接报错不会静默修正；某条消息未带messageTime时继承上一条已确定时间并在warnings中说明，首条也未带时取导入时刻；整份轨迹都不传时行为与旧版完全一致。本接口非幂等，重复调用会重复导入；发生超时后请先查询目标会话，禁止无条件重试。调用方应检查响应中的warnings，确认是否存在内容降级或轨迹缺失。

**关联定时任务历史运行**：响应中的 messageMappings 按导入顺序给出每轮对话落库后的userMessageId 和 assistantMessageId，只包含真正落库的轮次（不含被忽略的system消息和被丢弃的尾部无回答user消息），其中 turnIndex 只在本次调用内从1开始计数，不是会话内的累计轮次。迁移原本由定时任务产生的历史对话时，先调用本接口导入对话，再用对应轮次的 assistantMessageId 调用「定时任务」模块的「迁移历史运行记录」接口补齐执行历史。

## 请求参数

### 请求头参数

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

### Query 参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| agentId | integer | 是 | 归属智能体ID；智能体必须存在且处于启用状态 |
| sessionId | integer | 否 | 追加导入的目标会话ID；bizKey为空时生效，不传则新建会话 |
| bizKey | string | 否 | 外部会话业务键。命中时追加、未命中时新建；与sessionId同时传入时优先使用 |
| title | string | 否 | 新建会话的标题，最多100个字符；追加到已有会话时不生效 |
| modelName | string | 否 | 模型名称，用于记录到会话和助手消息 |

### Form Data

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| file | string | 否 | OpenAI messages轨迹JSON文件，最大20MB；如需还原历史时间线，可在文件内每条消息上增加可选字段messageTime，格式yyyy-MM-dd HH:mm:ss，例2025-03-01 10:20:30 |

## 响应

### 200

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | SessionImportResultVO | 响应数据 |
|     sessionId | integer | 导入目标会话ID，包括本次新建或追加的会话 |
|     sessionCreated | boolean | 本次是否新建会话；true表示新建，false表示追加到已有会话 |
|     importedTurns | integer | 成功导入的对话轮数 |
|     importedMessages | integer | 成功导入的消息数量 |
|     importedParts | integer | 成功导入的消息片段数量 |
|     skippedSystemMessages | integer | 导入时被忽略的system消息数量 |
|     droppedTrailingUserMessage | boolean | 是否丢弃了轨迹尾部没有assistant回答的user消息 |
|     firstMessageTime | string | 本次导入内容的最早消息时间，格式 yyyy-MM-dd HH:mm:ss（与导入时传入的时间格式一致）；新建会话时即会话创建时间 |
|     lastMessageTime | string | 本次导入内容的最晚消息时间，格式同 firstMessageTime；已写入会话的最后活跃时间，决定会话列表排序；分批追加导入时可直接回填为下一批消息时间的下界参考 |
|     messageMappings | array | 本次实际导入的每轮对话与本地消息ID的映射，按导入顺序返回。

只包含真正落库的轮次：被忽略的system消息、以及被丢弃的尾部无回答user消息都不会出现在这里，因此正常情况下该列表长度与 importedTurns 一致。
如果服务端版本尚未支持返回映射，本字段会是空列表，此时 importedTurns 仍大于0，调用方不能据此判定没有导入成功；按映射迁移历史运行前请先核对两者是否一致。
迁移定时任务历史运行时，取其中的 assistantMessageId 作为「迁移历史运行记录」接口的入参。 |
|         turnIndex | integer | 本次调用内实际导入的轮次序号，从1开始。该序号只在本次调用内计数，不是会话内的累计轮次；分批追加导入同一会话时，每次调用都会重新从1开始 |
|         userMessageId | integer | 本轮用户消息的本地消息ID |
|         assistantMessageId | integer | 本轮助手消息的本地消息ID，可直接用作「迁移历史运行记录」接口的 assistantMessageId |
|     warnings | array | 导入转换告警，例如外部图片降级、未知内容片段忽略或工具结果缺失；调用方应检查并妥善处理 |
| 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处理 |