open-kimi-ppt 技术分享：可编辑演示文稿的 Agent 工作流

资料快照：2026 年 8 月 6 日。
分析对象：GGquanta/open-kimi-ppt。

图 0：根据本文主题生成的封面图，采用与项目示例相近的深色产品发布会视觉风格。

一、先给结论

open-kimi-ppt-skill 是一个非官方的 Kimi Slides 兼容 Skill。它把演示文稿生成拆成四个可以复用、检查和迭代的环节：

1. 用 SKILL.md 把演示文稿生产流程写成智能体可执行的操作规程；
2. 用基于 YAML 的 PPTD 作为中间表示，保存主题、页面、元素位置和媒体引用；
3. 用本地浏览器编辑器承载预览、人工修改和自动保存；
4. 通过浏览器侧的演示文稿引擎导出可编辑的 PPTX，并在导出前执行视觉检查。

它的核心意义不在于“让模型一次生成一份漂亮幻灯片”，而在于把一次性生成结果变成一个可追踪、可修改、可验证、可继续交接的演示文稿工程产物。最终交付通常同时包含：

• 可继续编辑的 PPTD 项目目录；
• 可在 PowerPoint、WPS 等办公软件中继续处理的 PPTX 成品；
• 可选的页面图片和总览图，用于导出前视觉质检。

这套路线适合需要持续迭代和多人协作的技术汇报、产品介绍、培训课件、研究综述与方案宣讲。它不适合直接替代高度保密、完全离线、强依赖 PowerPoint 专有能力的生产系统。

二、项目概览与资料口径

2.1 项目定位

项目 README 将自身定位为“逆向 Kimi Slides 实现的非官方演示文稿 Skill”。它通过分析公开的 PPTD 格式、网页编辑器行为和通信协议，提供一个适配 AI Coding Agent 的本地宿主。

项目当前具备以下特征：

• 开源许可证为 MIT；
• 运行时要求 Node.js 18 或更高版本；
• CLI 包名为 open-kimi-ppt-skills；
• 支持的智能体包括 Codex、Claude Code、Cursor、WorkBuddy 等兼容 SKILL.md 规范的工具；
• 仓库同时包含 Skill 文档、PPTD 参考规范、导出脚本、本地编辑器、示例项目和自动化测试；
• GitHub 仓库页面在本资料快照时显示约 673 个 Star、192 个 Fork。该数据只能说明项目获得了一定关注，不等于生产可用性或长期维护承诺。

2.2 仓库结构

从工程职责看，仓库可以分成六层：

• skills/open-kimi-ppt/SKILL.md：面向智能体的任务触发条件、工作流、输出约定和验收清单；
• skills/open-kimi-ppt/reference/：PPTD、字体、形状、海报及不同演示场景的参考规范；
• skills/open-kimi-ppt/scripts/：页面图片导出、PPTX 导出和格式校验脚本；
• editor/ 与 lib/：本地浏览器编辑器、文件系统桥接和本地静态服务器；
• bin/open-kimi-ppt-skills.js：安装 Skill、启动编辑器和打开浏览器的 CLI；
• example/ 与测试目录：可运行的示例 PPTD 项目，以及服务器、路径安全、安装和导出逻辑测试。

图 1：项目 README 中的本地编辑器示例。原图见 docs/images/editor-overview.png。

2.3 必须保留的判断

它不是 Kimi 或 Moonshot AI 的官方 SDK，也不是一个稳定的企业级演示文稿转换 API。项目依赖公开网页编辑器的前端资源和兼容协议，未来可能因为上游页面、资源哈希、RPC 协议或 PPTD 行为变化而失效。

因此，采用时应把它视为：

• 一个可研究、可复用的 Agent 演示文稿生产工作流；
• 一个以 PPTD 为核心的本地编辑和导出工具链；
• 一个需要自行验证上游兼容性、数据边界和办公软件兼容性的开源项目。

三、核心意义：从“一次生成”转向“可维护产物”

3.1 把 PPTD 作为中间表示

传统的自动化 PPT 路线通常有三种：

• 直接调用 pptxgenjs 或 OOXML 接口拼接元素；
• 将整页渲染为图片后嵌入 PPTX；
• 生成 HTML 页面，用浏览器作为演示载体。

这些方案分别面临 API 细节多、编辑能力弱或办公软件兼容性不足的问题。open-kimi-ppt 选择在智能体和 PPTX 之间增加一层 PPTD：

需求、资料、参考图
        ↓
Agent 按 SKILL.md 生成内容与版式
        ↓
PPTD v2：清单 + 页面 + 媒体
        ↓
本地编辑器预览、修改、自动保存
        ↓
浏览器侧演示文稿引擎导出 PPTX
        ↓
页面图片质检 + 办公软件复核

PPTD 的价值是让中间结果具备明确结构。页面不再是模型“想象出来的画面”，而是由文本框、形状、图片、表格、图表等元素组成的可读文件。

3.2 把内容、版式和渲染引擎分离

PPTD 项目将职责分开：

• .pptd 负责全局尺寸、主题和页面顺序；
• .page 负责单页背景、备注和元素；
• media/ 负责图片等媒体资源；
• SKILL.md 负责智能体生产策略；
• 浏览器编辑器负责预览和人工调整；
• 导出脚本负责调用渲染引擎并验证结果。

这种拆分让团队可以只替换某一层。例如，内容团队修改 .page 文本，设计人员调整主题色和字号，工程人员维护导出脚本，而不必把整份 PPT 重新生成一遍。

3.3 把人工审美判断接入自动化链路

项目没有把“生成成功”直接等同于“交付成功”。SKILL.md 要求在导出 PPTX 前进行视觉检查，重点关注：

• 图片是否清晰、是否被拉伸；
• 文本是否压住人脸、产品主体或 Logo；
• 元素是否越过页面边界；
• 文字与背景的对比度是否足够；
• 页面之间的对齐、间距和字号层级是否一致；
• 文本是否溢出或被上层元素遮挡。

这说明项目的设计假设是：智能体负责加速生产，人仍然负责内容真实性、视觉取舍和最终验收。

3.4 在本地文件控制与远程引擎之间取平衡

本地宿主只在 127.0.0.1 启动静态服务器，PPTD 项目由用户主动选择文件夹后读取。编辑器通过 iframe 连接公开的 Kimi neo-ppt 页面，再通过 RPC 接收 PPTD 内容、返回保存请求和提供图片数据。

这个设计减少了本地部署完整演示文稿引擎的成本，同时保留了本地项目目录的控制权。但它并不等同于完全离线：

• 编辑器页面来自 www.kimi.com；
• 部分前端资源来自 statics.moonshot.cn；
• 导出和视觉质检需要网络、浏览器和 agent-browser；
• 远程图片、图标或字体仍可能从各自的外部域名加载。

因此，数据敏感性评估必须先于工具选型。

3.5 把 Skill 变成演示文稿生产 SOP

SKILL.md 并不是一段普通提示词。它规定了：

• 什么时候触发演示文稿工作流；
• 需要先读取哪些资料；
• 如何判断是新建、编辑还是复刻；
• 如何确定设计方向、输入类型和页数；
• 什么时候读取 PPTD 规范；
• 如何执行结构校验和视觉质检；
• PPTD 和 PPTX 如何交付；
• 导出失败时需要报告哪些边界条件。

这类 Skill 的价值在于把个人经验写成可重复的机器流程。团队成员换人、模型更换或任务切换后，仍然可以沿用同一套生产约定。

四、技术架构拆解

4.1 Skill 层：规定智能体应该怎么做

项目的 Skill 层主要承担“流程编排”职责。它要求智能体按以下顺序工作：

1. 读取用户上传的文件、链接和 PPTD 规范；
2. 判断任务属于创建、编辑还是复刻；
3. 判断输入是主题、完整文档还是逐页大纲；
4. 确定设计方向和页数；
5. 生成 PPTD 项目；
6. 校验结构和资源路径；
7. 导出页面图片进行视觉质检；
8. 修复问题后再导出 PPTX；
9. 同时交付 PPTD 项目目录与 PPTX 成品。

其中，“默认同时交付 PPTD 和 PPTX”是项目最重要的产品约定。只有用户明确要求 PPTD-only 时，才跳过 PPTX。

4.2 PPTD 层：用 YAML 描述演示文稿

PPTD v2 的主清单至少包括：

• version: v2；
• title；
• size；
• 可选的 theme；
• pages 页面相对路径列表。

典型项目结构如下：

deck/
  deck.pptd
  pages/
    01-cover.page
    02-content.page
  media/
    hero.jpg
  deck.pptx

页面文件包含：

• pageType：封面、目录、章节、正文或结尾等类别标签；
• background：页面背景；
• notes：演讲者备注；
• elements：页面元素数组。

规范定义的元素类型包括：

• text：文本框；
• shape：形状；
• line：线条；
• image：图片；
• icon：图标；
• table：表格；
• chart：图表。

PPTD 的几个关键约束是：

• 坐标单位为像素，原点在左上角；
• 推荐的 16:9 页面尺寸为 [960, 540]；
• 元素边界使用 [x, y, width, height]；
• elements 数组越靠后的元素层级越高；
• 页面和图片只能使用项目目录内的相对路径，不能越过项目根目录；
• 主题中的颜色、文本样式和表格样式可通过 $token 复用；
• 图片可以引用远程 URL，但正式交付更适合将资源放入 media/，以降低外部链接失效风险。

它的简洁性来自“页面自包含”：每个 .page 文件拥有自己的背景和元素，不需要理解 PowerPoint Master 等复杂继承关系。代价是大型项目需要自行维护主题一致性和组件复用约定。

4.3 本地编辑器层：文件夹授权与自动保存

本地编辑器的工作方式是：

1. CLI 在 127.0.0.1:55173 启动静态资源服务；
2. 浏览器加载本地编辑器壳；
3. 用户选择包含 .pptd、pages/ 和 media/ 的完整项目文件夹；
4. 编辑器扫描文件夹并查找 .pptd 清单；
5. 根据 pages 列表读取 .page 文件；
6. 将页面内容和图片传给远程 neo-ppt iframe；
7. 编辑器返回变更后，宿主自动写回 .pptd 和 .page 文件。

在支持 File System Access API 的 Chromium 浏览器中，编辑器可以获得文件夹读写权限并自动保存。其他浏览器会退化为文件夹上传的只读模式。

编辑器的安全边界包括：

• 只允许访问规范化后的相对路径；
• 拒绝绝对路径和包含 .. 的越界路径；
• 写入操作只允许修改 .pptd 和 .page；
• 不允许通过保存回调直接修改 media/ 等其他文件；
• 单个文本文件和图片存在大小限制；
• 多文件保存失败时会尝试按照备份回滚。

4.4 导出层：浏览器侧生成 PPTX

export_pptx.py 的实际链路不是本地 Python 直接编写 OOXML，而是：

1. 读取 .pptd，校验版本、页面列表和页面元素；
2. 检查页面路径是否越过项目目录；
3. 将本地图片转换成 data: URL，传给临时本地宿主；
4. 启动 agent-browser 和临时 HTTP 服务；
5. 打开公开 Kimi 演示文稿编辑器；
6. 调用编辑器的导出面板生成 PPTX；
7. 按默认配置处理字体嵌入和淡入淡出切换；
8. 修改 PPTX 内每个 ppt/slides/slide*.xml 的根级切换节点；
9. 校验 ZIP 完整性、幻灯片数量、切换动画位置和字体部件。

项目默认将单张本地图片限制为 20 MiB，本地图片总负载限制为 200 MiB。导出脚本还要求 agent-browser 版本不低于 0.33.2；版本过低时会尝试通过 npm 安装最新版。

4.5 视觉质检层：把导出图片变成验收输入

export_images.py 会调用同一个浏览器编辑器导出页面图片，将图片解压到输出目录，并按页码拼接总览图。总览图适合快速发现：

• 某一页的整体风格偏离；
• 页面密度突然升高；
• 标题、图片或图表被截断；
• 页码、边距和元素对齐不一致。

疑似问题页面还应回看单页原图，再修改对应的 .page 文件。项目的推荐顺序是“导出图片 → 检查 → 修复 → 重新导出”，而不是先下载 PPTX 再让办公软件暴露问题。

图 2：项目示例中的导出面板。原图见 docs/images/export-pptx.png。

五、面向哪些用户

5.1 AI Coding Agent 使用者

适合已经在 Cursor、Codex、Claude Code 或 WorkBuddy 中使用 Agent 的用户。用户不需要直接掌握 OOXML，可以通过自然语言描述主题、受众、页数和视觉方向，由智能体生成 PPTD。

这类用户最看重：

• 生成结果是否能继续修改；
• 是否能保留图片、文本和形状的独立编辑能力；
• 是否可以把一次成功的提示词、主题和目录结构复用到下一份 PPT；
• 是否能让智能体根据视觉质检结果进行定点修复。

5.2 技术方案、产品和咨询团队

技术方案、产品发布、售前汇报和咨询交付经常经历“内容变更—版式调整—领导审阅—再次导出”的循环。PPTD 将每页拆成文件后，适合进行版本管理和分工：

• 业务人员维护事实、数据和口径；
• 设计人员维护主题、字号和视觉层级；
• 工程人员维护媒体、导出和检查脚本；
• 负责人使用本地编辑器进行最终审阅。

5.3 教学、科普和研究团队

课程章节、实验步骤、论文综述和技术路线都具有明显的结构化特征，适合用 pageType、主题样式和逐页文件组织。对这些场景而言，“能够在 PPT 中继续改字和替换图片”通常比“生成一张不可拆分的海报”更有价值。

5.4 Skill 和工具链维护者

对于希望研究 Agent Skills、PPTD 或浏览器自动化的人，这个仓库提供了一个完整的小型样本：

• 如何编写触发条件和交付约定；
• 如何设计面向模型的中间格式；
• 如何做本地文件系统桥接；
• 如何通过浏览器自动化调用远程编辑器；
• 如何在生成后做结构校验和视觉验收；
• 如何用测试覆盖路径安全、安装逻辑和导出补丁。

5.5 不适合直接采用的用户

以下场景应谨慎或暂不采用：

• 处理未完成脱敏的商业秘密、个人信息或内部敏感材料；
• 必须在无外网、内网隔离或国产化闭环环境中运行；
• 依赖宏、复杂 SmartArt、专有动画、嵌套母版或 PowerPoint 特有交互；
• 需要把 PPTX 转换成 PPTD 的稳定批量 API；
• 需要长期锁定渲染结果并接受严格的办公软件像素级一致性；
• 需要无浏览器、无 GUI、可横向扩展的服务端批量生成。

六、安装与第一次运行

6.1 前置条件

使用 README 中的标准流程，至少需要：

• Node.js 18 或更高版本；
• Python 3；
• npm；
• Chromium 系浏览器；
• 可访问 www.kimi.com 和 statics.moonshot.cn 的网络；
• 导出时可用的 agent-browser；
• Python 包 PyYAML；
• 图片导出脚本使用的 websocket-client；
• 视觉质检时可用的 Pillow。

6.2 安装 Skill

推荐安装到跨 Agent 共享目录：

npx open-kimi-ppt-skills install

只有在当前智能体无法识别 ~/.agents/skills 时，才安装到专用目录。例如 Cursor：

npx open-kimi-ppt-skills install --target ~/.cursor/skills

两种安装路径应当二选一，不要在多个目录重复安装同一 Skill。更新时使用：

npx open-kimi-ppt-skills@latest install --force

团队正式使用时，建议记录 npm 包版本和 Skill 安装路径，不要在发布前临时追踪 latest。该项目依赖逆向协议，版本变动可能同时改变提示词、参考规范和导出行为。

6.3 启动本地编辑器

npx open-kimi-ppt-skills serve

默认访问地址为：

http://127.0.0.1:55173/

也可以启动后自动打开浏览器，或指定其他端口：

npx open-kimi-ppt-skills serve --open
npx open-kimi-ppt-skills serve --port 56000

打开编辑器后，应选择完整的 PPTD 项目文件夹，而不是只选择一个 .pptd 文件。项目目录至少应包含：

deck/
  deck.pptd
  pages/
  media/

6.4 最小提示词模板

仅给出一个主题，模型仍然可以生成 PPT，但页面数量、信息密度和视觉风格会有较大不确定性。建议至少提供以下信息：

使用 open-kimi-ppt 制作一份演示文稿。

主题：量子测风雷达在风电场功率预测中的应用
受众：能源企业技术负责人
目标：说明技术原理、系统架构、数据链路和落地价值
页数：8 页
内容来源：使用项目内的技术方案 Markdown，不虚构实验数据
风格：深色科技风，强调数据链路和工程架构，避免大面积渐变
素材：优先使用项目内 images/ 目录中的图片，远程素材必须注明来源
硬约束：文本、形状、图表保持可编辑；不要将整页渲染成一张图片
交付：PPTD 项目目录、PPTX 成品、视觉质检总览图

提示词的关键不是堆砌审美形容词，而是同时约束：

• 讲给谁听；
• 这份 PPT 要促成什么判断；
• 哪些事实可以使用；
• 哪些素材必须保留；
• 哪些元素必须可编辑；
• 需要交付哪些中间产物；
• 如何验收。

七、标准使用流程

7.1 从主题到页面大纲

先让智能体输出页面大纲，再生成 PPTD。页面大纲至少包含：

• 页码和页面标题；
• 本页唯一核心结论；
• 需要的数据、图片或图表；
• 预计的版式类型；
• 与前后页面的叙事关系。

这样可以避免智能体把大量正文直接压入页面，导致导出后文本溢出。

7.2 从大纲到 PPTD

生成时要求：

• deck.pptd 中明确列出全部 .page；
• 每个元素拥有唯一 elementId；
• 图片全部放在项目目录内；
• 主题色、字号和行距尽量通过 theme 统一；
• 需要单行显示的文字显式设置 wrap: false；
• 长文本使用合理的边界、字号和行距；
• 复杂页面拆分为多个相互独立的元素。

7.3 在本地编辑器中审阅

重点检查：

1. 封面是否在缩略图和大画布上都能识别；
2. 章节页是否真的承担了分段作用；
3. 页面之间的标题、页码、边距和色彩是否一致；
4. 图片是否保持主体完整，没有遮挡或拉伸；
5. 表格和图表是否仍然适合演讲场景；
6. 每页是否只有一个明确的主结论。

图 3：项目内置的 DJI Osmo Pocket 4 示例项目。原图见 docs/images/example-dji-pocket4-editor.png。

7.4 先导出页面图片，再导出 PPTX

默认 Skill 要求先进行视觉质检。示例命令如下：

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

确认 .qa-images/overview.jpg 和可疑单页没有问题后，再导出 PPTX：

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

如果使用 --target 安装 Skill，应将命令中的 Skill 路径替换为实际安装路径。已有输出文件默认不会被覆盖，需要明确使用 --force。

7.5 在办公软件中复核

导出的 PPTX 应至少在一种目标办公软件中打开，并检查：

• 中文字体是否替换；
• 图片是否丢失；
• 透明度、渐变和裁剪是否一致；
• 表格和图表是否仍可编辑；
• 淡入淡出切换是否被正确识别；
• 页面比例和页边距是否变化。

项目脚本会做 ZIP 完整性和 XML 结构检查，但这不能证明 PowerPoint、WPS 和 Keynote 对所有效果的播放结果完全一致。

八、适用场景分析

8.1 技术方案与项目汇报

这是最匹配的场景。方案内容通常具有“背景—问题—架构—实施—价值—计划”的固定骨架，PPTD 可以将页面、图表、架构图和讲稿备注分开维护。

建议实践：

• 先从 Markdown 方案生成页面大纲；
• 架构图和关键数据使用本地媒体；
• 每页保留一个可复核的结论；
• 将版本、数据口径和素材来源写入项目说明。

8.2 产品介绍与发布会材料

项目示例展示了 DJI Osmo Pocket 4、小米 YU7 等产品主题，说明它可以处理产品特性、参数、场景图片和价格信息。此类场景适合强调：

• 大图背景与文字层级；
• 章节页和卖点页的节奏；
• 可替换的产品图片；
• 在 PowerPoint 中继续修改产品名称、价格和参数。

图 4：DJI Osmo Pocket 4 示例导出的 PPTX。原图见 docs/images/example-dji-pocket4-pptx.png。

8.3 教学、培训与科普

pageType、主题样式、讲演者备注和页面顺序适合课程内容。可以将每个知识点拆成独立 .page，让智能体按章节复用同一套色彩和字号。

使用时应避免：

• 一页放入完整讲义；
• 用过多动画掩盖内容组织问题；
• 用装饰性图片替代概念解释；
• 让模型自行编造实验数据或引用。

8.4 研究综述与决策分析

论文综述、竞品分析和技术路线比较需要频繁更新。PPTD 的文件化结构便于替换单页，页面图片质检也适合发现图表密度和信息层级问题。

此类场景必须显式提供：

• 数据来源；
• 统计口径；
• 结论的适用范围；
• 不能推断的内容；
• 需要人工核验的引用。

8.5 风格迁移与参考图复刻

项目 Skill 支持从参考图片、PDF 或 PPTX 中分析版式，再生成可编辑 PPTD。它更适合复用“色彩、字号层级、图片比例和版式规律”，不应未经许可复制受版权保护的完整设计资产。

图 5：项目 README 中的 Liquid Glass 风格案例。原图见 docs/images/example-deepseek-liquid-glass.png。

图 6：项目 README 中的小米 YU7 产品案例。原图见 docs/images/example-yu7-pptx.png。

九、最佳实践

9.1 先定义叙事，再定义风格

建议使用以下顺序：

1. 明确受众和决策目标；
2. 列出页面结论；
3. 分配数据、图片和图表；
4. 确定页面类型；
5. 最后确定色板、字体和装饰。

如果一开始只给“高级科技风”或“苹果风”，模型容易优先优化外观，忽略内容顺序和信息密度。

9.2 使用主题令牌保持一致性

将背景色、正文色、强调色、标题字号和正文行距放入 theme。页面只引用 $accent、$pageTitle 等令牌。

这样做有三个好处：

• 统一修改全稿视觉风格；
• 降低智能体在不同页面中随意选色的概率；
• 让人工审阅可以围绕少数设计变量反馈，而不是逐个元素改色。

9.3 内容与版式分层维护

建议不要把大量业务事实直接埋在复杂的页面代码中。可以采用：

资料与事实
  → 页面大纲
  → page 文案
  → 版式与主题
  → 导出成品

如果需要反复更新数据，应优先让智能体修改文本、表格和图表元素，而不是重新生成整页背景图。

9.4 媒体资源本地化和命名

正式交付时，图片建议放在 media/，并遵守：

• 使用有语义的英文文件名或统一的编号；
• 避免空格、特殊字符和过深的目录层级；
• 控制分辨率和文件大小；
• 记录图片来源和授权范围；
• 不把临时下载目录、绝对路径或用户主目录路径写入 PPTD；
• 需要稳定复现时，不依赖远程图片 URL。

脚本会跳过超过 20 MiB 的单张本地图片，并限制总嵌入媒体负载。图片压缩应在生成前完成，而不是等导出失败后再处理。

9.5 建立“结构检查—视觉检查—办公软件检查”三道门

三道门分别解决不同问题：

• 结构检查：版本、页面路径、元素数组、资源边界和 YAML 是否有效；
• 视觉检查：遮挡、越界、对比度、溢出、裁剪和跨页一致性；
• 办公软件检查：字体、动画、透明度、图表和可编辑性。

只通过其中一道门，不能推断其他两道门也通过。

9.6 反馈要定位到页码和元素

与智能体迭代时，避免使用“整体再高级一点”这类不可验证的指令。建议写成：

第 5 页，“数据融合链路”标题与图片主体重叠；
将标题上移约 20 px，图片保持 cover 裁剪；
正文从 16 px 调整为 14 px，保留两行以内；
不要改变其他页面的主题色和页边距。

页码、元素名称、空间关系和期望数值越明确，修复范围越可控。

9.7 对外部依赖做版本和网络预案

团队使用时建议：

• 记录 npm 包版本、Skill 文件版本和目标浏览器版本；
• 在发布前先执行一次完整导出；
• 为 www.kimi.com、statics.moonshot.cn 不可访问准备失败说明；
• 对 agent-browser、Chrome/Chromium 和 Python 依赖进行环境检查；
• 不在正式交付时临时安装未知版本的全局依赖；
• 对重要 PPTD 项目保留原始目录和已验证的 PPTX，不只保留成品。

9.8 对敏感材料执行最小暴露原则

即使项目说明“不把 PPTD 项目作为文档上传”，编辑器仍然需要通过 iframe 和远程资源完成预览、编辑或导出。对于敏感材料，应：

• 先脱敏，再生成；
• 删除不必要的客户名称、账号、密钥和个人信息；
• 优先使用本地媒体，减少远程资源请求；
• 在组织安全政策允许的环境中使用；
• 对远程编辑器的通信边界进行内部评估；
• 对外分享前检查 PPTD、PPTX、图片总览图和临时目录是否残留敏感信息。

十、常见问题与排查路径

10.1 编辑器无法连接

可能原因：

• 当前网络无法访问公开 Kimi 编辑器；
• 上游页面结构、资源哈希或 RPC 协议已经变化；
• 浏览器拦截了 iframe 或第三方资源；
• 本地端口被占用。

排查顺序：

1. 先在浏览器中确认 www.kimi.com 可访问；
2. 使用 --port 更换本地端口；
3. 查看编辑器活动面板和浏览器控制台；
4. 确认当前 Skill 版本与仓库版本；
5. 将问题归类为环境问题还是上游兼容性问题，不要直接反复重生成内容。

10.2 找不到页面或图片

检查：

• .pptd 中的 pages 是否使用相对路径；
• .page 文件是否真的存在；
• 图片是否位于 .pptd 同目录下；
• 路径中是否包含绝对路径、.. 或未编码的特殊字符；
• 图片是否超过大小限制；
• 远程图片 URL 是否仍然有效。

10.3 浏览器只能只读打开

这是非 Chromium 浏览器或文件夹授权失败时的预期降级行为。只读模式可以预览，但不能把变更自动写回本地项目。需要编辑和保存时，应使用支持 File System Access API 的 Chromium 浏览器，并主动授权完整项目目录。

10.4 PPTX 导出失败

重点检查：

• Python 是否安装 PyYAML；
• agent-browser 是否可用且版本不低于 0.33.2；
• Chrome/Chromium 是否已安装；
• 网络是否能访问公开编辑器和相关静态资源；
• .pptd 是否为 v2；
• 页面是否至少有一个元素数组；
• 输出文件是否已存在；
• 本地图片总负载是否超过限制。

导出脚本使用浏览器下载成品，再进行 PPTX ZIP 和 XML 校验。因此，下载按钮无法操作、浏览器会话异常或上游导出界面变化，都会导致导出失败。

10.5 字体或动画与预期不一致

“启用字体嵌入”是导出选项，不是绝对保证。脚本会在官方导出器没有生成字体部件时给出警告。不同办公软件对字体、渐变、透明度和切换动画的支持也可能不同。

处理方式：

• 优先使用目标环境确定存在的字体；
• 在目标办公软件中打开成品；
• 将关键文本保持为文本框，不要转成图片；
• 对必须一致的页面提供静态图片备份；
• 不把淡入淡出动画视为业务功能。

十一、项目边界与风险判断

11.1 上游兼容性风险

本项目依赖公开网页编辑器，而不是稳定的官方服务端 API。上游更新可能改变：

• iframe 地址；
• 前端资源地址；
• RPC 方法；
• 导出面板的 DOM 结构；
• PPTD 解析和渲染行为。

如果团队依赖它完成固定周期的正式交付，应保留一份可运行版本，并把升级作为独立验证任务。

11.2 “格式互转”需要实测

README 宣称支持读取、复刻和 PPTX/PPTD 互转，但从当前公开文件树看，仓库中明确可见的核心 CLI 主要负责 Skill 安装和本地编辑器启动，导出脚本主要负责 PPTD 到 PPTX。当前没有看到一个独立、通用的 PPTX 到 PPTD 批量转换命令。

因此，对“现有 PPTX 可以完整转换并无损编辑”的判断应以目标版本的实际操作为准，不应把 README 中的能力描述直接当作稳定 API 约定。

11.3 不是完整的 PowerPoint 能力替代品

PPTD 覆盖文本、形状、图片、表格和图表等常用元素，但它不是完整的 OOXML 语义模型。复杂母版、宏、专有动画、嵌套对象、修订记录、批注和某些高级图表特性，都可能需要单独验证或回到 PowerPoint 中处理。

11.4 数据边界不是“本地运行”四个字可以概括

本地宿主、远程 iframe、本地文件数据、远程图片和导出下载之间存在多个边界。即使 PPTD 文件没有通过传统文件上传接口提交，也不能据此推断整个过程满足组织的保密要求。

对企业使用而言，至少需要完成：

• 数据分级；
• 网络访问评估；
• 远程资源清单；
• 临时文件清理；
• 输出制品脱敏；
• 供应链和上游变更评估。

十二、团队落地建议

12.1 先做小规模验证

建议用一份 6–8 页、非敏感、内容真实的技术汇报进行验证。验证内容包括：

1. 从主题和 Markdown 资料生成页面大纲；
2. 生成完整 PPTD 项目；
3. 在本地编辑器中修改至少 2 页；
4. 运行页面图片质检；
5. 导出 PPTX；
6. 在目标办公软件中打开并修改文本、图片和表格；
7. 记录生成耗时、人工修复轮次和缺陷数量。

12.2 用五个指标评估是否值得采用

• 可编辑率：文本、图片、形状和图表是否保持独立对象；
• 视觉缺陷率：每 10 页出现多少个遮挡、溢出、越界或对比度问题；
• 迭代成本：修改一页内容是否需要重新生成整份 PPT；
• 跨软件一致性：目标办公软件中的版式偏差是否可接受；
• 数据可接受性：组织是否允许内容经过公开网页编辑器和外部资源链路。

12.3 形成团队模板

如果验证通过，可以在团队内部固定：

• 一套安装版本和更新节奏；
• 一份提示词模板；
• 一套主题令牌；
• 一份页面大纲格式；
• 一份视觉验收清单；
• 一份办公软件兼容性清单；
• 一份敏感材料使用禁区；
• 一份 PPTD 项目目录与媒体命名规范。

这样做的目标不是让所有人生成同一种 PPT，而是让不同人员在同一条可复核的生产链路上协作。

十三、总结

open-kimi-ppt-skill 的技术价值可以归纳为一句话：

它把“让智能体生成 PPT”改造成“让智能体生成一个可编辑的演示文稿项目，并通过本地编辑、浏览器渲染和视觉质检形成闭环”。

其中最值得借鉴的不是某一种视觉风格，而是四个工程思想：

1. 用中间表示隔离智能体与复杂输出格式；
2. 用 Skill 把经验写成可复用的生产规程；
3. 用本地项目目录保留人类可接管的编辑权；
4. 用结构检查、视觉质检和办公软件复核共同定义“完成”。

对于非敏感的技术汇报、产品介绍、课程课件和研究综述，可以把它作为一个高效率的实验性工具链。对于保密、离线、强兼容或高并发场景，应先完成替代方案和风险评估，再决定是否纳入正式生产流程。

十四、参考资料与图片来源

• 项目仓库：GGquanta/open-kimi-ppt
• 项目 README
• Skill 定义：skills/open-kimi-ppt/SKILL.md
• PPTD 格式规范：skills/open-kimi-ppt/reference/pptd.md
• npm 包：open-kimi-ppt-skills
• 编辑器概览图
• 导出面板图
• DJI 编辑器案例图
• DJI PPTX 案例图
• Liquid Glass 案例图
• 小米 YU7 PPTX 案例图