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、备注写入和完整性验证；模型只负责语义理解与语言生成。即使生成内容听起来流畅，也不能绕过文件安全和交付门禁。

风格不是一个模糊的“更专业一点”。系统使用以下十个可审计维度：

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 报告中，不污染现场讲述正文。

医疗和患者教育默认采用保守边界。系统不得虚构研究、指南、适应证、剂量、禁忌、疗效、安全结论或诊疗建议；高风险声明依赖不可读内容时，正式写入会被阻断。

• 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 兼容性结论；
• 新的页面类型、场景预设或安全边界建议。

提交问题时请去除敏感信息，并尽量提供最小可复现文件、运行环境、命令、错误信息和预期行为。不要上传客户、患者或内部机密原始演示文稿。

本仓库当前未附带开源许可证。公开可见不等于自动授予复制、修改、分发或商业使用权；如需使用、二次开发或再分发，请先联系项目所有者取得授权。后续如确定开源范围，将在单独的许可证文件中明确。