k2f

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

K2F

Create, design, edit elegant Word (docx), PDF, fillable AcroForm PDF, and Adobe InDesign (IDML) with K2F. K2F designed for agents to design and edit elegant documents precisely and effortlessly. Use with AI agents when you need aesthetic documents—menus, certificates, planners, invitations, worksheets, and more. You can start from Gallery templates.

.K2F

is a ZIP: you edit a semantic JSON tree (meaning, not coordinates); the engine

pack

compile

s an immutable render lock. One reference engine → pixel-identical output everywhere.

使用 K2F 创建、设计和编辑精美的 Word（docx）、PDF、可填写的 AcroForm PDF 以及 Adobe InDesign（IDML）文档。K2F 专为 Agent 打造，使其能够精准、轻松地设计和编辑精美文档。配合 AI Agent 使用，可制作菜单、证书、规划手册、邀请函、工作表等美观文档。你可以从 Gallery 模板开始。

一个

.K2F

是 ZIP：你编辑的是语义 JSON 树（表达含义，而不是坐标）；引擎通过

pack

compile

生成不可变的渲染锁。一个参考引擎 → 在任何地方都产生像素级一致的输出。

Choose the workflow

选择工作流

Read one reference file for the task. Do not load all workflows.

Task	Read
Create or update a `.K2F` (CV, flyer, slide deck, poster, report, patch by node id)	references/writing.md
Convert Markdown ↔ K2F	references/converting-markdown.md
Export PDF from the published lock	references/exporting-pdf.md — bytes / looks wrong: pdf-contract.md
Export PPTX from the published lock	references/exporting-pptx.md
Export DOCX from the published lock	references/exporting-docx.md
Export IDML from the published lock	references/exporting-idml.md
Publish permanent `/v/{appearance_hash}` link	references/publishing.md
Embed `<k2f-viewer>` in a web app	references/embedding-viewer.md ( `npm i @openk2f/k2f` )

Writing (default): one loop — get a workspace (

source/

author package + deliverables at the root), edit JSON like source code, copy shapes from

catalog/content/ex_*.json

into root

children

(do not replace

content/root.json

with a fragment), and

scripts/pack_verify.py

. The author directory is

k2f unpack … -o ./out/doc/source

(user

.K2F

or a Gallery package), or

starter/

via

scripts/init_package.py --workspace ./out/doc

when nothing matches.

Do not use
```
Editor.insert_node
```
on an unpacked author directory — that API follows a narrower agent dialect; JSON authoring uses the full format schema validated at pack time.
Text
```
modifiers
```
need
```
intent
```
plus UTF-8 byte
```
range
```
— always run
```
scripts/modifier_range.py
```
; never hand-count (especially across
```
\n
```
).
Fillable blanks/checkboxes: copy
```
catalog/content/ex_form.json
```
(never
```
____
```
or
```
□
```
).

Gallery URL (

<origin>/gallery/<slug>

) or package URL: fetch

<origin>/api/gallery/templates/<slug>

(or package URL) to a

.K2F

on disk and

k2f unpack

— do not load the ZIP into context. MCP is optional. Writing does not require it and does not install it. If a site MCP with

list_templates

download_template

is already connected,

download_template

returns the same kind of

packageUrl

; fetch + unpack as in step 2 of writing.md. Missing tools, kind mismatch, or download failure → continue from

starter/

; do not stop the task.

针对任务，只阅读一个参考文件。不要加载所有工作流。

任务	阅读
创建或更新 `.K2F` （CV、传单、幻灯片、海报、报告；按节点 id 修补）	references/writing.md
转换 Markdown ↔ K2F	references/converting-markdown.md
从已发布的 lock 导出 PDF	references/exporting-pdf.md — 字节/外观异常：pdf-contract.md
从已发布的 lock 导出 PPTX	references/exporting-pptx.md
从已发布的 lock 导出 DOCX	references/exporting-docx.md
从已发布的 lock 导出 IDML	references/exporting-idml.md
发布永久 `/v/{appearance_hash}` 链接	references/publishing.md
在 Web 应用中嵌入 `<k2f-viewer>`	references/embedding-viewer.md（ `npm i @openk2f/k2f` ）

编写（默认）：一个循环——获取工作区（

source/

作者包，交付物位于根目录），像修改源代码一样编辑 JSON，将

catalog/content/ex_*.json

中的图元复制到根级

children

中（不要用片段替换

content/root.json

），然后运行

scripts/pack_verify.py

。作者目录的获取方式为

k2f unpack … -o ./out/doc/source

（来自用户的

.K2F

或 Gallery 包）；如果没有任何匹配项，则通过

starter/

和

scripts/init_package.py --workspace ./out/doc

获取。

不要在解包后的作者目录上使用
```
Editor.insert_node
```
——该 API 采用范围更窄的 Agent 方言；JSON 编写使用完整格式 Schema，并在打包时进行验证。
文本
```
modifiers
```
需要
```
intent
```
和 UTF-8 字节
```
range
```
——务必运行
```
scripts/modifier_range.py
```
；切勿手动计数（跨
```
\n
```
时尤其如此）。
可填写的空白项/复选框：复制
```
catalog/content/ex_form.json
```
（绝不要使用
```
____
```
或
```
□
```
）。

Gallery URL（

<origin>/gallery/<slug>

）或包 URL：将

<origin>/api/gallery/templates/<slug>

（或包 URL）下载为磁盘上的

.K2F

，然后执行

k2f unpack

——不要将 ZIP 加载到上下文中。MCP 是可选的。编写流程不需要 MCP，也不会安装它。如果站点 MCP 已连接并提供

list_templates

download_template

，则

download_template

会返回同类

packageUrl

；按照 writing.md 的步骤 2 下载并解包。如果工具缺失、kind 不匹配或下载失败 → 改从

starter/

继续；不要中止任务。

What K2F is

K2F 是什么

PDF is unreadable and uneditable for AI. HTML/CSS renders differently on every device. K2F fixes both: agents write plain JSON meaning, and one reference engine turns that meaning into pixel-identical output everywhere.

Instead of positioning content with coordinates:

{"text": "WARNING!", "x": 100, "y": 50, "color": "red", "bold": true}

K2F authors describe meaning:

{"id": "doc.warning", "role": "warning", "content": {"type": "text", "value": "WARNING!"}}

Every

.K2F

file is a ZIP holding two states:

State A — semantic tree (
```
content/root.json
```
, mutable, the file you edit). Every node has a stable dotted
```
id
```
, a
```
role
```
, an optional
```
variant
```
, and optional
```
modifiers
```
(inline emphasis/link/math on a byte range). No coordinates, no colors, no font sizes — those live only in
```
styles/theme.json
```
, keyed by role/variant.
State C — render lock (
```
document.K2F.lock
```
, immutable, generated). Exact geometry, paint operations, and integrity hashes. Every viewer and every PDF export paints this, not the tree.

The engine — not the agent — turns A into C by running

pack

compile

. Other package paths:

manifest.json

(page size, margins),

assets/fonts|images|data/*

changelog.json

(edit history), optional

signatures/v1.json

When handing a

.K2F

to the user, point them to k2f.dev/playground (browser) or k2f.dev/download (desktop app).

PDF 对 AI 而言难以阅读和编辑。HTML/CSS 在不同设备上的渲染结果各不相同。K2F 解决了这两个问题：Agent 使用普通 JSON 表达语义，由一个参考引擎将其转换为在任何设备上都像素级一致的输出。

你不再需要通过坐标来定位内容：

{"text": "WARNING!", "x": 100, "y": 50, "color": "red", "bold": true}

K2F 作者通过以下方式描述含义：

{"id": "doc.warning", "role": "warning", "content": {"type": "text", "value": "WARNING!"}}

每个

.K2F

文件都是一个 ZIP，包含两种状态：

状态 A — 语义树（
```
content/root.json
```
，可变，即你要编辑的文件）。每个节点都有稳定的点分
```
id
```
、
```
role
```
、可选的
```
variant
```
，以及可选的
```
modifiers
```
（应用于字节范围的内联强调、链接和数学内容）。没有坐标、颜色或字号——这些只存在于
```
styles/theme.json
```
中，并以
```
role
```
/
```
variant
```
为键。
状态 C — 渲染锁（
```
document.K2F.lock
```
，不可变，由系统生成）。包含精确几何数据、绘制操作和完整性哈希值。每个查看器和每次 PDF 导出都渲染此状态，而不是语义树。

引擎（而非 Agent）通过运行

pack

compile

将状态 A 转换为状态 C。包内其他路径包括：

manifest.json

（页面尺寸、页边距）、

assets/fonts|images|data/*

、

changelog.json

（编辑历史）以及可选的

signatures/v1.json

。

将

.K2F

交给用户时，请引导他们使用 k2f.dev/playground（浏览器）或 k2f.dev/download（桌面应用）。

Setup

设置

You have this skill folder only — no K2F source checkout, no

templates/

tree.

Install published tools before running workflows:

bash

pip install k2f              # CLI on PATH + Python SDK — no need to install Cargo
npm i @openk2f/k2f           # only when embedding <k2f-viewer> in a web app

你只有这个 skill 目录——没有 K2F 源码检出副本，也没有

templates/

目录树。

运行工作流前，安装已发布的工具：

bash

pip install k2f              # CLI on PATH + Python SDK — no need to install Cargo
npm i @openk2f/k2f           # only when embedding <k2f-viewer> in a web app

cargo install k2f # optional: CLI without Python


Run scripts from this skill directory (or pass absolute paths to them). Core scripts (`init_package.py`, `pack_verify.py`, `modifier_range.py`) are **stdlib-only** — `python scripts/…`. Optional `compare_images.py` needs `uv run` ([visual check](references/writing.md#reference-image-overlay-optional)). The author directory may live anywhere. `pack_verify.py` needs `k2f` on PATH (`pip install k2f`) or `K2F_CLI` — it does not walk a git checkout or build directory for a binary.


从此 skill 目录运行脚本（或传入其绝对路径）。核心脚本（`init_package.py`、`pack_verify.py`、`modifier_range.py`）**仅依赖标准库**——`python scripts/…`。可选的 `compare_images.py` 需要使用 `uv run`（[视觉检查](references/writing.md#reference-image-overlay-optional)）。作者目录可以位于任意位置。`pack_verify.py` 要求 `k2f` 位于 PATH 中（`pip install k2f`），或设置 `K2F_CLI`——它不会在 git checkout 或构建目录中查找二进制文件。

Core rules

核心规则

Empty paper in the lower third of a designed sheet is the most common visual failure.

pack_verify.py

exit 0 /

pages=1

does not mean filled — open the PNG. Fix: copy

ex_filled_page.json

as a root child (

height

= content box; leftover on

{fr:1}

table/notes/figure). Short letter and the last page of a growing document may stay short.

source/
edits are invisible until compile. Viewers paint

document.K2F.lock

, not author JSON. After content/theme edits, run

pack_verify.py

, then

tmp/preview.png

or reload the

.K2F

Style lives only in
theme.json
, never on a node. Putting a style field on a node is the single most common compile failure.
Never hand-edit
document.K2F.lock
. Mutate the tree (or theme), then
```
pack_verify.py
```
(relock).
PDF, PPTX, DOCX, and IDML are one-way drawings of the lock, not a second source. (
```
PDF_IS_NOT_A_SOURCE
```
,
```
PPTX_IS_NOT_A_SOURCE
```
,
```
DOCX_IS_NOT_A_SOURCE
```
,
```
IDML_IS_NOT_A_SOURCE
```
)
Signing is a separate human/org step. Agent output is
```
UNSIGNED
```
by design.
Validate after every edit. Fix from error codes in writing/errors.md; do not patch the lock.
Look at the pixels — empty bottom first. After pack, open every rendered page (
```
--render
```
writes
```
preview-1.png
```
…). If the lower third is blank paper on a designed sheet, you are not done. Designed sheet (invoice, CV, flyer, poster, slide, card, social, one-page infographic/checklist/planner — even if titled report) → copy
```
ex_filled_page.json
```
as a root child (pinned
```
height
```
+
```
{fr:1}
```
grower); a
```
page_shell
```
role on a hug stack is not the shell. Treat
```
PAGE_UNDERFILL
```
as must-fix even when
```
pack_verify.py
```
exits 0 (skipped if the content box is shorter than 180pt). Short letter may stay top-packed. Growing document (contract, long report, thesis, paper) → one flow tree; last page may be short; no
```
p1
```
/
```
p2
```
page wrappers and no page-height shell around the whole doc.
```
break_before: page
```
is fine on a chapter, annex, signature page, slide 2+, or card back. Details: writing.md.

设计版面的纸张下三分之一出现空白，是最常见的视觉缺陷。

pack_verify.py

退出码为 0 /

pages=1

并不意味着页面内容充实——请打开 PNG。修复方法：将

ex_filled_page.json

复制为根子节点（

height

= 内容框；剩余空间通过

{fr:1}

表格/注释/图示承接）。简短信函以及增长型文档的最后一页可以保持较短。

在编译前，
source/
中的编辑不可见。查看器渲染的是

document.K2F.lock

，而不是作者 JSON。完成内容和主题编辑后，运行

pack_verify.py

，然后查看

tmp/preview.png

或重新加载

.K2F

。

样式只能位于
theme.json
中，绝不能放在节点上。将样式字段放在节点上是最常见的编译失败原因。
切勿手动编辑
document.K2F.lock
。修改语义树（或主题），然后运行
```
pack_verify.py
```
（重新锁定）。
PDF、PPTX、DOCX 和 IDML 都是 lock 的单向渲染产物，而不是第二数据源。（
```
PDF_IS_NOT_A_SOURCE
```
、
```
PPTX_IS_NOT_A_SOURCE
```
、
```
DOCX_IS_NOT_A_SOURCE
```
、
```
IDML_IS_NOT_A_SOURCE
```
）
签名是单独的人工/组织流程。 按设计，Agent 输出为
```
UNSIGNED
```
。
每次编辑后都要验证。 根据 writing/errors.md 中的错误代码进行修复；不要修补 lock。
查看像素——先检查底部空白。 打包后，打开每个渲染页面（
```
--render
```
会写入
```
preview-1.png
```
等文件）。如果设计版面的纸张下三分之一为空白，则任务尚未完成。设计版面（发票、CV、传单、海报、幻灯片、卡片、社交媒体内容、单页信息图/清单/规划手册——即使标题为报告）→ 将
```
ex_filled_page.json
```
复制为根子节点（固定
```
height
```
+
```
{fr:1}
```
扩展器）；hug 堆栈上的
```
page_shell
```
role 并不是页面外壳。即使
```
pack_verify.py
```
退出码为 0，也必须将
```
PAGE_UNDERFILL
```
视为必须修复的问题（如果内容框高度不足 180pt，则跳过）。简短信函可以保持顶部紧凑排布。增长型文档（合同、长篇报告、论文）→ 使用一个流式树；最后一页可以较短；不要使用
```
p1
```
/
```
p2
```
页面包装器，也不要在整个文档外使用页面高度外壳。
```
break_before: page
```
可用于章节、附录、签名页、第 2 张及之后的幻灯片或卡片背面。详情：writing.md。

Content and design

内容和设计

Before editing

content/

styles/theme.json

, write content and design as Markdown inside the author directory. Long content does not go in one file. Split the same way as

content/*.json

. Name each file with a slug: lowercase ASCII

kebab-case

from that page or section’s topic (e.g.

executive-summary

title-slide

). A short single page may be one

content_and_design.md

. One page per file →

content_and_design_<slug>.md

(e.g.

content_and_design_agenda.md

for a slide). Section aligned with a JSON fragment →

content_and_design_<slug>.md

beside

content/<slug>.json

using the same slug. Then

python scripts/init_package.py --workspace ./out/doc …

(creates

source/

tmp/

; a notes-only

source/

that already holds these files can still be initialized in place).

Workspace layout:

./out/doc/
  doc.K2F                 # deliverable
  doc.pdf                 # optional exports, same stem
  source/                 # author package (edit this)
    content_and_design_executive-summary.md
    manifest.json
    content/
      root.json
      executive-summary.json   # optional fragment; same slug as its .md
    styles/ assets/ changelog.json
  tmp/                    # preview.png and other debug renders

Each file covers that page or section only, and includes both:

Content — every word, and every image (what it shows, width×height; a full generation prompt when the image must be made). Need figures → generate them
Design — type hierarchy, spacing, color, and layout

Shared type, color, and spacing for the whole document go in the first file. Later files state their own words and images, which shared set they use, and anything that differs.

User gave constraints — follow them.
User did not specify — highest aesthetic standard for the deliverable type (report, poster, slide deck, flyer, …). Do not ship the starter theme unchanged for styled work.

After the files are settled: look up allowed keys in writing/fields.md then

schema/

, implement

theme.json

content/

, run

pack_verify.py --render

, open the PNG, and iterate until the output matches these files. Rule 6 is the final gate — the files are the plan, render is the review.

在编辑

content/

或

styles/theme.json

之前，先在作者目录中将内容和设计写成 Markdown。长内容不能放在一个文件中。应按照

content/*.json

的相同方式拆分。每个文件使用 slug 命名：采用根据页面或章节主题生成的小写 ASCII kebab-case 名称（例如

executive-summary

、

title-slide

）。简短的单页内容可以放在一个

content_and_design.md

中。如果每页一个文件 → 使用

content_and_design_<slug>.md

（例如幻灯片使用

content_and_design_agenda.md

）。与某个 JSON 片段对应的章节 → 在

content/<slug>.json

旁使用相同的 slug 创建

content_and_design_<slug>.md

。然后运行

python scripts/init_package.py --workspace ./out/doc …

（创建

source/

和

tmp/

；仅含说明文档且已包含这些文件的

source/

仍可原地初始化）。

工作区布局：

./out/doc/
  doc.K2F                 # deliverable
  doc.pdf                 # optional exports, same stem
  source/                 # author package (edit this)
    content_and_design_executive-summary.md
    manifest.json
    content/
      root.json
      executive-summary.json   # optional fragment; same slug as its .md
    styles/ assets/ changelog.json
  tmp/                    # preview.png and other debug renders

每个文件仅涵盖对应页面或章节，并同时包括：

内容——每一个字和每一张图片（展示内容、宽×高；如果图片需要生成，则提供完整的生成提示词）。需要图示 → 生成图示
设计——字体层级、间距、颜色和布局

整份文档共享的字体、颜色和间距放在第一个文件中。后续文件说明自己的文字和图片、使用哪组共享设置，以及有何不同。

用户给定了约束——遵守这些约束。
用户未指定——按交付物类型采用最高美学标准（报告、海报、幻灯片、传单等）。对于需要视觉设计的工作，不要原样使用 starter 主题交付。

文件定稿后：先在 writing/fields.md 中查阅允许的键，再打开

schema/

中对应的 Schema 文件，实现

theme.json

content/

，运行

pack_verify.py --render

，打开 PNG 并迭代，直到输出与这些文件一致。规则 6 是最终关卡——文件是方案，渲染结果是审查对象。

Schema

Read-only format JSON Schemas live in

schema/

(same bytes the engine embeds). Do not copy them into an author directory —

k2f pack

injects schemas into the ZIP; hand-authored

schema/

files →

UNEXPECTED_PATH

Allowed keys: skim writing/fields.md, then open only the schema file you are editing —

content/

→

schema/nodes.schema.json

;

styles/theme.json

→

schema/styles.schema.json

schema/visual_primitives.schema.json

;

manifest.json

→

schema/manifest.schema.json

First draft shapes: copy from
```
catalog/content/ex_*.json
```
into root
```
children
```
— golden, packable examples. See
```
catalog/README.md
```
for a construct index.
SCHEMA_INVALID
: compare the failing object to the schema file. Key in schema but rejected → stale CLI (
```
pip install -U k2f
```
). Key not in schema → remove it; do not invent fields from HTML/CSS memory.

Version check:

k2f schema dump -o /tmp/k2f-schema

python -c "import k2f; print(k2f.format_schemas().keys())"

只读格式 JSON Schema 位于

schema/

（与引擎内嵌的字节完全一致）。不要将其复制到作者目录——

k2f pack

会把 Schema 注入 ZIP；手动编写的

schema/

文件 →

UNEXPECTED_PATH

。

允许的键： 浏览 writing/fields.md，然后只打开正在编辑的 Schema 文件——

content/

→

schema/nodes.schema.json

；

styles/theme.json

→

schema/styles.schema.json

schema/visual_primitives.schema.json

；

manifest.json

→

schema/manifest.schema.json

。

初稿图元： 从
```
catalog/content/ex_*.json
```
复制到根级
```
children
```
——这些都是标准且可打包的示例。构造索引请参阅
```
catalog/README.md
```
。
SCHEMA_INVALID
：将失败的对象与 Schema 文件进行对比。Schema 中存在但被拒绝的键 → CLI 版本过旧（
```
pip install -U k2f
```
）。Schema 中不存在的键 → 删除；不要凭 HTML/CSS 经验臆造字段。

版本检查：

k2f schema dump -o /tmp/k2f-schema

或

python -c "import k2f; print(k2f.format_schemas().keys())"

。

Bundled packages

内置包

Path	Purpose
`schema/`	Read-only format JSON Schemas — lookup after writing/fields.md; never copy into author dirs
`starter/`	Empty tree + core theme + Roboto — copied into `source/` when there is no existing `.K2F` and no matching Gallery package
`catalog/`	Golden shape dictionary — copy `ex_*.json` nodes into the author dir; not a deliverable (index)

路径	用途
`schema/`	只读格式 JSON Schema——查阅 writing/fields.md 之后使用；切勿复制到作者目录
`starter/`	空树 + 核心主题 + Roboto——当没有现有 `.K2F` 且没有匹配的 Gallery 包时复制到 `source/`
`catalog/`	标准图元库——将 `ex_*.json` 节点复制到作者目录；它不是交付物（索引）