从 XML 到叙事稿：我是如何用 AI Agent 自动编辑 PPT 演讲备注的

PPTX 演讲备注的技术真相

PPTX 文件本质上是一个 ZIP 压缩包，内部由 XML 文件组成。这个格式基于 ECMA-376 标准（也被 ISO 采纳为 ISO/IEC 29500），由 Ecma International 在 2006 年首次发布。

解压后的核心结构：

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:t> 标签中，和幻灯片文本使用完全相同的结构。

notesSlide 编号陷阱

这里有 一个几乎所有 PPTX 开发者都会踩的坑：notesSlide3.xml 不一定是第 3 页幻灯片的备注。

原因在于 PPTX 的增量编辑机制。当你删除幻灯片、调整顺序、或在不同版本的 PowerPoint 中编辑时，备注文件的编号会产生空洞或错位。真正的映射关系存储在 ppt/slides/_rels/slideN.xml.rels 中：

<!-- 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. 映射关系自动检测

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

输出示例：

slide1 -> notesSlide1.xml
slide2 -> notesSlide2.xml
slide3 -> notesSlide4.xml    # 注意：不是 notesSlide3！
slide4 -> notesSlide5.xml

2. 全局上下文建立

在逐页修改之前，先批量提取所有幻灯片文本，建立整体叙事结构。这是 python-pptx 脚本通常不会做的步骤：

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 特殊字符，必须正确转义：

修改时必须保留完整的 <a:t>...</a:t> 标签结构，不能只替换文本内容，否则会破坏 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 平台：

与 python-pptx 的对比

安装

# Claude Code
mkdir -p ~/.claude/skills/pptx-notes-editor && curl -fsSL  -o ~/.claude/skills/pptx-notes-editor/SKILL.md

# OpenClaw
/skill install @cm8421/pptx-notes-editor

# 通用方式
git clone 
# 复制 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…