版本与兼容性

Pling 有多条版本轴，它们不会一起移动。包发布、Surface 协议修订、持久化的连续性信封，以及应用的业务能力 id，都可能独立变化。把它们当成一个数字，会让升级看起来比实际更安全。

四条版本轴

轴	例子	变更意味着什么
包	@plingjs/vue 0.1.x	JavaScript API 与适配器行为
协议	pling.surface/0.1	Surface 与 Agent 客户端之间的请求、响应契约
持久状态	连续性信封版本	旧版本写入、新版本读取的数据
能力	orders.update_note	应用对外可见的动作契约

当前包使用预发布版本。这说明 API 仍在稳定过程中，不意味着可以静默破坏兼容性。预发布阶段应写明迁移，并把实验隔离；进入 1.0 后，每个包应独立遵守语义化版本。

兼容规则

增量变更通常可以留在同一个协议次版本内：新增可选字段、新增能力，或新增旧客户端可以安全归入“未知失败”的错误码。改变必填输入、包络形状，或既有结果的含义，属于破坏性变更，需要新的协议修订。

同一业务意图的能力 id 应保持稳定。若操作语义发生实质变化，应引入新 id 或带版本的应用命名空间，而不是静默改变旧 id 的行为。删除能力同样是权限与自动化的中断，即使底层 HTTP 接口仍然存在。

持久状态需要显式校验。旧版本写下的连续性检查点或待审批请求，在版本未知时必须被拒绝或迁移。不要因为其中“看起来有合理的字段”就执行一份未完全理解的信封。

按顺序升级

普通应用升级应遵循：

1. 阅读包变更记录与 Surface 协议说明。
2. 用新包运行声明与执行测试。
3. 用上一版本写下的状态测试回放与连续性。
4. 确认每个已暴露能力的 id、输入 schema、风险等级与审批行为没有意外改变。
5. 用较窄能力集和有界预算做灰度。
6. 保留无需修改业务页面就能关闭助手的回滚路径。

除非兼容矩阵明确支持，不要同时升级浏览器客户端和远端网关。独立版本轴的意义，正是让协议变化可以先在一侧落地。

弃用

弃用是一段迁移窗口，不是一句警告文案。应说明旧契约、新契约、首次发出警告的版本、最后接受旧形式的版本，以及移除后的可观察行为。除了文档，还要通过机器可读路径发出警告。

面对外部 Agent，使用协议修订与一致性检查；面对页面开发者，使用包发布说明与适配器迁移说明；面对持久状态，使用 fail-closed 校验与经过测试的迁移。不同受众在不同边界上遇到兼容问题，不能用同一条通知敷衍。

评审清单

• 包版本是否与协议版本独立？
• 变更新增了可选字段，还是改变了既有必填字段？
• 能力 id 与含义是否仍然稳定？
• 旧持久状态能否被清楚拒绝，或安全迁移？
• 旧客户端在声明的子集上是否仍可互操作？
• 是否有不依赖数据库重写的回滚路径？

版本管理不是发布时的文书工作。它定义了哪些独立部署的部分仍可以相互信任。参见 Surface 版本与治理与 安全升级 Pling。