API 版本控制
System One 如何对决策 API 做版本控制，以及 TypeScript SDK 应发送哪些请求头。
System One 托管 HTTP API 与独立 TypeScript SDK 有各自的版本边界。本页解释版本各自控制的内容，以及如何在升级时继续跟踪已有请求。客户端配置见 SDK 指南和托管快速开始。
常见问题
Q: How does / 如何 / どう / 어떻게 System One API versioning work?
A: System One 通过已文档化的版本请求头（及 SDK 默认值）对托管决策 API 做版本控制。生产环境请固定版本，升级时遵循本页。
四种独立的版本边界
| 边界 | 当前行为 |
|---|---|
| HTTP API 路径 | 决策和抽取都使用 POST /v1/systemone（请求体包含 fields 时走抽取）；模型发现使用公开的 GET /v1/models。目前没有 /v2 决策端点或通过请求头协商版本的机制。 |
| 维护中的契约 | typesafe-2026-09-18 标识文档中的兼容快照。GET /api/system-one/config 通过 contract 返回它；它不是模型 ID，也不是固定行为的请求头。 |
| SDK 包版本 | 各包独立发布。托管示例使用 core@0.8.0、transport-fetch@0.8.0 和 adapter-system-one@0.7.0（都解析到 core@^0.8.0）。包更新本身不改变 /v1。 |
| 请求模型 | 请求的模型 ID、别名和返回的解析后 model 与 HTTP、SDK 版本相互独立，别名可以随时间变化。 |
System One 适配器应明确设置 https://system-one.dev/v1。独立维护的官方 @typesafe-ai/sdk@0.6.0 是另一套客户端，其基础地址为 https://system-one.dev，不含 /v1，因为客户端会自行添加路径。连接本托管服务时，两者都使用 System One 密钥。直连提供方的 SDK 适配器使用各自的地址与凭据，也不代表这些提供方一定出现在托管目录中。详见 SDK 客户端与凭据。
查看当前模型信息
使用 Playground 模型选择器及旁边的 模型信息 按钮，或模型 API，查看当前模型、单价、能力和限制。不要将某一时刻显示的模型选项视为永久或穷尽的列表。详见选择模型。
模型 ID 或别名不保证版本固定不变，也不保证独立评估得到相同结果。不要自行拼造版本后缀，也不要假定 SDK 支持的直连模型一定由本站提供。有受支持的固定版本时可以选择它，并同时记录请求的模型 ID 与返回的 model；即使固定版本也不保证输出完全确定。
更换模型可能改变请求要求、答案和费用。提交前检查当前 capabilities、limits 和 pricing。Choice 最少选项数、问题名称规则、必填说明、null 与省略形式、扩展接受范围都可能不同。请求契约给出服务共同边界，不承诺每个模型都接受最宽泛的原生 HTTP 结构。保存请求时明确模型，不依赖可能变化的默认值。
更新集成
更新 SDK 包时，请查看 SDK 指南、API 请求字段和 SDK 迁移指南。旧 @system-one-ai/sdk@0.5.3 已弃用；当前示例使用独立的 core、adapter 和 transport 包。安装时明确版本，并在切换实际工作流程前评估具有代表性的问题。包迁移不会改变公开 HTTP 路径，也不会消除适配器契约的差异。
Core 0.8 导出 ImageInput、可选顶层 images，以及 Clairic 的 extract({ state, fields })。systemOneAdapter@0.7.0 会编码抽取请求（含图片），仍不会编码 evaluate() 的图片。因此托管决策图片使用 Fetch/HTTP。托管 Clairic 图片使用 SDK extract()。请读取 capabilities.inputs 中的 image、limits.images 与所选 limits.bytes，不要通过包版本推断能力。支持图片的 Clef 条目最高 13MB，仅文本条目（如 Jev）保留 64KB。该仅文本原始扩展及精度契约不变。网关会校验图片输入，但继续对 Clef 进行有界原生响应处理，保留四位小数容差；不会把所有响应交给 SDK 解码器或改写数值。
HTTP 与 SDK 响应兼容性
客户端应校验实际使用的答案字段，并容忍额外响应字段。可选 token 计数缺失或为 null 时表示未知，不是零。不要合成 warnings、rounding 或计费字段。Core SDK 返回规范化的类型结果，包括将原生 Noul 转成 Boolean 答案，将用量转成驼峰命名；原生 HTTP 与官方 TypeSafe 客户端的结构不同。需要原始响应头时，使用 Fetch 或官方客户端的 withResponse()，不要期望 Core 结果暴露每个头。
System One 积分、请求 ID、错误分类和重放状态应读取文档指定的 HTTP 头。X-TypeSafe-Request-Id 和官方客户端的快捷 requestId 表示 TypeSafe 跟踪标识；X-Request-Id 才是 System One 请求标识。成功响应及转发的 JSON 错误仍受文档说明的校验和安全例外约束，不应假定无条件按字节透传。参阅响应契约与错误参考。
弃用行为
目前没有公布固定的弃用通知期限、API 终止日期或支持 SLA。服务当前不发送 Deprecation 或 Sunset 头；缺少这些头不保证无限期兼容。也不承诺自动升级、旧模型永久可用，或提前通知每次模型变化。计划中的变更问题请联系 support@system-one.dev。
先处理已有操作
幂等以账户及规范化请求为范围，包含实际请求模型。恢复结果未知的操作时，必须保留相同键、模型和正文。接受的扩展字段、null 与省略、数组顺序和精确十进制值都参与比较。相同键下更换模型、评分标准或其他有意义的输入，会返回 409 idempotency_conflict。
更换模型属于新操作，需要新的键。不要将请求模型替换成响应中返回的解析后名称，也不要仅因响应延迟就切换模型或新建键，应先确认原操作结果。成功重放返回保存的结果，不再次评估或扣费，并保留原始 System One 请求 ID。
已完成操作的重放保护从请求创建起持续 24 小时。此后旧键可能发起新的计费操作，不提供永久去重保证。SDK 升级期间应保留未解决的操作数据；更新仍有处理中请求的客户端前，阅读幂等与重试。