# 为什么选择 K2F

机器可编辑的文档。人类可信赖的页面。

PDF 在任何地方看起来都一样，但 AI 智能体无法可靠地修改它。HTML 很容易被软件重写，但页面无法保持稳定。Markdown 是有语义却没有页面。Word 和 PowerPoint 是人类可编辑的文件，机器继承到的却是一团混乱。K2F 之所以存在，是因为 AI 时代需要同时满足这两边——而现有格式都不是为此设计的。

## 必须同时成立的事

当智能体编写合同、发票或报告时，有两件事必须同时成立。现有格式各自只能满足其中一件。

- **机器必须编辑语义。** 修改条款、合计金额或表格行——依据身份标识，而不是猜测像素或重绘页面。
- **人类必须信任页面。** 同一个文件必须在每个官方阅读器、每台设备、每次打开时都渲染出相同布局。就像 PDF 一样。

## 为什么现有格式行不通

### PDF——同样的页面。封闭的盒子。

PDF 是一串绘制指令：把这个字形放在这里，把那条线画在那里。这种一致性正是它的意义所在——也是陷阱。智能体无法安全地修改“第 4 条”。你可以对 PDF 做 OCR。但你不能把它当作允许模型重写的文档。

### HTML——可编辑。但无法保持稳定。

HTML 和 CSS 很容易被软件读写。它们也被设计为可重排：每个浏览器、窗口尺寸和样式表都可能移动文本。一份在不同机器之间会变形的合同，不是你能签署的合同。确定性从来不是它们的职责。

### Markdown——有语义。无页面。

Markdown 是智能体已经喜爱的格式。它几乎没有布局。同一个文件在 GitHub、预览窗格和导出的 PDF 中看起来都不一样。你可以存储意图。但仅靠 Markdown 无法交付经过设计的页面。

### Office——人类编辑。机器猜测。

Word 和 PowerPoint 存储的 XML 由专有应用进行布局。智能体得到的是一个脆弱的树结构，没有稳定的“这个段落”身份标识，而且两台电脑可能渲染出不同的像素。布局存在于应用程序中，而不是文件中。

## 让语义与像素分离

你无法在不放弃 PDF 本质——一幅绘制图——的情况下“让 PDF 可编辑”。你也无法在不放弃重排的情况下“让 HTML 像素级一致”。因此 K2F 是一种新格式，只有一条规则：语义存在于一处，像素存在于另一处，而固定版本引擎是唯一的桥梁。

> **语义意图。确定性几何。**
>
> 智能体编辑文档的语义。由引擎而非作者决定它在页面上的位置。

内容 + 主题（可编辑源）→ 固定版本引擎（编译一次）→ 渲染锁（处处相同像素）

### 语义树（`content/root.json`）

由标题、表格、警告和正文组成的 JSON 树。每个节点都有一个稳定 id，例如 invoice.total 或 contract.clause_4。智能体修补这些 id。它们不绘制 PDF，也不手动放置 x/y 坐标。

### 主题（`styles/theme.json`）

外观通过名称指定，而不是内联指定。节点声明 role：“warning”，而不是“把这个变成 13px 红色”。样式不能泄漏到内容树中。改变文档外观意味着更改主题，而不是重写文字。

### 渲染锁（`document.K2F.lock`）

版本固定的引擎将内容 + 主题 + 字体编译为精确几何和绘制顺序。打开文件时会按此渲染锁绘制。它不会重新布局。字体随包携带。规范输出不得依赖查看者的操作系统。

一个 .K2F 文件就是一个 ZIP。语义树、主题和渲染锁都位于同一个包中：

```
document.k2f
├── manifest.json          # 元数据
├── content/root.json      # 语义内容树
├── styles/theme.json      # 主题样式
└── document.K2F.lock      # 渲染锁（编译后生成）
```

## 这会带来什么变化

### 对智能体而言

像编辑函数一样编辑条款——按名称进行。差异是语义 JSON，而不是截图噪声。回滚针对的是节点，而不是被压平的页面。schema 有意保持精简，这样模型不必学习一门排版语言。

### 对人类而言

打开文件，页面就已经确定。官方阅读器会报告渲染锁是否仍与语义树、主题、字体和引擎匹配。如果有人未重新编译就篡改内容，横幅会给出提示。导出为 PDF、PowerPoint 或 Word 只是对该渲染锁的绘制——源文件仍然是 K2F。

## 我们不会妥协的原则

1. **语义优先**——智能体编辑语义树，绝不编辑像素或任意绘制命令。
2. **确定性渲染**——相同的包、主题、字体和固定版本引擎必须生成相同的规范页面。无声漂移是缺陷，而不是“浏览器差异”。
3. **语义与外观保持分离**——角色和变体控制外观。内容树中禁止使用一次性内联样式。
4. **最小、稳定的核心**——新的外观应放在主题和具名原语中。格式本身保持精简，以便长久存在。
5. **文件是完整的**——字体、主题、资源和引擎标识随包携带。规范输出不得依赖查看者的机器。

## K2F 不是什么

这些不是缺失的功能。它们是让语义与像素保持分离所付出的代价。

- **PDF 不是源文件。** PDF 是成品页面的绘制结果。导入 PDF 等于把像素伪装成语义。导出是单向的：该格式拒绝将 PDF 作为源文件。
- **官方查看器不会重排正文。** 重排正是 HTML 失去像素确定性的原因。打开已锁定文件时只会按渲染锁绘制，不会再次排版。
- **源文件中没有拖拽放置编辑器。** 布局由约束编译而来。鼠标坐标不属于语义树——幻灯片正是这样把语义困在布局里的。
- **幻灯片和无限画布不在 v0.1 中。** 它们是设计目标，尚未发布。v0.1 是分页文档。

## 接下来阅读

- [对比](/compare) — 与 PDF、Markdown、HTML 和 Word 的坦诚取舍。
- [格式规范](/spec) — 公开的 v0.1 契约：容器、语义树、渲染锁、签名。
- [编写](/docs/authoring/text) — 段落、图片、表格、布局和字体——你实际编写的 JSON。
- [实验场](/playground) — 编译文档并观察渲染锁如何绘制。