pptx

PPTX 的创建、编辑与分析

操作规范（请先阅读 — 不可妥协）

本技能必须先确保故事连贯且内容忠实覆盖，再制作精美幻灯片。如果本 SKILL.md 的各部分之间存在冲突，以本节规则为准。

1. 忠实性：不得编造事实

• 除非源材料中原文包含，否则不得添加指标、统计数据、ARR、定价或采用情况相关数字
• 如果需要用数字进行说明，请在演讲者备注中明确标注：“Example: ~$X (placeholder)”
• 如果不确定某项事实是否在源材料中，请省略

2. 锁定范围：仅限本章内容

演示文稿必须涵盖本章的学习目标，不得超出范围。

禁止涉及的主题（除非本章内容中明确提及）：

• 商业模式、定价策略
• ARR、MAU、收入预测
• “立即销售”、“变现”、市场规模估算
• “Digital FTE economics” 计算
• 竞争格局分析

如果某张幻灯片偏离了范围：删除或改写。

3. 统一叙事主线（避免主题跳跃）

选择一条主线并始终保持一致：

主线类型	流程
教学主线	问题 → 概念 → 机制 → 工作流 → 示例 → 陷阱 → 总结 → 后续步骤
章节主线	引子 → 学习目标 → 逐课讲解（概念 → 示例 → 尝试）→ 总结 → 行动号召

规则：

• 每张幻灯片必须恰好对应主线中的一个步骤
• 不得出现 A→B→A 的跳转（讲过主题 A 后，后面不要再回到它）
• 如果某张幻灯片不符合主线：删除，或拆分到合适的步骤中

4. 覆盖要求

生成任何 PPTX 文件之前，必须先准备好以下材料：

材料	用途
workspace/content-audit.md	每节课的研究笔记（已有）
workspace/slide-outline.md	标题以结论形式呈现的故事板（已有）
workspace/coverage-matrix.md	将每节课／目标映射到至少 1 张幻灯片
workspace/semantic-qa.md	最终连贯性检查清单

覆盖规则：

• 每节课都必须至少出现在 1 张幻灯片中
• 必须涵盖每个学习目标
• 如果无法涵盖所有内容：增加幻灯片数量，不要压缩内容
• 必须在 coverage-matrix.md 中明确说明任何遗漏的理由

5. 语义 QA 门槛（交付前必须通过）

生成最终演示文稿之前，使用以下清单完成 workspace/semantic-qa.md：

• 幻灯片顺序遵循所选主线（没有 A→B→A 的跳转）
• 每张幻灯片都有一个与大纲一致的明确要点
• 没有引入经批准的大纲中未包含的新主题
• 所有术语都在使用前介绍
• 没有编造的事实、指标或主张
• 没有禁止涉及的主题（见第 2 节）
• coverage-matrix 显示已覆盖 100% 的课程内容

如果任何一项未通过：请修改并重新生成。不要交付未通过检查的演示文稿。

6. 冲突处理政策

当内容无法放入一张幻灯片时：

1. 拆分成更多幻灯片（优先）
2. 将细节移至演讲者备注
3. 用图表／视觉元素替换文字
4. 以上方法都不可行时，再精简措辞
5. 绝不能将字号缩小到 MIT 排版规范的最低要求以下（正文 24pt，标题 40pt）

7. 独立呈现背景（默认）

除非另有明确要求，演示文稿应当独立完整：

• ❌ 错误：“第 5 章：Claude Code 功能”（假设观众了解书籍背景）
• ✅ 正确：“Claude Code：你的通用 Agent”（适用于任何受众）

规则：

• 标题中不得包含章节／小节／课程编号
• 不得引用“正如我们在第 X 课中讨论的内容”
• 演示文稿应适合从未读过源材料的人观看
• 如果用户需要教育背景标记，必须明确提出要求

8. 使用亲切易懂的语言

使用能让人感到受欢迎而非望而生畏的语言：

❌ 避免使用	✅ 建议使用
“你将掌握的内容”	“本节结束时”
“你必须了解的前置知识”	“建议先了解的内容”
“高级概念”	“更深入的模式”
“专家技巧”	“实用小贴士”

语气：自信而亲切。绝不居高临下，也不设置门槛。

9. 以吸引人的开场切入，而非列出目标

第一张内容幻灯片应激发好奇心，而不是罗列学习成果。

幻灯片顺序：

1. 标题页（引人注目的价值主张）
2. 引入页（范式转变、发人深省的问题或“如果……会怎样？”）
3. 然后才是学习目标

❌ 错误的开场：第 2 张幻灯片 = “你将学到什么：1. 安装…… 2. 配置……” ✅ 正确的开场：第 2 张幻灯片 = “如果一个通用 Agent 就能构建你所有的自定义 Agent，会怎样？”

---

概述

用户可能会要求你创建、编辑或分析 .pptx 文件的内容。.pptx 文件本质上是一个 ZIP 存档，其中包含 XML 文件和其他资源，你可以读取或编辑这些内容。针对不同任务，你可以使用不同的工具和工作流。

读取和分析内容

提取文本

如果只需要读取演示文稿中的文本内容，应将文档转换为 Markdown：

# Convert document to markdown
python -m markitdown path-to-file.pptx

访问原始 XML

以下内容需要访问原始 XML：批注、演讲者备注、幻灯片版式、动画、设计元素和复杂格式。对于这些内容，你需要解压演示文稿并读取其原始 XML 内容。

解压文件

python ooxml/scripts/unpack.py <office_file> <output_dir>

注意：unpack.py 脚本相对于项目根目录，位于 skills/pptx/ooxml/scripts/unpack.py。如果该路径下没有此脚本，请使用 find . -name "unpack.py" 查找。

关键文件结构

• ppt/presentation.xml - 演示文稿的主要元数据和幻灯片引用
• ppt/slides/slide{N}.xml - 单张幻灯片的内容（slide1.xml、slide2.xml 等）
• ppt/notesSlides/notesSlide{N}.xml - 每张幻灯片的演讲者备注
• ppt/comments/modernComment_*.xml - 特定幻灯片的批注
• ppt/slideLayouts/ - 幻灯片的版式模板
• ppt/slideMasters/ - 幻灯片母版模板
• ppt/theme/ - 主题和样式信息
• ppt/media/ - 图像和其他媒体文件

提取字体和颜色

收到需要仿照的设计示例时：始终先使用以下方法分析演示文稿的字体和颜色：

1. 读取主题文件：检查 ppt/theme/theme1.xml 中的颜色（<a:clrScheme>）和字体（<a:fontScheme>）
2. 抽样检查幻灯片内容：查看 ppt/slides/slide1.xml 中实际使用的字体（<a:rPr>）和颜色
3. 搜索模式：使用 grep 在所有 XML 文件中查找颜色（<a:solidFill>、<a:srgbClr>）和字体引用

不使用模板创建新的 PowerPoint 演示文稿

从头创建新的 PowerPoint 演示文稿时，使用 html2pptx 工作流，将 HTML 幻灯片转换为定位精准的 PowerPoint 幻灯片。

设计原则

重要：创建任何演示文稿之前，请先分析内容并选择合适的设计元素：

1. 考虑主题：这份演示文稿的主题是什么？它体现了怎样的语气、行业特点或氛围？
2. 检查品牌信息：如果用户提到了公司或组织，请考虑其品牌色彩和品牌形象
3. 让配色契合内容：选择能体现主题的颜色
4. 说明设计思路：编写代码之前，先解释你的设计选择

要求：

• ✅ 编写代码之前，先说明基于内容的设计思路
• ✅ 仅使用 Web 安全字体：Arial、Helvetica、Times New Roman、Georgia、Courier New、Verdana、Tahoma、Trebuchet MS、Impact
• ✅ 通过字号、字重和颜色建立清晰的视觉层级
• ✅ 确保易读性：对比度鲜明、字号适当、对齐整洁
• ✅ 保持一致：在各张幻灯片中重复使用相同的样式、间距和视觉语言

强制设计声明

编写任何代码之前，你必须先输出类似以下内容的设计声明：

## Design Approach

**Content analysis**: This presentation covers [topic]. The content suggests [mood/tone/energy].

**Color palette**: [Palette name] because [reason tied to content]
- Primary: #XXXXXX — [purpose, e.g., "titles, key statements"]
- Accent 1: #XXXXXX — [purpose, e.g., "highlights, CTAs"]
- Accent 2: #XXXXXX — [purpose, e.g., "secondary elements"]
- Background: #XXXXXX — light for projection

**Visual approach**: [e.g., "Accent bars on left edge, colored by topic"]

❌ 绝不能跳过此声明——直接开始编写代码会导致演示文稿平淡无奇、令人难忘。

配色反模式（绝对不要这样做）

❌ 反模式	错在哪里	✅ 应该这样做
藏青色（#1a1a2e）+ 灰色（#666）	“企业安全色”= 令人难忘	使用契合内容的鲜明配色
默认蓝色（#0066cc）	看起来像模板占位色	使用具有明确寓意的颜色
白底黑字	缺乏视觉活力	使用彩色标题和强调元素
跳过设计声明	导致选择流于惯性	务必先说明设计思路

颜色方案选择

创意选择颜色：

• 跳出默认选项：哪些颜色真正契合这个特定主题？避免不假思索地选择。
• 从多个角度考虑：主题、行业、氛围、活力程度、目标受众、品牌形象（如果有提及）
• 大胆尝试：试试出人意料的搭配——医疗主题的演示文稿不一定非要用绿色，金融主题也不一定非要用海军蓝
• 构建配色方案：选择 3-5 种相互协调的颜色（主色 + 辅助色调 + 点缀色）
• 确保对比度：文字在背景上必须清晰易读

配色方案示例（借此激发创意——选择一种、调整一种，或创建自己的方案）：

1. 经典蓝：深海军蓝 (#1C2833)、石板灰 (#2E4053)、银色 (#AAB7B8)、灰白色 (#F4F6F6)
2. 青绿与珊瑚色：青绿色 (#5EA8A7)、深青绿色 (#277884)、珊瑚色 (#FE4447)、白色 (#FFFFFF)
3. 醒目红色：红色 (#C0392B)、亮红色 (#E74C3C)、橙色 (#F39C12)、黄色 (#F1C40F)、绿色 (#2ECC71)
4. 暖腮红色：灰紫色 (#A49393)、腮红色 (#EED6D3)、玫瑰色 (#E8B4B8)、奶油色 (#FAF7F2)
5. 酒红奢华风：酒红色 (#5D1D2E)、深红色 (#951233)、铁锈色 (#C15937)、金色 (#997929)
6. 深紫与翡翠绿：紫色 (#B165FB)、深蓝色 (#181B24)、翡翠绿 (#40695B)、白色 (#FFFFFF)
7. 奶油色与森林绿：奶油色 (#FFE1C7)、森林绿 (#40695B)、白色 (#FCFCFC)
8. 粉色与紫色：粉色 (#F8275B)、珊瑚色 (#FF574A)、玫瑰色 (#FF737D)、紫色 (#3D2F68)
9. 青柠绿与李子色：青柠绿 (#C5DE82)、李子色 (#7C3A5F)、珊瑚色 (#FD8C6E)、蓝灰色 (#98ACB5)
10. 黑与金：金色 (#BF9A4A)、黑色 (#000000)、奶油色 (#F4F6F6)
11. 鼠尾草绿与陶土色：鼠尾草绿 (#87A96B)、陶土色 (#E07A5F)、奶油色 (#F4F1DE)、炭灰色 (#2C2C2C)
12. 炭灰与红色：炭灰色 (#292929)、红色 (#E33737)、浅灰色 (#CCCBCB)
13. 活力橙：橙色 (#F96D00)、浅灰色 (#F2F2F2)、炭灰色 (#222831)
14. 森林绿：黑色 (#191A19)、绿色 (#4E9F3D)、深绿色 (#1E5128)、白色 (#FFFFFF)
15. 复古彩虹：紫色 (#722880)、粉色 (#D72D51)、橙色 (#EB5C18)、琥珀色 (#F08800)、金色 (#DEB600)
16. 复古大地色：芥末黄 (#E3B448)、鼠尾草绿 (#CBD18F)、森林绿 (#3A6B35)、奶油色 (#F4F1DE)
17. 海岸玫瑰色：古玫瑰色 (#AD7670)、海狸棕 (#B49886)、蛋壳色 (#F3ECDC)、灰白色 (#BFD5BE)
18. 橙色与绿松石色：浅橙色 (#FC993E)、灰绿松石色 (#667C6F)、白色 (#FCFCFC)

视觉细节选项

几何图案：

• 使用对角线分隔区块，而非水平线
• 采用不对称的栏宽（30/70、40/60、25/75）
• 将文本标题旋转 90° 或 270°
• 为图片使用圆形／六边形边框
• 在角落添加三角形装饰图形
• 叠加图形以营造纵深感

边框与框架处理：

• 仅在一侧使用粗实色边框（10-20pt）
• 使用对比色双线边框
• 用角括号代替完整边框
• 使用 L 形边框（上边+左边或下边+右边）
• 在标题下方添加下划线装饰（粗 3-5pt）

排版处理：

• 极端字号对比（72pt 标题与 11pt 正文）
• 标题使用全大写，并加宽字间距
• 使用超大展示字体呈现编号章节
• 对数据／统计信息／技术内容使用等宽字体（Courier New）
• 对密集信息使用窄体字体（Arial Narrow）
• 使用描边文字突出重点

图表与数据样式：

• 使用单色图表，并以单一强调色标记关键数据
• 使用水平条形图，而非竖直条形图
• 使用点图，而非条形图
• 尽量减少网格线，或完全不使用
• 直接在图表元素上标注数据（不使用图例）
• 使用超大数字展示关键指标

布局创新：

• 使用满版图片，并叠加文本
• 设置侧边栏（宽度占 20-30%）用于导航／背景说明
• 使用模块化网格系统（3×3、4×4 区块）
• 采用 Z 形或 F 形内容流
• 在彩色图形上方放置浮动文本框
• 采用杂志风格的多栏布局

背景处理：

• 使用占据幻灯片 40-60% 的纯色区块
• 使用渐变填充（仅限垂直或对角方向）
• 使用分割背景（两种颜色，按对角线或垂直方向划分）
• 使用从一边延伸至另一边的色带
• 将留白作为设计元素

MIT 标准排版要求

所有演示文稿都必须满足。以下要求是不可妥协的质量门槛。

字号规则

元素	最小值	建议值	原因
幻灯片标题	40pt	44pt	在大型礼堂后排也清晰可见
正文	24pt	28pt	MIT 专业场合的最低要求
项目符号文本	24pt	28pt	与正文相同，项目符号文本不得更小
代码块	18pt	20pt	等宽字体可略小一些
图注／脚注	16pt	18pt	仅用于非关键细节

执行要求：定稿前，检查每张幻灯片的所有文本是否都达到这些最低字号。如果有任何文本低于 24pt（图注除外），请调大字号。

内容密度规则

1. 每张幻灯片只讲一个观点——每张幻灯片都要传达一个核心结论
2. 最多 4 个项目符号——比 MIT 的 6 个更严格，以增强效果
3. 每个项目符号最多 6 个词——促使内容简洁
4. 每张幻灯片最多 50 个词——幻灯片是视觉辅助工具，而非文档
5. 标题应为结论——使用“数据证明了 X”，而非“数据分析”

视觉层次原则

• 大小传达重要性：最大的元素 = 重点内容
• 克制使用颜色：最多 3 种颜色（黑色／白色除外）
• 策略性留白：20% 以上的内边距可留出呼吸空间
• 浅色背景：投影时至关重要（深色模式的投影效果较差）
• 对齐保持一致：基于网格，采用可预测的布局

自我检查清单

交付任何演示文稿前，请确认：

• 所有标题都是可执行的结论（而非标签）
• 没有小于 24pt 的文本（图注除外）
• 每张幻灯片的项目符号不超过 4 个
• 每个项目符号不超过 6 个词
• 至少 30% 的幻灯片包含视觉元素
• 配色方案不超过 3 种颜色 + 黑色／白色
• 全文使用浅色背景
• 代码示例使用语法高亮

创建“有灵魂”的演示文稿

机械呆板与引人入胜的幻灯片之间的区别：

机械呆板（避免）：

• 泛泛的标题：“介绍”“概览”“总结”
• 项目符号堆砌：列表中有 8 项或更多
• 只有文字：没有图表或视觉元素
• 内容密度一致：每张幻灯片的内容量都相同
• 默认配色：毫无设计意图的基础蓝灰色

有灵魂（目标）：

• 可行动的标题：“技能可将输出偏差降低 80%”
• 内容聚焦：1 个观点，最多 3–4 个支撑要点
• 视觉化叙事：图表、流程图、对比
• 灵活调整内容密度：复杂主题使用更多幻灯片
• 有意选择配色：与层级／主题／氛围相匹配

“灵魂”测试

在定稿前，先问问自己：

1. 只看标题，是否就能理解核心信息？
2. 每张幻灯片是否都有明确的视觉焦点？
3. 这套幻灯片用于 KubeCon/Strange Loop 演讲时，是否足够专业？
4. 每张幻灯片上是否都留有充足的呼吸空间（留白）？

布局技巧

创建带图表或表格的幻灯片时：

• 双栏布局（首选）：使用横跨全宽的标题栏，下方分为两栏——一栏放文字／项目符号，另一栏放重点内容。这种布局更均衡，也让图表／表格更易读。使用宽度不等的 flexbox 栏（例如 40%/60%），为不同类型的内容优化空间。
• 全页布局：让重点内容（图表／表格）占据整张幻灯片，以获得最大的视觉冲击力和可读性。
• 绝不要纵向堆叠：不要把图表／表格放在单栏文字下方——这会导致可读性变差和布局问题。

工作流

1. 必须——阅读整个文件：从头到尾完整阅读 html2pptx.md。阅读此文件时绝不要设置范围限制。 在开始创建演示文稿前，阅读完整文件内容，以了解详细语法、关键格式规则和最佳实践。
2. 为每张幻灯片创建一个 HTML 文件，并设置正确的尺寸（例如，16:9 的 720pt × 405pt）
   • 所有文字内容都使用 <p>、<h1>-<h6>、<ul>、<ol>
   • 对将添加图表／表格的区域使用 class="placeholder"（渲染时使用灰色背景以便查看）
   • 关键：先使用 Sharp 将渐变和图标栅格化为 PNG 图片，再在 HTML 中引用
   • 布局：对于带图表／表格／图片的幻灯片，使用全页布局或双栏布局，以提高可读性
3. 使用 html2pptx.js 库创建并运行 JavaScript 文件，将 HTML 幻灯片转换为 PowerPoint 并保存演示文稿
   • 使用 html2pptx() 函数处理每个 HTML 文件
   • 使用 PptxGenJS API 将图表和表格添加到占位区域
   • 使用 pptx.writeFile() 保存演示文稿
4. 视觉验证：生成缩略图并检查布局问题
   • 创建缩略图网格：python scripts/thumbnail.py output.pptx workspace/thumbnails --cols 4
   • 阅读并仔细检查缩略图，留意以下问题：
     • 文字被裁切：文字被标题栏、形状或幻灯片边缘裁切
     • 文字重叠：文字与其他文字或形状重叠
     • 位置问题：内容距离幻灯片边界或其他元素太近
     • 对比度问题：文字与背景之间的对比度不足
   • 如果发现问题，调整 HTML 边距／间距／颜色，然后重新生成演示文稿
   • 重复此过程，直到所有幻灯片的视觉效果都正确

编辑现有的 PowerPoint 演示文稿

编辑现有 PowerPoint 演示文稿中的幻灯片时，需要使用原始 Office Open XML（OOXML）格式。这包括解包 .pptx 文件、编辑 XML 内容，然后重新打包。

工作流

1. 必须执行——完整阅读文件：从头到尾完整阅读 ooxml.md（约 500 行）。读取此文件时，绝不要设置范围限制。 在编辑任何演示文稿之前，完整阅读文件内容，详细了解 OOXML 结构和编辑工作流。
2. 解包演示文稿：python ooxml/scripts/unpack.py <office_file> <output_dir>
3. 编辑 XML 文件（主要是 ppt/slides/slide{N}.xml 和相关文件）
4. 至关重要：每次编辑后立即验证，并在继续之前修复所有验证错误：python ooxml/scripts/validate.py <dir> --original <file>
5. 打包最终演示文稿：python ooxml/scripts/pack.py <input_directory> <office_file>

使用模板创建新的 PowerPoint 演示文稿

如果需要创建遵循现有模板设计的演示文稿，请先复制并重新排列模板幻灯片，然后再替换占位内容。

工作流

1. 提取模板文本并创建视觉缩略图网格：

   • 提取文本：python -m markitdown template.pptx > template-content.md
   • 阅读 template-content.md：完整阅读整个文件，以了解模板演示文稿的内容。读取此文件时，绝不要设置范围限制。
   • 创建缩略图网格：python scripts/thumbnail.py template.pptx
   • 更多详情请参阅创建缩略图网格部分

2. 分析模板并将清单保存到文件：

   • 视觉分析：查看缩略图网格，了解幻灯片布局、设计模式和视觉结构
   • 在 template-inventory.md 中创建并保存模板清单文件，内容如下：

     # Template Inventory Analysis
     **Total Slides: [count]**
     **IMPORTANT: Slides are 0-indexed (first slide = 0, last slide = count-1)**
     
     ## [Category Name]
     - Slide 0: [Layout code if available] - Description/purpose
     - Slide 1: [Layout code] - Description/purpose
     - Slide 2: [Layout code] - Description/purpose
     [... EVERY slide must be listed individually with its index ...]
     

   • 使用缩略图网格：参考视觉缩略图，识别以下内容：
     • 布局模式（标题幻灯片、内容布局、章节分隔页）
     • 图像占位符的位置和数量
     • 幻灯片组之间的设计一致性
     • 视觉层级和结构
   • 下一步选择合适的模板时，必须使用此清单文件

3. 根据模板清单创建演示文稿大纲：

   • 查看第 2 步中可用的模板。
   • 为第 1 张幻灯片选择一个开场或标题模板。应从前几个模板中选择。
   • 为其他幻灯片选择安全的纯文本版式。
   • 重要：版式结构必须与实际内容相匹配：
     • 单栏版式：用于统一叙述或单一主题
     • 双栏版式：仅当你恰好有 2 个不同的条目或概念时使用
     • 三栏版式：仅当你恰好有 3 个不同的条目或概念时使用
     • 图片 + 文本版式：仅当你有要插入的实际图片时使用
     • 引言版式：仅用于带有出处的真实人物引言，切勿用于强调内容
     • 切勿使用占位符数量多于内容数量的版式
     • 如果有 2 个条目，不要硬塞进三栏版式
     • 如果有 4 个或更多条目，可考虑拆分到多张幻灯片，或使用列表格式
   • 选择版式前，先统计实际内容项的数量
   • 确认所选版式中的每个占位符都会填入有意义的内容
   • 为每个内容部分选择一个最合适的版式。
   • 保存 outline.md，其中包含内容和模板映射，并充分利用可用设计
   • 模板映射示例：

     # 要使用的模板幻灯片（从 0 开始索引）
     # 警告：请确认索引在有效范围内！包含 73 张幻灯片的模板，索引范围为 0-72
     # 映射：大纲中的幻灯片编号 -> 模板幻灯片索引
     template_mapping = [
         0,   # 使用幻灯片 0（标题/封面）
         34,  # 使用幻灯片 34（B1：标题和正文）
         34,  # 再次使用幻灯片 34（为第二张 B1 幻灯片创建副本）
         50,  # 使用幻灯片 50（E1：引言）
         54,  # 使用幻灯片 54（F2：结束语 + 文本）
     ]
     

4. 使用 rearrange.py 复制、重新排序和删除幻灯片：

   • 使用 scripts/rearrange.py 脚本，按所需顺序创建新的演示文稿：

     python scripts/rearrange.py template.pptx working.pptx 0,34,34,50,52
     

   • 该脚本会自动复制重复的幻灯片、删除未使用的幻灯片并重新排序
   • 幻灯片索引从 0 开始（第 1 张幻灯片为 0，第 2 张为 1，依此类推）
   • 同一个幻灯片索引可以出现多次，以复制该幻灯片

5. 使用 inventory.py 脚本提取所有文本：

   • 运行清单提取：

     python scripts/inventory.py working.pptx text-inventory.json
     

   • 阅读 text-inventory.json：阅读整个 text-inventory.json 文件，以了解所有形状及其属性。读取此文件时，切勿设置任何范围限制。

   • 清单 JSON 结构：

       {
         "slide-0": {
           "shape-0": {
             "placeholder_type": "TITLE",  // 或非占位符时为 null
             "left": 1.5,                  // 位置，单位为英寸
             "top": 2.0,
             "width": 7.5,
             "height": 1.2,
             "paragraphs": [
               {
                 "text": "Paragraph text",
                 // 可选属性（仅在非默认值时包含）：
                 "bullet": true,           // 检测到显式项目符号
                 "level": 0,               // 仅在 bullet 为 true 时包含
                 "alignment": "CENTER",    // CENTER、RIGHT（不包括 LEFT）
                 "space_before": 10.0,     // 段前间距，单位为磅
                 "space_after": 6.0,       // 段后间距，单位为磅
                 "line_spacing": 22.4,     // 行距，单位为磅
                 "font_name": "Arial",     // 取自第一个文本运行
                 "font_size": 14.0,        // 字号，单位为磅
                 "bold": true,
                 "italic": false,
                 "underline": false,
                 "color": "FF0000"         // RGB 颜色
               }
             ]
           }
         }
       }
     

   • 主要特性：

     • 幻灯片：命名为 "slide-0"、"slide-1" 等。
     • 形状：按视觉位置（从上到下、从左到右）排序，命名为 "shape-0"、"shape-1" 等。
     • 占位符类型：TITLE、CENTER_TITLE、SUBTITLE、BODY、OBJECT 或 null
     • 默认字号：default_font_size，单位为磅，从版式占位符中提取（如果可用）
     • 幻灯片编号会被筛除：带有 SLIDE_NUMBER 占位符类型的形状会自动从清单中排除
     • 项目符号：当 bullet: true 时，始终包含 level（即使值为 0）
     • 间距：space_before、space_after 和 line_spacing 的单位为磅（仅在设置时包含）
     • 颜色：RGB 颜色使用 color（例如 "FF0000"），主题颜色使用 theme_color（例如 "DARK_1"）
     • 属性：输出中仅包含非默认值

6. 生成替换文本并将数据保存到 JSON 文件 根据上一步的文本清单：

   • 关键：首先确认清单中有哪些形状——只引用实际存在的形状
   • 验证：replace.py 脚本会验证替换 JSON 中的所有形状是否存在于清单中
     • 如果引用了不存在的形状，系统会报错并显示可用形状
     • 如果引用了不存在的幻灯片，系统会报错并指出该幻灯片不存在
     • 脚本退出前会一次性显示所有验证错误
   • 重要：replace.py 脚本会在内部使用 inventory.py 来识别所有文本形状
   • 自动清除：除非你为清单中的文本形状提供了“paragraphs”，否则这些形状中的文本都会被清除
   • 对需要内容的形状添加“paragraphs”字段（而非“replacement_paragraphs”）
   • 替换 JSON 中没有“paragraphs”的形状，其文本会被自动清除
   • 带项目符号的段落会自动左对齐。当 "bullet": true 时，不要设置 alignment 属性
   • 为占位文本生成合适的替换内容
   • 根据形状大小确定合适的内容长度
   • 关键：包含原始清单中的段落属性——不要只提供文本
   • 重要：当 bullet: true 时，文本中不要包含项目符号（•、-、*）——脚本会自动添加
   • 必要的格式规则：
     • 标题通常应设置 "bold": true
     • 列表项应设置 "bullet": true, "level": 0"（bullet 为 true 时必须设置 level）
     • 保留所有对齐属性（例如，居中文本应设置 "alignment": "CENTER"）
     • 与默认值不同的字体属性应一并提供（例如，"font_size": 14.0、"font_name": "Lora"）
     • 颜色：RGB 颜色使用 "color": "FF0000"，主题颜色使用 "theme_color": "DARK_1"
     • 替换脚本要求段落采用正确的格式，不能只提供文本字符串
     • 重叠形状：优先选择默认 font_size 较大或 placeholder_type 更合适的形状
   • 将包含替换内容的更新后清单保存到 replacement-text.json
   • 警告：不同的模板布局包含的形状数量不同——创建替换内容前，务必检查实际清单

   展示正确格式的 paragraphs 字段示例：

   "paragraphs": [
     {
       "text": "New presentation title text",
       "alignment": "CENTER",
       "bold": true
     },
     {
       "text": "Section Header",
       "bold": true
     },
     {
       "text": "First bullet point without bullet symbol",
       "bullet": true,
       "level": 0
     },
     {
       "text": "Red colored text",
       "color": "FF0000"
     },
     {
       "text": "Theme colored text",
       "theme_color": "DARK_1"
     },
     {
       "text": "Regular paragraph text without special formatting"
     }
   ]
   

   替换 JSON 中未列出的形状会被自动清除：

   {
     "slide-0": {
       "shape-0": {
         "paragraphs": [...] // This shape gets new text
       }
       // shape-1 and shape-2 from inventory will be cleared automatically
     }
   }
   

   演示文稿中的常见格式模式：

   • 标题幻灯片：使用粗体文本，有时居中
   • 幻灯片中的章节标题：使用粗体文本
   • 项目符号列表：每个列表项都需要 "bullet": true, "level": 0
   • 正文：通常无需特殊属性
   • 引文：可能需要特殊的对齐方式或字体属性

7. 使用 replace.py 脚本应用替换内容

   python scripts/replace.py working.pptx replacement-text.json output.pptx
   

   脚本将：

   • 首先使用 inventory.py 中的函数提取所有文本形状的清单
   • 验证替换 JSON 中的所有形状是否存在于清单中
   • 清除清单中识别出的所有形状中的文本
   • 仅将新文本应用到替换 JSON 中定义了“paragraphs”的形状
   • 根据 JSON 中的段落属性保留格式
   • 自动处理项目符号、对齐方式、字体属性和颜色
   • 保存更新后的演示文稿

   验证错误示例：

   ERROR: Invalid shapes in replacement JSON:
     - Shape 'shape-99' not found on 'slide-0'. Available shapes: shape-0, shape-1, shape-4
     - Slide 'slide-999' not found in inventory
   

   ERROR: Replacement text made overflow worse in these shapes:
     - slide-0/shape-2: overflow worsened by 1.25" (was 0.00", now 1.25")
   

创建缩略图网格

若要创建 PowerPoint 幻灯片的可视化缩略图网格，以便快速分析和参考：

python scripts/thumbnail.py template.pptx [output_prefix]

功能：

• 创建：thumbnails.jpg（如果演示文稿较大，则创建 thumbnails-1.jpg、thumbnails-2.jpg 等）
• 默认值：5 列，每个网格最多 30 张幻灯片（5×6）
• 自定义前缀：python scripts/thumbnail.py template.pptx my-grid
  • 注意：如果要将输出保存到指定目录，前缀应包含路径（例如 workspace/my-grid）
• 调整列数：--cols 4（范围：3-6，影响每个网格中的幻灯片数量）
• 网格限制：3 列 = 每个网格 12 张幻灯片，4 列 = 20 张，5 列 = 30 张，6 列 = 42 张
• 幻灯片采用从 0 开始的索引（Slide 0、Slide 1 等）

使用场景：

• 模板分析：快速了解幻灯片布局和设计模式
• 内容审阅：直观浏览整个演示文稿
• 导航参考：根据幻灯片的外观查找特定幻灯片
• 质量检查：确认所有幻灯片的格式正确

示例：

# Basic usage
python scripts/thumbnail.py presentation.pptx

# Combine options: custom name, columns
python scripts/thumbnail.py template.pptx analysis --cols 4

根据教学章节创建演示文稿

当用户要求为某个章节创建幻灯片时（例如“为第 5 章制作幻灯片”）：

工作区结构

所有工作文件都放在 workspace/ 目录中（在项目根目录或指定位置创建）：

workspace/
├── content-audit.md      ← Phase 1: Research notes
├── slide-outline.md      ← Phase 2: Storyboard (user approves)
├── draft-v1.pptx         ← Phase 4: First draft
├── draft-v2.pptx         ← Phase 5: After fixes
├── review/               ← Phase 5: Thumbnail grids
│   └── thumbnails.jpg
└── [chapter]-slides.pptx ← Phase 6: Final delivery

阶段 0：解析章节路径

重要：遵循 CLAUDE.md 中的 CHAPTER/PART RESOLUTION PROTOCOL。

1. 解析输入：ch X = 第 X 章，part X = 第 X 部分，单独的 X = 询问用户
2. 通过文件系统查找路径（事实依据）：

   # For chapter:
   ls -d apps/learn-app/docs/*/05-*/   # Chapter 5
   
   # For part:
   ls -d apps/learn-app/docs/05-*/     # Part 5
   

3. 统计内容：

   ls apps/learn-app/docs/02-AI-Tool-Landscape/05-*/*.md | wc -l
   

4. 创建工作区：mkdir -p workspace
5. 继续之前先与用户确认

示例：“ch 5” → ls -d apps/learn-app/docs/*/05-*/ → 02-AI-Tool-Landscape/05-claude-code-features-and-workflows/

阶段 1：研究与探索

目标：在规划幻灯片之前，深入理解内容。

输出：保存到 workspace/content-audit.md

1. 阅读章节 README，了解学习目标和范围
2. 完整阅读每一课并做结构化笔记：

   # Content Audit: [Chapter Name]
   
   **Chapter path**: [discovered path]
   **Total lessons**: [N]
   **Pedagogical layer**: [L1/L2/L3/L4]
   
   ---
   
   ## Lesson 1: [Title]
   - **Core concept**: [One sentence]
   - **Key takeaways**: [3-5 bullets]
   - **Needs diagram**: [Yes/No - what kind?]
   - **Memorable quote/example**: [If any]
   - **Word count**: [X words]
   
   ## Lesson 2: [Title]
   ...
   
   ---
   
   ## Narrative Arc
   - **Problem this chapter solves**: [...]
   - **The "aha moment"**: [...]
   - **What to remember a week later**: [...]
   

3. 梳理叙事脉络：
   • 本章要解决什么问题？
   • “顿悟时刻”是什么？
   • 一周后，读者应该记住什么？
4. 记下 frontmatter 中的教学层级（L1-L4）

阶段 2：编写故事板并制定计划

目标：在生成任何幻灯片之前，创建完整的幻灯片大纲。

输出：保存到 workspace/slide-outline.md

步骤 2a：确定幻灯片数量

内容类型	每 1000 个单词对应的幻灯片数	特点
概念型（L1）	6-8	更多图表和类比
流程型（L2）	8-10	分步呈现
技术型（L3-L4）	5-7	代码示例、架构

步骤 2b：逐张起草幻灯片大纲

在 workspace/slide-outline.md 中创建详细的故事板：

# Chapter X Presentation Outline

**Total slides**: [N]
**Estimated duration**: [N slides × 1-2 min = X minutes]
**Primary color**: [Layer color]

## Opening (Slides 1-3)
1. **Title**: "[Chapter Title]" — [Type: Title]
2. **Hook**: "[Provocative question or problem statement]" — [Type: Hook]
3. **Roadmap**: "What you'll learn" — [Type: Concept, 3 bullets max]

## Lesson 1: [Title] (Slides 4-8)
4. **[Slide title as conclusion]** — [Type: Concept]
   - Key point 1
   - Key point 2
   - Visual: [diagram description]
5. **[Next conclusion]** — [Type: Comparison]
   - Left: [Option A]
   - Right: [Option B]
...

## Closing (Slides N-2 to N)
- **Summary**: "3 Things to Remember" — [Type: Summary]
- **Call to Action**: "[What to do next]" — [Type: Title]

步骤 2c：应用“所以呢？”测试

针对大纲中的每张幻灯片，询问：

• 唯一要点是什么？（如果不清楚，就拆分或删去）
• 为什么受众会关心？（与他们的目标关联）
• 能否改为视觉呈现？（优先使用图表，而非项目符号）

步骤 2d：征求用户批准

停止并向用户展示大纲：

• 幻灯片总数
• 叙事流程摘要
• 任何省略的内容（以及原因）
• 关于侧重点或受众的问题

在用户批准大纲之前，不要继续生成。

步骤 2e：创建内容覆盖矩阵

用户批准后，创建 workspace/coverage-matrix.md，以确认内容覆盖完整：

# Coverage Matrix: [Chapter Name]

**Chosen spine**: [Teaching / Chapter]

| # | Lesson Title | Key Concepts | Slide(s) | Status |
|---|--------------|--------------|----------|--------|
| 1 | [Lesson 1 title] | [Main concepts] | 4, 5 | ✓ Covered |
| 2 | [Lesson 2 title] | [Main concepts] | 6, 7, 8 | ✓ Covered |
| ... | ... | ... | ... | ... |

## Learning Objectives Coverage

| Objective | Slide(s) | Status |
|-----------|----------|--------|
| [Objective 1] | 3 | ✓ |
| [Objective 2] | 5, 6 | ✓ |

## Omissions (must justify)

- None / [Reason for any excluded content]

规则：

• 每一课至少对应 1 张幻灯片
• 每个学习目标都必须体现
• 必须明确说明省略内容的理由
• 如果覆盖不完整：增加幻灯片，不要压缩内容

阶段 3：应用设计系统

教学层颜色

层级	主色	强调色	用途
L1	#4472C4 (蓝色)	#2E5C9A	基础知识、首次接触
L2	#70AD47 (绿色)	#548235	AI 协作
L3	#9B59B6 (紫色)	#7D3C98	技能、MCP、自动化
L4	#ED7D31 (橙色)	#C65911	综合项目、生产代码

幻灯片类型模式

类型	使用场景	视觉处理
标题	开场幻灯片	大号居中文字、层级颜色
引入	叙事开场	引言或发人深省的问题
概念	定义／框架	图表 + 最多 2-3 个要点
对比	对比选项	并排表格
流程	逐步操作	编号路径／流程图
示例	代码／演示	深色代码块和输出
与 AI 练习	交互式提示词	设计为聊天／终端卡片
总结	关键要点	3 条编号结论

阶段 4：生成草稿

输出：保存到 workspace/draft-v1.pptx

1. 按照已批准的大纲生成幻灯片
2. 应用 MIT 排版规则（最小 24pt，最多 4 个要点）
3. 保存为 workspace/draft-v1.pptx

阶段 5：验证循环（两层）

此阶段包含两层。第 1 层（语义）必须通过后，才能进入第 2 层（视觉）。

┌──────────────────────────────────────────────────────────────────────┐
│                                                                      │
│  Draft → Semantic QA → Pass? ─No─→ Revise outline/content            │
│              │                           │                           │
│             Yes                          │                           │
│              ↓                           │                           │
│        Thumbnails → Visual QA → Pass? ─No─→ Fix layout/typography    │
│              │                       │                               │
│             Yes                      │                               │
│              ↓                       │                               │
│            Done ←────────────────────┘                               │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

---

第 1 层：语义验证（首先执行）

生成缩略图之前，请验证演示文稿是否讲述了连贯的故事。

步骤 5a：创建语义 QA 检查清单

创建 workspace/semantic-qa.md：

# Semantic QA: [Chapter Name] Presentation

**Chosen spine**: [Teaching / Chapter]
**Date**: [YYYY-MM-DD]

## Checklist

| Check | Pass? | Issue (if any) |
|-------|-------|----------------|
| Slides follow chosen spine (no A→B→A jumps) | | |
| Each slide has ONE clear takeaway | | |
| No topics introduced outside approved outline | | |
| All terminology introduced before use | | |
| No invented facts, metrics, or claims | | |
| No forbidden topics (pricing, revenue, market size) | | |
| Coverage-matrix shows 100% lesson coverage | | |

## Slide-by-Slide Review

| Slide | Title | Spine Role | Takeaway | Issues |
|-------|-------|------------|----------|--------|
| 1 | | Title | | |
| 2 | | Hook | | |
| 3 | | Roadmap | | |
| ... | | | | |

## Flagged Issues

1. [Issue description and which slide]
2. ...

## Decision

- [ ] **PASS** — Ready for visual QA (Layer 2)
- [ ] **FAIL** — Must revise (see flagged issues above)

步骤 5b：根据语义标准进行评估

对于每张幻灯片，请验证：

1. 主线一致性：这张幻灯片是否属于叙事流程？
2. 单一要点：能否用一句话说出唯一的核心要点？
3. 来源忠实度：每项事实是否都能追溯到章节内容？
4. 范围合规性：是否没有涉及禁止的话题（定价、收入等）？

步骤 5c：修复语义违规

如果任意一项语义检查未通过：

1. 找出违反哪些规则的幻灯片
2. 根据需要修改大纲
3. 重新生成受影响的幻灯片
4. 重新运行第 1 层，直至所有检查通过

第 1 层通过前，不要进入第 2 层。

---

第 2 层：视觉验证

仅在第 1 层通过后，验证视觉质量。

步骤 5d：生成缩略图网格

python scripts/thumbnail.py workspace/draft-v1.pptx workspace/review --cols 4

步骤 5e：视觉检查清单

检查每张缩略图，并确认：

检查项	是否通过？	需要修复
所有标题都是结论（而非标签）
没有文字小于正文
每张幻灯片的要点不超过 4 个
没有要点换行至 2 行或更多（过长）
每张幻灯片都有清晰的视觉层次
全程使用浅色背景
配色方案一致
没有文字被截断或重叠
留白充足（不拥挤）

步骤 5f：修复视觉违规

对于每项未通过的检查：

1. 记录幻灯片编号和问题
2. 找出根本原因（内容过于密集？字体过小？）
3. 在源 HTML／代码中修复
4. 重新生成受影响的幻灯片

步骤 5g：迭代

重复步骤 5d-5f，直至：

• 视觉检查清单中的所有项目均通过
• 缩略图审查达到专业水准
• 能通过“KubeCon 演讲”测试

阶段 6：最终交付

输出：保存到 workspace/[chapter-name]-slides.pptx

1. 将 workspace/draft-vN.pptx 重命名为 workspace/[chapter-name]-slides.pptx
2. 生成最终缩略图网格，供用户审阅：

   python scripts/thumbnail.py workspace/[chapter-name]-slides.pptx workspace/final --cols 4
   

3. 向用户展示：
   • 最终幻灯片数量
   • 与已批准大纲的任何偏差（及原因）
   • 缩略图网格图片（workspace/final-thumbnails.jpg）

常见错误，务必避免

这些错误曾导致演示实际出错。不要重蹈覆辙。

错误	发生了什么	如何避免
跳过设计声明	直接开始写代码 → 配色平淡，只有海军蓝／灰色	务必先输出设计方案
在标题中使用“第 X 章”	内容无法独立呈现，默认听众了解书籍背景	除非另有说明，否则面向任何受众进行构思
以目标开场	内容枯燥，缺少吸引力，听众容易走神	以范式转变或引人深思的问题开场
使用学术语言	“精通”“先修条件”等措辞让人觉得有门槛	使用亲切的措辞：“学完后……”
使用默认配色	海军蓝 + 灰色 = 公司模板风格	选择鲜明、有意设计且符合内容的配色
跳过缩略图检查	只有用户发现了视觉问题	交付前生成并检查缩略图
简略进行语义 QA	漏掉内容覆盖缺口，违反主线要求	完整进行逐页审核
直接使用 python-pptx	需要手动定位，迭代更困难	新建演示文稿时优先使用 html2pptx

规则：如果用户还得纠正设计或构思方面的问题，说明这项技能未达标。这些问题应在首次交付时就处理妥当。

将幻灯片转换为图像

若要对 PowerPoint 幻灯片进行视觉分析，请分两步将其转换为图像：

1. 将 PPTX 转换为 PDF：

   soffice --headless --convert-to pdf template.pptx
   

2. 将 PDF 页面转换为 JPEG 图像：

   pdftoppm -jpeg -r 150 template.pdf slide
   

   这会生成 slide-1.jpg、slide-2.jpg 等文件。

选项：

• -r 150：将分辨率设为 150 DPI（可根据质量和大小的平衡进行调整）
• -jpeg：输出 JPEG 格式（如需 PNG，可使用 -png）
• -f N：要转换的起始页（例如，-f 2 从第 2 页开始）
• -l N：要转换的结束页（例如，-l 5 在第 5 页结束）
• slide：输出文件的前缀

转换指定页码范围的示例：

pdftoppm -jpeg -r 150 -f 2 -l 5 template.pdf slide  # Converts only pages 2-5

代码风格指南

重要：为 PPTX 操作生成代码时：

• 编写简洁的代码
• 避免使用冗长的变量名和冗余操作
• 避免不必要的 print 语句

依赖项

必需的依赖项（应该已经安装）：

• markitdown：pip install "markitdown[pptx]"（用于从演示文稿中提取文本）
• pptxgenjs：npm install -g pptxgenjs（通过 html2pptx 创建演示文稿）
• playwright：npm install -g playwright（用于在 html2pptx 中渲染 HTML）
• react-icons：npm install -g react-icons react react-dom（用于图标）
• sharp：npm install -g sharp（用于 SVG 栅格化和图像处理）
• LibreOffice：sudo apt-get install libreoffice（用于转换 PDF）
• Poppler：sudo apt-get install poppler-utils（用于通过 pdftoppm 将 PDF 转换为图像）
• defusedxml：pip install defusedxml（用于安全解析 XML）

工件模板

创建所需的工作区工件时，请复制以下模板。

coverage-matrix.md 模板

# Coverage Matrix: [Chapter Name]

**Chapter path**: [apps/learn-app/docs/.../XX-chapter-name/]
**Chosen spine**: [Teaching / Chapter]
**Date**: [YYYY-MM-DD]

## Lesson Coverage

| # | Lesson Title | Key Concepts | Slide(s) | Status |
|---|--------------|--------------|----------|--------|
| 1 | | | | |
| 2 | | | | |
| 3 | | | | |
| ... | | | | |

## Learning Objectives Coverage

| Objective (from chapter README) | Slide(s) | Status |
|---------------------------------|----------|--------|
| | | |
| | | |

## Omissions

List any content intentionally excluded and justify why:

- **None** — all content covered

OR

- **[Topic]**: [Reason for exclusion]

## Verification

- [ ] Every lesson has ≥1 slide
- [ ] Every learning objective is addressed
- [ ] All omissions are justified above

semantic-qa.md 模板

# Semantic QA: [Chapter Name] Presentation

**Chosen spine**: [Teaching / Chapter]
**Date**: [YYYY-MM-DD]
**Reviewer**: Claude

## Semantic Checklist

| # | Check | Pass? | Issue (if failed) |
|---|-------|-------|-------------------|
| 1 | Slides follow chosen spine (no A→B→A jumps) | | |
| 2 | Each slide has ONE clear takeaway | | |
| 3 | No topics introduced outside approved outline | | |
| 4 | All terminology introduced before use | | |
| 5 | No invented facts, metrics, or claims | | |
| 6 | No forbidden topics (pricing, revenue, market size) | | |
| 7 | Coverage-matrix shows 100% lesson coverage | | |

## Slide-by-Slide Audit

| Slide | Title | Spine Role | Single Takeaway | Issues |
|-------|-------|------------|-----------------|--------|
| 1 | | | | |
| 2 | | | | |
| 3 | | | | |
| ... | | | | |

## Flagged Issues

List all issues found during review:

1. [None found]

OR

1. **Slide X**: [Description of issue]
2. **Slide Y**: [Description of issue]

## Forbidden Topic Scan

Searched for and found:

- [ ] Business models / pricing → **Not found** / Found on slide(s): ___
- [ ] ARR / MAU / revenue → **Not found** / Found on slide(s): ___
- [ ] Market sizing → **Not found** / Found on slide(s): ___
- [ ] "Digital FTE economics" → **Not found** / Found on slide(s): ___

## Final Decision

- [ ] **PASS** — All semantic checks pass. Ready for Layer 2 (visual QA).
- [ ] **FAIL** — Issues found above must be fixed before proceeding.

### If FAIL, action plan:

1. [What needs to change]
2. [Which slides to regenerate]