pptx

PowerPoint 演示文稿

你已经了解 python-pptx 和 PptxGenJS。本技能新增了一个转换器，可将 HTML 幻灯片转换为原生、可编辑的 PowerPoint 对象；还提供了可让模板工作流程更可靠的脚本，以及用于检查演示文稿是否有效、外观是否正确的工具。

运行脚本

<skill> 是包含此文件的目录。请从用户的工作目录使用绝对路径运行随附脚本，这样脚本文件的相对路径才能正常工作：

uv run <skill>/scripts/thumbnail.py deck.pptx

运行你编写的 Python 代码时，请声明其依赖项，可使用 uv run --with python-pptx script.py 或 PEP 723 标头。运行 Node 脚本时，使用 NODE_PATH=<skill>/node_modules node build.js；如果缺少 <skill>/node_modules，请在 <skill> 中运行一次 npm install。渲染需要 LibreOffice（soffice）和 poppler（pdftoppm）。

选择工作流程

任务	工作流程
读取演示文稿的文本	uv run --with 'markitdown[pptx]' python -m markitdown deck.pptx
新建演示文稿，不使用模板	使用下文的 html2pptx。请先阅读 html2pptx.md 和 design.md。
使用模板新建演示文稿	使用下文的模板工作流程
修改现有演示文稿	使用 python-pptx 处理文本和形状。对于 python-pptx 无法访问的内容，请使用幻灯片 XML（ooxml.md）。
演讲者备注	scripts/notes.py

markitdown 从 1 开始为幻灯片编号（``）；此处的每个脚本都从 0 开始计数。若要沿用现有演示文稿的风格，请从解包后的文件中读取 ppt/theme/theme1.xml（<a:clrScheme>、<a:fontScheme>），并查看其缩略图网格。

新建演示文稿：html2pptx

1. 确定设计系统（design.md）：调色板、字体大小比例和网格。编写代码前，用两句话说明设计系统。
2. 按照 html2pptx.md 中的规则，为每张幻灯片编写一个 HTML 文件。使用 class="placeholder" 标记图表和表格区域。
3. 编写构建脚本，为每张幻灯片调用 html2pptx()，使用 PptxGenJS 在占位区域添加图表和表格，并调用 pptx.writeFile({ fileName })。html2pptx 会一次性报告幻灯片上的所有问题；请修复所有问题后重新运行。
4. 检查输出（见下文）。

使用模板新建演示文稿

1. 查看模板。 使用 markitdown 提取文本，并通过 uv run <skill>/scripts/thumbnail.py template.pptx grid 生成缩略图网格。查看网格图片。

2. 盘点版式。 按从 0 开始的索引列出每张幻灯片及其用途，例如“12：两列，每列各有标题和项目符号”。

3. 将内容映射到版式。 先统计每张幻灯片的内容项数，再选择槽位数量完全匹配的版式：

   • 两项内容选双栏版式，三项内容选三栏版式
   • 只有在内容包含图片时才使用图片版式
   • 只有引用内容确实为引文且注明出处时才使用引用版式
   • 四项或更多内容拆分到多张幻灯片，或放入列表

   不要将占位符留空，也不要编造内容来填充占位符。

4. 组装幻灯片。复制完整内容，包括图表、嵌入的工作簿、备注和链接：

   uv run <skill>/scripts/rearrange.py template.pptx working.pptx 0,12,12,31,40
   

5. 盘点文本。 阅读 inventory.json 的全部内容：

   uv run <skill>/scripts/inventory.py working.pptx inventory.json
   

6. 编写替换内容（格式如下），然后应用：

   uv run <skill>/scripts/replace.py working.pptx replacements.json output.pptx
   

7. 检查输出（见下文）。

清单与替换内容

inventory.json 将 slide-N 映射到 shape-N，两者均从 0 开始。形状按从上到下、再从左到右的顺序排列，且不包含幻灯片编号。每个形状都有以英寸为单位的 left、top、width 和 height，以及 paragraphs。此外还包含：

• placeholder_type（TITLE、CENTER_TITLE、SUBTITLE、BODY、OBJECT……），仅适用于占位符
• default_font_size，当版式设置了默认字体大小时
• 检测到相关情况时的 overflow、overlap 和 warnings

段落仅列出与默认值不同的属性。

替换文件结构相同，其中每个要填充的形状都包含 paragraphs：

{
  "slide-0": {
    "shape-0": {"paragraphs": [{"text": "Revenue grew 18%", "bold": true}]},
    "shape-1": {"paragraphs": [
      {"text": "Renewals drove two thirds of growth"},
      {"text": "Churn fell to 4%", "bullet": true, "level": 0}
    ]}
  }
}

• 段落字段：
  • text、bold、italic、underline
  • font_size、font_name
  • color（"C0392B"）或 theme_color（"ACCENT_1"）
  • alignment（LEFT、CENTER、RIGHT、JUSTIFY）
  • space_before、space_after、line_spacing（单位为磅）
  • 带有 level 的 bullet
• 保留清单中为该位置显示的属性，以维持模板样式。
• 切勿输入项目符号字符。项目符号段落会自动左对齐。
• 对列出的每张幻灯片，都会清空所有文本形状，然后填入内容。 文件中未列出的形状最终会变空，从而移除模板中遗留的文本。未列出的幻灯片不受影响。
• 如果某个键不存在（"Shape 'shape-9' not found on 'slide-0'. Available shapes: …"），或者新文本在文本框中的溢出程度超过旧文本（"Text overflow worsened: slide-0/shape-2: …"），replace.py 将不会保存任何内容。请缩短文本或选择空间更充裕的版式。

编辑幻灯片 XML

先阅读 ooxml.md。然后解包、编辑、每次修改后进行验证，再重新打包：

uv run <skill>/ooxml/scripts/unpack.py deck.pptx unpacked
uv run <skill>/ooxml/scripts/validate.py unpacked --original deck.pptx
uv run <skill>/ooxml/scripts/pack.py unpacked edited.pptx

演讲者备注

uv run <skill>/scripts/notes.py deck.pptx                    # print {"slide-0": "…", …}
uv run <skill>/scripts/notes.py deck.pptx notes.json -o out.pptx

JSON 将幻灯片键映射到纯文本，每行一个段落。空字符串会清除某张幻灯片的备注，未列出的幻灯片则保留原备注。在 html2pptx 构建中，请改用 slide.addNotes('…')。

检查输出

完成演示文稿的标准是通过验证并检查每张幻灯片。

1. 验证。 对于新演示文稿，运行 uv run <skill>/ooxml/scripts/validate.py deck.pptx。对于编辑过的演示文稿或基于模板制作的演示文稿，添加 --original template.pptx，这样只会报告新问题。请修复列出的所有问题。

   对于复制的幻灯片，validate.py 还会报告模板中已有的架构错误。继续排查前，请将这些错误与源幻灯片进行比较。

2. 查看。 运行 uv run <skill>/ooxml/scripts/render.py deck.pptx pages 并查看每张图片。检查以下问题：

   • 文本被截断、相互重叠或挤到边缘
   • 对比度不足
   • 模板中遗留的文本或空占位符
   • 内容偏离网格

   thumbnail.py deck.pptx grid --outline-placeholders 会生成概览，并为每个文本框描边。

3. 修复并重复检查，直到两项检查都通过。

容易悄无声息地导致失败的问题

• PptxGenJS 颜色值不能带 #。'#C0392B' 会损坏文件。
• 在浏览器中能放下的文本，在 PowerPoint 中可能因字体替换而溢出。请遵守 design.md 中的字体规范。
• 手动复制 XML 来复制幻灯片会丢失图表，并导致幻灯片共用备注。请使用 rearrange.py。
• 除 markitdown 的输出外，幻灯片索引均从 0 开始。