# 版本控制与弃用

> 了解 Kanorio 如何进行 API 版本控制、定义重大变更，以及在移除功能前如何公告弃用信息。

> Markdown version of https://kanorio.com/zh-CN/developers/basics/versioning. Append `.md` to any developer docs URL for this format. Index: https://kanorio.com/llms.txt · MCP: https://app.kanorio.com/api/mcp
>
> Translated from the English original: https://kanorio.com/en/developers/basics/versioning.md

所有三种 API 皆通过 URL 进行版本控制，例如 `/api/v1`。兼容性变更会持续发布，无需建立新版本。重大变更则遵循本页所述流程。目前 API 处于 **beta** 阶段：数据结构仍可能调整，且每次变更皆会先于 [更新日志](https://kanorio.com/en/developers/changelog) 中公告。

## 兼容性变更

此类变更随时会发布，请确保您的客户端程序具备容错能力：

- 新增端点、操作、MCP 工具与 Webhook 事件。
- 新增选填的请求字段与查询参数。
- 新增响应字段。请忽略您未知的字段。
- 新增错误代码。请依照 HTTP 状态码处理未知代码，详见 [错误处理](https://kanorio.com/zh-CN/developers/basics/errors)。
- 新增权限，以及更宽松的验证规则（接受更多数值）。

## 重大变更

此类变更绝不会在未经通知的情况下发布：

- 移除或重命名端点、操作、工具或字段。
- 变更字段的类型或意义，或将选填字段改为必填。
- 变更错误代码或其 HTTP 状态码。
- 收紧验证规则，或变更操作所需的权限。

针对稳定的操作，重大变更会经历弃用流程，并通过新的 URL 版本保留旧版本至少六个月。在当前阶段，重大变更会在发布当日列于更新日志中。

## 如何接收弃用通知

当操作被弃用时，所有渠道会同步通知您：

| 位置 | 您会看到的内容 |
|---|---|
| 响应头 | `Deprecation` 包含弃用日期，`Sunset` 包含移除日期，并附带 `Link` 头指向此政策及替代方案 |
| OpenAPI | 在操作中标记 `deprecated: true`、`x-kanorio-sunset` 和 `x-kanorio-replaced-by` |
| MCP | 工具描述开头会标注为 `[Deprecated, removed after …; use …]` |
| API 参考文档 | 显示弃用徽章，并标注移除日期和替代方案 |
| CLI | 在 stderr 显示警告信息 |
| 电子邮件 | 在移除前，会向过去 30 天内调用过该操作的 Token 持有者发送提醒 |

```http
Deprecation: @1788134400
Sunset: Sat, 01 May 2027 00:00:00 GMT
Link: <https://kanorio.com/en/developers/basics/versioning>; rel="deprecation"
```

操作仅会在超过停用日期（sunset date）后才会被移除。

## 发布阶段

每个操作与产品皆有其发布阶段。详见 [发布阶段](https://kanorio.com/zh-CN/developers/basics/release-phases)。

## SDK、Elements 与 MCP 版本

- `@kanorio/sdk` 与 `@kanorio/elements` 遵循语义化版本控制（Semantic Versioning）。经常变更的规则（如机器人防护、爬虫封锁列表与重定向）由 API 提供，因此已部署的前端无需升级即可自动获取更新。
- MCP 服务器会在 `serverInfo` 及其注册条目中发布语义化版本。主要版本更新（Major version）代表现有的调用行为可能会有所不同。每次变更时，更新日志皆会注明该版本号。