先理解整套演示，再生成逐页讲稿；只把干净、可朗读的正文写入 PowerPoint 备注，并在交付前重新打开验证。
presentation-speaker-notes 是一个 Codex Skill 和 Python CLI。它接收已有的 .pptx，创建一份新的、可继续编辑的 PowerPoint，并为每一页写入与听众、时长、页面角色和表达风格匹配的演讲者备注。
它不是“逐页把文字扩写一遍”。系统会先分析整套演示的目标、章节、叙事和风险，再分配时长、生成 Slide Brief、写逐页讲稿、检查跨页一致性，最后才接触 PowerPoint 备注区。
普通的 PPT 讲稿生成很容易出现四类问题：
- 每一页各写各的，整套演示没有叙事；
- 把标题、编号和页面文字机械念一遍；
- “进一步看”“这里可以看到”等模板词跨页重复；
- 把建议时间、备用稿、模型状态和“待复核”一起塞进备注。
本项目把“内容工作台”和“最终讲稿”分开。质量报告可以复杂，但 PowerPoint 备注必须简单：默认只包含现场可以直接朗读的 main_script 正文。
flowchart LR
A["输入 PPTX"] --> B["预检与安全复制"]
B --> C["提取文字、表格、图表与已有备注"]
C --> D["渲染页面并理解整套叙事"]
D --> E["分配时长与解析表达风格"]
E --> F["Slide Brief + 三层讲稿"]
F --> G["事实、口语、时长与一致性复核"]
G --> H["只写入最终主讲稿"]
H --> I["重新打开并验证新 PPTX"]
文件处理和模型推理被刻意分层：确定性代码负责复制、解析、Schema、备注写入和完整性验证；模型只负责语义理解与语言生成。即使生成内容听起来流畅，也不能绕过文件安全和交付门禁。
| 能力 | 具体行为 |
|---|---|
| 整套理解 | 先识别目标、章节、叙事弧、页面角色、缺口、重复与风险，再逐页写稿 |
| 讲稿模式 | 支持 verbatim 逐字稿、outline 提纲和 hybrid 混合模式 |
| 三层脚本 | 主讲稿、可选扩展稿、时间不足时的压缩稿分别保存 |
| 时长控制 | 按总时长、章节和单页要求分配秒数，并估算实际朗读时间 |
| 风格引擎 | 10 个 0–100 表达维度、10 个预设、自然语言偏好与逐页覆盖 |
| 内容边界 | strict、explanatory、research_enhanced 三种模式 |
| 备注策略 | replace、preserve、merge，正式交付默认 replace |
| 局部修订 | 可按页码或章节重试，随后重新执行整套一致性检查 |
| 安全交付 | 不覆盖源文件；验证页数、顺序、Slide XML、关系、Notes 拓扑和备注正文 |
| 可恢复运行 | 使用源文件、配置、Prompt、Schema、资源和实现指纹判断缓存是否仍然有效 |
风格不是一个模糊的“更专业一点”。系统使用以下十个可审计维度：
professionalism、humor、detail、storytelling、emotionality、interaction、persuasiveness、accessibility、directness、pace。
内置预设覆盖正式汇报、管理层简报、深度讲解、培训、销售提案、学术表达、故事化和自然互动等场景。页面类型、章节和单页可以继续覆盖，但医疗安全、临床数据、风险和合规规则始终最后生效。
从 GitHub Releases 下载 presentation-speaker-notes-1.0.0-skill.zip，解压后把其中的 presentation-speaker-notes/ 放入 Codex Skills 目录：
mkdir -p ~/.codex/skills
cp -R presentation-speaker-notes ~/.codex/skills/
cd ~/.codex/skills/presentation-speaker-notes
python -m pip install .然后在 Codex 中附上 .pptx，直接说：
请使用 $presentation-speaker-notes 处理我附上的 PPTX。
听众：第一次了解这个主题的非专业听众
总时长：20 分钟，预留 3 分钟问答
讲稿：混合模式，专业但不生硬，结论先行
内容边界：只使用 PPT 和我提供的材料，不补充未经核验的外部事实
已有备注：替换
交付：生成新的 PPTX，源文件不要修改；备注区只保留最终可朗读正文
更完整的对话模板、逐页反馈方式和验收清单见 中文用户手册。
直接安装 Release wheel：
python -m pip install \
https://github.com/Nathanielguo/presentation-speaker-notes/releases/download/v1.0.0/presentation_speaker_notes-1.0.0-py3-none-any.whl或从源码安装：
git clone https://github.com/Nathanielguo/presentation-speaker-notes.git
cd presentation-speaker-notes
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[dev]'检查安装：
presentation-notes --version
presentation-notes --help准备环境变量：
cp .env.example .env
# 在 .env 中填写 OPENAI_API_KEY
set -a
source .env
set +a运行模型驱动的完整流程：
presentation-notes run \
--input ./deck.pptx \
--config ./examples/config-product-presentation.json \
--provider openai \
--output ./output解析自然语言表达偏好：
presentation-notes style \
--text '结论先行，产品部分详细一些，数据页严谨，不要像念报告' \
--preset professional_engaging \
--output ./style-preference.json需要单独控制流程时，可以使用九个子命令：
inspect render analyze generate retry
inject validate style run
例如只重写第 2、4 页：
presentation-notes retry \
--project ./output/<project-id> \
--slides 2,4没有模型凭据时，可以验证 PPTX 复制、解析、数据合同、备注写入和重新打开链路：
presentation-notes run \
--input ./tests/fixtures/executive-review-synthetic.pptx \
--config ./examples/config-executive-review.json \
--provider offline \
--artifact-purpose engineering_test \
--project-id offline-smoke-test \
--output ./output离线产物只会写入 engineering-preview/，文件名包含 NON_DELIVERABLE。它可以证明工程链路，不代表真实模型的视觉理解或讲稿质量，也不能生成正式交付文件。
每次运行创建独立项目，并先复制源文件：
output/<project-id>/
├── source/original.pptx
├── slides/ # 页面图、原始文字、表格、图表和元数据
├── deck-manifest.json
├── deck-analysis.json
├── slide-briefs.json
├── speaker-profile.json
├── style-resolution.json
├── style-report.json
├── speaker-script.md # 只包含最终主讲稿
├── speaker-script-main.md
├── speaker-script-optional-expansion.md
├── speaker-script-compressed.md
├── quality-report.json
├── quality-report.md
├── run-log.jsonl
├── final/*_with-speaker-notes_*.pptx
└── engineering-preview/*_NON_DELIVERABLE.pptx
正式 PowerPoint 备注默认严格等于对应页面的最终主讲稿，不包含：
- 建议时间或倒计时；
- 备用扩展稿或压缩稿；
- “待复核”、风险标记或置信度；
- provider、模型、缓存或工程诊断；
- 互动建议、转场标签或内部字段名。
这些信息保留在独立 JSON/Markdown 报告中，不污染现场讲述正文。
| 模式 | 允许范围 | 典型场景 |
|---|---|---|
strict |
只使用 PPT、已有备注和用户提供的材料 | 医疗、合规、财务、正式汇报 |
explanatory |
可增加解释、类比和过渡，但不能添加外部事实 | 培训、产品介绍、一般科普 |
research_enhanced |
只有显式允许并提供、核验来源后才使用 | 需要外部证据的演示 |
医疗和患者教育默认采用保守边界。系统不得虚构研究、指南、适应证、剂量、禁忌、疗效、安全结论或诊疗建议；高风险声明依赖不可读内容时，正式写入会被阻断。
- Python 3.11+
- PowerPoint
.pptx文件；不支持旧.ppt - LibreOffice (
soffice/libreoffice) 用于可移植页面渲染 - Poppler (
pdftoppm) 用于 PDF 到页面图转换 - 模型凭据仅在选择外部模型 provider 时需要
PowerPoint 本身不是包级备注写入与验证的硬依赖，但最终交付仍建议在目标电脑的 Microsoft PowerPoint 演讲者模式中打开一次。第三方库无法完整模拟每个字体、动画、嵌入对象和桌面版本。
东亚文字渲染采用保守策略：原始 slide.png 始终保留；只有确认目标区域为空、坐标映射可靠且不存在可见字形证据时，才生成单独的 slide-semantic-overlay.png。语义辅助图会明确标记降级，不能冒充 PowerPoint 原生保真。
Version 1.0.0 的发布证据：
170 passed，覆盖单元、集成、端到端和发布包合同；- Python 源码编译通过；
- 官方 Skill
quick_validate.py校验通过； - wheel 在独立虚拟环境中安装并验证 CLI 与 33 项运行时资源；
- Skill ZIP 解压后再次完成结构校验与源码编译；
- 真实 25 页 ZEISS PPTX 完成离线工程链路、Notes 精确投影和包级重新打开验证；
- offline provider 的正式交付阻断已验证有效。
本次发布没有使用真实在线模型凭据完成内容质量验收。因此可确认的是工程链路、数据合同、文件安全和交付门禁；不能据此宣称离线文案等价于真实多模态模型质量。
运行测试：
pytest
python -m compileall src- PPTX 文件默认在本地复制、解析、写入和验证；
- 只有显式选择外部 provider 时，才会发送模型所需的最小页面上下文；
- API Key 只从环境变量读取，不应写入配置、日志、报告或仓库；
- 页面截图、已有备注、客户名称和患者信息都应视为敏感数据；
- 处理受监管或机密材料前，应核对模型服务商的数据保留和区域策略；
- 外部模型调用前，应尽可能去标识化个人信息和受保护健康信息。
presentation-speaker-notes/
├── SKILL.md # Codex Skill 行为合同
├── agents/openai.yaml # Skill 展示与默认提示
├── src/presentation_speaker_notes/ # Python 包与 CLI
├── config/ # 默认配置和预设
├── schemas/ # 可验证的数据合同
├── prompts/ # 分阶段模型提示
├── references/ # 讲稿、时长、风格与安全规则
├── examples/ # 场景配置示例
├── scripts/build_release.py # 可复现 Skill 打包器
└── tests/ # 单元、集成、E2E 与合成 PPTX fixtures
- 只支持
.pptx；加密、损坏和旧.ppt文件需先转换或修复； - SmartArt、动画顺序、嵌入对象、音视频、公式和截图文字可能无法完整提取；
- 渲染结果受操作系统、字体和 LibreOffice 版本影响；
- 自然语言风格解析是有限、确定性的规则系统，不是通用语义解释器；
- 风格匹配分数是工程指标，不是听众研究或个人声音模仿证明；
- 自动网页检索和自主来源核验不属于 Version 1.0；
- 包级验证不能替代在目标 PowerPoint 环境中的最终人工检查。
欢迎通过 Issues 提交：
- 无法解析或验证的 PPTX 兼容性问题；
- 可复现的讲稿污染、跨页重复或时长控制问题；
- 渲染器、字体和 Notes Slide 兼容性结论；
- 新的页面类型、场景预设或安全边界建议。
提交问题时请去除敏感信息，并尽量提供最小可复现文件、运行环境、命令、错误信息和预期行为。不要上传客户、患者或内部机密原始演示文稿。
本仓库当前未附带开源许可证。公开可见不等于自动授予复制、修改、分发或商业使用权；如需使用、二次开发或再分发，请先联系项目所有者取得授权。后续如确定开源范围，将在单独的许可证文件中明确。
Built for presentations that must be spoken, reviewed, and trusted — not merely generated.