k2f

K2F

使用 K2F 创建、设计和编辑精美的 Word（docx）、PDF、可填写的 AcroForm PDF 和 Adobe InDesign（IDML）文档。K2F 专为 Agent 设计，让它们能够精准、轻松地设计和编辑精美文档。需要制作美观文档（如菜单、证书、计划表、邀请函、练习册等）时，可与 AI Agent 搭配使用。你可以从 Gallery 模板开始。

.K2F 是一个 ZIP 文件：你编辑语义 JSON 树（含义，而非坐标）；引擎会 pack / compile 出不可变的渲染锁文件。使用一个参考引擎，即可在任何地方获得像素级一致的输出。

选择工作流

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

任务	阅读
创建或更新 .K2F（简历、传单、幻灯片、海报、报告、按节点 ID 打补丁）	references/writing.md
转换 Markdown ↔ K2F	references/converting-markdown.md
从已发布的锁文件导出 PDF	references/exporting-pdf.md — 字节 / 外观不正确：pdf-contract.md
从已发布的锁文件导出 PPTX	references/exporting-pptx.md
从已发布的锁文件导出 DOCX	references/exporting-docx.md
从已发布的锁文件导出 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 编写使用完整格式架构，并在打包时验证。
• 文本 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 是可选的。编写不需要它，也不会安装它。如果已连接具备 list_templates / download_template 的站点 MCP，download_template 会返回同类的 packageUrl；按 writing.md 第 2 步所述获取并解包。工具缺失、类型不匹配或下载失败时 → 从 starter/ 继续；不要停止任务。

K2F 是什么

PDF 对 AI 来说无法读取和编辑。HTML/CSS 在不同设备上的呈现效果各不相同。K2F 解决了这两个问题：Agent 用普通 JSON 描述 含义，再由一个参考引擎将其转换为在任何地方都像素级一致的输出。

K2F 作者不再用坐标定位内容：

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

而是描述含义：

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

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

• 状态 A — 语义树（content/root.json，可变，即你编辑的文件）。每个节点都有稳定的点分隔 id、一个 role、一个可选的 variant，以及可选的 modifiers（在字节范围内添加行内强调、链接或数学公式）。没有坐标、颜色或字号——这些只存在于按角色/变体索引的 styles/theme.json 中。
• 状态 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（桌面应用）。

设置

你只有此技能文件夹——没有 K2F 源代码检出目录，也没有 templates/ 目录树。

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

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

请从此技能目录运行脚本（或向脚本传入绝对路径）。核心脚本（init_package.py、pack_verify.py、modifier_range.py）仅依赖标准库——使用 python scripts/… 运行。可选的 compare_images.py 需要 uv run（视觉检查）。作者目录可以位于任意位置。pack_verify.py 需要 PATH 中有 k2f（pip install k2f）或设置 K2F_CLI——它不会在 git 检出目录或构建目录中查找二进制文件。

核心规则

设计页面的下三分之一留白，是最常见的视觉问题。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。

1. 样式只能放在 theme.json 中，绝不能放在节点上。 将样式字段放在节点上，是最常见的编译失败原因。
2. 切勿手动编辑 document.K2F.lock。 修改树（或主题），然后运行 pack_verify.py（重新锁定）。
3. PDF、PPTX、DOCX 和 IDML 都是对锁定文件的单向绘制结果，不是第二个源文件。（PDF_IS_NOT_A_SOURCE、PPTX_IS_NOT_A_SOURCE、DOCX_IS_NOT_A_SOURCE、IDML_IS_NOT_A_SOURCE）
4. 签署是单独由人工/组织完成的步骤。 Agent 输出按设计为 UNSIGNED。
5. 每次编辑后都要验证。 根据 writing/errors.md 中的错误代码修复；不要修补锁定文件。
6. 检查像素——先看底部是否留白。 打包后，打开每个渲染页面（--render 会写出 preview-1.png …）。如果设计页面的下三分之一是空白，那就还没完成。设计页面（发票、简历、传单、海报、幻灯片、卡片、社交媒体内容、单页信息图/清单/规划表——即使标题是报告也一样）→ 将 ex_filled_page.json 复制为根节点的子节点（固定 height + {fr:1} 填充项）；hug 堆栈上的 page_shell 角色并不算页面外壳。即使 pack_verify.py 退出码为 0，也必须修复 PAGE_UNDERFILL（内容框短于 180pt 时会跳过）。短函件可以保持内容靠上排列。不断扩展的文档（合同、长篇报告、论文、学术论文）→ 使用一个流式树；最后一页可以较短；不要使用 p1/p2 页面包装节点，也不要在整个文档外套上页面高度外壳。章节、附录、签名页、第 2 页及之后的幻灯片，或卡片背面可以使用 break_before: page。详情：writing.md。

内容与设计

编辑 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 旁创建 content_and_design_<slug>.md，使用相同的 slug。然后运行 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

每个文件只涵盖对应的页面或章节，并同时包含：

• 内容——所有文字和所有图片（图片展示的内容、宽×高；需要生成图片时，提供完整的生成提示词）。需要插图？→ 生成插图
• 设计——字体层级、间距、颜色和布局

整个文档共用的字体、颜色和间距设定写在第一个文件中。后续文件说明各自的文字和图片、使用哪套共用设定，以及有哪些不同之处。

• 用户提供了约束——遵循这些约束。
• 用户未作指定——采用该交付物类型（报告、海报、幻灯片、传单等）的最高审美标准。需要设计样式时，不要原样交付入门主题。

文件定稿后：在 writing/fields.md 和 schema/ 中查找允许使用的键，然后实现 theme.json + content/，运行 pack_verify.py --render，打开 PNG，并反复调整，直到输出与这些文件一致。规则 6 是最终关卡——这些文件是计划，渲染结果是审核对象。

Schema

只读格式 JSON Schema 位于 schema/ 中（与引擎内嵌的字节完全一致）。不要将它们复制到作者目录——k2f pack 会将 schema 注入 ZIP；手动创建 schema/ 文件会导致 UNEXPECTED_PATH。

1. **允许使用的键：**先浏览 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。
2. **首稿结构：**将 catalog/content/ex_*.json 中的内容复制到根目录的 children 中——这些是经过验证、可打包的示例。构造索引见 catalog/README.md。
3. SCHEMA_INVALID：将失败对象与 schema 文件进行对比。键存在于 schema 中却被拒绝 → CLI 版本过旧（pip install -U k2f）。键不存在于 schema 中 → 删除它；不要凭 HTML/CSS 经验臆造字段。
4. **版本检查：**运行 k2f schema dump -o /tmp/k2f-schema 或 python -c "import k2f; print(k2f.format_schemas().keys())"。

随附软件包

路径	用途
schema/	只读格式 JSON Schema——参照 writing/fields.md 查找；切勿复制到作者目录
starter/	空树 + 核心主题 + Roboto——当不存在现有 .K2F 且没有匹配的 Gallery 软件包时，复制到 source/ 中
catalog/	标准结构字典——将 ex_*.json 节点复制到作者目录；不是交付物（索引）