PPT Master 动画系统实战指南：原生 PowerPoint 转场与对象动画的完整控制

PPT Master 将页面转场与可选的元素级对象动画写为真正的 PowerPoint OOXML，而不是嵌入视频；对象动画覆盖入场（entrance）、强调（emphasis）、运动路径（motion path）与退场（exit）四类效果。读完本篇，你可以掌握从命令行一键切换转场、三种动画启动模式的选型逻辑，到用 animations.json 旁车文件精细编排单个对象的完整生命周期（入场—移动—强调—退场），并理解导出的严格校验与兼容边界。

默认行为：克制是设计前提

PPT Master 的两层默认值如下：

层	默认	含义
页面转场	fade，0.4 秒	幻灯片之间以克制的视觉转场切换
元素对象动画	none（关闭）	每一页以完整页面出现；只有当运动确实有助于表达时才开启

这一"元素动画默认关闭"的设计意图在 动画执行参考 中被明确说明：每页都自动触发的元素动画是无请求的"AI 生成痕迹"，因此对象动画是显式选入（opt-in）的。

修改动画设置不需要重新生成幻灯片。复用同一份 svg_output/ 即可：重新运行 svg_to_pptx.py，但默认发布导出仍要求当前通过的 final SVG 质量报告；若不存在当前匹配且通过的 final 报告，需先运行 final checker 并解决其阻塞项，再重新运行 svg_to_pptx.py。

常用命令配方

以下配方覆盖了绝大多数使用场景，全部基于 svg_to_pptx.py 的命令行参数（参数解析实现位于 cli.py 等文件）：

目标	命令
保持默认	python3 skills/ppt-master/scripts/svg_to_pptx.py <project>
更换页面转场	python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push
移除视觉转场	python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t none
每 5 秒自动翻页	python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --auto-advance 5
启用自动元素渐显	python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto
全程使用一种入场效果	python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation entrance_fade
点击时显示元素	python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-trigger on-click
所有元素一起动画	python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-trigger with-previous
放慢渐显序列	python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-duration 0.5 --animation-stagger 0.8

几个关键行为细节：

• -t/--transition 接受 48 个规范转场键、兼容旧名或 none；--transition-duration 单位为秒，默认 0.4。
• --auto-advance 以秒为单位，点击翻页仍然保留（点击或计时器到期均可推进）。注意 -t none 只移除视觉效果，不会移除已显式配置的自动翻页计时。
• -a/--animation 选择效果或模式；--animation-trigger 选择启动模式；--animation-duration 与 --animation-stagger 控制基础时序；--no-animations 禁用全部页面/对象运动但保留旁车配置。
• 有一条**"不静默降级"硬规则**：未知转场效果、不受支持的 Effect Option、非法或非有限时长的持续时长都会直接使导出失败，绝不会被悄悄替换为 fade。

选择页面转场：48 个规范键按"页间关系"选型

转场选择的原则是从相邻两页的关系出发，而不是从效果库里挑花样。下表是文档给出的选型起点：

相邻幻灯片的关系	推荐起点
同一章节内的普通延续	fade
无延续性需要保留的立即切换	none 或 cut
有方向的步骤、时间线、可见的层级推进	push、wipe、cover 或 uncover（带有意义方向）
同一对象或场景改变位置、大小、裁切或外观	morph
章节开篇、关键揭示、标记性状态边界	选择性的 split、reveal、shape、flash 或 random_bars
一组重复内容在一个空间框架中推进	pan、conveyor 或 ferris_wheel；个体对象需保留身份时用 Morph
视点围绕或穿越连续空间	rotate、window、orbit 或 fly_through
主题支持舞台、纸张、实体书页隐喻	选择性的 fall_over、drape、curtains、wind、prestige、peel_off、page_curl、airplane、origami 或 doors
打断性节拍：破碎、坍塌、离散	选择性的 fracture、crush、dissolve、vortex 或 shred
揭示受益于几何、定时或纹理图案	选择性的 checkerboard、blinds、clock、ripple、honeycomb、glitter 或 comb
卡片、面板、画廊或视点明显翻转	选择性的 switch、flip、gallery、cube、box 或 zoom

核心纪律：当没有其他转场能增加语义时，保持 fade 或 none；不要为了制造变化而更换效果；random 只在"不可预测性本身就是意图"时才合适。

完整的 48 个规范转场键

这 48 个键覆盖当前 PowerPoint 转场画廊的全部三个分区：

• Subtle（细微）：morph、fade、push、wipe、split、reveal、cut、random_bars、shape、uncover、cover、flash。
• Exciting（华丽）：fall_over、drape、curtains、wind、prestige、fracture、crush、peel_off、page_curl、airplane、origami、dissolve、checkerboard、blinds、clock、ripple、honeycomb、glitter、vortex、shred、switch、flip、gallery、cube、doors、box、comb、zoom、random。
• Dynamic Content（动态内容）：pan、ferris_wheel、conveyor、rotate、window、orbit、fly_through。

旧名 strips、circle、diamond、newsflash、plus、pull、wedge 和 wheel 仅作为兼容输入被接受：新旁车、计划、转换跟踪与输出只使用规范键。兼容输入会"糖化"为原生效果加 Effect Options——例如 diamond 变成带 shape: diamond 的 shape，wedge 变成带 style: wedge 的 clock。

设置效果专属选项（effect_options）

方向、形状、图案、Morph 作用域、黑屏过场、页数、弹跳等效果专属选项通过 transition.effect_options 配置，并针对所选效果做校验。运行以下命令查看某个转场的确切合法取值：

python3 skills/ppt-master/scripts/pptx_animations.py --describe-transition <effect>

从源码结构看，需要较新 Office 命名空间的效果在 OOXML 中以 mc:Choice 承载真正的 PowerPoint 效果、并以 fade 作为旧消费者的 mc:Fallback；校验器要求请求的主效果存在，绝不接受 fallback 作为静默替代（见 references/animations.md §3）。

选择启动模式：对应 PowerPoint 动画窗格的 Start 下拉框

启动模式	行为	最适合
on-click	每次点击出现一个内容组	演讲者控制节奏的现场演示
with-previous	幻灯片出现时所有内容组一起动画	单一协调的入场节拍
after-previous（默认）	各内容组无需点击依次出现	无人值守播放、走查、带旁白（narrated）的演示稿

注意：--recorded-narration（录制的语音旁白）不支持 on-click；为旁白就绪或视频就绪的输出，请使用 after-previous 或 with-previous。

选择对象动画：203 个原生键，先定"生命周期"再选"视觉效果"

对象动画默认从 none 开始。当对象运动承担沟通职责时，先选择它的生命周期，再选择视觉效果：

沟通任务	选择	边界
按阅读或旁白顺序揭示信息	auto 或原生 entrance_* 键	这是对象动画的通常情形
把注意力引回已可见的对象	显式的 emphasis_* 键	不要用作该对象的首次揭示
展示有意义的空间或因果移动	显式的 path_* 键，或跨相邻幻灯片的 Morph	路径本身应承载意义；刻意的背景氛围动效是高级例外
在同一页内移除、替换或为内容腾出空间	显式的 exit_* 键	普通换页本身就会移除旧页
为通用入场增加确定性或种子化变化	mixed 或 random	这些模式仍只选择入场效果
没有明确运动任务	none	保持幻灯片静态

规范注册表包含 203 个 PowerPoint 原生键：53 个入场、33 个强调、64 个运动路径、53 个退场预设。这一数字与仓库中的注册表数据文件 pptx_animation_presets.json 一致（可核验：effects 条目总数为 203）。新增选择、旁车、自动选择、跟踪与示例都使用这些带类别前缀的键；auto、mixed 和 random 只选择入场效果，强调、运动路径或退场行为必须使用显式规范键。

29 个既定短名仅作为兼容输入被接受：它们在写入前被规范化，不保留第二套行为引擎。旧的 Fly 方向名全部规范化为 entrance_fly，旧的 Wipe 方向名全部规范化为 entrance_wipe，方向作为选项保留；遗留的 wheel 保留四个辐条。完整分类列表可用以下命令查看：

python3 skills/ppt-master/scripts/pptx_animations.py --list

另外，四个媒体播放命令（play/pause/stop/play from bookmark）不属于 SVG 分组对象的效果，由音频/视频工作流负责处理。

-a auto 的行为是语义化的：从 references 文档 看，它把图表/表格/时间线映射到 entrance_wipe、卡片/步骤映射到 entrance_fly、标题/要点映射到 entrance_fade、图片类 id 轮转一个更丰富的效果池、未匹配的 id 在 fade/wipe/fly/zoom 间轮转。random 从有效的 deck 输入派生种子，相同输入产生相同选择，因此结果可复现。

用 animations.json 定制具体对象

只有当全 deck 设置不够用时才使用 animations.json——例如某个对象要依次入场、移动、吸引注意、然后离场。工作流是：列出真实分组 → 只对受影响的幻灯片和对象写稀疏覆盖 → 校验 → 导出：

python3 skills/ppt-master/scripts/animation_config.py list-groups <project>
python3 skills/ppt-master/scripts/animation_config.py validate <project>
python3 skills/ppt-master/scripts/svg_to_pptx.py <project>

scaffold 是可选的中性编辑起点：python3 skills/ppt-master/scripts/animation_config.py scaffold <project> 会将默认对象效果设为 none，未被触碰的 {} 分组条目不会启用任何动画——创建 scaffold 本身不等于把 deck 选入对象运动。

锚点模型：顶层 <g id> 是形状目标锚点

旁车针对稳定的顶层 <g id="..."> 内容分组。分组 id 是 PowerPoint 形状目标锚点，不是 Animation Pane 行。兼容的单效果对象仍只创建一行；而 effects[] 数组可以为同一个形状创建多条有序行。下例中 risk-marker 一个分组承载了入场、路径、强调、退场四条 Animation Pane 行：

{
  "version": 1,
  "slides": {
    "03_threshold": {
      "animation": { "trigger": "after-previous" },
      "groups": {
        "risk-marker": {
          "effects": [
            { "effect": "entrance_fade", "order": 1, "duration": 0.25 },
            { "effect": "path_right", "order": 2, "delay": 0.1, "duration": 0.7 },
            { "effect": "emphasis_teeter", "order": 3, "trigger": "with-previous", "duration": 0.45 },
            { "effect": "exit_fade", "order": 4, "trigger_shape": "details-button", "duration": 0.3 }
          ]
        }
      }
    }
  }
}

规则要点：

• 非空分组必须二选一：遗留单效果字段，或 { "effects": [...] } 形式，绝不混用。effects 必须非空，且每行都显式命名 effect。
• 现有单效果旁车完全向后兼容；遗留形式中的 effect: none 可让某个对象保持静态（用于覆盖继承的通用动画）。
• slides 的键匹配 SVG 文件名主干（03_market.svg → 03_market）；groups 的键匹配顶层 <g id> 锚点。
• 对于扁平 SVG（根下没有顶层 <g> 包装、只有裸 <rect>/<text>/<path>）：8 个及以下可见顶层基元时每个基元各成一个锚点；超过 8 个时该页跳过对象动画（页面仍正常渲染）。
• 页面框架（chrome）保持静态：背景、母版/版式内容、占位符与页面装饰不会成为动画目标；data-pptx-layer 与显式静态角色/占位符标记是绝对约束。

常用行字段

字段	用途
effect	选择一个显式效果；遗留形式可用 none 让该对象保持静态
trigger	覆盖本行的启动模式；否则继承幻灯片动画 trigger
order	在不改变幻灯片层序的前提下对普通行排序；trigger-shape 行保持独立的交互序列
delay	为该行解析后的启动行为追加一段停顿
duration	覆盖该行计划的动画时长
effect_options	设置效果专属的 direction、amount、color、font_name、relative、size
trigger_shape	当另一个顶层分组被点击时触发行（对应 PowerPoint 的 On Click of）
时序修正	repeat_count/repeat_duration、auto_reverse、rewind、accelerate、decelerate、bounce_end、restart
完成效果	after_effect（none、变暗、隐藏、或下次点击时隐藏）
音效	可选的项目本地 sound 路径；捆绑库选择走下文按需同步

补充语义：order、delay、duration、trigger 与 trigger_shape 按行解析，幻灯片级动画 trigger 只作继承用。trigger_shape 隐含 on-click；若该行同时声明 trigger，也必须是 on-click。使用 python3 skills/ppt-master/scripts/pptx_animations.py --describe <canonical_effect> 可查看某效果确切接受的选项；速度由 duration 控制，平滑起止由 accelerate/decelerate 控制；Change Font 的 font_name 必须是目标机器上安装的一个 PowerPoint 字体，绝不能是 CSS 字体栈。

继承链为：未列出的幻灯片继承 defaults.transition/defaults.animation，再落到 CLI/导出器解析；显式 CLI 标志覆盖对应旁车字段；组继承幻灯片解析出的时长、启动模式、时序修正、完成效果与音效到每一行；trigger_shape 从不被继承。

进阶：确定性 Morph 对象配对

当同一个语义对象跨相邻两页延续时，目标页可在 animations.json 中声明显式的强制 Morph 配对（morph 块，from 指向前一 SVG 主干，pairs 中每个键映射源/目标两个唯一的直接根 <g id>）。导出器会把两个分组 id 解析为最终 PowerPoint 形状、在 Master/Layout 处理之后写入 !!<key> 名称，然后重新打开包验证相邻性、Morph-by-object 与对象类型匹配；缺失、结构性、错位或含糊的目标会失败而不是回退到自动匹配。详见 动画执行参考 §2.1。

选定运动之后再加音效

音效默认关闭。PPT Master 附带一个全局 CC0 发现库，但它不会在策略阶段或普通项目搭建时被复制。正确顺序是：先完成 SVG 页面、选定转场/对象运动；只有当某个已解决的节拍有具体听觉职责时，才去发现并同步音效：

python3 skills/ppt-master/scripts/sound_sync.py list --query whoosh
python3 skills/ppt-master/scripts/sound_sync.py \
  <project> bigsoundbank/1797 kenney-interface/click_001

第二条命令只把被选中的文件复制到 <project>/sounds/<namespace>/。没有选中音效时，不会创建任何项目 sounds 目录，也不复制任何文件。recommended 目录旗标只是发现用的短名单，不是自动选择。

配置始终引用复制后的项目本地路径，绝不引用全局 templates/sounds/ 路径或库 id：

{
  "version": 1,
  "slides": {
    "02_process": {
      "transition": {
        "effect": "push",
        "sound": "sounds/bigsoundbank/1797.wav"
      },
      "groups": {
        "next-step": {
          "effect": "entrance_fade",
          "sound": "sounds/kenney-interface/click_001.wav"
        }
      }
    }
  }
}

格式边界：transition.sound 使用 WAV；对象动画的 sound 还接受项目相对或绝对路径的 .m4a、.mp3、.wav；捆绑选择是 WAV，应使用复制后的项目相对路径。仅转场音效可用稀疏 animations.json 承载；幻灯片级 transition.sound: null 用于清除继承的默认音效。导出前先校验。不要仅仅为了演示功能存在而加音效。

一个重要边界：该校验只证明可编辑 PPTX 中包含原生音效，不证明 PowerPoint 的 MP4 音轨中包含它。对于带已解决音效的直出旁白视频，应遵循 Audio Narration & Video Export，在"验证过的原生导出混音"或"显式 PowerPoint 幻灯片放映录制（含系统音频）"二选一，不要混用两条路径。

校验与兼容边界

PPT Master 对动画设置做严格校验：未知效果或启动模式、非法时序值、缺失的幻灯片/分组引用、试图动画化结构性对象——都会直接失败，而不是静默改变行为。导出还会在替换已有输出前读回候选 PPTX 的每页 timing 树（行数量/顺序、触发器、形状目标、预设类、时长与时间线偏移），并做包级验证。

边界	用户可感知的后果
动画目标	元素动画作用于逻辑顶层内容分组锚点；一个锚点可拥有多条 Animation Pane 行
静态结构	背景、母版/版式内容、占位符与页面框架保持静态
不受支持的对象构造	不会从分组 SVG 内容推断段落/文本范围构造、自定义自由运动路径、原生 Chart/SmartArt 构造序列或媒体播放命令
输出路由	动画存在于从 svg_output/ 生成的原生 PPTX 中；svg_final/ 是静态预览
已有 PPTX 路由	Template Fill 与 Native Enhance 保留源对象动画，而不把它们翻译成本生成模型
PPTX 转 SVG 导入	仅重建当前注册表行（精确原生时长与唯一顶层分组目标）；高级/构造/媒体时序保持被诊断状态
播放兼容性	桌面版 Microsoft PowerPoint 是首要验证目标；Keynote、WPS、LibreOffice 与旧版 Office 可能重新映射或省略个别效果

延伸阅读与可复现示例

• 动画执行参考：完整旁车 schema、锚点回退逻辑、OOXML 读回规则与视频适配契约。
• customize-animations 工作流阶段：当用户要求 AI 调单个对象时使用的定制阶段。
• svg-pipeline.md、pptx-animations.md、pptx-transitions.md：完整 CLI 参考与转场/动画实现细节。
• 仓库中的示例项目带有真实 animations.json 供参照，如 global_ai_capital_2026 示例的动画配置 与 attention_is_all_you_need 示例，可对照查看规范键在实际 deck 中的稀疏用法。