# K2F — 常见问题

## Table of contents

1. [先问几个问题](#1-先问几个问题)
2. [`.K2F` 文件包](#2-k2f-文件包)
3. [确定性渲染](#3-确定性渲染)
4. [AI agents、skills 与编辑](#4-ai-agentsskills-与编辑)
5. [导出与交付](#5-导出与交付)
6. [Gallery 与模板](#6-gallery-与模板)
7. [生态与工具](#7-生态与工具)
8. [隐私、安全与数据处理](#8-隐私安全与数据处理)
9. [版本控制与协作](#9-版本控制与协作)
10. [和其他格式、工具的比较](#10-和其他格式工具的比较)
12. [边界、路线图与信任](#12-边界路线图与信任)

---

## 1. 先问几个问题

### 用一句话说明，K2F 是什么？

K2F 是面向 AI 时代的**开放文档文件格式**（类似 PDF 或 DOCX）：你在一个 ZIP 里编辑**语义 JSON 树**和一份 **theme**；参考引擎把它**编译**成 **render lock**，于是每个 K2F 查看器都画出同样的像素。从这个 lock 可以导出 Word、PowerPoint、可填写 PDF、IDML、Markdown 和图片。

### K2F 是 SaaS、库，还是文件格式？

三层都有：

- **文件格式** — Apache 2.0 规范和 schema；`.K2F` 文件可以放在任何地方。
- **参考引擎和 SDK** — 开源；发布在 PyPI（`pip install k2f`）、npm（`@openk2f/k2f`）和 crates.io（`cargo install k2f`）。
- **k2f.dev 上的服务** — 可选：Gallery、Playground、文档，以及托管的查看器 URL。下载 Gallery 模板，或在本地走 agent skill 流程，都不需要账号。

### K2F 是给谁用的？

- 希望 **AI agent** 做出或改好**设计完成的文档**，而不必去对付 OOXML 或 PDF 坐标的团队。
- 需要**一份语义源**、多种**交付格式**的人（法律用 DOCX，按页的幻灯片用 PPTX，签署用 PDF，InDesign 用 IDML）。
- 希望文档源**适合 Git**、能按节点修改，并在 K2F 查看器里做**确定性审阅**的组织。
- 通过 **CLI、Python/JS SDK、WASM 或 MCP** 嵌入文档的开发者。

K2F 是为了和团队已经在用的工具**一起工作**：Office、InDesign、PDF 阅读器和设计软件都留在流程里。它最强的地方是做**适合 agent 的源**和编译中枢，而不是桌面 Office、InDesign 或随手设计工具的逐项替代；见[边界、路线图与信任](#12-边界路线图与信任)。

### 我需要安装什么？

Agent 工作流的最低要求：

```bash
pip install k2f    # CLI + Python SDK on PATH
```

可选：

```bash
npx skills add suzheng/k2f --skill k2f   # Agent skill for Cursor, Claude Code, Codex, etc.
npm i @openk2f/k2f                                 # Only if you embed <k2f-viewer> in a web app
```

### 大约 60 秒怎么开始？

**路径 A — Gallery：** 打开 [k2f.dev/gallery](https://k2f.dev/gallery)，下载一个 `.K2F` 模板（不用登录），在 [Playground](https://k2f.dev/playground) 里打开，或用 `k2f unpack` 解开。

**路径 B — Agent：** 把下面这段贴给 agent：

```text
Use the K2F skill to create a [describe what you want]. Install with npx skills add suzheng/k2f --skill k2f if needed.
```

Agent 会编辑 `source/` 下的 JSON，执行 pack/compile，并交出 `.K2F` 以及你要求的导出文件。

### K2F 免费吗？要付费方案或账号吗？

**格式和参考引擎**开源（Apache 2.0）。**CLI/SDK** 可以从公开仓库免费安装。**Gallery** 模板可以不登录下载。**k2f.dev** 的 Gallery、文档、Playground 浏览和 agent skill 流程都不需要账号。可选的托管功能（k2f.dev 上的分享/发布链接）只是方便，不是按量计费的「K2F 云编译」产品。隐私以及哪些操作会碰到服务器，见[第 8 节](#8-隐私安全与数据处理)。

### K2F 和 Word、PowerPoint、InDesign、PDF 怎么配合？

K2F 是技术栈里的**多出来的一层**，不是替换你们组织已经标准化的那些应用。

| 角色 | 怎么配合 |
|------|----------|
| **适合 agent 和 Git 的写作** | 需要结构化修改时，`.K2F` 的语义树加 theme 就是你拿来编译的可编辑源。 |
| **一致的审阅** | Playground、Desktop Reader 和 Web Viewer 绘制同一份 lock；基于 lock 的 PDF 是常见的审批路径。 |
| **桌面协作** | 导出 DOCX、PPTX 或 IDML，同事在熟悉的软件里继续工作；**改内容请回到 K2F 再导出**。那些文件是交付物，不是权威源。 |
| **原生幻灯片或白板写作** | **今天交付的是分页文档**（`canvas_mode: "paged"`）；原生幻灯片和无限画布还在路线图上。 |

---

## 2. `.K2F` 文件包

### `.K2F` 文件里有什么？

`.K2F` 文件是一个 **ZIP 包**。常见布局：

| 路径 | 作用 |
|------|------|
| `manifest.json` | 元数据：页面尺寸、边距、画布模式、引擎身份 |
| `content/root.json` | **State A** — 语义内容树（你编辑的东西） |
| `content/**/*.json` | 从根文件引入的可选片段 |
| `styles/theme.json` | 角色、色板、排版：外观，不含坐标 |
| `assets/fonts/`、`assets/images/`、`assets/data/` | 内嵌资源 |
| `/schema/` | 内嵌的 JSON Schema，用来校验 |
| `document.K2F.lock` | **State C** — 编译后的几何和绘制计划（`compile` 之后） |
| `changelog.json` | 可选的编辑历史 |
| `signatures/v1.json` | 可选的 Ed25519 签名 |

**解释、编译和渲染**这份文档所需的东西，都在包里，或由 manifest 绑定到版本上，而不是某个随意的 CDN 字体 URL。

### 为什么说这个包是「自包含」的？

- **字体**放在 `assets/fonts/` 里；规范渲染不依赖审阅者电脑上装了什么字体。
- **图片和数据**放在 `assets/` 里；agent 可以换数据集，而不破坏结构。
- **Schema** 随 ZIP 一起走，校验器和 agent 可以离线自检。
- 编译之后，**lock** 记下精确版面，查看器不必猜测字体或重新排文字。

你可以把一个 `.K2F` 文件用邮件发出去、提交到 Git，或交给 agent。对方拿到的是完整材料。

### 我能把 `.K2F` 交给同事或另一个 AI agent 吗？

**可以。** 这是一条主要工作流。

1. 对方 **unpack**（或用 SDK/Playground），拿到 `content/root.json` 和 `styles/theme.json`。
2. 对方按稳定的节点 `id` 改**含义**（文字、表格、结构），或调整 **theme** 做全局换肤。
3. 对方 **pack** 再 **compile**，刷新 `document.K2F.lock`。
4. 查看器和导出走新的 lock。

对方**不应该**手改 lock 文件，也不应该把导出的 DOCX 当成新的源（`DOCX_IS_NOT_A_SOURCE`）。

### 我编辑的东西，和查看器显示的东西，有什么差别？

- **State A（语义树）** — 可改的 JSON：标题、段落、表格、`form_field` 节点、角色、变体。内容层**没有物理坐标**。
- **State C（render lock）** — compile 的不可变输出：字形位置、盒子、绘制顺序、`content_hash`、`appearance_hash`。

内容或 theme 变了才 **compile**。在查看器里**打开**只是**执行** lock，不会重新排正文。JSON 上的修改，在重新编译之前，预览里看不到。

### 打开或校验文件需要联网吗？

工具装好之后不需要。CLI、Desktop Reader（预览构建在 [k2f.dev/download](https://k2f.dev/download)）和本地 WASM 都可以离线打开和导出。拉 Gallery 是可选的；模板可以存下来在本地反复用。

### 源文件是「就是 JSON」吗？能用 Git 吗？

可以。内容和 theme 都是 JSON。工具链使用**规范 JSON**（稳定的键顺序、一致的空白），diff 会突出语义变化。稳定的层级 id（例如 `invoice.header`、`financials.q3_results.table_revenue`）让代码审阅和 agent 补丁比二进制 DOCX 可读。

### 能用程序创建和编辑 K2F 文件吗？

**可以。** `.K2F` 文件是 **ZIP**。解开之后，写作面就是 `content/` 和 `styles/theme.json` 里的普通 **JSON**。任何语言都能读、创建或修补这些文件。

常见自动化路径：

- **CLI** — `k2f unpack`，改文件，`k2f pack`，`k2f compile`，`k2f export-*`
- **Python** — `pip install k2f`（pack、compile、verify、导出）
- **JavaScript/TypeScript** — `npm i @openk2f/k2f`（WASM 编译、嵌入查看器、导出）
- **Agents** — K2F skill 加上 `pack_verify.py` 循环

不需要图形界面。schema 形状和角色见[文档](https://k2f.dev/docs)，以及每个包里内嵌的 `/schema/`。

### 读一个 `.K2F` 文件需要 K2F 引擎吗？

**取决于你说的「读」是什么。**

| 目标 | 需要参考引擎吗？ |
|------|------------------|
| 读或改**语义 JSON**（内容 + theme） | **不需要** — 解开包；用 Git、脚本或任何 JSON 工具 |
| **预览**设计好的页面，或**导出** PDF/DOCX/PPTX/IDML | **需要** — 必要时 compile，然后跑 CLI、SDK、Desktop Reader 或 `<k2f-viewer>` |
| 在 K2F 查看器里按像素一致地绘制已有的 **`document.K2F.lock`** | **需要** — 查看器执行 lock；它们不会只靠 JSON 重新排版 |

格式是开放的；引擎是把 JSON 加 theme 变成版面和交付格式的受支持方式。

---

## 3. 确定性渲染

这一节说明我们说的「确定性」是什么，以及我们**不**指什么。

### 对 K2F 来说，「确定性渲染」是什么意思？

给定**同一份** `.K2F` 包（内容、theme、内嵌字体、manifest）和**同一个钉死的参考引擎版本**，**规范输出在任何地方都相同**：

- [Playground](https://k2f.dev/playground)
- Web Viewer（`<k2f-viewer>`）
- Desktop Reader
- 从 lock 绘制的默认 **PDF 导出**（交给客户的路径）

同一份文档，在每台设备、每个兼容 K2F 的应用上，像素相同。这是 **K2F 原生**查看和基于 lock 的 PDF 所追求的、类似 PDF 的一致性。

### K2F 如何在不同机器上处理字体和渲染？

**在 K2F 内部（查看器、lock PDF、Playground）：** 字体在包里的 `assets/fonts/`。规范渲染用这些内嵌文件，而不是「这台笔记本碰巧装了什么」。所以同一份 lock、同一条引擎线，K2F 预览在不同机器上是一致的。

**导出到 Word 或 PowerPoint：** DOCX 和 PPTX **不是**像 `.K2F` ZIP 那样自带整套字体的载体。默认的 Office 导出绘制 lock，但**不会像 K2F 那样嵌入完整字体集**。Word 和 PowerPoint 会替换字体或按度量匹配，于是**换行和间距可能移动**。这也是 Office 导出适合交接协作，而不是 K2F 查看器的像素级复制品的主要原因之一。

**导出 IDML：** 默认的 **IDML 包导出**带有 **`Document Fonts/`** 文件夹，里面是这次导出用到的字体，所以交给 InDesign 时更接近「字体跟文件走」。InDesign 仍有自己的排版引擎，**轻微重排仍然可能发生**。

需要最接近 K2F 所显示结果的审批和印刷路径时，用**从 lock 导出的 PDF**。

### 我打开文档时，K2F 查看器可以重新排版吗？

**不可以。** 查看器是 **lock 执行器**：它们绘制 `document.K2F.lock`。打开一个已经 lock 的包，你看到的是编译结果，不是浏览器各自重排你的 JSON。内容变了，就**重新编译**，产生新的 lock。

### 导出到 Word、PowerPoint、PDF 或 IDML 后，版面和 K2F 查看器完全一样吗？

**不保证，而且这是预期的。**

导出是把已发布的 lock **单向画进**别的格式。它们**不是**第二套规范渲染器：

| 导出 | 和 K2F 查看器的关系 |
|------|---------------------|
| **PDF**（来自 lock） | 最接近像素一致；主要的印刷/审批路径。可填写字段用 AcroForm，除非加 `--flatten`。 |
| **DOCX** | 可编辑的 Word 绘制；**在 Word 里出现轻微文字重排是预期且允许的**。不是 Word 自己的流式模型。 |
| **PPTX** | 和 DOCX 同一类：lock 几何映射进幻灯片；**可能轻微重排**。 |
| **IDML** | 用 InDesign 自己的引擎打开；默认包导出时字体放在导出文件夹里；**可能轻微重排**。 |

文件格式、字体度量和应用行为都不同，所以 **macOS 和 Windows 上的 Word**、**PowerPoint 的主题默认值**，或 **InDesign 版本**都可能改变间距、换行或替换字体。K2F **不**承诺导出的 Office 或 IDML 文件和 K2F 查看器像素一致。

**确定性渲染适用于 K2F 对 lock 的执行**，不是「K2F 进了 Word 之后，到哪里都永远和 K2F 长得一模一样」。

### 「确定性」是不是说，换 K2F 版本之后导出文件也不会变？

Lock 哈希和导出字节绑在**引擎版本**上（lock 上的 `engine_version`）。升级 CLI/SDK 可能需要重新编译。导出始终反映**编译当时发布的那份 lock**，不是你改了 JSON 但还没保存并重新编译的现场内容。

---

## 4. AI agents、skills 与编辑

### 为什么 PDF 和 DOCX 不适合当 AI agent 的*源*？

- **PDF** 把含义关在坐标和不透明的绘制指令里。可靠地抽出结构、安全地修改，都很难（`PDF_IS_NOT_A_SOURCE`）。
- **DOCX** 是一包复杂的 OOXML：样式、编号、关系和被拆开的文本 run。天真地「转成 Markdown 再转回去」会毁掉格式；整篇重新生成会弄坏表格和编号。业界把这叫做 AI 的 **Word last mile** 问题。

K2F 给 agent 的是一种**小的语义 JSON 方言**（角色、id、封闭的修饰类型），而不是让它去做 OOXML 手术。

### K2F 怎么减少「agent 把我的版面弄坏了」？

1. **内容 / 样式分离** — 节点带 `role` / `variant`；颜色和字号只活在 `theme.json` 里。节点上的内联样式是非法的，编译会失败。
2. **稳定 id** — 改 `invoice.details`，不用碰无关节点。
3. **版面归引擎** — Agent 描述东西*是什么*；引擎在编译时计算几何。
4. **用 lock 预览** — 所有人审阅同一份编译结果；K2F 查看器里没有 HTML/CSS 重排的意外。

换肤（「换成深色企业色板」）是改 **theme** 再编译，不是去挪坐标。

### K2F skill 是什么，怎么用？

**K2F skill** 是一套可安装的说明，加上脚本和示例（k2f 仓库里的 [`skills/core/k2f`](https://github.com/suzheng/k2f/tree/main/skills/core/k2f)）。安装：

```bash
npx skills add suzheng/k2f --skill k2f
```

然后这样说：

```text
Use the K2F skill to create a [describe what you want].
```

Skill 教 agent 编辑循环：工作区布局、`pack_verify.py`、目录示例、导出参考和错误码。**不需要**检出这整个 monorepo。

### 哪些 AI agent 能和 K2F 一起用？

任何能跑 shell、能用 **Agent Skills**（或能照着 skill 文件做），并且 PATH 上有 `k2f` 的 agent。文档里写过的包括 **Cursor**、**Claude Code**、**Codex**、**WorkBuddy**、**Manus**、**OpenClaw**、**MUSE**、**Hermes**、**Pi Agent**、**Grokbot**，以及同类工具。复制那一行提示即可；本地 skill 加 Gallery 的流程不需要 K2F 账号或 OAuth。

### 必须用 MCP 吗？

**不必。** MCP stdio（`k2f_mcp`）在某些环境里可选，用来列出或下载模板。没有 MCP 时，skill 会明确地从 `starter/` 或 Gallery 拉取继续。**远程 HTTP MCP 还没有发布**（路线图）。

### 新用户和 agent 最常犯哪些错？

| 错误 | 改法 |
|------|------|
| 设计好的页面下三分之一是空的 | 照 skill catalog 里填满的页面来；核对 PNG 预览，不要只看 `pack_verify` 的退出码 |
| 用 `____` 或 `□` 做表单 | 用 `form_field` 节点（`ex_form.json`）；导出 AcroForm PDF |
| 把 `color` / `font_size` 写在内容节点上 | 把样式挪到 `theme.json` 的角色里 |
| 手改 `document.K2F.lock` | 改树或 theme → pack → compile |
| 改了 JSON 却指望不编译预览也会更新 | 跑 pack/compile；查看器画的是 lock |
| 为 `modifiers` 手算 UTF-8 字节范围 | 用 skill 里的 `modifier_range.py` |

### Agent 能一次改掉整篇文档的样式吗？

可以。改 `styles/theme.json`（色板、角色定义、基元）再编译。语义结构还在，外观全局更新。这是**语义优先的换肤**，和在 Word 里全选文字再套一个样式不是一回事。

---

## 5. 导出与交付

### 可以导出哪些格式？

从**已编译**的 `.K2F`（已发布的 lock），参考引擎可以绘制成：

- **PDF** — 默认为 `form_field` 节点带**可填写的 AcroForm**；`--flatten` 则只有静态字形
- **DOCX** — Word
- **PPTX** — PowerPoint
- **IDML** — InDesign（默认带 `Document Fonts/` 的包目录）
- **Markdown** — 经 `k2f_to_markdown` / bridge API
- **图片** — CLI 和查看器里的光栅预览路径

见文档站上的[导出概览](https://k2f.dev/docs/guide/exporting)。

### 可填写 PDF 怎么做？

在内容树里用语义 **`form_field`** 节点定义空格和复选框。编译之后，默认 PDF 导出把 **AcroForm** 控件放在 lock 的位置上。查看器可以叠输入框，并通过 relock 流程保存。

**Word 和 PowerPoint 导出只是按 lock 画方框和文字，它们不是可交互的 Office 表单控件。** 要可填写的行为，请交付 PDF。

### 能把 Word、PowerPoint、PDF 或 IDML 导入 K2F 吗？

**不能。** 只有单向导出：

- `DOCX_IS_NOT_A_SOURCE`
- `PPTX_IS_NOT_A_SOURCE`
- `PDF_IS_NOT_A_SOURCE`
- `IDML_IS_NOT_A_SOURCE`

请通过 Markdown bridge、Gallery 模板、agent 写作或 SDK **写进** K2F，而不是把 Office 二进制当成权威源导入。

### 签名和完整性呢？

包可以在 lock 上带 `content_hash` 和 `appearance_hash`。`signatures/v1.json` 里可选的 **Ed25519** 签名支持完整性流程。查看器会报告 `SIGNED`、`UNSIGNED`、`BROKEN_INTEGRITY`、`ENGINE_MISMATCH` 等状态。**agent 生成的文件按设计常常是 `UNSIGNED`**。组织签名是另一步。

---

## 6. Gallery 与模板

### Gallery 免费吗？

免费。**没有账号、没有付费墙、没有水印、没有下载上限**。[k2f.dev/gallery](https://k2f.dev/gallery) 上的模板可以交给任何 agent，也可以在本地用。

### 每个模板我能拿到什么？

每个正式模板通常提供这些下载：

- **`.K2F`** — 可编辑的语义源
- **Word（DOCX）**
- **PowerPoint（PPTX）**
- **IDML**

一份设计，多种交接格式，不用维护四份互不相干的源文件。

### Agent 应该怎么用 Gallery 模板？

取模板包（Gallery API，或在可用时用 MCP 的 `download_template`），把 `.K2F` 存到磁盘，`k2f unpack` 到 `source/`，改 JSON，再编译。**不要**把整个 ZIP 塞进对话上下文。模板是**活的语义包**，不是预览用的 JPEG。

---

## 7. 生态与工具

### 我能把 K2F 嵌进自己的产品吗？

可以。用 npm 的 `@openk2f/k2f`、WASM 初始化，以及 `<k2f-viewer>` 做应用内预览；编译之后调用导出 API。格式和引擎是 Apache 2.0，可以嵌进 SaaS 报表生成器、合同流水线和教育平台。

## 8. 隐私、安全与数据处理

评估的人常问：*用 K2F 是不是要把文档发到你们的服务器？* *能在本地部署吗？* *机密内容和 AI agent 怎么办？* 这一节把**开放格式 + 本地引擎**、**可选的 k2f.dev 服务**，以及**你的 AI 供应商**分开说。

### 要用这个格式或引擎，必须把文档上传到 K2F 吗？

**不必。** `.K2F` 格式和参考引擎（`pip install k2f`、Desktop Reader、嵌在你自己应用里的 WASM）跑在**你的机器或你的基础设施上**。写作、编译、校验和导出都可以在**不**建 K2F 账号、也**不**把包字节发到 k2f.dev 的情况下完成。

只有当你**选择**一项托管功能时，字节才会发到 k2f.dev。例如在 Playground 里点 **Save & share** 或 **Publish**，或通过 HTTPS 下载一个公开的 Gallery 模板。

### 哪些在本地跑，哪些会碰到 k2f.dev？

| 活动 | 典型的数据走向 |
|------|----------------|
| 你笔记本上的 agent + skill + `k2f` CLI | 留在你的机器上（以及**你**配置的那些路径）。没有 K2F 账号。 |
| `k2f pack` / `compile` / `export-*` / `verify` | 只在本地。 |
| Desktop Reader 打开 / 导出 | 只在本地。 |
| 在**你的**产品里用本地字节嵌入 `<k2f-viewer>` | 你的托管环境；K2F WASM 在用户浏览器里跑。字节会不会进你的后端，由你决定。 |
| 在 k2f.dev 上浏览文档或 Gallery | 普通网页请求；Gallery **下载**的是公开模板字节（你不是在上传自己的文档）。 |
| Playground：丢入 `.K2F` 或编译 Markdown | 预览/编译走**浏览器内**的引擎路径；在你点分享/发布之前，文件不会上传。 |
| Playground：**Save & share** | **上传：** 完整 `.K2F` ZIP 在服务端保存 **24 小时** → 链接 `/p/{uuid}`。 |
| Playground 或 API：**Publish**（永久） | **上传：** 按 `appearance_hash` 存储 lock 过的包 → 公开的 `/v/{hash}`（公开站点上每个包最大 **8 MiB**）。 |
| 在**你自己的** K2F 站点上永久发布 | 如果你用数据库自托管这套站点，模型相同。来源由你控制。 |

如果你从不点分享/发布，也不用托管 API，就把 K2F 当成任何本地文件工具链。

### 我用 AI agent 加上 K2F skill，谁看得到我的内容？

这是两条不同的边界：

1. **K2F 工具** — skill 脚本和 `k2f` CLI 跑在**你**跑 agent 的地方（本地磁盘、你的 CI、你的虚拟机）。它们自己不会把语义 JSON 上传到 K2F，除非你调用了 k2f.dev 的分享/发布 API 或类似接口。
2. **LLM / agent 产品** — Cursor、Claude、ChatGPT、Codex 等会按**它们**的条款，把提示和文件上下文发到**它们**的云（或你的企业部署）。把合同正文放进 `content/root.json` 再让 agent 去改，意味着那段文字可能被**那个供应商**处理。机密材料请用你们组织批准的 agent 部署、脱敏策略，以及**只在本地**编译/导出。这和任何 AI 编程或写作工具是同一套判断。

K2F 不代替你对 AI 次级处理方的供应商审查；它给你的是 agent 写到磁盘之后的一份**本地、可审计的文件**。

### 如果 k2f.dev 变了或关掉，我会被锁住吗？

对格式本身来说，**不会**：

- 规范和 schema 是开放的；`.K2F` 文件留在你的磁盘和 Git 仓库里。
- 引擎源码在 GitHub 上；你可以自己构建，或钉住 SDK 版本。
- 导出（PDF、DOCX、PPTX、IDML）是你们组织已经在归档的标准交付格式。

托管的 Gallery、Playground 和 `/v/` 链接是**方便**；核心价值不依赖它们。

### 可以商业使用 K2F 吗？

可以。Apache 2.0 适用于格式和参考引擎：嵌进产品、在内部当服务跑、把生成的文档交给客户。请遵守包里第三方**字体许可**，以及 [k2f.dev](https://k2f.dev/trademark) 上关于在营销中使用 K2F 名称和标志的商标说明。

## 9. 版本控制与协作

### 为什么 K2F 在 Git 里比 DOCX 好？

Office 文件是不透明 XML 的二进制 ZIP。K2F 的源是 **JSON**，diff 有意义：你看到哪个 `id` 变了，而不是一堵十六进制。制度、报告和 agent 生成的文档，可以按代码审阅的习惯来管。

### 能只回滚一节，而不还原整个文件吗？

原则上可以：稳定的节点 id 和树结构让 agent 或人修补特定子树。可选的 `changelog.json` 记录编辑历史。用 includes 时，Git 历史可以还原 `content/` 上的提交，或单个片段文件。

## 10. 和其他格式、工具的比较

### 能把 PDF 转成 K2F 吗？

**不能。** `PDF_IS_NOT_A_SOURCE`。PDF 导出是把已发布的 lock **画出来**。把 PDF 当成只读渲染，不是权威的文档状态。

### K2F 是为原生幻灯片或白板写作做的吗？

**还不是。** 今天发布的表面是 **`canvas_mode: "paged"`** 文档。幻灯片模式和无限画布在路线图上。很多模板仍然**导出 PPTX**，这样演示文稿的交接留在你们团队已经在用的 PowerPoint 里。

## 12. 边界、路线图与信任

### 今天的 K2F 格式有多稳定？

磁盘上的契约是 **[format spec v0.3](https://k2f.dev/spec)**，随 PyPI、npm 和 crates.io 上的 **0.3.x** SDK 一起发布。在早期发布线上，**schema 和包的形状变化得很慢**。从更早的预览到 **v0.3** 是增量，不是重写。

**今天：**

- **补丁版 SDK**（0.3.1、0.3.2……）保持规范 **v0.3**，除非内嵌 schema 或 lock 格式必须打破兼容。
- **当前的 0.3.x 工具打算打开并使用受支持的 v0.3 线上产出的包**：unpack、compile、verify、查看和导出，而不是把每个文件都当成遗留格式。
- **`ENGINE_MISMATCH`** 表示读取器构建和 lock 上记录的编译器不同。这是来源信息，不是文件损坏。想让 lock 和当前引擎对齐时，重新编译。

更早的 **0.2.x 及以前** SDK 线**不再**提供安全支持；生产请用当前的 **0.3.x**。完整政策见 [Compatibility](https://k2f.dev/compatibility) 和 [Changelog](https://k2f.dev/changelog)。

### 今天已经发布了什么（如实的范围）？

- **Format spec v0.3**，CLI/SDK **0.3.x**，在 PyPI、npm、crates.io 上
- **`canvas_mode: "paged"`** 文档
- 导出：PDF（含 AcroForm）、DOCX、PPTX、IDML、Markdown、图片
- Web viewer、Playground、agent skill、**MCP stdio**
- Desktop Reader 安装包 — **预览**（未签名；操作系统信任流程在路线图上）

### 还没有发布什么？

| 项目 | 说明 |
|------|------|
| **幻灯片 / 无限画布模式** | 设计目标；不是 v0.1 |
| **远程 HTTP MCP** | 计划中；今天只有 stdio |
| **桌面代码签名 / 公证** | 安装包已有；信任流程在路线图上 |
| **把 DOCX/PDF/PPTX/IDML 当源导入** | 有意如此：单向导出 |

### 如果我看到 `ENGINE_MISMATCH` 或 `BROKEN_INTEGRITY` 怎么办？

用当前受支持的引擎重新编译，或用产生这份 lock 的引擎版本打开。不要手改 lock。见站点上的 [Integrity](https://k2f.dev/integrity)。

---