第八章：版本管理

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. 不增加已有接口的必需参数