PPT 动画（ppt-animation）
概述
python-pptx 不支持动画，本技能通过直接操作 slide XML 中的 <p:timing> 树为 .pptx 写入动画，并提供一套六册动画库（图片/文字/图形/情景/视频/GIF，共 1000+ 页实例）的设计知识与移植工具。
三条核心能力：
- 诊断：列出任意 pptx 每页的动画数量、效果类型、形状清单 ——
scripts/inspect_pptx_animations.py - 注入：按 JSON 规格给指定形状加基础动画（淡入、飞入、擦除、缩放、旋转、路径等）——
scripts/add_basic_animation.py - 移植：把内置动画模板（或任意来源 pptx 某页）的完整动画时间轴复制到目标页，按形状名自动重映射 ——
scripts/transplant_animation.py
脚本只用 Python 标准库，无需联网、无需安装依赖；一律生成新文件，绝不原地修改输入。技能完全自包含：29 个动画模板已内置在 references/timing-templates/，不依赖任何外部文件。
工作流程
第 0 步：明确任务类型
| 用户意图 | 路径 |
|---|---|
| 给已有/新建 PPT 加常见动画（淡入、飞入、缩放……） | 路径 A：注入 |
| 要库中看到的某个复杂效果（多段组合、情景动画） | 路径 B：移植 |
| 看看某份 PPT 里有什么动画 / 找参考效果 | 路径 C：诊断 |
| 从零做带动画的整份 PPT | 先用 tencent-pptx 类技能生成文稿，再叠加路径 A/B |
新建文稿阶段注意：给要加动画的形状起有意义的名字（动画脚本按形状名定位），并让每个需要独立动画的元素成为独立形状（逐字动画 = 每字一个文本框）。
路径 A：注入基础动画
- 先诊断目标页形状名：
python scripts/inspect_pptx_animations.py deck.pptx --slide 3 - 编写 spec JSON（格式见
add_basic_animation.py头部注释；效果清单见references/effects-catalog.md）。 - 执行：
python scripts/add_basic_animation.py deck.pptx --spec spec.json --out deck.anim.pptx - 按「验证」节复核。
内置效果：
- 进入：appear / fade_in / fly_in(direction) / wipe_in(direction) / zoom_in
- 强调：spin(angle) / grow_shrink(factor)
- 退出：disappear / fade_out / fly_out(direction) / wipe_out(direction)
- 路径：motion_path(dx, dy)（dx/dy = 幻灯片宽高的分数，如 0.25 = 向右移 1/4 屏宽）
- 自定义：custom + 显式 transition/filter/presetID（用于盒状、百叶窗、轮子等内置未覆盖效果）
编排字段：trigger = click（单击）/ with_previous（与上一同时）/ after_previous（上一之后），duration、delay 单位均为秒。
路径 B：移植复杂动画（模板优先）
- 浏览内置模板，按分类和说明选效果：
python scripts/transplant_animation.py --list-templates - 看模板动画作用于哪些形状（决定目标页要准备哪些形状）：
python scripts/transplant_animation.py --template scene-scroll-unroll --list-src - 确保目标页已有对应形状（缺什么补什么，名字随意，靠映射对应），执行移植：
python scripts/transplant_animation.py --template scene-scroll-unroll \ --dst deck.pptx --dst-slide M \ --map "模板形状名=目标形状名" --allow-partial \ --out deck.anim.pptx
---map：显式配对（可多个；形状名可用spid:N代替）
---auto-map：同名形状自动配对；--allow-partial：无对应的动画丢弃
- 不加--allow-partial时，遇到未映射形状会报错并列出清单（推荐，避免静默丢效果） - 按「验证」节复核。
模板不够用时（用户有自己的动画库 pptx 想整页复刻），同一脚本支持 deck 模式：--src 库.pptx --src-slide N 替代 --template，其余参数相同。
路径 C：诊断 / 逛库
python scripts/inspect_pptx_animations.py file.pptx # 全deck逐页摘要（有动画的页带 *）
python scripts/inspect_pptx_animations.py file.pptx --slide 5 # 单页：形状表 + preset + 原语统计
python scripts/inspect_pptx_animations.py file.pptx --slide 5 --xml # 导出完整 timing XML 研读
内置动画模板
references/timing-templates/ 内置 29 个经典动画时间轴模板（从六册动画库精选抽取，纯 XML 无媒体素材，仅 1.1MB），按类别组织：
- 图片（8 个）：垂直突出亮相、浮动+飞旋、图片切割、多图翻转落幕、快进慢行、路径排列、纵深翻转、故事片开场
- 文字（8 个）：逐字母飞入、10 秒/3-2-1 倒计时、滚动字幕、闪烁、上升缩小、聚光灯、弹跳
- 图形（6 个）：0-100% 进度条、LOADING 逐帧、3D 旋转展示、图层分离、Logo 拼装、TAB 切换
- 情景（7 个）：单摆、仪表指针、卷轴展开、滑块解锁、齿轮联动、盖章、时钟
每个模板的形状需求（spid/形状名）、原语构成、出处见 references/timing-templates/index.json；挑选与映射方法见路径 B。
设计方法论（节奏、空间感、克制原则）见 references/design-playbook.md；六册原始动画库（>500MB）不随技能分发也不需要——references/library-catalog.md 保留其页码目录，仅供持有库文件的用户深挖更多效果（走 deck 模式移植）。
验证（每次写完动画必做）
- 脚本输出自带复核行（primitives 计数），确认非零且数量符合预期。
- 再跑一遍
inspect_pptx_animations.py 输出文件 --slide N确认动画落在正确页。 - 可选：
python -c "from pptx import Presentation; Presentation('输出.pptx')"确认包结构完整。 - 告知用户：在 PowerPoint/WPS 中按 F5 放映目检（沙箱无法渲染动画），WPS 对部分老式效果（如轮子、百叶窗子类型）支持可能略有差异。
注意事项
- 脚本参数中的页码 = 放映顺序（第几页），内部已按 presentation.xml 解析，不等于 slideN.xml 的文件编号。
presetSubtype只影响 PowerPoint 界面里显示的效果名标签，真实运动由filter字符串驱动；脚本已把 filter 配对正确。- 目标页已有动画时脚本会拒绝覆盖，显式加
--replace-timing（或 spec 中replace_timing: true）才重写。 - 动画引用形状的 XML id，删除/重建形状会使动画失锚；改内容时尽量改形状文本而不是删了重画。
- 详细技术参考（presetID 表、filter 字符串表、单位换算）：
references/effects-catalog.md。
