document-pptx

Document PPTX

**适用范围：**当 claude.ai Slides artifact type 或 Anthropic 官方 pptx skill 可用时，处理简单创建/编辑、通用模板填充和视觉 QA 时优先使用它。此技能适用于以下专门场景：

• 自动化前检查模板（布局、占位符 idx、形状名称、OOXML 部件）
• 使用 PPTX-Automizer 填充设计师制作的模板
• 提取演讲者备注和检查受损演示文稿
• 无障碍和 EN 301 549 审查

快速参考

任务	默认方式	说明
填充前检查模板	scripts/pptx_inventory.py --json	布局名称、占位符 idx 和类型、形状名称
检查受损演示文稿或其部件	scripts/pptx_ooxml_inspect.py	关系损坏、目标缺失、修复对话框
提取或备份演讲者备注	scripts/pptx_extract_notes.py	Markdown 或 JSON
填充设计师制作的模板	PPTX-Automizer	仅替换命名元素（图表数据、文本、表格、图像）
使用 Python 进行报告或提取	python-pptx	标准图表、备注、占位符
使用 JS/TS 或浏览器导出	PptxGenJS	真正的组合图表；默认布局为 16:9

脚本和退出代码

脚本	0	1	2
pptx_ooxml_inspect.py	没有损坏的关系目标	发现损坏的目标（门禁）。对于结构良好但存在损坏目标的包，--report-only 会以 0 退出	文件缺失、包无效或关系部件格式错误
pptx_inventory.py / pptx_extract_notes.py	已写入	不适用	文件缺失、不可读或不是 .pptx

决策规则

• **优先使用模板，或从头开始。**如果演示文稿面向外部受众、需要经过品牌或法务审核，或者请求中提到“我们的模板”，就使用带品牌标识的模板。对于内部草稿、探索性模型或重视速度胜过品牌呈现的数据型报告，则从头开始制作。存在模板时，切勿猜测品牌颜色、字体或布局名称：先检查模板。没有模板且不要求品牌呈现时，简洁的无品牌标识演示文稿胜过凭空设计的企业风格。
• **PPTX-Automizer 仅用于有限的填充任务。**它将命名元素合并到设计师制作的结构中；它不是通用幻灯片生成器。
• **每次都按名称解析布局。**布局索引无法在不同模板间通用，而且设计师可能会在不同版本间调整布局顺序或名称。
• 根据 idx 集合检查占位符。1 in slide.placeholders 始终为 False；应使用 {ph.placeholder_format.idx for ph in slide.placeholders} 进行检查。请参阅 references/pptx-template-branding.md。
• 每张幻灯片只讲一个要点，图表数据应可追溯到一个唯一真实来源，并注明单位、时间范围和来源。
• **无障碍是创作的一部分：**标题、阅读顺序、对比度和替代文本都应考虑，而不是留到最后检查。

已知限制

• python-pptx 没有动画 API（不支持构建或进入效果），也没有幻灯片切换 API。两者都需要直接编辑 OOXML <p:timing>/<p:transition>；在承诺动态效果前，请参阅 references/pptx-animations-transitions.md。

• python-pptx 无法创建真正的组合图表（柱形图加折线图）；它没有多绘图区图表构造函数。请使用 replace_data 填充模板组合图表，或使用 PptxGenJS。

• python-pptx 没有渐变填充 API，也不支持编辑主题颜色（theme1.xml）。两者都需要直接编辑 XML，并应先备份。

• 颜色类是 RGBColor（来自 pptx.dml.color），而不是 RgbColor；大小写错误会引发 ImportError。

• 默认幻灯片尺寸有所不同：python-pptx 的默认模板为 10 × 7.5 in（4:3），PptxGenJS 的默认尺寸为 10 × 5.625 in（16:9）。请根据目标尺寸检查每个形状和图表（y + h <= slide height）；从 4:3 示例复制的位置会超出 16:9 幻灯片的范围。

• PptxGenJS 没有幻灯片切换或自动播放选项；slide.transition / advanceAfter 会被静默忽略。请改为编写 <p:transition> OOXML。

• PPTX-Automizer 的 modifyElement(selector, callback) 接受修改回调（ModifyTextHelper.setText(...)、ModifyTableHelper.setTable(...)、ModifyChartHelper.setChartData(...)），而不是类似 { text: ... } 的选项对象。

• 盲目修改模板可能会破坏计时、媒体或文件可修复性。Keynote 或 Google Slides 能顺利打开文件，并不能确认其与 PowerPoint 兼容，反之亦然。

• 库的行为会随版本变化。在依赖某个已知 API 缺失项或默认行为前，请使用已安装的版本重新测试；无法验证时，应标注为未经验证。

工作流

1. 对任务进行分类：新建演示文稿、填充模板、提取备注或修复。
2. 编写幻灯片代码前，先构建幻灯片叙事（assets/slide-narrative-template.md）。
3. 进行任何自动化修改前，检查模板（pptx_inventory.py --json、pptx_ooxml_inspect.py --json）。
4. 生成或编辑，然后运行下方的发布检查。

幻灯片渲染发布检查

最终保存后，重新打开演示文稿并盘点幻灯片数量、版式名称、占位符、媒体关系、图表数据和演讲者备注。将每张幻灯片渲染为图像或 PDF，格式应符合声明的交付目标；检查文本裁切、字体替换、对象超出幻灯片范围、图表标签损坏、图像分辨率过低以及意外的空白占位符。如果 PowerPoint 保真度或无障碍性属于验收标准，则必须实际使用 PowerPoint 检查；否则，请使用可用的目标渲染器，并将 PowerPoint 保真度标注为未经验证。

渲染后，将图表和关键数据与源数据进行比较，而不只是检查生成代码。对于模板编辑，请确认母版和主题关系仍然有效，并且声明的目标查看器打开文件时不会弹出修复对话框。记录查看器特有的差异，不要把某个查看器的结果当作另一个查看器的证明。

导航

参考资料

• references/pptx-layouts.md
• references/pptx-charts.md
• references/pptx-template-branding.md
• references/pptx-speaker-notes-delivery.md
• references/pptx-accessibility-compliance.md
• references/pptx-troubleshooting-repair.md
• references/pptx-animations-transitions.md
• references/deck-narrative-and-visual-patterns.md — 选择演示文稿结构、说服路径、逐页布局、幻灯片类型比例或图表时加载
• references/extraction-stack.md — 为新的 LLM/RAG 管道选择提取工具（原生解析、Docling 或 OCR）时加载
• data/sources.json

脚本

• scripts/pptx_inventory.py
• scripts/pptx_extract_notes.py
• scripts/pptx_ooxml_inspect.py

模板

• assets/pitch-deck.md
• assets/quarterly-review.md
• assets/slide-narrative-template.md

相关技能

• ../document-pdf/SKILL.md
• ../document-xlsx/SKILL.md
• ../product-management/SKILL.md

经验总结循环

如果以往的决策或陷阱与当前情况相关，并且 learnings.consolidated.md 存在，请查阅该文件；仅在需要了解历史记录或将其作为可用的备用方案时，才使用 learnings.md。否则跳过这两个文件。

应用后，如果遇到值得记住的模式、值得避免的错误，或令你意外的领域事实，请通过 agents-skills-feedback-loop/scripts/append_learning.py 在 learnings.md 中追加一条带日期的要点。不要修改 SKILL.md 本身。