API 版本与变更
区分 HTTP 契约、SDK 发布、上游模型与当前弃用行为。
核对日期：2026 年 9 月 20 日。本页说明当前实现与已发布文档，不保证未来可用性或通知期限。
四种独立的版本边界
| 边界 | 当前行为 |
|---|---|
| HTTP 路径 | 决策使用 POST /v1/systemone，模型发现使用需认证的 GET /v1/models。目前未实现 /v2 决策端点或通过请求头协商版本。 |
| 维护中的契约 | typesafe-2026-09-18 表示文档中的兼容快照，公开配置通过 contract 暴露它。它不是模型 ID，也不是用于固定行为的请求头。 |
| TypeScript 包 | @system-one-ai/core、@system-one-ai/transport-fetch 和 @system-one-ai/adapter-system-one 的稳定版本为 0.6.0。包版本不会改变 /v1 路径。 |
| 上游模型 | 请求模型、提供方映射和返回的解析模型，与 HTTP 和 SDK 版本各自独立。别名可能随时间变化。 |
独立维护的官方 @typesafe-ai/sdk@0.6.0 是另一套客户端。其 base URL 不包含 /v1，而 System One 适配器的 base URL 包含 /v1。参阅快速开始。
模型名称与可复现性
默认 Workers AI 路径使用 typesafe/jev。当前兼容映射会将 jev-* 和其他 TypeSafe 别名转换到该绑定模型，因此在此路径提交 Jev 别名不代表固定到不可变的 TypeSafe 版本。显式 typesafe/jev-* 名称会交给绑定，由绑定判断该名称是否存在且受支持。
TypeSafe HTTP 路径会原样转发通过校验的显式模型名；部署未覆盖时，默认使用 jev-latest。上游提供固定版本时，可以使用该版本并记录返回的 model。固定版本名称不保证独立评估得到完全相同的结果。
GET /v1/models 需要平台密钥。Workers AI 返回平台目录，当前列出 typesafe/jev；TypeSafe 返回真实上游 { models } 正文；OpenRouter 返回 501 model_listing_not_supported。列表不是完整版本白名单。公开 SDK 为其他提供方提供适配器，不表示本站已托管对应服务。
原生与适配的边界
读取 X-System-One-Response-Mode，不要仅凭端点 URL 判断：
| 模式 | 含义 |
|---|---|
typesafe-native | 校验后保留有效 TypeSafe 成功文本、状态与扩展；仍受已记录的传输、大小、凭据安全与无效响应例外约束。 |
cloudflare-workers | 将 Workers AI 绑定输出映射为原生形状的答案，不属于 TypeSafe HTTP 字节透传。 |
openrouter-adapted | 网关转换 OpenRouter 决策协议并返回适配结果。 |
legacy-cache | 重放升级前已保留的答案，不执行新推理；无法还原原始上游字节。 |
原生 nullable 输入和扩展字段仍需上游接受。Core 0.6 与绑定 / 适配路径可表达的输入范围更窄；Workers AI 和 OpenRouter 会拒绝不支持的顶层扩展。请核对请求字段，不要假定每个适配器都拥有相同能力。
客户端可以容忍额外的上游响应字段，同时继续校验实际使用的答案字段。平台积分、请求 ID、错误分类与重放状态从文档指定的响应头读取，可选值缺失时保持未知。
当前演进与弃用行为
目前没有公布固定的弃用通知期限、API 终止日期或支持 SLA。网关当前不发送 Deprecation 或 Sunset 响应头；这些头缺失不代表承诺无限期兼容。本页不承诺自动升级、永久提供旧版本，或提前通知每项上游变更。
升级时请检查维护中的 API 文档及 SDK 迁移指南。旧 @system-one-ai/sdk@0.5.3 包已弃用；当前客户端示例使用独立包，并显式配置适配器和传输。本仓库后端也已迁移到 0.6.0 独立包：共享类型和错误来自 @system-one-ai/core，OpenRouter 使用 @system-one-ai/adapter-openrouter，Workers AI 绑定使用 @system-one-ai/adapter-cloudflare/workers。包迁移不会改变公开的 /v1 路径，也不代表适配响应变成了 TypeSafe HTTP 透传。
升级期间的在途请求
幂等按账户和规范化请求确定范围，并包含实际请求模型。恢复未知结果时，保留原键与请求。用同一键修改模型、评分标准或其他有意义的字段，会返回 409 idempotency_conflict。
新重放记录在内部版本化结构中保存响应文本、状态与允许的响应头，该存储格式不是公开 HTTP 版本。旧缓存保留原 24 小时过期时间并显式标记，过去合成的字段不一定能可靠移除。超过保留窗口后，同一键可能发起新的计费操作。升级尚有未完成操作的客户端前，请阅读幂等与重试。