结构化输出与 SDK 版本

使用 JSON Schema 描述结果，并区分官方示例和 v2 类型字段。

结构化输出通过 StructuredOutput 工具让模型返回符合 JSON Schema 的对象。普通 text 是默认输出类型；需要验证 JSON 形状时使用 json_schema。

描述期望的数据

请求中的 format 对象可以写成：

{
  "type": "json_schema",
  "schema": {
    "type": "object",
    "properties": {
      "summary": {
        "type": "string",
        "description": "A short summary of the repository"
      },
      "languages": {
        "type": "array",
        "items": { "type": "string" }
      }
    },
    "required": ["summary", "languages"]
  },
  "retryCount": 2
}

type 与 schema 必填，retryCount 可选，官方 SDK 页给出的验证重试默认值是 2。通过字段 description 说明含义，用 required 明确必填，避免为一个小任务设计过深的嵌套结构。

先确认 SDK 入口

截至核验日期，官方 SDK 页同时出现 body.format 和方法表里的 body.outputFormat；示例还以 structured_output 读取结果。对照同一仓库提交的生成类型：

位置	已核实的类型形状
默认 `@opencode-ai/sdk` 的 SessionPromptData	没有 format / outputFormat 字段
`@opencode-ai/sdk/v2` 的 SessionPromptData	请求体字段是 `format?: OutputFormat`，路径字段为 `sessionID`
v2 的 AssistantMessage	结果字段是 `structured?: unknown`
v2 的 StructuredOutputError	`name` 为 `StructuredOutputError`，详情放在 `data.message` 与 `data.retries`

因此不能原样拼接文档里的默认 import、path.id、format 与 structured_output。上面的 JSON 只展示 format 的内容；实际调用形状应由已安装 SDK 入口和类型定义确定，不能通过类型断言绕过不匹配。

处理失败

官方说明所有验证重试失败后，消息携带 StructuredOutputError。这与 HTTP 客户端错误不同：即使请求返回，仍需检查助手消息中的 error，再读取结构化值。

v2 类型将结果定义为 unknown；业务程序还应按自己的数据类型验证或收窄结果。客户端的 throwOnError 控制 API 错误处理，不应把它理解为自动处理所有模型输出验证失败。

本页记录的是所核验官方提交的差异，不承诺后续发布保持相同字段；更新 SDK 后应重新检查生成类型和服务端 OpenAPI。