资源与工件模块 API 文档

基础前缀：/external/private/api 鉴权：DEFrame-UserId、DEFrame-TenantId、DEFrame-ExtendedInfo 文档版本基准：4f46278（2026-08-11）

统一响应体结构：

{
  "code": 0,
  "message": "success",
  "data": {},
  "ext": null
}

---

1. 上传策略查询

名称：上传策略 作用：根据用途（usage）返回允许上传的文件类型、大小上限与数量上限。

• 请求方式：GET
• 路径：/external/private/api/resource-upload-policy
• 查询参数：usage（必填）、agentId（可选）、conversationId（可选）
• usage 合法值：CONVERSATION_ATTACHMENT / AGENT_CONTEXT / CASE_ARTIFACT

响应体：

{
  "code": 0,
  "message": "success",
  "data": {
    "usage": "CONVERSATION_ATTACHMENT",
    "maxFileSize": 104857600,
    "maxFileCount": 10,
    "supportedFileTypes": [
      {
        "uploadFileType": "CSV",
        "label": "CSV 文件",
        "extensions": ["csv"],
        "mimeTypes": ["text/csv"],
        "maxFileSize": 104857600
      }
    ]
  },
  "ext": null
}

---

2. 对话附件上传

名称：对话附件上传 作用：将文件上传为对话附件，返回资源引用信息。

• 请求方式：POST
• 路径：/external/private/api/conversation-attachments/upload
• 请求体：multipart/form-data，字段 file（必填）、uploadFileType（必填）、conversationId（可选）

响应体：

{
  "code": 0,
  "message": "success",
  "data": {
    "resourceType": "FILE",
    "resourceId": "file-001",
    "uploadFileType": "CSV",
    "minioUrl": "minio://bucket/path/负荷曲线.csv",
    "displayName": "负荷曲线.csv",
    "mimeType": "text/csv",
    "fileSize": 102400,
    "sourceModule": "CONVERSATION_ATTACHMENT",
    "metadata": {}
  },
  "ext": null
}

---

3. 列出会话工件

名称：会话工件列表 作用：返回指定会话下产生的所有工件（Artifact）列表。

• 请求方式：GET
• 路径：/external/private/api/conversations/{conversationId}/artifacts

响应体：

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "artifactId": "art-001",
        "artifactType": "TABLE",
        "resourceType": "DATASET",
        "resourceId": "ds-001",
        "displayName": "预测结果表",
        "mimeType": "application/json",
        "previewStatus": "READY",
        "createdAt": "2026-08-11T15:00:00",
        "metadata": {}
      }
    ]
  },
  "ext": null
}