预先生成一个空会话并返回sessionId。适用于需要在发起对话前获取sessionId的场景，如前端需要sessionId来建立SSE连接。传入 projectId 时创建项目会话并使用该项目目录；不传时创建临时会话。可通过 environmentId 绑定沙箱环境，后续该会话的运行均在此环境中执行，环境必须归属当前租户/应用，否则返回无权访问错误。可通过 vaultIds 绑定当前应用空间的密钥；不传或空列表时不绑定密钥，列表中任一密钥不归属当前租户/应用时返回无权访问错误。身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

根据会话ID或业务键(bizKey)查询会话完整信息，包含Token消耗统计和会话当前状态(sessionStatus)。sessionStatus可能的值：IDLE(空闲就绪)、PROCESSING(执行中)、WAITING_PERMISSION(等待权限确认)、ERROR(执行出错)。bizKey与sessionId二选一，bizKey优先级更高。身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

返回最近一次已结算请求的输入总量及分类；历史会话无快照时自动估算，estimated=true

查询当前登录用户指定会话下的后台子任务运行记录。返回CREATED、PROCESSING、SUSPENDED、COMPLETED、FAILED、CANCELLED状态的任务；已删除的记录不返回。

查询当前登录用户指定会话下某个后台任务的完整执行详情。当前支持子智能体（SUBAGENT），executionParts 默认返回最近10个执行步骤的可见思考、正文、工具调用参数与结果；同一步内容不拆分或截断。可传nextBeforeStep至beforeStep读取更早10步。同时保留任务计划、最近工具步骤等摘要字段。任务结束后仍可查询该次运行，不跳转至后续运行。

停止当前用户指定会话下的一次后台任务执行。只需传sessionId和列表中的taskId，类型由服务端识别。保留记录和已有结果；重复请求返回ALREADY_TERMINAL及当前状态，不会取消后续新运行。停止请求接受后可刷新后台任务列表查看状态。

按当前用户维度分页查询会话列表，支持按智能体、会话状态和触发来源类型过滤。智能体过滤可使用agentIdList（多值，适用于跨智能体聚合列表）或agentId（单值），两者同时传入时以agentIdList为准。triggerSourceTypeList可按触发来源类型收窄范围（精确匹配，命中任一类型即返回），适用于区分用户对话与定时任务产生的会话；注意早期会话可能未记录触发来源，传入该过滤条件时这类会话不会返回。返回结果包含sessionStatus字段，可选值：IDLE(空闲就绪)、PROCESSING(执行中)、WAITING_PERMISSION(等待权限确认)、ERROR(执行出错)。默认（includeProjectSessions=false）仅返回未绑定项目的临时会话；传true时返回当前身份主体符合其余过滤条件的全部会话（含项目会话），可用于单列表同时展示临时会话与项目会话。身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

按关键词全文搜索当前主体名下的会话，匹配范围为会话标题、用户输入和助手输出三个字段。结果按会话折叠：每个会话仅返回相关性最高的一条消息作为代表，total为满足条件的会话数。highlight=true（默认）时命中词以<em>标签包裹返回高亮片段，未命中的字段高亮列表为空；highlight=false时三个高亮字段均返回空列表，查询开销略有降低。支持按agentId、triggerSourceTypeList精确过滤收窄搜索范围，过滤条件可自由组合，不影响相关性排序和高亮。返回的代表消息附带requestId、userMessageId、assistantMessageId，可用于跳转定位到会话内的具体消息（消息ID写入索引时未提供则为空）。用户模式仅搜索当前登录用户名下的会话；应用模式仅搜索请求头X-Principal-Id指定主体名下的会话。

根据会话ID或业务键(bizKey)分页查询消息列表。bizKey与sessionId二选一，bizKey优先级更高。默认按对话时间升序返回（sortOrder=asc），旧消息在前；传入sortOrder=desc时按时间倒序返回，新消息在前，第1页即最新消息，适合查询最近聊天记录的场景。身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

不传view或传full：按partId升序返回完整部件数组，保留存量行为。传summary：按partId倒序分页返回摘要对象，不包含正文、参数、输出及Token统计。摘要模式每页最多扫描pageSize条候选，过滤SUMMARY、SUBAGENT_NOTIFICATION及hidden工具；items可能为空，请按hasMore和nextBeforePartId翻页。普通会话与子会话均校验主体归属。API调用须传X-Principal-Id，页面调用使用登录身份。

根据sessionId定位会话，通过principalId进行归属校验后更新标题。归属校验失败时返回错误提示。标题更新成功后会同步刷新搜索索引，若索引同步失败接口将返回错误，此时标题已更新，可安全重试本接口完成索引同步。身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

对源会话进行深拷贝，创建一个独立的新会话副本。深拷贝范围包括消息、消息片段、上下文和附件（OSS独立副本），沙箱环境不会被复制。可通过forkPointMessageId指定分叉点，仅复制该消息及之前的已完成消息；不传则复制全部已完成消息。前置条件：源会话必须处于空闲状态（IDLE或ERROR），正在处理中的会话会拒绝分叉操作。身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

用户对整个会话或其中某条消息提交文字反馈。反馈为纯追加写：同一会话允许多次提交，每次生成一条新记录，不做覆盖。会话必须归属当前操作主体，否则返回403；messageId可选，不传表示针对整个会话，传入时必须属于该会话且未删除，否则返回404。lastAssistantMessageId可选，建议前端传入提交时会话中最后一条助手消息ID，便于后台还原反馈时的会话位置。

根据会话ID或bizKey获取最近一次（或全量）LLM 调用的请求消息序列，用于复现/重放、训练数据导出等场景。bizKey与sessionId二选一，bizKey优先级更高。pruned=true（默认）表示精确还原最后一轮 LLM 调用时的请求（含 Prune+Token Budget 裁切）；pruned=false 表示返回全量历史不裁切。includeLastResponse 仅在 pruned=true 时生效，true（默认）输出完整轨迹（请求+响应），false 仅输出纯 request body，可直接重放。调用方需对会话归属拥有访问权限（用户模式按 user 维度、应用模式按 app 维度校验），无权访问将返回 403。身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

将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 调用「定时任务」模块的「迁移历史运行记录」接口补齐执行历史。

将一组用户问题和模型回答导入为一轮完整对话，适用于不包含工具调用过程的历史数据。同一外部会话有多轮问答时，应使用相同bizKey或sessionId并按原始对话顺序逐次调用。bizKey命中时追加、未命中时新建；仅传sessionId时追加到指定会话；两者都不传时新建；两者都传时bizKey优先。追加时principalId和agentId必须与目标会话一致，正在执行或等待权限确认的会话不允许追加。需要还原历史时间线时，可传userMessageTime和assistantMessageTime（格式yyyy-MM-dd HH:mm:ss，另兼容ISO的T分隔符与省略秒两种等价写法）；assistantMessageTime不传时继承userMessageTime且不能早于它，两者都不传时行为与旧版完全一致；时间不能晚于当前时间、不能早于2000-01-01，追加导入时也不能早于目标会话已有最后一条消息的时间。本接口非幂等，重复调用会重复导入；发生超时后请先查询目标会话，禁止无条件重试。

关联定时任务历史运行：本接口每次只导入一轮对话，响应中的 messageMappings 固定只有一项，其 turnIndex 恒为1（只在本次调用内计数，不是会话内的累计轮次）。迁移原本由定时任务产生的历史对话时，先调用本接口导入问答，再用该项的 assistantMessageId 调用「定时任务」模块的「迁移历史运行记录」接口补齐执行历史。

根据会话ID或bizKey删除会话（软删除）。bizKey与sessionId二选一，bizKey优先级更高。删除成功后会同步清除搜索索引中该会话的全部消息文档，若索引同步失败接口将返回错误，此时会话已删除，可安全重试本接口完成索引同步。身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

按sessionId和partId读取可见部件，校验当前主体与会话归属。已删除或隐藏部件不可访问。返回TEXT、REASONING或TOOL的完整展示内容，不返回内部提供商字段。API调用须传X-Principal-Id，页面调用使用登录身份。