兼容性与支持矩阵¶
本页给出当前源码版本、运行时支持面，以及历史 candidate（候选）入口的一次迁移规则。版本与入口由 package.json、 Contracts 登记表和能力目录复核。
当前版本¶
| 包 | 当前源码版本 | 角色 |
|---|---|---|
skill-family-contracts |
0.13.0 | Contracts 1.13.0 机器契约 |
skill-family-harness-node |
0.13.0 | Contracts 的 Node 机制实现 |
skill-family-engineering-kit |
0.13.0 | 四个工程命令与构建期投影 |
| 私有父工作区 | 0.13.0 | 唯一开发真源 |
三个叶子包锁步发布，不能混用版本。Contracts 规格版本与 npm 包版本是两条不同版本线。
两代成熟度规则¶
历史 candidate API 先迁移一次到规范入口。旧入口在兼容窗口内继续解析同一模块；最终删除必须有公开弃用、真实消费者 引用清零、至少一个发布周期和独立主版本决策。
0.10.0 以后新增的 API 从首个 candidate 版本起就使用最终规范身份。candidate 阶段主动升级仍可能需要适配；但提供方
决定晋升 stable 时，只能改变兼容承诺，不能同时更换入口、能力 ID、Schema $id、operation、请求、结果或错误语义。
消费者要取得新发布的 stable 承诺，仍需更新三个包的精确 pin；Bundle 是否重建由既有 package identity、来源摘要与
provenance 绑定输入决定，不能仅因成熟度标签另加要求。机器规则见 FND-ADR-016 和 Contracts
CANDIDATE_PROMOTION_POLICY。
历史 candidate 迁移矩阵¶
| 历史坐标或能力 | 0.10.0 迁移目标 | 当前处理 |
|---|---|---|
skill-family-contracts/candidate/quickstart-profile |
skill-family-contracts/quickstart-profile |
两个入口同源；消费者迁移一次 |
skill-family-harness-node/candidate/quickstart-profile |
skill-family-harness-node/quickstart-profile |
两个入口同源；operation 不变 |
skill-family-harness-node/candidate/rename-directory-no-replace |
skill-family-harness-node/rename-directory-no-replace |
两个入口同源；不等同于高层固定集合发布 |
skill-family-engineering-kit/candidate/quickstart-profile |
skill-family-engineering-kit/quickstart-profile |
Quickstart builder 迁移一次 |
| 旧 Quickstart 命名空间中的 adoption | skill-family-engineering-kit/adoption |
职责明确的规范入口；实现仍与旧命名空间同源 |
| 包内或投影中的 skill naming candidate | skill-family-engineering-kit/skill-naming |
新增规范包入口；不增加 Kit 顶层命令 |
| 0.4.0 固定集合 candidate Schema 与原语 | 0.9.0 stable Schema $id、skill-family-harness-node/fixed-set-publication |
旧 Schema 继续随包提供；消费者迁移到高层 API |
0.9.0 validate-many-by-schema-id candidate Schema |
/foundation-mechanisms/v1/schema-validation-batch-{request,result}.json |
规范 Schema 只保留一份；旧新 ID 指向同一编译 validator，operation 与结果回显不变 |
Quickstart v2 的 Resource、Task、Result、consumer inventory、Harness surface inventory/detectors 六个身份也从
/candidate/quickstart-profile/v2/ 一次迁移到 /quickstart-profile/v2/。Contracts loader 只返回规范 $id；Bundle 在
兼容窗口内同时接受旧新 ID，不建立第二套 Schema 或通用 alias registry。
Quickstart v1 在 0.3.0 以前已被 v2 替换。需要 v1 的消费者只能继续精确锁定 0.2.1；0.10.0 不重写历史发布物， 也不重新打包 v1。
R05 与旧 platform-manifest 迁移¶
R05 的 request/result Schema 是 logicalMappings 的唯一结构事实源。消费者迁移时只保留自身领域字段，完成真实目录验证后删除重复的 closure、digest 和文件清单字段，不永久双写。
| 旧字段 | 迁移裁决 |
|---|---|
familyId |
映射为 skillFamilyId。 |
platformId |
先由已登记 Descriptor 证明，再映射为 canonical hostId。request 声明本身不构成证明。 |
version |
保留为消费者包版本。 |
sourceDigest |
映射为 commonSourceClosure.digest。 |
projectionDigest |
没有自动等价关系；manifest.digest 不得代替它。 |
fileCount / files |
从标准 manifest 派生；peer 根的 skills/ 不包含父目录旧 manifest，迁移后删除旧清单。 |
logicalMappings |
只由 request/result 持有。 |
lifecycleStatus / blocked / blockingReasons / advisories |
留在消费者领域。 |
verified |
不推导产品、Audit 或发布状态。 |
Node 与工具链¶
- Node：
>=22.22.2 <23；.node-version固定精确 floor22.22.2。 - pnpm：
10.30.0。 - projen：
0.101.23，是受管工程文件唯一生成入口。 - Schema 校验器：Ajv
8.20.0，支持 draft-07 与 2020-12。
低于 Node floor 或高于锁定 major 的结果不能替代权威门禁结果。
Contracts 与工程边界¶
- 顶层 Contracts 对象为 42 类，以
packages/skill-family-contracts/src/registry.json为唯一真源。 - Kernel 协议是 stable
skill-family.kernel.operation；本轮 Contracts 规格为 1.13.0，Kernel 文档仍按既有生命周期保持 1.8.0 字节基线。 - 错误码只增不改、不复用。
- Kit 顶层命令固定为
scaffold、adopt-plan、projection、check。 - 远端或通用
host apply、删除式uninstall、完整 Qoder driver、远端发布、业务状态机、模型编排与领域审计语义不在稳定支持面；本地 install/update 仍处于 0.10.0 unstable 计划 API 边界，unsupported 宿主不会获得自动生命周期能力，也不构成远端发布保证。
宿主的实时支持状态以能力目录、Profile descriptor 和真实 driver 为准；仅有目录结构或 CLI 身份事实不等于受支持闭环。