#版本与兼容
平台有四条各自独立演进的版本线。搞清楚哪条影响你，比记住某个具体版本号有用。
#四条版本线
| 版本线 | 谁在用 | 变更节奏 | 兼容承诺 |
|---|---|---|---|
| 网关协议 | 插件 ↔ 客户端 | 极慢 | 只增不改。已有字段永不删除、永不改语义 |
客户端 API (/v1/) |
客户端 ↔ 云端 | 慢 | 同一大版本内向后兼容；破坏性变更走 /v2/ |
| 开发者 API | 开发工具 ↔ 云端 | 中 | 变更提前在文档标注 |
| 客户端本体 | 玩家 | 快 | 自更新，minSupported 以下强制升级 |
为什么要拆开：客户端要在用户机器上跑很久，装了不更新的用户永远存在。 如果 API 和网站共用一条版本线，网站改版就会打死老客户端。 拆开之后，网站可以随便改，客户端 API 保持稳定。
#网关协议的兼容承诺
这是整个生态的地基，也是最不该动的一层。
承诺
- 已有字段永不删除，永不改变语义
- 新增字段一律可选，老插件不传也能正常工作
POST /v1/events和GET /v1/game-integrations/<source>/adapter-config这两个端点的路径不会变
这意味着什么
现有 Gamehub 生态里的插件（截至目前 53 个）不用改一个字节就能配本平台的客户端使用， 反之亦然。独立的是平台和运营，不是协议。
如果哪天真要破坏性变更，会：
- 新端点与老端点并存至少 12 个月
- 客户端同时支持两套
- 老端点返回
Deprecation响应头
#客户端 API 版本
当前是 /v1/。
属于向后兼容、随时可能发生的变更
- 响应里新增字段
- 新增可选查询参数
- 新增端点
- 错误消息文案调整
所以客户端解析响应时必须忽略未知字段，不要用严格模式反序列化。
属于破坏性、会走 /v2/ 的变更
- 删除或重命名字段
- 改变字段类型或语义
- 改变现有端点的路径
- 新增必填参数
#插件的版本号
manifest.json 里的 version 用宽松语义化版本：主.次.修订，
可带预发布后缀，如 1.0.0-beta.1。
平台强制的规则
| 规则 | 原因 |
|---|---|
| 同一版本号不可重复发布 | 已发布的包永远不覆盖，否则 SHA-256 校验失去意义 |
| 新版本必须严格大于所有历史版本 | 包括被拒审的版本 |
| 同内容（同 SHA-256）不可重复上传 | 内容没变就不需要新版本 |
| 正式版 > 同号预发布版 | 1.0.0 > 1.0.0-beta.1 |
建议的语义
- 修订号：修 bug、调冷却参数、改文案
- 次版本号：新增事件、支持新游戏版本
- 主版本号：改了已有
eventKey、改了source（等于新插件）、 或者游戏侧 Mod 的安装方式变了
改 eventKey 是破坏性变更 —— 用户在客户端里绑好的映射会失效。
如果只是想改显示名，改 name 不要动 eventKey。
#游戏版本兼容
插件应该在 USAGE.md 里写清支持的游戏版本范围。
建议
- 只用游戏公开的 Mod API，不打 Harmony/内存补丁 —— 大版本更新后通常还能用
- 用官方遥测接口（GSI、Live Client 等）的插件最稳，这些接口本身就是对外承诺
- 打了补丁的插件，每次游戏更新都可能要跟
游戏更新导致插件失效时，发一个新的修订版本，并在 USAGE.md 里更新版本范围。
不要留着旧版本让用户装了发现不能用。
#变更记录
#平台 v0.1.0 · 2026-09
首个版本。
- 四个 Worker：主站 / 文档站 / 开发者中心 / 客户端 API
- 插件市场、波形广场、开发者注册与发版、人工审核
- 直传（≤100MB）与分片上传（≤200MB，跨请求流式 SHA-256）
- 零依赖 ZIP 安全校验（含 ZIP64），21 个对抗用例实测通过
- 本地自检 CLI 与服务端共用同一份校验代码