jingyibi93/ppt-speaker-notes 教程

jingyibi93/ppt-speaker-notes 是一个 Codex skill，用来把旧的 PPT、PPTX 或 PDF 演示文稿整理成自然的演讲备注；它适合处理视觉或设计含量较高、原本没有讲稿的 deck，并能在 PPTX 输入时生成一个新的 _with_notes.pptx 副本，把逐页讲稿写进 PowerPoint 备注区。

这个项目的核心思路不是让模型只读幻灯片文字，而是先准备整套材料：能渲染 PDF 时看每页画面，能读取 PPTX 时保留结构和媒体关系，再按角色、专业方向、汇报场景写出中文、英文或双语讲稿。最终常见产物是 <deck-name>_speaker_notes.md，如果有 PPTX，还会多一个不会覆盖原文件的 <deck-name>_with_notes.pptx。

一分钟先跑通入口

本仓库默认分支是 main，根目录有 SKILL.md、README.md、scripts/ 和 references/。本地安装到 Codex skills 目录时，可以克隆后复制整个目录：

git clone https://github.com/jingyibi93/ppt-speaker-notes.git
mkdir -p ~/.codex/skills
cp -R ppt-speaker-notes ~/.codex/skills/ppt-speaker-notes

重启 Codex 或新开会话后，直接用自然语言触发。例如中文讲稿：

用 ppt-speaker-notes 给这个 PPT 生成中文讲稿：我的作品集.pptx

英文或双语也能在请求里指定：

Use ppt-speaker-notes to generate English speaker notes for this deck: my-presentation.pptx
Use ppt-speaker-notes to create bilingual speaker notes for this presentation.

如果要提高视觉理解稳定性，最推荐同时给出同一份演示的 PPTX 和 PDF：

Use ppt-speaker-notes with these two files:
portfolio.pptx
portfolio.pdf

Use the PDF for visual analysis and write the notes back into a new PPTX copy.

为什么它偏爱 PPTX 加 PDF

视觉型演示里，页眉、版式、图像节奏、作品集场景和材料质感往往比幻灯片文字更重要。PPTX 适合保存页结构、提取文本和写回备注；PDF 则适合稳定渲染成逐页图片，让 Codex 按画面证据理解每页在强调什么。

仓库明确避免默认调用 PowerPoint、Keynote 或 LibreOffice 做 PPT 转换。这个选择很务实：桌面软件可能弹权限窗口，转换后也可能发生版式漂移。更稳的路径是先由人从原演示导出匹配 PDF，再用 Poppler 或 PyMuPDF 渲染页面。

如果只有 PPTX，而且任务要求分析视觉或设计细节，skill 应先提醒补充同名 PDF，而不是直接从抽取文本生成“看似完整”的讲稿。只有在明确接受文本草稿时，才应把结果标成 text-only。

本地依赖看三类能力

scripts/check_render_environment.py 会检查渲染和媒体支持，返回一份 JSON。最关键的是 PDF 是否能稳定渲染为图片：Poppler 的 pdftoppm 或 Python 的 PyMuPDF 任意一个可用即可。

python scripts/check_render_environment.py

macOS 上推荐先准备这些依赖：

brew install poppler
brew install ffmpeg
python3 -m pip install PyMuPDF pypdf Pillow

其中 Poppler 或 PyMuPDF 负责 PDF 转图片，ffmpeg 和 ffprobe 用于提取视频预览帧，Pillow 用于 GIF 关键帧和联系表，pypdf 用于 PDF 文本提取。缺少某项并不总是失败，但视觉分析要可靠，至少要能产出逐页图片。

准备材料的脚本怎么工作

真正进入写稿前，skill 会调用 scripts/prepare_ppt_speaker_notes.py。它能读取 .ppt、.pptx、.pdf，默认输出到 <deck-name>_speaker_note_materials，也能用 --output 指定临时目录。

python scripts/prepare_ppt_speaker_notes.py INPUT_FILE --output /tmp/ppt-speaker-notes-demo --require-render

--require-render 很重要：视觉或设计类 deck 如果没有渲染出每页图片，就应清楚失败，而不是悄悄降级为只读文字。准备成功后会看到 manifest.json、deck_context.md、slides/、contact_sheets/，如果文件里有 GIF 或视频，还可能出现 animated_media/ 和 animated_previews/。

deck_context.md 适合查看整体页数、渲染状态、媒体状态和每页摘要；contact_sheets/ 适合快速判断整套 deck 的节奏、章节变化和重复视觉语言；slides/ 才是逐页讲稿的主要画面依据。

讲稿语气由三个选项决定

这个 skill 不只生成“第几页应该说什么”，还会先确定演讲画像：角色、专业方向、使用场景。角色包括学生、老师、设计师、职场人；专业方向包括建筑及室内设计、交互设计、视觉传达、艺术设计、平面设计、品牌设计；场景包括正式汇报、课堂讲解、作品集答辩、轻松分享。

这些选项会影响表达方式。学生更强调过程和反思，设计师更强调意图、取舍和专业判断，职场人更强调目标和沟通效率。作品集答辩会更关注个人贡献和迭代，课堂讲解会更慢、更解释性，正式汇报则更清晰、克制和结构化。

中文请求默认输出中文讲稿，英文请求默认输出英文讲稿，明确要求双语时按中英双结构输出。如果角色、专业、场景或保存位置没说清楚，skill 会一步一步问，而不是一次抛出长表单。

写回 PPTX 时只生成副本

Markdown 讲稿确认后，scripts/write_notes_to_pptx.py 负责把逐页 讲稿 字段写入 PPTX 的 speaker notes。它不会改原文件，默认输出 <deck-name>_with_notes.pptx。

python scripts/write_notes_to_pptx.py INPUT.pptx OUTPUT_FOLDER/deck_speaker_notes.md --output OUTPUT_FOLDER/deck_with_notes.pptx

脚本会解析 Markdown 中的页码和字段，找到或创建每页 notes slide，再把讲稿文本写进去。默认字段名是 讲稿，英文或自定义格式时可通过 --field 指定。

适合的场景和边界

jingyibi93/ppt-speaker-notes 很适合给作品集、课程展示、设计汇报、品牌方案或旧 PPT 补讲稿。它的优势在于把视觉证据、演讲语气和文件安全分开处理，尤其适合那些“页面很好看，但备注区是空的”的演示文稿。

边界也要提前说清：它不是 PPT 美化工具，不负责重新设计版式；也不是强制转格式工具，不建议靠 soffice 把 PPTX 硬转 PDF。动画、视频、声音和交互效果如果只存在于源文件里，PDF 静态页通常只能提供一帧证据，需要额外素材或录屏才适合深入分析。

如果只记一个工作顺序，就是先检查渲染环境，再用 PDF 准备可看的逐页材料，确认讲稿 Markdown，最后再把讲稿写回新的 PPTX 副本。这样做慢一点，但能把视觉误读、文件覆盖和桌面软件弹窗这三类风险降下来。