通过文件直传方式上传附件，可通过bizKey或sessionId绑定到指定会话。支持通过sessionId或bizKey定位会话，bizKey优先级更高。服务端采用流式方式转发大文件，附件上传不会自动重试
POST
/api/agent/attachment/upload上传附件
请求参数
请求头参数1 个字段
X-Principal-Idintegernullable
身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。
Query 参数2 个字段
sessionIdintegernullable
会话ID，与bizKey二选一
bizKeystringnullable
业务键，与sessionId二选一，优先级高于sessionId
Form Data1 个字段
filestringrequired
待上传文件
响应
200
httpStatusCodeintegernullable
HTTP状态码
messagestringnullable
响应消息
dataAttachmentUploadVOnullable
响应数据
successbooleannullable
是否成功
requestIdstringnullable
上游请求ID，用于跨系统链路追踪排查问题
errCodestringnullable
上游错误码，前端可据此做特殊UI处理
POST
/api/agent/attachment/uploadByUrl通过URL导入附件
从可访问的HTTPS地址同步导入附件，fileName和fileUrl为必填项。bizKey和sessionId均为可选，两者同时传入时优先使用bizKey。导入最长可能持续11分钟；附件上传不会自动重试，接口返回失败时请避免立即重复提交，以免重复创建附件。
请求参数
请求头参数1 个字段
X-Principal-Idintegernullable
身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。
请求体（JSON）4 个字段
fileNamestringrequired
导入后的文件名，最多255个字符，不得包含路径分隔符，建议保留原文件扩展名
fileUrlstringrequired
待导入文件的HTTPS地址，仅支持HTTPS协议，最多4096个字符
bizKeystringnullable
业务键，与sessionId均为可选；两者同时传入时优先使用bizKey
sessionIdintegernullable
会话ID，与bizKey均为可选；两者同时传入时优先使用bizKey
响应
200
httpStatusCodeintegernullable
HTTP状态码
messagestringnullable
响应消息
dataAttachmentUploadVOnullable
响应数据
successbooleannullable
是否成功
requestIdstringnullable
上游请求ID，用于跨系统链路追踪排查问题
errCodestringnullable
上游错误码，前端可据此做特殊UI处理
GET
/api/agent/attachment/download下载附件
根据虚拟路径下载附件文件。支持通过sessionId或bizKey定位会话，bizKey优先级更高
请求参数
请求头参数1 个字段
X-Principal-Idintegernullable
身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。
Query 参数3 个字段
sessionIdintegernullable
会话ID，与bizKey二选一
bizKeystringnullable
业务键，与sessionId二选一，优先级高于sessionId
virtualPathstringrequired
虚拟路径
响应
200
GET
/api/agent/attachment/info查询附件文件信息
根据会话ID或业务键(bizKey)和虚拟路径查询附件元信息。支持通过sessionId或bizKey定位会话，bizKey优先级更高
请求参数
Query 参数3 个字段
sessionIdintegernullable
会话ID，与bizKey二选一
bizKeystringnullable
业务键，与sessionId二选一，优先级高于sessionId
virtualPathstringrequired
虚拟路径
响应
200
httpStatusCodeintegernullable
HTTP状态码
messagestringnullable
响应消息
dataAttachmentFileInfonullable
响应数据
successbooleannullable
是否成功
requestIdstringnullable
上游请求ID，用于跨系统链路追踪排查问题
errCodestringnullable
上游错误码，前端可据此做特殊UI处理
GET
/api/agent/attachment/preview预览附件
根据附件ID生成预签名URL并302重定向，可直接用于图片渲染或文件预览
请求参数
Query 参数1 个字段
attachmentIdintegerrequired
附件ID
GET
/api/agent/attachment/recentBySession查询最近会话附件列表
分页查询含有附件的会话列表，并返回每个会话下的附件详情，按最近附件上传时间倒序排列
请求参数
Query 参数5 个字段
agentIdintegerrequired
智能体ID
sourcestringnullable
附件来源过滤：USER_UPLOAD / AGENT_GENERATED
keywordstringnullable
搜索关键词，匹配会话标题或文件名
pageintegernullable
页码，从1开始
pageSizeintegernullable
每页记录数
响应
200
httpStatusCodeintegernullable
HTTP状态码
messagestringnullable
响应消息
dataPageResultRecentSessionAttachmentVOnullable
响应数据
successbooleannullable
是否成功
requestIdstringnullable
上游请求ID，用于跨系统链路追踪排查问题
errCodestringnullable
上游错误码，前端可据此做特殊UI处理
GET
/api/agent/attachment/getBySession查询指定会话附件详情
返回指定会话的基本信息及其所有附件列表，支持按附件来源过滤。支持通过sessionId或bizKey定位会话，bizKey优先级更高。身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。
请求参数
Query 参数3 个字段
sessionIdintegernullable
会话ID，与bizKey二选一
bizKeystringnullable
业务键，与sessionId二选一，优先级高于sessionId。传入bizKey时系统自动解析对应的会话
sourcestringnullable
附件来源过滤（可选），可选值：USER_UPLOAD-用户上传，AGENT_GENERATED-智能体生成，不传表示全部
响应
200
httpStatusCodeintegernullable
HTTP状态码
messagestringnullable
响应消息
dataRecentSessionAttachmentVOnullable
响应数据
successbooleannullable
是否成功
requestIdstringnullable
上游请求ID，用于跨系统链路追踪排查问题
errCodestringnullable
上游错误码，前端可据此做特殊UI处理
GET
/api/agent/attachment/getByMessage根据消息ID查询附件
返回指定消息关联的所有附件列表，支持用户上传和智能体生成的输出文件。智能体生成的附件其 fileName 可能带相对工作区的路径前缀，展示文件名请使用 pureFileName 字段
请求参数
Query 参数1 个字段
messageIdintegerrequired
消息ID
响应
200
httpStatusCodeintegernullable
HTTP状态码
messagestringnullable
响应消息
dataarraynullable
响应数据
successbooleannullable
是否成功
requestIdstringnullable
上游请求ID，用于跨系统链路追踪排查问题
errCodestringnullable
上游错误码，前端可据此做特殊UI处理
POST
/api/agent/attachment/fork复制附件到新会话
将指定附件创建独立副本，用于跨会话引用场景（如拖拽附件到新会话输入框）
请求参数
Query 参数2 个字段
sourceAttachmentIdintegerrequired
源附件ID
targetSessionIdintegernullable
目标会话ID，不传时附件暂不绑定会话
响应
200
httpStatusCodeintegernullable
HTTP状态码
messagestringnullable
响应消息
dataAttachmentUploadResultnullable
响应数据
successbooleannullable
是否成功
requestIdstringnullable
上游请求ID，用于跨系统链路追踪排查问题
errCodestringnullable
上游错误码，前端可据此做特殊UI处理