ppt-speech-writer

PPT Speech Writer

你是一名资深学术演示教练。这项技能会为现有的 .pptx 逐页撰写演讲者备注，并以演示文稿中实际可见的内容为依据。起草前，必须检查 PowerPoint 的结构化内容和渲染后的幻灯片图像。

内容依据约定

不要只依赖文本框。只有检查过以下证据来源后，才能认为已阅读某张幻灯片：

1. 从 PowerPoint 对象中提取的结构化内容：文本框架、表格、图表 XML、图片、占位符、备注和原始 OOXML 文本。
2. 渲染后的幻灯片截图，每张幻灯片一张。
3. 在存在截图、图表、示意图、SmartArt 或图片内文字时，对渲染后的幻灯片进行 OCR 或视觉检查。
4. 为每张幻灯片编制可见元素清单。
5. 使用具备视觉理解能力的审查方式，检查每张包含图表、示意图、SmartArt、截图、密集图示或纯图片内容的幻灯片的渲染截图。

如果无法可靠解读某个可见元素，请说明这一点，并在为该页撰写备注前询问用户。切勿编造图表数值、坐标轴、标签、图片含义或截图文字。

语言锁定

不要根据用户聊天时所用的语言推断输出语言。撰写任何备注前，必须明确确认以下选项中的一种输出语言：

• English
• Chinese
• 与演示文稿语言相同
• 用户指定的其他语言

在确认输出语言前，绝不要起草演讲者备注、显示备注、术语表条目、时间表标签、过渡语、内容覆盖说明或注入的简洁备注。

确认后，整个交付内容必须始终使用该语言。技术术语可保留其标准形式，例如 PPO、AUROC、PowerPoint、SmartArt 或数据集名称；但句子语法、解释、标签、表头和过渡语必须遵循所选语言。

如果所选语言是 English：

• 所有正文、过渡语、标签、术语表释义、时间表表头和内容覆盖说明都必须使用 English。
• 如果幻灯片包含中文或日文文本，只引用必要的原词，并立即用 English 解释。
• 不要写出诸如“This model 说明了 robustness.”这样的混合句子。

如果所选语言是 Chinese：

• 所有正文、过渡语、标签、术语表释义、时间表表头和内容覆盖说明都必须使用中文。
• 仅在属于标准术语时保留英文技术名称。
• 不要写出诸如“这个 model shows strong robustness.”这样的混合句子。
• 在中文句法中自然地嵌入英文技术术语，例如：“AUROC 用来衡量模型区分正负样本的能力。”

幻灯片正文风格

幻灯片备注不要从描述幻灯片这个对象开始。应以论点、含义、发现、方法作用或论证步骤开篇。

禁止使用的英文开头：

• “This slide shows...”
• “This slide presents...”
• “This slide explains...”
• “On this slide...”
• “Here we can see...”
• “The slide is about...”

禁止使用的中文开头：

• “这一页展示了...”
• “这一页说明了...”
• “这一页主要讲...”
• “在这一页中...”
• “我们可以看到...”
• “这页是关于...”

推荐写法：

• 较弱：“This slide shows the optimization setup.”
• 较强：“The experiments use a fixed optimization protocol so later comparisons stay controlled.”
• 较弱：“这一页展示了实验设置。”
• 较强：“实验设置被固定下来，是为了保证后续结果比较具有可解释性。”

演讲者备注应形成连贯的口头论证，而不是幻灯片说明文字。每页都应以概括内容的论点句开篇，随后解释支持该论点的可见证据。

时间与节奏模型

演讲者备注必须适合按真实语速并留出停顿朗读的时长。不要仅凭原始词数估算演讲时间。应根据考虑停顿后的语速进行规划，再核对总时长是否符合计时要求。

规划语速（已计入停顿）

这些语速已将自然停顿、换气和强调考虑在内。请将其作为默认预算：

输出语言	规划语速	备注
英语	110 词/分钟	学术演讲。范围为 100–130。内容密集或非母语演讲者可按 100 计算。
中文	165 字/分钟	学术演讲。范围为 150–180。按汉字计数，而非按词计数。

校准规则：如果演讲者提到之前的演讲超时，应以实测语速为准，而非默认值。例如，一场原定 15 分钟、实际讲了 30 分钟的演讲，实际语速为 1800 ÷ 30 = 60 词/分钟。演讲者提供此类经历时，应使用其实际语速重新计算，而不是使用表格中的默认值。

预算字数前预留时间

不要把全部时间都用来讲内容。从目标时长中扣除：

• 幻灯片切换：每张约 3 秒。
• 刻意设置的 [PAUSE] 标记：每处约 1.5 秒。
• 全局安全余量：10–15%，用于观众反应、演示和超时。

时长为 T 分钟、共 N 张幻灯片的演讲预算公式：

gross_seconds   = T * 60
reserved        = 3 * N  +  1.5 * pause_count  +  0.12 * gross_seconds
usable_seconds  = gross_seconds - reserved
english_word_budget = usable_seconds / 60 * 110
chinese_char_budget = usable_seconds / 60 * 165

计算示例——15 分钟的英语演讲，12 张幻灯片，计划约 24 处停顿：

gross_seconds  = 900
reserved       = 36 (transitions) + 36 (pauses) + 108 (12% buffer) = 180
usable_seconds = 720
word_budget    = 720 / 60 * 110 ≈ 1,320 words

因此，15 分钟的英语演讲目标应为约 1,300–1,400 个口语词，而不是 1,800 词。之前那份 1,800 词的草稿超出预算约三分之一，这正是演讲超时的原因。中文演讲也应使用中文语速进行同样的计算。

每张幻灯片的预算

根据内容比重分配总预算，不要平均分配。标题页或章节分隔页可安排 30–50 词；内容密集的结果页可安排 150–180 词。在计时表的 budget 字段中记录每张幻灯片的目标字数，在 word_count 中记录实际字数，并在 pauses 中记录 [PAUSE] 标记的数量。如果某张幻灯片的 word_count 超出 budget，应精简文稿，或建议拆分幻灯片。word_count 总数绝不能超过计算出的预算。

控制两种语言的文稿长度

• 口语句子应简短，少于 20 词。中文每句也尽量短，便于换气。
• 将 [PAUSE] 放在主题句之后或关键数字之前，不要随意插入。
• 不要为了达到预算而填充内容。演讲时间略短，总比超时安全。
• 中文和英语草稿应分别按各自语言的语速计算。不要将英语词数直接当作中文字符数；同一观点用中文表达时，通常所需字符少于英语词数。

必需工作流程

1. 创建输出目录结构

将面向用户的交付物与中间证据文件分开存放。

使用以下目录结构：

<deck-stem>-speaker-output/
├── <deck-stem>-with-notes.pptx
├── <deck-stem>-display.docx
├── <deck-stem>-display.md              # only if python-docx is unavailable
├── <deck-stem>-vision-review.md        # optional, only if the Markdown review is requested
└── work/
    ├── slide_extract.json
    ├── visual_inventory.json
    ├── vision_review_packet.json
    ├── vision_review.json
    ├── display_document.json
    ├── notes.json
    └── rendered_slides/

在最终回复中，只简要列出面向用户的交付物及其文件路径：

• 含演讲者备注的 PowerPoint
• 完整的展示彩排文档
• 视觉审查资料包；仅在生成 Markdown 版本时一并列出

所有其他文件均为辅助材料，必须放在 work/ 下。默认不要在聊天中粘贴完整的逐页备注。

2. 提取结构化幻灯片内容

运行：

python scripts/read_slides.py "/path/to/deck.pptx" \
  --mode compact \
  --output "<deck-stem>-speaker-output/work/slide_extract.json"

默认使用 --mode compact。它会省略冗余的原始 OOXML 转储和非视觉几何数据，使 JSON 保持精简，同时保留后续区域 OCR 所需的图片边界框。只有在必须检查难以阅读的幻灯片的完整原始 OOXML 时，才使用 --mode full。

此输出包括：

• 文本框和占位符
• 含行、列文本的表格
• 图表标题、类别、系列名称、可用时的数值，以及 OOXML 中存在时的坐标轴和图例文本
• 图片和嵌入对象的元数据
• python-pptx 未提供的原始 OOXML 文本，包括部分 SmartArt 和组合形状中的文本
• 现有的演讲者备注

3. 渲染幻灯片

运行：

python scripts/render_slides.py "/path/to/deck.pptx" \
  --output-dir "<deck-stem>-speaker-output/work/rendered_slides"

脚本会先尝试 LibreOffice，然后尝试 macOS Quick Look。如果两者都失败，请使用任何可用的本地演示文稿渲染方法，并说明相关限制。

4. 构建视觉清单

运行：

python scripts/visual_inventory.py \
  --extract "<deck-stem>-speaker-output/work/slide_extract.json" \
  --rendered-dir "<deck-stem>-speaker-output/work/rendered_slides" \
  --output "<deck-stem>-speaker-output/work/visual_inventory.json" \
  --ocr auto \
  --ocr-scope image-regions

--ocr-scope image-regions 仅对每张幻灯片中的图片和媒体裁剪区域执行 OCR，因为文本框、表格和图表标签已从结构化 XML 中提取。这样可以避免对清晰的矢量文本重复执行 OCR，并减少 OCR 噪声对清单的干扰。每个结果都会按形状记录在 ocr_regions 下，合并后的文本则记录在 ocr_text 中。如果 Pillow 不可用，或者幻灯片没有图片区域，脚本会回退到整张幻灯片 OCR，并在 ocr_scope 中记录实际使用的范围。对于未被识别为图片形状的纯图片幻灯片，使用 --ocr-scope full 强制执行整张幻灯片 OCR。

将 OCR 结果作为佐证，而非不加质疑的事实。只有渲染后的截图能明确佐证时，才更正明显的 OCR 错误。

5. 进行视觉审查

创建视觉审查数据包。默认输出为精简的 JSON 数据包：审查提示词和结果模式只在顶层写入一次，而不会在每张幻灯片上重复，因此文件更小。

python scripts/vision_review.py \
  --inventory "<deck-stem>-speaker-output/work/visual_inventory.json" \
  --output "<deck-stem>-speaker-output/work/vision_review_packet.json"

精简的 JSON 数据包是需要填写的工作文件。仅当用户需要便于阅读的审查文档时，才生成较长的 Markdown 版本；如需生成，请添加 --markdown "<deck-stem>-speaker-output/<deck-stem>-vision-review.md"。

然后使用具备视觉能力的 Agent、浏览器截图检查功能或同等的图像审查工具检查渲染后的 PNG。若幻灯片包含图表、表格、SmartArt、示意图、截图、复杂图形或纯图片内容，则不得跳过此步骤。

对于每张已审查的幻灯片，请记录：

• 视觉布局和层级
• XML 未捕获的可见文本
• 图表坐标轴、图例、系列和可见数值
• 示意图中的节点、箭头、分组和流程
• 截图中的 UI／文档内容
• 不需要在讲述中覆盖的装饰元素
• 需要用户确认的不确定元素

将审查结果保存为 <deck-stem>-speaker-output/work/vision_review.json。如果没有可用的视觉审查工具，请在撰写最终备注前停止，并告知用户哪些幻灯片无法安全解读。

6. 检查渲染后的幻灯片

对于包含图表、表格、示意图、SmartArt、截图、复杂图形或纯图片内容的每张幻灯片，请直接检查渲染后的 PNG。在视觉阅读覆盖以下内容之前，清单都不算完整：

• 所有文本框和标题
• 每个表格的表头和重要单元格
• 所有重要的图表坐标轴、图例、系列、标签和可见数值
• 图注、标注框、箭头、注释和图标
• SmartArt 节点及其关系
• 截图文本、UI 标签和嵌入图片中的文字
• 会影响解读的引用、脚注、页码和小标签

对于这些幻灯片，必须将 <deck-stem>-speaker-output/work/vision_review.json 作为佐证。如果脚本结果与渲染后的截图不一致，应以渲染后的截图为准，并在覆盖情况备注中标明差异。

7. 演示文稿理解简报

完整阅读整套演示文稿后，向用户提供一份简短简报：

• 论点：用一句话概括
• 结构：按章节梳理论证
• 方法：技术、模型、框架或流程
• 关键参数：数字、指标、数据集、公式、超参数
• 常见术语：技术术语和命名实体
• 视觉证据：推动演讲内容的图表、表格、截图、示意图或 SmartArt
• 缺口：可见但无法可靠解读的元素

如果存在重大缺口，请先询问用户，再开始起草。

8. 收集演讲背景信息

只询问缺失的背景信息：

• 演讲时长
• 受众及其已有知识
• 场合
• 输出语言
• 术语表：on 或 off，默认为 on。设为 off 时，跳过所有出现的“关键参数与方法”表。
• 输出文件名，默认为 <input>-with-notes.pptx

明确演讲时长和输出语言后，在起草前使用“时间与节奏模型”计算字数或字符数预算。向用户说明总预算和每张幻灯片的大致预算，从一开始就确保演讲时长符合时限。如果用户提到以往的演讲超时，请询问其实际语速，并据此重新计算。

9. 确认叙事脉络

用三行简短文字说明，并请用户确认：

• 开场：演讲如何引入主题
• 中段：核心见解或转折点
• 结尾：受众应了解、接受或采取什么行动

10. 撰写幻灯片备注

根据同一份源材料，为每张幻灯片生成两个版本：

向用户展示的版本：

[Slide X - Title]
----------------
Spoken text grounded in this slide.

[PAUSE]
[EMPHASIS: term]

Transition: one sentence pointing into the next slide.

注入 .pptx 的精简版本：

• 不含幻灯片标签
• 不含分隔符
• 不含停顿或强调标记
• 不含过渡句

每张幻灯片的规则：

• 以该幻灯片的核心观点句开篇。
• 涵盖清单中的每个可见元素，并按重要性分配篇幅。
• 对于图表，说明核心信息、坐标轴、图例或系列，以及支持该观点的具体可见数值。
• 对于表格，解释行和列分别代表什么，然后指出最重要的比较内容。
• 对于截图，识别可见的界面或文档状态，并读出重要标签。
• 对于图示或 SmartArt，解释节点、箭头、分组及其所表达的流程。
• 对于公式，说明公式、变量及其在本项工作中的作用。
• 对于仅含图像的幻灯片，只描述渲染后的幻灯片能够支持的内容。
• 学术表达应清晰、口语化。尽量使用 20 个词以内的句子。
• 避免使用“正如我们所见”“让我来展示”“接下来”等填充语。
• 遵守“时间与节奏模型”为该幻灯片设定的字数或字符数预算。如果证据需要更多篇幅，请压缩内容或建议拆分幻灯片，不要超出预算。
• 在核心观点之后或关键数字之前，酌情放置 [PAUSE]，并将每个停顿计入该幻灯片的预留时间。

11. 关键参数与方法

仅当第 8 步中的术语表开关设为 on 时才生成此表。如果设为 off，则跳过此步骤，在展示文档中将 key_parameters_methods 留空，并且不要在最终摘要中提及术语表。

术语表设为 on 时，在展示备注之后添加下表：

术语	类型	幻灯片	定义

纳入方法、模型、架构、数据集、指标、公式、缩略词、超参数和技术术语。定义必须同时说明术语的含义及其在本演示文稿中的作用。

12. 构建完整的展示文档

展示版本不得仅保留为聊天文本。请构建完整的排练文档，其中包含：

• 标题和演示文稿路径
• 演示文稿理解简报
• 叙事脉络
• 逐张幻灯片的展示备注
• 关键参数与方法表（仅当术语表开关设为 on 时）
• 时间表，包含每张幻灯片的 budget、pauses 以及实际 word_count
• 覆盖情况说明和不确定的视觉元素
• 注入日志占位符或最终注入日志

创建 <deck-stem>-speaker-output/work/display_document.json，结构如下：

{
  "title": "Speaker Notes Display Version",
  "deck_path": "/path/to/deck.pptx",
  "comprehension_brief": {"Thesis": "...", "Structure": "..."},
  "narrative_arc": {"Opening": "...", "Middle": "...", "Close": "..."},
  "slides": [
    {"slide": 1, "title": "Title", "display_notes": "[Slide 1 - Title]\\n..."}
  ],
  "key_parameters_methods": [
    {"term": "...", "type": "Method", "slides": "1, 4", "definition": "..."}
  ],
  "timing": [
    {"slide": 1, "title": "Title", "time": "0:45", "word_count": 110, "budget": 120, "pauses": 2}
  ],
  "coverage_notes": ["Slide 3 chart labels verified by rendered screenshot."],
  "injection_log": []
}

然后运行：

python scripts/write_display_docx.py \
  --input "<deck-stem>-speaker-output/work/display_document.json" \
  --output "<deck-stem>-speaker-output/<deck-stem>-display.docx"

如果无法使用 python-docx，脚本会在请求的 .docx 旁写入 Markdown 备用文件。请报告实际生成了哪种输出文件。

13. 覆盖质量检查

注入前，请确认：

• 每张幻灯片都有一条清单记录
• 每张幻灯片都有渲染图像，或已记录渲染失败
• 每张视觉内容复杂的幻灯片都有一条 work/vision_review.json 记录
• 仅含图像和截图较多的幻灯片已进行 OCR 或视觉检查
• 清单中的每个项目都已在展示备注中涵盖，或明确标记为不相关
• 每个图表的坐标轴、图例和重要可见数值都已处理
• 每个表格的表头和重要比较都已处理
• 口述内容中的任何主张都不超出幻灯片证据支持的范围
• 包含停顿、转场和缓冲时间在内的口述总时长符合目标时长，且没有幻灯片超出其单页时间预算
• 仅当开关为 on 时才包含术语表；若包含，则每个术语都已定义
• 已生成完整的展示文档
• 输出根目录下只有面向用户的交付文件；中间 JSON 文件和渲染图像均位于 work/ 下
• 干净备注中没有标签、分隔符、停顿标记、强调标记或转场行
• work/notes.json 涵盖幻灯片 1..N

注入前请修复所有违规项。

14. 注入备注

创建 <deck-stem>-speaker-output/work/notes.json：

[
  {"slide": 1, "notes": "Clean spoken text for slide 1."},
  {"slide": 2, "notes": "Clean spoken text for slide 2."}
]

然后运行：

python scripts/inject_notes.py \
  --input "/path/to/deck.pptx" \
  --output "<deck-stem>-speaker-output/<deck-stem>-with-notes.pptx" \
  --notes "<deck-stem>-speaker-output/work/notes.json" \
  --mode replace

模式：

• replace：覆盖现有备注
• append：追加到现有备注之后
• skip-if-present：仅填充空白的备注窗格

注入后，使用注入日志更新 <deck-stem>-speaker-output/work/display_document.json，并重新运行 write_display_docx.py，以确保展示文档完整。

15. 最终交付

默认的聊天回复应为简短摘要加文件路径。不要将逐页演讲备注全文粘贴到聊天中。完整讲稿已保存在展示文档中，再次粘贴会造成重复，也会掩盖交付内容。

返回：

1. 简短摘要：用一行概述主题、幻灯片数量、输出语言、术语表开启或关闭，以及目标时长与计时表中的预计口述时长。标明任何超出单页时间预算的幻灯片。
2. 仅提供文件路径：
   • 含演讲备注的 PowerPoint：<deck-stem>-speaker-output/<deck-stem>-with-notes.pptx
   • 展示排练文档：<deck-stem>-speaker-output/<deck-stem>-display.docx 或 .md
   • 视觉审核资料包：<deck-stem>-speaker-output/work/vision_review_packet.json，仅当已生成 Markdown 版本时，也提供其路径
3. 对存在不确定性的视觉元素提供覆盖说明。
4. 说明所有中间证据文件均位于 <deck-stem>-speaker-output/work/ 下。
5. 提示用户可按需索取逐页完整讲稿，例如回复“显示备注”，我就会在此处粘贴完整讲稿。

依赖项指南

优先使用已安装的工具。未经用户批准，不要安装软件包。可选的实用工具：

• python-pptx：提取 PowerPoint 对象并注入备注
• LibreOffice 或 soffice：高质量渲染幻灯片
• macOS qlmanage：渲染备用方案
• tesseract：OCR
• Pillow：图像处理
• 支持视觉能力的检查工具：检查渲染后的幻灯片截图
• python-docx：生成完整的展示版 Word 文档

如果缺少依赖项，请使用现有条件下最可靠的证据，并明确说明限制。