K2F — 常见问题

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

三层都有：

• 文件格式 — 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 流程，都不需要账号。

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

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

Agent 工作流的最低要求：

pip install k2f    # CLI + Python SDK on PATH

可选：

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

路径 A — Gallery： 打开 k2f.dev/gallery，下载一个 .K2F 模板（不用登录），在 Playground 里打开，或用 k2f unpack 解开。

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

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 以及你要求的导出文件。

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

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

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

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

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

你可以把一个 .K2F 文件用邮件发出去、提交到 Git，或交给 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）和本地 WASM 都可以离线打开和导出。拉 Gallery 是可选的；模板可以存下来在本地反复用。

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

可以。 .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 形状和角色见文档，以及每个包里内嵌的 /schema/。

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

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

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

• Playground
• Web Viewer（<k2f-viewer>）
• Desktop Reader
• 从 lock 绘制的默认 PDF 导出（交给客户的路径）

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

在 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。

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

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

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

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

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

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

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

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

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

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

K2F skill 是一套可安装的说明，加上脚本和示例（k2f 仓库里的 skills/core/k2f）。安装：

npx skills add suzheng/k2f --skill k2f

然后这样说：

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

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

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

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

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

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

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

见文档站上的导出概览。

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

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

不能。 只有单向导出：

• 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。组织签名是另一步。

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

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

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

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

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

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

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

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

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

这是两条不同的边界：

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 写到磁盘之后的一份本地、可审计的文件。

对格式本身来说，不会：

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

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

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

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

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

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

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

磁盘上的契约是 format spec v0.3，随 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 和 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 安装包 — 预览（未签名；操作系统信任流程在路线图上）

用当前受支持的引擎重新编译，或用产生这份 lock 的引擎版本打开。不要手改 lock。见站点上的 Integrity。