统一内容协议（Content Parts）

百积木使用 content 数组描述消息正文。数组中的每一项是一个内容片段，通过 type 标识类型。 本页说明 Content Parts 1.0.0。这是一份平台内容协议；对接模型提供商或外部渠道时，由适配层转换为对方的格式。

基本结构

content 必须是非空数组，每项必须是对象。数组顺序就是内容顺序，即使只有一段文字也使用数组。 生产者使用下文规定的小写 type，并提供对应内容字段。1.0.0 的校验会拒绝未知类型和未知字段； 正文与资源字段按原值保留，空白检查不会修改正文。

{
  "content": [
    { "type": "text", "text": "报告已生成，请查看附件。" },
    {
      "type": "file",
      "file": {
        "url": "https://example.com/report.pdf",
        "name": "报告.pdf",
        "mimeType": "application/pdf"
      }
    }
  ]
}

示例地址仅用于说明格式。实际资源必须能够被目标消费者按其授权方式访问；不要假定浏览器中可打开的 地址就一定能被外部渠道读取。

当前内容类型

name 是资源展示名称，mimeType 是资源的媒体类型。它们不能替代资源地址。 地址协议、文件大小、格式和访问条件还受具体接口及渠道限制。

{
  "content": [
    { "type": "text", "text": "以下是本次沟通的材料。" },
    { "type": "image", "image": { "url": "https://example.com/photo.png" } },
    {
      "type": "audio",
      "audio": { "url": "https://example.com/voice.mp3", "name": "录音.mp3", "mimeType": "audio/mpeg" }
    },
    {
      "type": "video",
      "video": { "url": "https://example.com/demo.mp4", "name": "演示.mp4", "mimeType": "video/mp4" }
    },
    {
      "type": "file",
      "file": { "url": "https://example.com/report.pdf", "name": "报告.pdf", "mimeType": "application/pdf" }
    }
  ]
}

这些是内容片段示例，不代表一个渠道支持将全部片段合并成一条原生消息。

内容与消息外层

内容协议只描述正文，不定义接收人、会话、通知类别或投递状态。

• 接收人、工作区与会话由具体调用接口定义。
• 通知的 category、urgency 属于整条通知的属性，位于 content 外层。
• 消息事件的类型与内容片段的 type 是两个不同概念。
• 工具调用、工具结果和业务执行状态不属于这里的内容类型。

链接放在文本中，例如 {"type":"text","text":"查看报告：https://example.com/report"}。 当前未定义独立的 link、button、html、card 或 form 类型。text 也不意味着所有消费者都会 执行 HTML 或以相同方式渲染 Markdown。

本页定义内容结构，不声明某个工作区已安装通知模块。调用前仍须发现实际服务并读取 methodDefinition；通知接口的可用性和投递状态见通知与投递。

扩展与渠道能力

新增内容类型时，外层仍使用 content[]。扩展必须统一定义类型名称、字段、校验、版本和消费者支持范围， 不能只传一个新 type 就假定所有接口都能处理。当前发送入口会拒绝五种已登记类型之外的内容类型。

区分两个检查：内容是否合法，以及目标渠道能否投递。通过内容校验并不保证外部渠道能够展示所有片段。 当前渠道适配可能将媒体转成可读文本或省略不支持的片段；对内容完整性有要求时，需要核对该渠道的实际能力 和投递结果，不能把受理成功当作完整展示的证明。

与 OpenAI 格式的关系

内容数组和类型字段是共同的设计方式，字段结构并不相同。例如图片片段：

调用模型时必须使用对应适配，不能把百积木正文直接当作 OpenAI 请求发送。 第三方字段以 OpenAI Chat Completions 文档 和 Responses 图片输入文档为准。