# 版本控制與棄用

> 了解 Kanorio 如何進行 API 版本控制、定義重大變更，以及在移除功能前如何公告棄用資訊。

> Markdown version of https://kanorio.com/zh-HK/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-HK/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-HK/developers/basics/release-phases)。

## SDK、Elements 與 MCP 版本

- `@kanorio/sdk` 與 `@kanorio/elements` 遵循語意化版本控制（Semantic Versioning）。經常變更的規則（如機器人防護、爬蟲封鎖清單與重新導向）由 API 提供，因此已部署的前端無須升級即可自動獲取更新。
- MCP 伺服器會在 `serverInfo` 及其登錄項目中發布語意化版本。主要版本更新（Major version）代表現有的呼叫行為可能會有所不同。每次變更時，更新日誌皆會註明該版本號。