版本和兼容

插件 API 的版本就是 @nextskin/plugin-sdk 的版本，与插件自己的版本、NextSkin 核心产品版本分别计算。要发布插件或兼容旧站时，先确认构建所用 SDK 版本。

两个包和 manifest

SDK 与 @nextskin/plugin-cli 永远同版本发布，安装、升级时一起指定相同版本。构建命令读取插件项目的 SDK package.json：找不到、版本不合法、比 CLI 自带 SDK 新或大版本不同，都会报错；同一大版本下旧 SDK 可以由较新 CLI 构建，但日常仍建议两包装同版。

manifest 由构建器生成，不手写 api：

项目 SDK 版本	生成的 api
1.3.2	^1.3.0
1.0.0-rc.1	^1.0.0-rc.1

正式版本取 ^主.次.0，因为补丁不加接口；预发布保留完整版本和后缀后加 ^。例如 1.0.0-rc.2、1.0.0 都满足第二行，但不会因此接受其他主次补丁基数上的任意预发布版本。

核心实现的 API 版本必须满足 api 范围，不满足报 plugin_api_incompatible。想兼容实现 1.2 的旧核心，就用 1.2 次版本 SDK 构建；不会根据你“实际只用了旧方法”自动推算最低版本。

运行时的 SDK、zod 由 host 提供，查询类型还依赖 SDK 配套的 Kysely。不要自行换成不匹配的 zod/Kysely 版本。SDK 依赖锁次版本；核心升级它们时 SDK 也相应发版。

哪些变化用哪个版本

版本级别	变化
补丁	文档、doc 注释、构建命令 bug 修复，公开 API 报告不变
次版本	新增事件、扩展点、能力、可选参数；开放字符串联合增加成员；插件写给核心的能力、视图、字段、列格式等联合增加选项
大版本	删除、改名、收窄参数、放宽返回类型、封闭对象联合增加成员；CLI 命令、项目约定和包格式的破坏性变化

公开 API 报告有任何变化至少是次版本。zod 大版本、Kysely 的破坏性次版本（0.x）属于 SDK 大版本；兼容的依赖次版本变化也要跟随 SDK 次版本。候选期先发 1.0.0-rc.N，公开面仍可能调整，不能把候选版当成最终冻结面。

接口废弃时标 @deprecated，写明替代方案，至少保留到下一个大版本。核心同时只实现一个大版本插件 API；发大版本需要给出迁移方式，不会靠同时加载多代 SDK 维持旧插件。

插件表的查询子集和设置的可生成控件形状也是契约，之后只放宽、不收紧，不能拿“类型来自 Kysely/zod”当成收紧的理由。

开放和封闭联合

UserRole、TextureType、两个更新事件的 fields、report.resolved 的 action 是开放字符串联合，包含 string & {}。比较已知字面量可以，switch 必须有默认分支。例如：

import type { TextureType } from '@nextskin/plugin-sdk'

export function label(type: TextureType): string {
  switch (type) {
    case 'steve':
      return '经典皮肤'
    case 'alex':
      return '纤细皮肤'
    case 'cape':
      return '披风'
    default:
      return '其他材质'
  }
}

不要把未知值抛成“不可能”。Actor 是封闭对象联合，包含 user、system 和 plugin；第一版核心不会产生 plugin 操作者，但你可以提前处理这个分支。给 Actor 再加新 kind 是大版本，和开放字符串不同。

插件版本、requires 和 conflicts

package.json 的 version 是完整 semver，格式为 主.次.补丁[-预发布][+构建元数据]。三段是非负安全整数、不能有前导零；预发布和构建标识是点分隔的 ASCII 字母、数字、连字符，预发布纯数字标识不能有前导零。拒绝 v1.2.3、1.2、首尾空白；manifest 版本字符串最多 64 字符。构建元数据不影响版本比较。

nextskin.requires 是 { 插件id: 范围字符串 }；nextskin.conflicts 是插件 id 数组，conflicts 不接受版本范围。依赖必须启用、版本满足；冲突不能同时启用。id 规则见入门。

核心实际支持的范围语法如下：

语法	例子和含义
完整版本、等号	1.2.3、=1.2.3
比较符	>1.2.3、>= 1.2.3、<2.0.0、<=2.0.0
^	^1.2.3 到 2.0.0 之前；^0.2.3 到 0.3.0 之前；^0.0.3 到 0.0.4 之前
~	~1.2.3 到 1.3.0 之前；~1 到 2.0.0 之前
部分版本和通配	1、1.2、1.x、1.2.X、1.2.*、*，缺少的后段作为通配
空白交集	>=1.0.0 <2.0.0；各比较条件必须都满足
双竖线并集	1.x || 3.x；满足任一组
连字符范围	1.0.0 - 2.0.0 包括两端；1.2 - 2.3 包括整个 2.3 系列；可再用双竖线连接其他组

通配只能在末尾，不接受 1.x.3。部分版本也能配比较符，例如 >1.2 从 1.3.0 开始，<=1.2 包括整个 1.2 系列。范围非空，操作符后允许空格，连字符范围的分隔符两侧需要空白。

不支持标签（latest、rc）、v 前缀、!=、逗号交集、单竖线、括号、npm 别名、URL 或 Git 依赖范围。不能把 npm 接受的任意语法都放进 manifest。

预发布默认排除：*、>=1.0.0 不会匹配 1.2.3-beta.1。某个交集组必须显式含同一主.次.补丁基数的预发布比较条件，才允许匹配该基数的预发布；例如 ^1.2.3-beta.1 可接受 1.2.3-beta.2，不接受 1.3.0-beta.1。正式版满足范围时仍可匹配。