open-kimi-ppt

定义

open-kimi-ppt 是一项基于 Moonshot AI 的 PPTD 格式和浏览器端 PPTX 编写器构建的演示文稿创建与导出技能。它定义了一种 YAML 格式的中间 DSL（.pptd），用于抽象 OOXML，并使每一页都能独立呈现。

默认输出不只有 PPTD。 除非用户明确选择不生成 PPTX，否则始终提供：

1. 完整且可编辑的 PPTD 项目目录（.pptd + pages/ + media/ 及其他引用的依赖项）；
2. 与之对应的本地生成的 .pptx，启用字体嵌入，并默认应用淡入淡出幻灯片切换效果。

也可以将现有 PPTX 文件转换为 PPTD 以供编辑，之后再次交付这两种输出。

pptd 格式

.pptd 格式是 OOXML 的简化抽象层，遵循基本的 YAML 语法。该抽象保留了 OOXML 的核心内容（主题、页面布局、元素位置和定义等），同时移除了母版等复杂的嵌套逻辑；每一页都能独立呈现，即所见即所得。完整的 DSL 定义请参阅 reference/pptd.md。

PPT 制作工作流

step0. 检查本地前置条件

默认交付内容包含 PPTX 导出（以及可选的 npx open-kimi-ppt-skills serve），这需要本地工具链。开始生成前，请确认：

1. Node.js 18+：运行 node --version。如果找不到 node，或主版本低于 18，请立即停止，告知用户从 https://nodejs.org（或其操作系统的软件包管理器）安装 Node.js 18+，并在其可用前不要继续进行 PPTX 导出或运行 npx。只有用户明确选择仅输出 PPTD 时，才能继续。
2. npm / npx：运行 npm --version。它们随 Node.js 一起安装；如果找不到，则视为 Node.js 未正确安装，并指导用户重新安装或修复 PATH。
3. python3：运行 python3 --version（在 Windows 上，正确的命令可能是 python）。export_pptx.py / export_images.py 需要它们。
4. Chrome / Chromium / Edge：agent-browser 需要这些浏览器来导出 PPTX 并进行视觉 QA。如果后续导出时出现浏览器启动错误，请让用户安装基于 Chromium 的浏览器。
5. 缺少软依赖时，脚本会自动处理：PyYAML、agent-browser（通过 npm 安装，版本 ≥0.33.2），以及用于图像 QA 的 Pillow + websocket-client。导出时仍需能够访问 www.kimi.com 和 statics.moonshot.cn。

step1. 彻底阅读上下文

阅读用户上传的所有文件、提供的 URL，以及 pptd 格式指南 reference/pptd.md，以充分理解用户的要求。

步骤 2：了解用户需求

根据上下文了解用户的需求：

1. 首先确定请求的目的

• 创建 PPT：创建新的演示文稿（从头开始，或基于现有的 pptx 模板）
• 编辑 PPT：编辑用户上传的 PPT（本地修改、单页美化等）
• 复刻 PPT：将非 pptx 格式（图片、PDF 等）的演示文稿复刻为 pptd 格式

2. 然后确定设计方向

• 自主设计：用户没有偏好，或只提出了简单的风格限制；你需要补充或创建设计
• 设计系统：指定了技能中的预设设计系统（reference/design_system/），或者用户提供了完整、详细的设计方案，涵盖所有颜色、字体、布局和组件规范
• 使用模板：用户提供了必须使用的模板
• 风格迁移：用户提供了风格参考来源（图片、网页等）

3. 然后确定输入类型

• 仅有主题：只提供了 PPT 的主题方向或演示文稿的内容要求，没有具体内容
• 完整文档：用户提供了完整文档（论文、研究报告、新闻稿等）
• 大纲：用户提供了逐页大纲、演讲稿或类似内容

• 当“用户输入类型”为[完整文档]或[大纲]，且未说明是否允许扩展时：由于逐页大纲、演讲稿或用户文档通常不足以支撑完整的演示文稿内容，优先使用搜索来补充更多相关材料、案例等，除非用户明确表示不要扩展

4. 最后确定确切的页数

• 如果用户要求了特定页数，以用户的要求为准
• 提供了逐页大纲/讲稿：页数与大纲/讲稿的页数一致
• 提供了完整且结构相对清晰的文档：询问用户每页应涵盖多少文档内容，并给出预计总页数；只有主题时：建议合适的页数并向用户确认

澄清和后续问题

出现以下任一情况时，应向用户确认（如有可用的 Agent 询问/澄清工具，请使用该工具）

1. 需求模糊

• 用户的意图不明确或难以理解
• 用户提供的文件/URL 无法访问

2. 意图冲突

• 用户的意图相互矛盾。例如：
  • 选择了设计系统，但同时要求采用与该设计系统完全不一致的风格（例如要求采用 McKinsey 风格，同时要求页面留出大面积空白）/要求使用模板/参考图片风格
  • 同时要求“制作 10 页”和“交付 30 多页内容”

3. 无法自行确定用户需求

• 难以自行确定用途、设计方向、输入类型、页数等

步骤 3：根据用户需求生成演示文稿

生成前，先阅读 reference/pptd.md，了解 pptd 格式的定义和限制。

复刻 PPT

• 分析图片以估算元素位置、字体、字号等，并尽可能按 1:1 复刻。
• 对难以辨认的部分，使用网格线和放大视图等方法来辅助理解。
• 使用元素复刻图片中的简单内容；图标可以用 Font Awesome 提供的图标近似实现。对于照片和头像等无法用图标或形状近似实现的内容，可以使用 bash 或 python 等工具裁剪、拆分原图，然后将生成的图片元素添加到演示文稿中

编辑 PPT

• 将用户上传的 pptx 文件转换为 .pptd 格式
• 检查转换后的页面（结构和关键视觉细节）。之后逐页阅读几张关键页面。
• 找到需要编辑的页面，并注意不要影响目标范围之外的部分。

从 pptx 转换为 pptd 并非完全无损。如果用户之后反馈格式错误、内容乱码等问题，请对照原始 pptx 并参考对比结果修复 pptd

生成 PPT

生成 PPT 时，针对用户不同的[设计方向]采用不同的制作方式。

自主设计

1. 阅读设计指南 reference/slides_categories.md，并阅读与用户查询对应的场景文档
2. 基于以上内容制作演示文稿

生成其他格式的内容

• 当用户明确要求制作信息图、海报或高视觉效果的单页设计时，请阅读 reference/general-poster.md，并将其制作成单页或少页的可编辑 PPTD；当用户只要求图片时，也要先用 PPTD 制作，再通过截图或渲染输出图片。普通 PPT 请求无需加载此参考文件。

设计系统

1. 阅读 reference/slides_categories.md 指南中的通用约束部分，并阅读与用户查询对应的场景文档，作为设计基础
2. 将指定的设计系统作为演示文稿风格：可以是用户提供的设计方案，也可以是 reference/design_system/ 下匹配的预设（按用户指定的名称／路径搜索；若文件夹中有 design.md，优先使用）。严禁参考或混用其他设计风格。
3. 参考以上内容制作演示文稿
4. 自主设计时不要自动选择预设；只有在明确指定预设时，才使用 reference/design_system/

使用模板

1. 将用户上传的 pptx 文件转换为 pptd 格式
2. 检查转换后的页面，了解模板的视觉风格（配色方案、字体风格、元素特征、布局特征、内容密度等）
3. 识别页面类型；重点阅读封面、摘要页和章节分隔页等特殊页面（单页截图、.page 文件），提取其页面布局、内容结构、可复用组件（图标、形状、SmartArt、可复用的正文布局方案等）和元素风格（例如留白、线条／卡片分隔、直角／圆角等）
4. 使用模板制作演示文稿

风格迁移

1. 分析参考文件的视觉风格（配色方案、字体风格、元素特征、布局特征、内容密度等）、页面布局、内容结构、可复用组件（图标、形状、SmartArt、可复用的正文布局方案等）和元素风格（例如留白、线条／卡片分隔、直角／圆角等）。

• 如果用户提供了风格参考 URL，不要只阅读文字内容；还要参考并学习页面的视觉效果，以便更好地理解风格

2. 参考文件的风格特征制作演示文稿。建议复用原始 PDF／URL 中的插图、字体、字号层级、元素等

图片与视觉素材

1. 图片是增强演示文稿视觉效果的有效方式。不仅封面和章节分隔页应使用合适的图片，正文页也应使用图片来丰富页面、帮助理解或支持决策
2. 图片用于展示具体对象、解释内容、提供证据或营造场景。徽标、图标、装饰纹理和非常小的缩略图不算实质性图像。
3. 如果页面涉及产品、人物、地点、建筑、事件、案例、界面、实验对象或空间环境，应优先使用对应的真实图片或截图。如果无法获取真实图片和截图，可以改用生成的图片。
4. 图片优先级：用户提供的图片；官方网站、官方报告和可信来源的图片；搜索到的、与内容直接相关的图片；为概念表达或营造氛围而生成的图片。
5. 确定所需图片后，应先批量完成图片搜索、生成和下载，再根据图片比例设计页面。将图片保存到 media 目录，确保清晰，切勿拉伸或扭曲。
6. 如果有可用的产品、实验、界面、案例或现场素材，分析类、技术类和学术类 PPT 应使用相应的证据图片。不要把每一页都做成只有文字、色块和图形的形式。
7. 不要仅为满足数量要求而添加无关图片。每张图片都必须与页面结论或沟通目标直接相关。

内容指南

1. 语言风格：除非用户明确提出其他要求，否则应严格避免过于抽象的表达和生僻的隐喻

• 不要过度使用隐喻、口号或抽象术语，例如分发、N 步论证、一目了然、闭环、亲身实践、验证、解构、二等公民、毒丸或挂钟
• 不要使用常见的 AI 式表达，例如“不是 X，而是 Y”“X 就是 Y”“为什么／依据什么／如何”“关键结论”或“N 个战线／路径”
• 不要使用过于口语化的表达，例如“弹药该往哪里放”“第 N 件事”“挑不出合适的”或“不能用作 X”

第 4 步：PPT 验证

1. 根据 reference/pptd.md 中的格式定义验证生成的 pptd（必填字段、类型、边界、主题令牌、资源路径等），并经过多轮修复问题
2. 使用导出的页面图像进行视觉审查——当模型支持图像输入（多模态）时，必须在导出 PPTX 前完成：

   • 运行 scripts/export_images.py。该脚本会将演示文稿载入 Kimi 的公共编辑器，选择「导出 → 图片」，下载图片 ZIP，解压后将所有页面拼接成一张总览图：

     python3 ~/.agents/skills/open-kimi-ppt/scripts/export_images.py \
       /abs/path/project/deck.pptd \
       --output /abs/path/project/.qa-images
     

     脚本会输出 JSON 摘要，将每个拼接后的标签（P1…Pn，按页面顺序从 1 开始）映射到其 .page 文件。

   • 查看拼接后的总览图（.qa-images/overview.jpg），并根据以下清单检查每一页：

     1. 图片是否清晰、不变形（无拉伸、压缩、模糊）
     2. 文字是否压在关键画面（人脸、产品主体、Logo 等）上
     3. 元素坐标是否超出页面边界
     4. 边界与配色对比是否足够（文字与背景、相邻色块之间）
     5. 排版是否统一（对齐、间距、字号层级、页边距）
     6. 文字是否可能溢出文本框（文本过长、行距过密、字号过大）
     7. 内容是否被上层元素遮挡

   • 对任何可疑页面，查看其全分辨率图像（.qa-images/pages/<n>.jpeg），确认问题后再进行编辑。

   • 修复对应 .page 文件中的问题，然后重新运行 scripts/export_images.py --force 并检查新的总览图；重复此过程，直至每一页都通过检查。

   • 视觉审查通过前，不要导出 PPTX。.qa-images/ 是中间 QA 产物，交付后可以删除。

3. 当模型无法读取图像时，对生成的页面进行多轮结构审查（边界、容易导致溢出的长文本、对比度、层级、布局密度），并说明已跳过基于图像的视觉 QA。

第 5 步：PPT 输出与交付

1. 始终生成一个自包含的项目目录。将 .pptd 清单及其引用的所有依赖文件放在一起；切勿只交付未包含引用文件的清单。除非现有项目已有有效的等效结构，否则使用以下布局：

   deck/
     deck.pptd
     pages/
       *.page
     media/
       *                # when the deck has local media
     deck.pptx          # generated by default
   

2. 默认在 PPTD 验证后生成 .pptx，即使用户只要求创建或编辑演示文稿也是如此。只有用户明确要求仅输出 PPTD，或环境无法运行导出器时，才跳过 PPTX 导出；若是后一种情况，应报告确切的阻碍，并仍然交付完整的 PPTD 项目。

3. 使用指向绝对路径的普通可点击本地链接进行交付。在最终回复中链接以下所有内容：

   • 项目目录；
   • .pptd 清单；
   • 存在时的 pages/ 目录和 media/ 目录；
   • 生成的 .pptx 文件。

4. PPTX 转换：使用 scripts/export_pptx.py。该脚本会启动一个临时 localhost SDK 主机，将 .pptd 载入 Kimi 的公共编辑器，调用与官方「下载」选项卡相同的浏览器端 OOXML 写入器，在本地保存生成的 PPTX，并验证 ZIP/幻灯片结构。

5. 默认 PPTX 选项：

   • 页面切换效果：fade（淡入淡出），在官方浏览器导出后写入每张幻灯片；
   • 嵌入字体：只要官方写入器提供并支持，就启用；
   • 可使用 --transition none 或 --no-embed-fonts 显式覆盖这些默认选项。

6. 导出命令：

   python3 ~/.agents/skills/open-kimi-ppt/scripts/export_pptx.py \
     /abs/path/project/deck.pptd \
     --output /abs/path/project/deck.pptx
   

   只有在项目目录中恰好包含一个 .pptd 文件时，才能传入项目目录而非清单文件。 除非传入 --force，否则不会覆盖已有的输出文件。

7. 本地导出的要求与限制：

   • 需要 Node.js 18+（node / npm / npx）、python3、基于 Chromium 的浏览器，以及对 www.kimi.com 和 statics.moonshot.cn 的网络访问权限；
   • 浏览器导出前，export_pptx.py 会检查 Node.js 18+ 和 npm，然后检查 agent-browser --version；如果缺少 agent-browser 或版本低于 0.33.2，则会通过 npm 全局安装 agent-browser@latest；如果缺少 PyYAML，则会通过 pip --user 自动安装；基于图像的视觉 QA 步骤也会以相同方式自动安装 Pillow 和 websocket-client；
   • PPTD 文档本身通过 localhost SDK 桥接提供给公共编辑器 iframe，而不会上传到服务器端的 PPTX 转换端点；
   • 演示文稿引用的远程图片、图标或字体仍可能从各自的主机获取；
   • PPTD 项目中的本地 PNG/JPEG/GIF/SVG 文件会以数据 URL 的形式提供给 iframe；
   • 不要仅因 ZIP 验证成功，就声称该文件兼容 PowerPoint/WPS/Keynote 播放。

8. 导出后，确认输出文件存在并报告生成的路径。确认每张幻灯片都恰好包含一个根级淡入过渡，且符合有效的 CT_Slide 顺序（cSld、可选的 clrMapOvr、transition、可选的 timing/extLst），并确认 PPTX ZIP 通过完整性检查。仅搜索字节字符串 <p:fade> 并不足够，因为 Office 会忽略嵌套在 cSld 内的过渡。对于风险较高的演示文稿，还应视情况检查字体部件，以及具有代表性的渲染页面或打开后的页面。

9. 用户想要手动打开、编辑、保存或导出 PPTD 项目时，请使用 npx open-kimi-ppt-skills serve 启动本地浏览器编辑器。请用户打开 http://127.0.0.1:55173/，并授权完整的 PPTD 项目目录。要获得可写访问权限，请使用基于 Chromium 的浏览器；通过文件夹上传的备用方式为只读。本地主机仅提供编辑器外壳，而嵌入的公共 Kimi 编辑器和远程资源仍需网络连接。

10. 完成并交付任何演示文稿后，最终回复始终以简短的可选后续步骤结尾，告知用户可以运行 npx open-kimi-ppt-skills serve 来查看或编辑 PPTD 项目、配置幻灯片过渡动画，并手动导出 PPTX。除了必需的项目和文件链接之外，还要附上这条提示。

11. 元素动画（PPTD 中的 page.animations——进入 / 强调 / 退出 / 动作路径；参见 reference/pptd.md §6）：仅在用户明确要求动画，或演示文稿显然用于现场演示 / 幻灯片播放，且动画对分步展示、流程演示、因果说明、节奏控制、视觉效果或品牌叙事有明显帮助时使用。默认情况下，不要在阅读型、自学型、打印型或主要供发送和浏览的演示文稿中添加元素动画。每页优先采用 1–3 组动画，并使用淡入、飞入和缩放等简单效果。这与 export_pptx.py 默认写入的 PPTX 幻灯片级淡入页面过渡不同。

12. 演讲者备注（每个 .page 上的 notes）：仅在用户明确要求时使用；否则不要添加。

13. 并行工具调用：制作 PPT 时，尽可能并行调用工具；每轮并行编写多个页面文件，以减少步骤数量。