版本与兼容

基于 API 开发的应用可能多年不更新，所以 /v1 只会以现有客户端能继续正常工作的方式变化。

/v1 里可能发生的变化

• 新内容原地加入： 新接口、新的可选请求字段和查询参数、新的响应字段、新的事件类型、新的错误码。
• 取值集合会扩充： 事件类型、错误码、状态、步骤类别、界面组件类型等枚举都可能新增取值。遇到不认识的取值请忽略；遇到不认识的错误码，按它的 HTTP 状态码大类处理。
• JSON 里的字段顺序，以及给人看的 message 的措辞，可能会变。

永远不变的

• 任务如何结束。 任务以 task.completed、task.failed 或 task.stopped 结束，其状态为 completed、failed 或 stopped。新的结束原因会作为已有结束事件上的新错误码出现，所以客户端永远不会等待一个它认不出的结束。
• 字段永远不会被删除、改名，或改变类型和含义；默认值不会变；今天接受的输入明天也不会被拒绝；接口要求的凭证保持不变。

不兼容的变化

会破坏客户端的变化——上面列出的任何一种——只会针对受影响的资源推出新版本（该资源的 /v2/…），与旧版本并存。其他资源仍留在 /v1。

• 新版本推出后，旧版本至少继续服务 36 个月；之后只要还有人调用，就继续服务。
• 下线会在响应里提前告知：从下线日前至少六个月开始，带上 Deprecation 和 Sunset 响应头。
• 下线日之后，旧版本返回 410 endpoint_retired。在 /v1 上，410 只有这一个含义，所以客户端可以把任何 410 当作"需要升级"。

请求是严格的

请求体会拒绝未知字段，/v1 也会拒绝未知的查询参数（422 validation_failed）。新字段总是先在服务端上线，客户端才开始发送，所以客户端永远不会依赖一个服务端还不认识的字段。

声明客户端的协议版本

当不同代际的客户端需要不同行为时，服务端依据 VI-Protocol-Version 请求头区分：值为客户端开发时依据的协议修订日期，例如 VI-Protocol-Version: 2026-10-16。不带这个请求头的请求得到最初的行为，所以从不发送它的客户端，行为也永远不会在它不知情时改变。