乾策立方开放平台文档

附件接口

附件上传接口必须通过 X-Employee-Virtual-Id 指定当前操作人，上传后可把返回 URL 回填到任务创建请求的 attachmentUrls。

POST /api/openplatform/attachments

上传附件，表单字段名固定为 file，一次只能提交一个文件，单个文件最大 100MB。

必填请求头：必须提供 X-Employee-Virtual-Id 和 UUID 格式的 X-Client-Request-Id。未传操作人时返回 403。

{
  "statusCode": 100,
  "msg": "上传成功",
  "data": {
    "url": "https://cdn.example.com/task/20260617/demo.pdf",
    "fileName": "demo.pdf",
    "fileSize": 204800,
    "id": "b34b6f3f-f84e-45ce-8c44-bb85d55a9ef5"
  }
}

MCP 工具 attachment_upload

个人 MCP 服务可直接上传本地文件。调用者需要拥有 attachments.write 权限；系统固定以个人 API Key 所有者作为操作人，上传成功后返回的 attachmentUrl 可直接放入其他 MCP 工具的 attachmentUrls。

文件限制：fileName 只能是单一文件名；contentBase64 必须是原始二进制内容的标准 Base64 字符串，不得传 data: 前缀。MCP 单文件解码后最大 10MB；REST 上传接口仍保持单文件最大 100MB。

请求示例：下例的 contentBase64 是一个真实可解码的 42 字节 GIF（GIF89a 开头、0x3B 结尾），可照抄自测。

{
  "fileName": "dot.gif",
  "contentBase64": "R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"
}

响应示例：

{
  "attachmentUrl": "https://cdn.example.com/task/20260617/dot.gif",
  "fileName": "dot.gif",
  "sizeBytes": 42,
  "attachmentId": "b34b6f3f-f84e-45ce-8c44-bb85d55a9ef5"
}

MCP 工具 attachment_upload_begin / attachment_upload_complete / attachment_upload_abort

大文件直传通道：文件字节不经过模型上下文，由调用方自己把文件直接提交到对象存储，服务端只负责签发一次性票据与验收。适合 attachment_upload 的 Base64 撑不下的大文件。

// 1) 申请票据：申报文件名与字节数，服务端按申报字节预扣成员当日上传额度
{ "fileName": "video-demo.mp4", "sizeBytes": 36700160 }

// 返回：uploadTicket 与直传表单字段
{
  "uploadTicket": "6f2c1a9d5e4b4f77a1c0d9e2b7c34a11",
  "uploadUrl": "https://temp.example.com",
  "policyFields": {
    "key": "temp/op/6c9c.../6f2c....mp4",
    "policy": "eyJleHBpcmF0aW9uIjoi...",
    "OSSAccessKeyId": "LTAI...",
    "signature": "X3k9...",
    "success_action_status": "200",
    "x-oss-forbid-overwrite": "true",
    "x-oss-object-acl": "private"
  },
  "expiresAt": "2026-10-12T12:15:00.0000000Z"
}

// 2) 调用方直接提交到对象存储（表单字段必须原样携带，再加 file）
//    curl -F key=... -F policy=... -F OSSAccessKeyId=... -F signature=... \
//         -F success_action_status=200 -F x-oss-forbid-overwrite=true \
//         -F x-oss-object-acl=private -F file=@video-demo.mp4 https://temp.example.com

// 3) 验收换取绑定地址
{ "uploadTicket": "6f2c1a9d5e4b4f77a1c0d9e2b7c34a11" }
{
  "attachmentUrl": "https://work.example.com/comm/res/show?id=b34b6f3f...",
  "attachmentId": "b34b6f3f-f84e-45ce-8c44-bb85d55a9ef5",
  "fileName": "video-demo.mp4",
  "sizeBytes": 36700160
}

使用约束：票据有效期 15 分钟，过期后必须重新申请；policyFields 的七个字段必须全部原样提交，删改任一项（包括把 x-oss-object-acl 改成公开读）都会被对象存储直接拒绝；实际上传字节不得大于申报的 sizeBytes；单文件上限 100MB，且受企业套餐的「成员 MCP 每日上传附件上限」约束，额度为 0 表示该企业未开放直传。

额度与计费：attachment_upload_begin 消耗一次 MCP 调用次数并按申报字节预扣当日上传额度；attachment_upload_complete 与 attachment_upload_abort 属结算类调用，只计量、不再消耗调用次数。验收后按实际字节校正差额，放弃或过期则全额回补。未验收也未放弃的票据由平台结算任务在过期后回收额度。

失败重试：若在文件尚未传完时调用 complete，会返回"直传对象尚未上传完成"，此时应完成上传后用新的 request id 重新调用 complete，不要重复调用 begin（会重复占用额度）；已验收成功的票据重复调用 complete 会幂等返回首次结果，重复调用 abort 会被拒绝。

类型政策：附件一律按扩展名与文件头双重校验，只接受常见办公格式（图片、PDF、Office 文档、纯文本、音视频）与 SVG 纯图形；可执行、脚本与可渲染类文件（exe/dll/bat/ps1/html/js 等）以及清单外的格式不接收原始形态，请压缩为 zip/rar/7z 后上传。企业网盘不受该清单限制。

与 REST 通道的差异：直传目前只经 MCP 提供，REST 侧仍只有 POST /api/openplatform/attachments（multipart 代传，单文件 100MB）。两条通道返回的 attachmentUrl 形态一致，业务侧绑定方式没有区别。

GET/api/openplatform/resources/{id}/url

换取单个附件资源的可访问地址。权限 attachments.read，必须带 X-Employee-Virtual-Id（缺失返回 403，错误信息为“请通过 X-Employee-Virtual-Id 指定当前操作人”）。只读。

参数	类型	必填	说明
`id`	guid	是	资源标识（来自附件上传或各业务接口返回的资源 Id）。非合法 Guid 属路由不匹配，返回 `404` 且无响应体。

data 为对象 {id, url, fileName, isImage}。私有附件返回源站签发的短时效签名地址，过期后需重新调用本接口；非私有附件是公共读直链，不设过期。

失败情况：资源不存在或不可见时返回 404，msg 为具体原因原文：“资源不存在”“操作人不在该附件的可见范围内”“私有附件签名失败，请稍后重试”。下游服务异常统一转 502。