PPTX 演讲备注的技术真相
PPTX 文件本质上是一个 ZIP 压缩包，内部由 XML 文件组成。这个格式基于 ECMA-376 标准（也被 ISO 采纳为 ISO/IEC 29500），由 Ecma International 在 2006 年首次发布。
解压后的核心结构：
ini
pptx-unpacked/
├── ppt/
│ ├── slides/ # 幻灯片 XML
│ │ ├── slide1.xml
│ │ └── _rels/ # 幻灯片关联关系（关键！）
│ │ └── slide1.xml.rels
│ ├── notesSlides/ # 备注文件
│ │ ├── notesSlide1.xml
│ │ └── notesSlide2.xml
│ └── _rels/
│ └── presentation.xml.rels
└── [Content_Types].xml演讲备注存储在 ppt/notesSlides/notesSlideN.xml 中，使用三个核心 XML 命名空间：
| 前缀 | 命名空间 | 用途 |
|---|---|---|
a: |
DrawingML | 文本内容、形状、格式 |
p: |
PresentationML | 幻灯片结构、备注页结构 |
r: |
Relationships | 资源间引用关系 |
备注的文本内容在 <a:t> 标签中，和幻灯片文本使用完全相同的结构。
notesSlide 编号陷阱
这里有 一个几乎所有 PPTX 开发者都会踩的坑 ：notesSlide3.xml 不一定是第 3 页幻灯片的备注。
原因在于 PPTX 的增量编辑机制。当你删除幻灯片、调整顺序、或在不同版本的 PowerPoint 中编辑时，备注文件的编号会产生空洞或错位。真正的映射关系存储在 ppt/slides/_rels/slideN.xml.rels 中：
xml
<!-- slide5.xml.rels 的内容 -->
<Relationship Id="rId2"
Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/notesSlide"
Target="../notesSlides/notesSlide3.xml"/>这意味着第 5 页幻灯片对应的备注在 notesSlide3.xml 中。如果你直接按编号去改，你会改错页。
解决方案：pptx-notes-editor
我做了 pptx-notes-editor，一个专注于 PPT 备注编辑的 AI Agent Skill。和市面上的 AI PPT 工具不同（300+ 个，99% 专注创建幻灯片），它只做一件事：编辑演讲备注。
核心处理流程
解压 PPTX → 检测 slide-notes 映射 → 通读全文建立上下文 → 逐页生成草稿 → 用户确认 → 写入 XML → 打包验证1. 映射关系自动检测
bash
for f in pptx-unpacked/ppt/slides/_rels/slide*.xml.rels; do
slide=$(basename "$f" .xml.rels)
notes=$(grep -o 'notesSlide[0-9]*\.xml' "$f" | head -1)
if [ -n "$notes" ]; then
echo "$slide -> $notes"
fi
done输出示例：
rust
slide1 -> notesSlide1.xml
slide2 -> notesSlide2.xml
slide3 -> notesSlide4.xml # 注意：不是 notesSlide3！
slide4 -> notesSlide5.xml2. 全局上下文建立
在逐页修改之前，先批量提取所有幻灯片文本，建立整体叙事结构。这是 python-pptx 脚本通常不会做的步骤：
bash
for f in pptx-unpacked/ppt/slides/slide*.xml; do
slide=$(basename "$f" .xml)
echo "=== $slide ==="
grep -oh '<a:t>[^<]*</a:t>' "$f" | sed 's/<a:t>\([^<]*\)<\/a:t>/\1/g'
done通读后呈现全局概览，让 AI 理解每一页在整体叙事中的角色（铺垫、核心论点、案例、转折、总结），避免备注之间内容重复或逻辑断层。
3. XML 安全编辑
备注文本可能包含 XML 特殊字符，必须正确转义：
| 字符 | XML 转义 | 说明 |
|---|---|---|
& |
& |
必须转义 |
< |
< |
必须转义 |
> |
> |
建议转义 |
" |
" |
属性中使用时必须转义 |
修改时必须保留完整的 <a:t>...</a:t> 标签结构，不能只替换文本内容，否则会破坏 XML 解析。
多段备注的结构：
xml
<a:p>
<a:r><a:t>第一段备注</a:t></a:r>
</a:p>
<a:p>
<a:r><a:t>第二段备注</a:t></a:r>
</a:p>需要分别修改每个 <a:t> 标签。
4. 四种备注风格
| 风格 | 输出特点 | 适用场景 |
|---|---|---|
| 叙事风格 | 口语化，有起承转合，像讲故事 | 对外汇报、投资人演示 |
| 精简要点 | 关键信息提炼，简洁有力 | 内部周会、快速汇报 |
| 逐字稿 | 完整口语化讲稿，可直接朗读 | 重要演讲、远程录制 |
| 自定义 | 按用户描述的风格生成 | 任何特殊需求 |
Agent 生态兼容性
这个 Skill 基于 SKILL.md 标准，兼容多个 AI Agent 平台：
| Agent | SKILL.md 支持 | 安装方式 | 备注 |
|---|---|---|---|
| Claude Code | 原生支持 | curl 到 ~/.claude/skills/ |
完整支持 |
| OpenClaw | 原生支持 | /skill install |
完整支持 |
| 其他 SKILL.md Agent | 标准 SKILL.md | 复制到 skill 目录 | 依赖 Agent 的 shell 执行能力 |
与 python-pptx 的对比
| 维度 | python-pptx 脚本 | pptx-notes-editor |
|---|---|---|
| 编程要求 | 需要 Python | 无，自然语言 |
| 映射检测 | 需要自己实现 | 自动检测 |
| 上下文分析 | 不支持 | 先通读全 PPT |
| XML 转义 | 库自动处理 | Skill 指导处理 |
| 备注风格 | 固定模板 | 4 种 + 自定义 |
| 交互确认 | 不支持 | 逐页确认 |
| 备注导出 | 需额外编码 | 一键导出 Markdown |
安装
bash
# Claude Code
mkdir -p ~/.claude/skills/pptx-notes-editor && curl -fsSL https://raw.githubusercontent.com/cm8421/pptx-notes-editor/main/SKILL.md -o ~/.claude/skills/pptx-notes-editor/SKILL.md
# OpenClaw
/skill install @cm8421/pptx-notes-editor
# 通用方式
git clone https://github.com/cm8421/pptx-notes-editor.git
# 复制 SKILL.md 到你的 Agent skill 目录FAQ
Q：修改后 PPT 打不开怎么办？ A：通常是 XML 结构被破坏。确保修改时保留完整的 <a:t>...</a:t> 结构，特殊字符（& < > "）必须转义。Skill 内置了验证步骤，修改后会重新解压检查 XML 完整性。
Q：如何处理 XML 转义字符？ A：写入备注时，& → &，< → <，> → >，" → "。读取时反向解码。Skill 会自动处理这些转换。
Q：为什么不能直接按编号改 notesSlide？ A：PPTX 的增量编辑机制会导致编号空洞。比如你删除了第 3 页幻灯片，对应的 notesSlide3.xml 不一定会被删除，但可能已经不再被任何幻灯片引用。必须通过 .rels 文件确认实际映射。
Q：支持 WPS 和 Google Slides 导出的 PPTX 吗？ A：支持。只要文件符合 ECMA-376 标准的 PPTX 格式就可以。WPS 和 Google Slides 导出的 PPTX 都遵循这个标准。
Q：能批量导出备注吗？ A：可以。Skill 内置了按实际映射关系导出的脚本，将所有备注按幻灯片顺序输出为单个 Markdown 文件，包含每页标题。
链接
GitHub: github.com/cm8421/pptx...