ppt

PPT 技能 — 演示文稿级编排

构建幻灯片时，将文件系统视为数据库：每份演示文稿都是 .pptwork/<deck-name>/ 下的一个文件夹，其中包含机器可读的 deck.json、每页各自的 design.md 和 slide.html，以及可选的大纲／研究笔记。

此技能包含：

• 方法论：用于明确意图、规划故事脉络、进行视觉质检和导出（本文档及 references/）。
• 脚本：位于 scripts/，用于演示文稿的增删改查（deck.mjs）、无头缩略图生成（screenshot.mjs）和 PPTX 导出（export.mjs，支持可编辑和栅格两种模式）。
• 配套的 ppt-html-authoring 技能负责单页创作（实际编写 slide.html 时，请阅读其 SKILL.md）。

此技能在 assets/ 下附带 两个内置起始模板集：

• assets/corporate-light/ — 5 种布局（封面、议程、双栏＋图表、KPI 行、结束页）
• assets/claude-warm/ — 5 种布局（封面、章节、时间线、引言、便当盒网格）

每个模板集都包含一个 index.json，列出每种布局的 id、pageType、description、authoringHints 和 htmlPath。规划故事时会读取 index.json 来选择布局；创作时会读取匹配的 HTML，借鉴其构图。你可以在起始模板集旁添加自己的模板集，也可以完全跳过模板集，从头开始创作。

设置（首次使用）

cd skills/ppt
npm install   # or `bun install`

截图／导出脚本会启动真实的无头浏览器。它们会按以下顺序查找 Chrome／Edge：PPT_BROWSER_EXECUTABLE 环境变量 → Playwright 随附的 Chromium → 系统 Chrome（channel）→ 系统 Edge。如果这些方式都不可用，请运行一次 npx playwright install chromium。

导出工具链：

库	作用
playwright-core	使用无头 Chromium／Edge 渲染 slide.html、生成截图
html2pptx-pro	可编辑的 PPTX（映射 HTML 结构）— 默认导出引擎
dom-to-pptx	DOM → 幻灯片元素 — 用于诊断的备用可编辑引擎
pptxgenjs	PPTX 文件写入、栅格导出

工作目录

所有脚本都基于 process.cwd()/.pptwork/ 运行。请在用户的项目根目录中运行它们。

磁盘布局

完整约定请参见 references/disk-layout.md。简而言之：.pptwork/<deck>/deck.json 是幻灯片顺序的唯一事实来源；每页的文件夹中包含 design.md、slide.html 和 thumbnail.png。

端到端工作流程

由一个操作者（你）依次完成各阶段，不存在隐藏的子 Agent。进入某个阶段时，请阅读对应的 references/<phase>.md。

1. Clarify intent
2. (optional) Material digest        → references/material-digest.md
3. (optional) Research               → references/research.md
4. Story planning                    → references/story-planning.md
5. Initialize deck + first slides    → scripts/deck.mjs init / init-slide
6. Author each slide                 → ppt-html-authoring skill
7. Visual QC each slide              → references/visual-qc.md + scripts/screenshot.mjs
8. Export                            → scripts/export.mjs (+ references/export-troubleshooting.md)

步骤 1 — 明确意图

只询问缺失的信息，不要自行编造：

• 受众（内部报告／客户提案／公开演讲／培训）
• 场景与时长（会议时长、目标决策、是否需要离线阅读？）
• 预期页数（下限／上限）
• 风格／品牌（企业模板？特定参考 PPTX？配色方案？）
• 必备章节（用户坚持要求的内容）
• 输出语言
• 是否需要核实外部事实（数字／新闻／市场数据）
• 导出目标：询问用户需要 raster 还是 editable
  • 默认建议使用 raster：像素效果忠实，但无法在 PowerPoint 中编辑
  • editable 仅适用于在 PowerPoint 中编辑，且存在布局偏移风险；创作时必须遵循 references/editable-html-rules.md

步骤 2 — 材料摘要（需要时）

出现以下任一情况时触发：

• 用户提供了长文档／多个文件／会议纪要。
• 导入的参考演示文稿较大（HTML 页数较多）。

如果用户只提供了一句话主题，或你已经有摘要，则跳过。

方法 → references/material-digest.md。

步骤 3 — 调研（需要时）

适用情形：

• 主题涉及时效性数据（市场规模、发布节奏、政策）。
• 用户明确要求你核实某个数字或事实。
• 缺少竞争对手或行业基准信息。

此技能不自带网页抓取或搜索工具。请使用宿主应用内置的 webfetch / websearch（OpenCode webfetch/websearch、Claude Code WebFetch/WebSearch、Cursor WebSearch/WebFetch 等）。将结构化调研结果存档到 .pptwork/<deck>/materials/research.md，避免它们占用主上下文。

方法 → references/research.md。

步骤 4 — 规划故事线

输入：澄清信息 +（可选）摘要 +（可选）调研总结。 输出：页数 ≥ 5 的演示文稿使用 .pptwork/<deck>/outline.md；较短的演示文稿则在上下文中提供结构化摘要。进行简要检查，确保模板多样、注明来源，并涵盖必需章节。

此阶段不要编写 slide.html。

方法 → references/story-planning.md。

步骤 5 — 初始化演示文稿并搭建幻灯片骨架

node skills/ppt/scripts/deck.mjs init <deck-name> --mode raster
node skills/ppt/scripts/deck.mjs init-slide <deck-name> <slide-name>

<slide-name> 应简短且有意义（intro-dark、agenda-clean、summary-bold）。

先制作 1~2 页并请用户确认，再扩展到更多页面。 结构性错误的代价高于耗时；如果到第 12 页才发现故事线有误，就得重做 10 页。

步骤 6 — 编写每张幻灯片

将单页编写工作交给 ppt-html-authoring 技能。该技能有独立的触发点，因此只想要“帮我设计一张幻灯片”的用户无需走完整个演示文稿流程。它会生成：

• design.md（frontmatter 包含 title + layout + ## Content / ## Note / ## Design）
• slide.html（单文件、自包含；演讲者备注会镜像到 #ppt-speaker-notes-json 脚本岛中）

将演示文稿的 exportMode 传递给编写步骤。如果 exportMode=editable，则要求编写步骤遵循 references/editable-html-rules.md。

对于较长的演示文稿，逐页进行编写；不要在一次编写调用中批量处理所有页面。

步骤 7 — 对每张幻灯片进行视觉质量检查

node skills/ppt/scripts/screenshot.mjs <deck> <slide>

然后阅读生成的 thumbnail.png，并按照 references/visual-qc.md 中的清单逐项检查。微调 slide.html，直到通过清单检查；最多迭代 3 次，并将尚未解决的问题告知用户。

步骤 8 — 导出

# default: editable via html2pptx-pro — editable, but still verify output
node skills/ppt/scripts/export.mjs <deck-name>

# high-fidelity fallback: raster — pixel-faithful, text not editable
node skills/ppt/scripts/export.mjs <deck-name> --mode raster

# backup editable engine for one-slide diagnostics
node skills/ppt/scripts/export.mjs <deck-name> --editable-engine dom-to-pptx

默认输出到 .pptwork/<deck-name>/<deck-name>.pptx。可通过 --output <path> 覆盖。

如果演示文稿的 deck.json 中有 exportMode，则省略 --mode 时会遵循该设置。没有 exportMode 的演示文稿将按 editable 处理。

**可编辑（默认）**模式使用 html2pptx-pro 将幻灯片 HTML 转换为可编辑的 PowerPoint 对象。这是目前的主要路径，但仍需在 PowerPoint 中验证：字体、复杂 CSS 和布局边缘情况可能会出现偏差。

修订流程如下：

edit slide.html  →  screenshot.mjs to verify  →  export.mjs to ship

这是受支持的“编辑演示文稿”方式：修改 HTML，然后重新导出。不要尝试编辑 .pptx 输出文件并指望修改能够往返同步。

栅格化模式会将每张幻灯片合成为一张整页 PNG，并放置到 13.333×7.5 英寸的幻灯片上。当可编辑输出出现偏差，且视觉保真度比 PowerPoint 可编辑性更重要时，使用此模式。

dom-to-pptx 仅作为诊断用的备用可编辑引擎。它在实际演示文稿中出现过布局偏差，目前仅支持单页备用导出。

如果导出结果有误，请参阅 references/export-troubleshooting.md。

如果用户先创建了栅格化或复杂 HTML 演示文稿，之后又要求生成可编辑的 PPTX，不要直接重新运行 --mode editable。应先根据 references/editable-html-rules.md，使用语言模型重写每个 slide.html，然后进行截图质量检查并导出为可编辑格式。

模板桶

内置模板：assets/corporate-light/ 和 assets/claude-warm/ （参见仓库中的 examples/，其中包含使用这两种模板的演示文稿）。将其他 模板桶放在 assets/<bucket-name>/ 下即可扩展模板库。

模板桶是具有以下结构的目录：

assets/<bucket>/
├── index.json                     # array of template descriptors
├── html/<id>.html                 # one self-contained reference slide per id
├── specs/<id>.json                # optional structured zone description
└── materials/<id>/                # optional images/svgs the template uses
    └── manifest.json

最简 index.json 条目（未标记为可选的字段均为必填项）：

{
  "id": "cover-hero",
  "pageType": "cover",
  "description": "Hero opener with full-bleed background and a single conclusion title.",
  "authoringHints": "Title goes in the centered `[data-role=hero-title]` slot. Background image at `[data-role=hero-bg]`.",
  "htmlPath": "html/cover-hero.html",
  "materialDir": "materials/cover-hero",
  "zones": [
    { "selector": "[data-role=hero-title]", "kind": "text" },
    { "selector": "[data-role=hero-bg]",    "kind": "image" }
  ]
}

故事规划只读取 id / pageType / description / authoringHints，不会读取原始 HTML。HTML 正文供创作阶段借鉴其构图 （版本安全区域、分栏、层级、占位位置）。不要将参考 HTML 中的占位文案 （“Acme Corp”、“2024 Q3 revenue”、“scene illustration”）复制到实际演示文稿中。

如果还没有模板桶，该技能仍然可以使用——故事规划可以用纯文本描述布局，创作阶段则可以从头生成 slide.html。模板桶只是通过提供经过验证的构图供创作步骤参考，加快这两个阶段。

脚本参考

脚本	用途
scripts/deck.mjs init <deck>	创建 .pptwork/<deck>/deck.json 骨架。
scripts/deck.mjs init-slide <deck> <slide> [--at N]	创建幻灯片文件夹和空的 design.md，并在 deck.json 中注册。
scripts/deck.mjs move <deck> <slide> <to-pos>	重新排序幻灯片。
scripts/deck.mjs delete <deck> <slide> [<slide>...]	移除幻灯片文件夹及 deck.json 条目。
scripts/deck.mjs path <deck> <slide>	打印绝对路径和文件夹内容。
scripts/deck.mjs list <deck>	按 deck.json 中的顺序列出幻灯片。
scripts/screenshot.mjs <deck> <slide>	无头渲染 slide.html → thumbnail.png。
scripts/screenshot.mjs <slide-dir>	相同功能，直接指定幻灯片目录。
scripts/export.mjs <deck> [--mode editable|raster] [--output ...]	将演示文稿导出为单个 .pptx 文件。

每个脚本都会在 stdout 上输出一个 [Done] / [State] / [Next] / [Hint] / [Error] 块 ——这些标签用于跟踪下一步操作。将其视为待办清单。

常见问题

• 跳过澄清环节，直接开始故事规划 → 用户会说“这不是我想要的”。
• 用户提供了包含大量材料的 10MB PPTX，而你没有先运行材料摘要 → 上下文被撑爆。
• 未先研究就创作时效性较强的页面 → 数字是幻觉。
• 长篇演示文稿没有进行视觉质检 → 导出的文件有 3 页被裁切。
• 一次批量创作 20 页 → 创作会在前几页后停止；“一次只做单页”是硬性要求。
• 用户没有要求，你却主动选择了 --mode editable → 不要这样做。 默认模式是 raster。只有当用户明确需要在 PowerPoint 中编辑时，才使用 editable 模式，因为可编辑导出在复杂 CSS / 字体 / SVG 上会出现偏差。
• 用户在 raster 演示文稿创作完成后要求可编辑，而你没有按可编辑规则重写 HTML 就直接导出 → 错误。
• 可编辑导出效果不佳 → 移除 --mode editable 标志。默认的 raster 模式最可靠；不要一直停留在 editable 模式中反复调整同一张幻灯片。
• 用户要求“编辑一张幻灯片”，你却试图修改导出的 .pptx → 错误的工作流。应编辑 slide.html，然后重新截图、重新导出。 HTML 是唯一可信来源。
• 尝试使用名为 web_fetch / web_search 的工具，但该工具不存在 → 改用宿主内置的 webfetch / websearch。此技能本身不提供这些工具。