spec 1.0 · 规范性

版本管理

规范、schema 和实现规范的工具分别独立进行版本管理。

规范#

规范采用 SemVer 版本号（当前为 1.0.0）。破坏性变更需要主版本；每一次变更都记录在仓库的变更日志中。
上下文层在 leji.json 中通过自命名的 leji 键声明它面向的规范版本系列（例如 "leji": "1.0"），沿用 OpenAPI 的约定。该值是规范的版本系列（major.minor），绝不是规范的补丁版本：补丁发布（1.0.0 到 1.0.1）打磨措辞或工具而不移动版本系列，因此清单在每一次补丁之后仍保持 "1.0"。工具必须对照所声明的版本系列校验上下文层，而不是最新的版本系列。

预览版本系列#

规范版本系列可以被指定为预览。预览版本系列可以原地修订：在它于正式发布（GA）时被冻结之前，它可以发生本来属于破坏性的变更，而不必提升到新的版本号。“破坏性变更需要主版本”这条规则（第 1 条）与“形态发生不兼容变更时 $id 随之改变”这条规则（第 3 条）自 GA 冻结起生效，而不是在版本系列仍处于预览期间。到 GA 时该版本系列被冻结，两条规则同时生效。

若某个版本系列在正式发布（GA）之前就已发布，必须在首次发布时声明其预览状态。

1.0 版本系列在 v1.3.0 参考工具发布时冻结。在这个系列内部，schema 变更只能是增量的，$id 保持在 v1.0 上；任何不兼容的变更都作为新的版本系列发布，绝不原地进行。

Schema#

每个 schema 携带形如 https://leji.org/schemas/v<major>.<minor>/<name>.schema.json 的稳定 $id。只有当 schema 的形态发生不兼容变更时，$id 的版本系列才移动。
在已发布的版本系列内部，schema 变更必须是增量的（新增可选字段）。删除字段或改变语义需要新的版本系列。
除清单以外的机器可读产物，通过 schemaVersion 声明它们所依据撰写的 schema 版本系列；清单则通过自命名的 leji 键声明它面向的规范版本系列（第 2 条）。

稳定集合#

以下内容在同一规范版本系列内被冻结；工具（包括未来的商业实现）据以构建，无需并行的 schema：

清单的形态及其固定文件名 leji.json，
类别标识符（domain、system、practice、governance、decisions），
一致性级别标识符（core、indexed、governed、federated），
machine-readable-surface.md 中的标识符与路径归一化规则，
索引条目、变更日志条目、智能体配置与决策记录的形态。

实现工具（非规范性）#

各 SDK 和 CLI 分别按 SemVer 管理版本，并声明所支持的规范版本系列。本仓库中的参考 SDK 包括 npm 包 @leji-org/leji（packages/sdk）、PyPI 包 leji（packages/sdk-py），以及 Go 模块 leji（packages/sdk-go，单个静态二进制）。三者行为完全一致，并使用同一套共享 fixture 测试套件进行测试。