ppt-html-authoring

单页 PPT 编写

给定：

• 目标幻灯片目录（通常为 .pptwork/<deck>/<slide-name>/）
• 一个大纲条目（pageType、assetId、关键内容、来源、转场）
• 演示文稿的 exportMode（raster 或 editable）

生成：

• design.md — frontmatter 包含 title 和 layout，之后是 ## Content / ## Note / ## Design（这三个部分都不能为空）
• slide.html — 自包含的单文件，并将 ## Note 文本同步到 <script type="application/json" id="ppt-speaker-notes-json"> 节点中

**不在本任务范围内：**跨页规划（使用 ppt 技能的故事规划阶段）、截图和视觉质检（使用 ppt 技能的 screenshot.mjs + visual-qc 参考文档）、导出（使用 export.mjs）、网页搜索（使用宿主应用的 webfetch / websearch）。

文件规范

design.md

• frontmatter：
  • title（必填）
  • layout（必填，简短的英文标识符，与所用布局匹配）
• 正文包含三个部分，均不能为空：
  • ## Content — 面向读者的页面文案：一个以结论为导向的完整句标题，以及支持性项目符号 / 简短段落。
  • ## Note — 使用自然语言撰写的演讲者备注（不要使用项目符号）。
  • ## Design — 视觉 / 工程说明：布局选择理由、与上一页的转场、数据来源、TBD 标记。
• 不得使用空占位符。“这是一张介绍页”不可接受。
• 详细规范 → references/design-md-spec.md

slide.html

• 必须是自包含的单文件：CSS 写在 <style> 中，JS 写在 <script> 中。
• 图片：使用内联 base64 或 https CDN。禁止使用本地相对路径（<img src="assets/...">、<link href="...">）——它们在 <iframe srcdoc> 预览和基于静态服务器的渲染器中会失效，除非配套文件恰好放在 HTML 文件旁边。
• 字体、chart.js、d3 等：从 https CDN 加载。
• 将 ## Note 内容同步到 <script type="application/json" id="ppt-speaker-notes-json">…</script> 节点中。这是演讲者备注写入导出 PPTX 的唯一方式。
• 为使幻灯片按正确的 PowerPoint 画布尺寸渲染，请设置 html, body { width: 1280px; height: 720px; overflow: hidden; }。
• 硬性规则和常见问题 → references/slide-html-rules.md （必读）。
• 如果 exportMode=editable，还需遵循 references/editable-html-rules.md。

工作流

1. 阅读上下文

大纲条目（pageType / assetId / 关键内容 / 来源 / 转场）+ 现有幻灯片骨架（design.md 是空模板，slide.html 可能只有 <html> 头部 / 尾部）+ exportMode。

2. 查找布局（素材规范）

如果大纲指定了 assetId，请在同级 ppt 技能的 ../ppt/assets/<bucket>/index.json 中查找，并阅读匹配的 描述文件：

阅读内容	用途
index.json 条目的 htmlPath	查找 HTML 参考路径
index.json 条目的 materialDir / zones / authoringHints	了解布局的插槽构成
解析后的 html/<id>.html	借鉴构图（版本安全区、分栏、层级）
specs/<id>.json 的 zones	获取各插槽的结构化描述（可选）

默认素材库位于同级 ppt 技能的 ../ppt/assets/corporate-light/ 和 ../ppt/assets/claude-warm/ 中（每个素材库有 5 种布局）。如果大纲指定了 assetId，请阅读 index.json 和匹配的 html/<id>.html。如果未配置素材库，请跳过此步骤，并根据 references/slide-html-rules.md 和 references/ppt-best-practices.md 中的构图指南，从头编写 slide.html。

不要自行选择 assetId——这是故事规划阶段的决定，大纲已指定该值（或明确写明“无预设，从头设计”）。

3. 不要原样照搬模板 HTML

只借鉴布局（版本安全区、列、层级、占位位置）。将所有占位文案（“Acme Corp”“2024 Q3 revenue”“scene illustration”等）替换为页面的真实内容。占位内容残留在成品演示文稿中，是最常见的创作失误之一。

4. 先编写 design.md

按 Content → Note → Design 的顺序：

• ## Content：以结论为导向的完整句子标题（不要使用名词短语）+ 支持性要点 / 短段落。
• ## Note：演讲者备注，使用自然行文，不要写成要点。
• ## Design：布局选择理由、过渡提示、数据来源、TBD 标记。

5. 然后编写 slide.html

根据 Content 部分编写 HTML。只要数据适合，优先使用可视化，而非纯文本：

• 趋势 / 占比 / 比较 → Chart.js（参见 references/diagram-and-chart.md）。
• 流程 / 架构 / 系统边界 → 内联 SVG。
• 装饰性图像 → base64 内联；对于大型图像（>2MB），请压缩或使用远程 CDN。
• 图标 → 使用远程 https SVG 图标库（Heroicons、Lucide、Feather、Tabler 等），或粘贴单个内联 SVG。

如果 exportMode=editable，请将 HTML 编写为 PowerPoint 原生对象：重要文案使用真实文本节点，卡片使用简单的纯色填充形状，表格使用真实表格，Chart.js 数据应可提取，并将背景装饰分离。不要将重要文本放在 SVG、canvas、图像或伪元素中。

6. 将 Note 同步到 HTML 中

将 ## Note 文本同步到 <script type="application/json" id="ppt-speaker-notes-json">…</script> 区块中。这是演讲者备注写入导出 PPTX 的唯一途径。

7. 需要外部事实？

如果单页缺少一个数字 / 事实 / 引用 / 竞品数据点：

• 使用宿主应用内置的 webfetch / websearch 工具。此技能本身不提供网络工具。
• 将调查结果追加到 .pptwork/<deck>/materials/research.md（以免跨幻灯片污染主上下文）。
• 在 ## Design 中按 source: research.md §<timestamp> 的格式引用事实。
• 不要捏造数字。

8. 自检

• 是否有 <img src="assets/..."> / <link href="..."> 这类相对路径？请改为 base64 或远程 https。
• 是否已将 Note 部分同步到 HTML 中？
• data-id / data-role 属性是否足够稳定，能支持后续以 edit / patch 方式微调？

参考资料（按需阅读）

操作	阅读
编写 design.md	references/design-md-spec.md
编写 / 编辑 slide.html	references/slide-html-rules.md（必读）
编写 / 重写可编辑演示文稿 HTML	references/editable-html-rules.md
添加图表、内联 SVG、示意图	references/diagram-and-chart.md
字体排印、字号、对齐、视觉焦点	references/ppt-best-practices.md

决策规则

• 用户说“调整一句话” → 使用 edit / patch 修改匹配的 data-id 节点，保持外部结构不变。
• 用户说“重新设计布局” → 重写整个 slide.html，但保留 design.md 的叙述内容。
• 现有的栅格图像 / 复杂 HTML 演示文稿现在需要可编辑输出 → 按照 editable-html-rules.md，使用语言模型重写每一页；不要依赖纯规则转换器。
• 内容本质上是关于占比 / 趋势 / 比较 → 优先使用图表，不要罗列原始数字。
• 内容本质上是关于流程 / 架构 / 边界 → 优先使用内联 SVG，不要堆砌段落。
• 需要背景 / 品牌图像 → 使用 base64 内联；对于大型图像（>2MB），先压缩或使用远程 CDN。
• 缺少数据 → 使用宿主的 webfetch/websearch，不要编造数字。

常见陷阱

• 完成的页面中仍留有模板占位文案（例如不相关演示文稿中的“Acme Corp Case”）。
• 数据页只有“数字 + 一段文字”，没有图表。
• image-slot 中仍留有“场景插图”占位内容——缩略图会显得空荡。
• 使用 <img src="assets/diagram.png"> 相对路径——iframe 预览会失效。
• 忘记将 Note 同步到 #ppt-speaker-notes-json——导出的 PPTX 演讲者备注为空。
• 标题写成名词短语（如“AI Agent 市场”），而不是结论句。
• 没有快速抓取数据或询问用户，而是编造了一个数字。