Core Versioning

版本与兼容性

StackPanel 有三个独立的版本维度：

维度	单一来源	用途
内核产品版本	KERNEL_VERSION	镜像、发行和产品更新
内核 API 契约	KERNEL_API_VERSION	插件 manifest.apiVersion、SDK、开放能力
宿主前端 ABI	KERNEL_FRONTEND_ABI	主题与插件前端包的 externals

当前值在 packages/spec/src/version.ts。不能用产品版本代替 API 或前端 ABI 兼容范围。

变更规则

• 删除字段、改变权限语义、改变既有行为：提高 API 契约 major，并提供迁移页。
• 新增可选字段或能力：提高 API 契约 minor。
• 文档修订：提高 patch；不得改变现有运行时行为。
• 新增或改变 Agent Surface 的输入、输出、审批或风险语义，按 API 契约变更处理。

所有公开契约必须经 pnpm --filter @stackpanel/api contract:snapshot -- --check 校验。 兼容窗口内同时保留旧入口、旧 schema 和弃用说明；窗口结束前在 release note 和 API 响应中给出迁移指引。