第八章：版本管理

8.1 概述

協定版本管理確保在協定演進過程中保持相容性，使技能提供者和消費者能夠平滑過渡到新版本。

8.2 語意化版本控制

協定遵循語意化版本控制（Semantic Versioning）規範：

MAJOR.MINOR.PATCH

版本號	變更類型	相容性
MAJOR	不相容的協定變更	破壞性變更，消費者需升級
MINOR	向後相容的功能新增	舊版消費者仍可正常運作
PATCH	向後相容的問題修復	文件修正、Schema 修復

8.3 版本宣告

每個技能描述符必須宣告所遵循的協定版本：

{
  "protocol": {
    "version": "1.0.0",
    "changelog_url": "https://skill-sharing.org/changelog"
  }
}

8.4 版本相容性規則

相容性判定

消費者支援版本: X.Y.Z
描述符協定版本: A.B.C

相容條件: A == X（主版本號相同）
不相容條件: A != X（主版本號不同）

相容性矩陣範例

消費者版本	描述符版本	相容性	說明
1.0.0	1.0.0	✓ 相容	完全符合
1.0.0	1.2.0	✓ 相容	次要版本向後相容
1.0.0	1.2.3	✓ 相容	修補版本向後相容
1.0.0	2.0.0	✗ 不相容	主版本號不同
2.0.0	1.5.0	✗ 不相容	主版本號不同

版本不相容回應

當消費者遇到不相容的協定版本時：

{
  "error": {
    "code": "VERSION_INCOMPATIBLE",
    "message": "Protocol version 2.0.0 is not compatible with consumer version 1.x",
    "details": {
      "descriptor_version": "2.0.0",
      "consumer_supported_range": "1.x.x",
      "upgrade_url": "https://skill-sharing.org/upgrade-guide"
    }
  }
}

8.5 Schema 版本化目錄

Schema 定義檔按版本組織：

schema/
├── draft/                    # 目前開發中的草稿
│   ├── schema.json
│   ├── schema.ts
│   └── schema.mdx
└── 2025-10-25/              # 已發佈的版本
    ├── schema.json
    ├── schema.ts
    └── schema.mdx

• draft/：目前正在開發的最新版本，可能包含未穩定的變更
• {date}/：已發佈的穩定版本，以發佈日期命名

8.6 版本變更日誌

協定 Schema 中包含版本變更日誌的參照路徑（changelog_url），記錄每個版本的變更內容：

• 新增的欄位或功能
• 廢棄的欄位或功能
• 破壞性變更說明
• 遷移指南

8.7 向後相容保證

次要版本更新時的向後相容保證：

1. 不刪除已有的必要欄位
2. 新增欄位預設為選用
3. 不改變已有欄位的語意
4. 不縮小列舉型別的值域
5. 不增加已有介面的必要參數