兼容性

K2F 兼容性分为三层：磁盘格式（规范 v0.3）、SDK 发布线（PyPI、npm 和 crates.io 上的 0.3.x），以及记录在每个锁文件上的编译器身份（engine_version、engine_commit_sha）。本页说明这些层面的策略。字段规则以格式规范为准；查看器横幅和验证哈希代码在完整性与验证中概述。

概览

主题	策略
格式契约	规范 v0.3，随 SDK 0.3.x 发布
较旧的发布线	0.2.x 及更早版本不受支持（安全）
SDK 补丁版本	保持规范 v0.3，除非 JSON schema 或锁格式发生破坏性变更
锁文件 `engine_version`	锁文件上记录完整编译器 semver；不是第二个公开规范编号
`ENGINE_MISMATCH`	读取器引擎不同时的来源信息——不是包损坏
安全修复	仅当前 0.3.x 发布线（安全）

支持的 SDK 运行时

本仓库中的参考 SDK 面向：

运行时	版本	安装
Python	3.9+	`pip install k2f`
Node.js	18+	`npm i @openk2f/k2f`（带作用域；npm 上无作用域的 `k2f` 已被占用）
Rust	最新稳定版	`cargo install k2f`

从源码构建引擎或桌面阅读器需要 Rust（稳定版）。贡献者工具链参见贡献指南。

打包的桌面阅读器安装程序会捆绑一个引擎构建；它们遵循与 CLI/SDK 相同的格式契约，而不是独立的 semver 产品线（桌面阅读器）。

格式与 SDK 版本管理

格式规范 0.3 是当前磁盘契约，与 0.3.x SDK 发布线对齐。除非内嵌 schema 或锁格式破坏兼容性，SDK 补丁版本不会重命名规范文件。

破坏性的 schema 或锁格式变更会提升规范版本，并与 SDK 在同一版本中发布。发布说明：变更日志。已发布与计划中的功能：项目状态。

锁文件中的引擎身份

每个编译后的锁文件都会记录：

engine_version — 编译引擎的 semver（与构建时的 k2f_core 值相同）
engine_commit_sha — 构建引擎所用的 git 提交

appearance_hash 绑定这些字段的锁文件存储值。验证会使用记录的身份重新计算哈希。当哈希链有效，但读取器由不同版本或提交构建时，验证会报告 ENGINE_MISMATCH。这属于来源信息，而非篡改：查看器仍保持 UNSIGNED 或 SIGNED，并渲染已发布的锁文件。

不要将 ENGINE_MISMATCH 映射为 BROKEN_INTEGRITY 或 SIGNED_BUT_BROKEN。详情参见规范中的完整性验证以及安全。

在锁文件上重写 engine_version 或 engine_commit_sha 而不刷新 appearance_hash，会得到 APPEARANCE_CHANGED（篡改），而不是静默不匹配。

当验证报告某个代码时该怎么做

代码	典型操作
`ENGINE_MISMATCH`	照常读取和导出；仅在用当前引擎重新编译时重新锁定
`CONTENT_CHANGED`	从更新后的语义树重新编译
`APPEARANCE_CHANGED`	在主题、字体、页面或未绑定的引擎字段变更后重新编译
`FONT_MISSING`	使用所需的内嵌字体重新打包

完整代码列表和横幅规则：完整性。

发布构建与 `K2F_ENGINE_COMMIT_SHA`

k2f_core 的发布构建在 engine_commit_sha 将为 UNKNOWN 时会 panic。在没有 git 检出的环境中（例如某些 CI 镜像），请设置 K2F_ENGINE_COMMIT_SHA。除非设置了该变量，调试构建可能记录 UNKNOWN。

跨平台锁文件

对于给定的引擎构建和语义树，布局旨在保持确定性。examples/published/ 下的示例锁文件会在 macOS 上的 CI 中验证（lock-macos 作业），以捕获平台特定的布局差异。

兼容性

概览