# 兼容性

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

## 概览

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

## 支持的 SDK 运行时

本仓库中的参考 SDK 面向：

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

从源码构建引擎或桌面阅读器需要 **Rust（稳定版）**。贡献者工具链参见[贡献指南](CONTRIBUTING.md#prerequisites)。

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

## 格式与 SDK 版本管理

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

破坏性的 schema 或锁格式变更会提升规范版本，并与 SDK 在同一版本中发布。发布说明：[变更日志](CHANGELOG.md)。已发布与计划中的功能：[项目状态](docs/guide/status.md)。

## 锁文件中的引擎身份

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

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

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

不要将 `ENGINE_MISMATCH` 映射为 `BROKEN_INTEGRITY` 或 `SIGNED_BUT_BROKEN`。详情参见规范中的[完整性验证](docs/spec/k2f-v0.3.md#integrity-verification)以及[安全](SECURITY.md)。

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

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

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

完整代码列表和横幅规则：[完整性](/integrity)。

## 发布构建与 `K2F_ENGINE_COMMIT_SHA`

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

## 跨平台锁文件

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

## 相关

- [完整性](/integrity) — 查看器横幅和验证代码
- [变更日志](CHANGELOG.md) — 发布与规范版本提升
- [贡献指南](CONTRIBUTING.md) — 开发环境设置和黄金测试套件