AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He
docs(animations): guide motion choices by slide semantics
hugohe3d9614aac076b
diff --git a/docs/animations.md b/docs/animations.mdindex cfc80487..850a45fa 100644--- a/docs/animations.md+++ b/docs/animations.md@@ -30,13 +30,30 @@ Changing animation settings does not require regenerating the slides. Rerun `svg| Auto-advance every 5 seconds | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --auto-advance 5` || Enable automatic element reveals | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto` || Use one entrance effect throughout | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation entrance_fade` |-| Use one native emphasis effect | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation emphasis_spin` |-| Use one native motion path | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation path_circle` |-| Use one native exit effect | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation exit_fade` || Reveal elements on click | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-trigger on-click` || Animate all elements together | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-trigger with-previous` || Slow the reveal sequence | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-duration 0.5 --animation-stagger 0.8` |+## Choose a Page Transition++| Relationship between adjacent slides | Start with |+|---|---|+| Ordinary continuation within one section | `fade` |+| Immediate change with no continuity to preserve | `none` or `cut` |+| Directional steps, timeline, or visible layer progression | `push`, `wipe`, `cover`, or `uncover` with a meaningful direction |+| The same object or scene changes position, size, crop, or appearance | `morph` |+| Section opening, key reveal, or marked state boundary | A selective `split`, `reveal`, `shape`, `flash`, or `random_bars` |+| A repeated collection advances through one spatial frame | `pan`, `conveyor`, or `ferris_wheel`; use Morph when individual objects must retain identity |+| The viewpoint travels around or through a continuous space | `rotate`, `window`, `orbit`, or `fly_through` |+| The theme supports a stage, paper, or physical-page metaphor | A selective `fall_over`, `drape`, `curtains`, `wind`, `prestige`, `peel_off`, `page_curl`, `airplane`, `origami`, or `doors` |+| A disruptive beat represents breakage, collapse, or dispersal | A selective `fracture`, `crush`, `dissolve`, `vortex`, or `shred` |+| A marked reveal benefits from a geometric, timed, or textured pattern | A selective `checkerboard`, `blinds`, `clock`, `ripple`, `honeycomb`, `glitter`, or `comb` |+| A card, panel, gallery, or viewpoint visibly turns or changes face | A selective `switch`, `flip`, `gallery`, `cube`, `box`, or `zoom` |++Keep `fade` or `none` when no other transition adds meaning. Do not change+effects merely to create variety; `random` is appropriate only when+unpredictability is itself intentional.+The 48 canonical transition keys cover all three sections in the currentPowerPoint gallery:@@ -75,18 +92,19 @@ an explicitly configured auto-advance timer.`--recorded-narration` does not support `on-click`; use `after-previous` or `with-previous` for narrated or video-ready output.-## Choose an Effect+## Choose an Object Animation-| Choice | Use it when |-|---|---|-| `auto` | You want PPT Master to choose a generic entrance from each content group's role; this is the recommended automatic opt-in |-| A native `entrance_*` key | You want one of PowerPoint's 53 native entrance presets |-| A native `emphasis_*` key | An already visible object should draw attention or change appearance |-| A native `path_*` key | An object should follow one of PowerPoint's 64 motion paths |-| A native `exit_*` key | An object should leave the slide during the sequence |-| `mixed` | You need deterministic variation across the canonical entrance pool |-| `random` | You want seeded variation from the same canonical entrance pool |-| `none` | You want to disable element animation |+Start with `none`. When object motion has a communication job, choose its+lifecycle before its visual effect:++| Communication job | Choice | Boundary |+|---|---|---|+| Reveal information in reading or narration order | `auto` or a native `entrance_*` key | This is the usual object-animation case |+| Redirect attention to an already visible object | An explicit `emphasis_*` key | Do not use it as the object's first reveal |+| Show meaningful spatial or causal movement | An explicit `path_*` key, or Morph across adjacent slides | The path itself should carry meaning; deliberate background ambience is an advanced exception |+| Remove, replace, or make room for content on the same slide | An explicit `exit_*` key | A normal slide change already removes the old page |+| Add deterministic or seeded variation to generic entrances | `mixed` or `random` | These modes still select entrance effects only |+| No clear motion task | `none` | Keep the slide static |The canonical registry contains 203 PowerPoint-native keys: 53 entrance, 33emphasis, 64 motion path, and 53 exit presets. New selections, sidecars,diff --git a/docs/zh/animations.md b/docs/zh/animations.mdindex a702aac3..ca266584 100644--- a/docs/zh/animations.md+++ b/docs/zh/animations.md@@ -28,13 +28,29 @@ OOXML,而不是嵌入视频。对象动画包括进入、强调、动作路径| 每 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> --animation emphasis_spin` |-| 全部使用同一种原生动作路径 | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation path_circle` |-| 全部使用同一种原生退出效果 | `python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation exit_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` |+## 选择页间切换++| 相邻页面关系 | 优先考虑 |+|---|---|+| 同一章节内的普通连续叙述 | `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 个规范页间切换标识已经覆盖当前 PowerPoint 效果库的三个完整分组:- 细微:平滑 `morph`、淡入/淡出 `fade`、推入 `push`、擦除 `wipe`、@@ -71,18 +87,19 @@ OOXML,而不是嵌入视频。对象动画包括进入、强调、动作路径`--recorded-narration` 不支持 `on-click`;带旁白或用于视频导出的 deck 应使用 `after-previous` 或 `with-previous`。-## 选择动画效果+## 选择对象动画-| 选择 | 适用场景 |-|---|---|-| `auto` | 让 PPT Master 根据内容组角色选择通用进入效果;这是自动开启元素动画时的推荐选项 |-| 原生 `entrance_*` | 使用 PowerPoint 的 53 个原生进入预设之一 |-| 原生 `emphasis_*` | 让已显示对象获得关注或改变外观 |-| 原生 `path_*` | 让对象沿 PowerPoint 的 64 条动作路径之一移动 |-| 原生 `exit_*` | 让对象在动画序列中退出页面 |-| `mixed` | 在规范进入预设池中确定性轮换 |-| `random` | 从同一规范进入预设池中按固定种子生成变化 |-| `none` | 关闭元素动画 |+从 `none` 开始。只有对象运动承担明确沟通任务时,才先选择生命周期,再选择+视觉效果:++| 沟通任务 | 选择 | 使用边界 |+|---|---|---|+| 按阅读或旁白顺序揭示信息 | `auto` 或原生 `entrance_*` | 这是最常见的对象动画场景 |+| 让已经可见的对象重新获得关注 | 显式 `emphasis_*` | 不用于对象第一次出现 |+| 表达有意义的空间或因果移动 | 显式 `path_*`,或在相邻页间使用 Morph | 路径本身应承载意义;刻意设计的背景氛围运动属于高级例外 |+| 在同一页移除、替换内容或腾出空间 | 显式 `exit_*` | 普通翻页已经会移走旧页面 |+| 为通用进入效果增加确定性或固定种子变化 | `mixed` 或 `random` | 两种模式仍只选择进入效果 |+| 没有明确的运动任务 | `none` | 保持静态 |规范注册表包含 203 个 PowerPoint 原生标识:53 个进入、33 个强调、64 条动作路径、53 个退出。现在新选择、sidecar、自动决策、转换轨迹和示例都只使用diff --git a/skills/ppt-master/references/animations.md b/skills/ppt-master/references/animations.mdindex 6cf91fea..284fba05 100644--- a/skills/ppt-master/references/animations.md+++ b/skills/ppt-master/references/animations.md@@ -242,6 +242,33 @@ The generated names follow Microsoft's## 3. Page Transitions+**Reference — not a constraint**: choose a transition from the relationship+between adjacent pages, not from gallery coverage. Run this playbook before+selecting a canonical key:++| Pass | Decision |+|---|---|+| Relate | Decide whether the destination continues the same object or space, advances in a meaningful direction, opens a new section, or intentionally breaks continuity. |+| Diagnose | Name the transition's job: neutral continuity, immediate cut, directional progress, object/state continuity, spatial movement, or a deliberate thematic beat. |+| Select | Use the smallest family that performs that job; keep `fade` when no stronger relationship exists. |+| Coordinate | Align direction, duration, and recurrence with reading order, narration, and the deck's established motion language. |+| Stop | Keep `fade` or `none` when another effect adds no meaning; never vary transitions for catalog coverage. |++| Page relationship | Candidate family |+|---|---|+| Ordinary continuation within one section | `fade` |+| Immediate change with no continuity to preserve | `none` or `cut` |+| Directional steps, timeline, or layer progression | `push` / `wipe`; use `cover` / `uncover` when an overlay relationship is visible |+| The same semantic object or scene changes across adjacent pages | `morph`; use §2.1 pairs when identity must be deterministic |+| Section opening, key reveal, or marked state boundary | Selective `split` / `reveal` / `shape` / `flash` / `random_bars` |+| A repeated collection advances through one spatial frame | `pan` / `conveyor` / `ferris_wheel`; use the §4.2 Morph carousel when individual cards need deterministic identity |+| The viewpoint travels around or through a continuous space | `rotate` / `window` / `orbit` / `fly_through` |+| The narrative or theme supports a stage, paper, or physical-page metaphor | Selective `fall_over` / `drape` / `curtains` / `wind` / `prestige` / `peel_off` / `page_curl` / `airplane` / `origami` / `doors` |+| A disruptive beat represents breakage, collapse, or dispersal | Selective `fracture` / `crush` / `dissolve` / `vortex` / `shred` |+| A marked reveal benefits from a geometric, timed, or textured pattern | Selective `checkerboard` / `blinds` / `clock` / `ripple` / `honeycomb` / `glitter` / `comb` |+| A card, panel, gallery, or viewpoint visibly turns or changes face | Selective `switch` / `flip` / `gallery` / `cube` / `box` / `zoom` |+| Unpredictability is itself the requested behavior | `random`; never use it merely to create variety |+```bash# Pick a different effectpython3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push --transition-duration 0.6@@ -338,11 +365,22 @@ PowerPoint's separate **Trigger → On Click of** behavior uses row-specific`trigger_shape`. It links that row to another top-level group while unlinkedrows keep the slide Start mode; it is not a fourth deck-wide Start mode.-**Lifecycle-first selection**: classify semantic `initial → action → end`-before choosing an effect: `enter→entrance_*`,-`emphasize→emphasis_*`, `move→path_*` or Morph, `exit→exit_*`, and-`static→` no row (or legacy `effect: none` to suppress inheritance). A unit may-use several ordered `effects[]` rows. There is no category quota.+**Mandatory — lifecycle before effect selection**: start from `static`, then+classify semantic `initial → action → end` before choosing an effect. Generic+staged reveals normally use `enter`; narrower communication jobs select their+matching lifecycle instead.++| Duty | State contract | Use when | Effect family |+|---|---|---|---|+| `static` | present → hold as reference → present | Motion adds no clarity or intended feeling | No row; legacy `effect: none` only suppresses inheritance |+| `enter` | absent → introduce → present | Information should be withheld, ordered, or revealed with narration | `entrance_*`; modes only for generic reveal |+| `emphasize` | present → redirect attention → present/altered | An already visible object must regain attention or show a local change; never substitute for its first reveal | Explicit `emphasis_*` |+| `move` | state/position A → progress → state/position B | The trajectory carries spatial or causal meaning, or §4.1 adopts subordinate ambient motion; use Morph for cross-page continuity | Explicit `path_*`, or endpoint pages + Morph |+| `exit` | present → retire → absent | The same slide must remove, replace, or make room for content; an ordinary page change needs no object exit | Explicit `exit_*` |++Entrance is the common opt-in family for staged information, not a deck or+category quota. A unit may use several ordered `effects[]` rows only when it+has several real lifecycle duties.The registry exposes two layers:diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.jsonindex 3c32927e..03dc42e6 100644--- a/skills/ppt-master/scripts/prompt_audit_manifest.json+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json@@ -12,7 +12,7 @@"skills/ppt-master/templates/schemas/*.json"],"exclude": [],- "max_tokens": 393375+ "max_tokens": 394495},"file_budgets": {"AGENTS.md": 2400,@@ -186,7 +186,7 @@"skills/ppt-master/references/svg-effects.md","skills/ppt-master/references/native-shape-authoring.md"],- "max_tokens": 53040+ "max_tokens": 53348},"route.generate.quick-generate.topic-research": {"description": "Quick Generate with gap-targeted factual research before direct resource preparation and SVG authoring.",@@ -196,7 +196,7 @@"stage.generate.topic-research"],"files": [],- "max_tokens": 54540+ "max_tokens": 54848},"route.generate.quick-generate.icon": {"description": "Quick Generate with project-local bundled icon selection and synchronization.",@@ -207,7 +207,7 @@"files": ["skills/ppt-master/templates/icons/README.md"],- "max_tokens": 54940+ "max_tokens": 55248},"route.generate.quick-generate.in-hand-image": {"description": "Quick Generate with supplied, extracted, or placeholder image resources prepared before SVG authoring.",@@ -217,7 +217,7 @@"stage.generate.executor.image"],"files": [],- "max_tokens": 62925+ "max_tokens": 63233},"route.generate.quick-generate.formula": {"description": "Quick Generate with manifest-driven formula rendering and formula-image realization.",@@ -229,7 +229,7 @@"files": ["skills/ppt-master/scripts/docs/image.md"],- "max_tokens": 66100+ "max_tokens": 66408},"route.generate.quick-generate.ai-two-types": {"description": "Quick Generate with AI resource preparation, representative rendering inputs, and two local image types.",@@ -240,7 +240,7 @@"stage.generate.executor.image"],"files": [],- "max_tokens": 86025+ "max_tokens": 86333},"route.generate.quick-generate.web-image": {"description": "Quick Generate with web resource preparation, provenance, attribution, and image execution.",@@ -251,7 +251,7 @@"stage.generate.executor.web-image"],"files": [],- "max_tokens": 70675+ "max_tokens": 70983},"route.generate.planning-image": {"description": "Generate-PPTX planning context after a non-none image source is proposed or confirmed, including the compact layout math and vocabulary.",@@ -702,7 +702,7 @@"skills/ppt-master/scripts/docs/pptx-transitions.md","skills/ppt-master/scripts/docs/svg-pipeline.md"],- "max_tokens": 30490+ "max_tokens": 31302},"stage.generate.video-motion-plan": {"description": "Conditional resolved animation-to-video handoff contract.",@@ -718,7 +718,7 @@"files": ["skills/ppt-master/references/animations.md"],- "max_tokens": 7175+ "max_tokens": 8021},"stage.shared.generate-audio": {"description": "Shared narration-audio stage.",diff --git a/skills/ppt-master/workflows/profiles/quick-generate.md b/skills/ppt-master/workflows/profiles/quick-generate.mdindex 7e2b31a8..7d588632 100644--- a/skills/ppt-master/workflows/profiles/quick-generate.md+++ b/skills/ppt-master/workflows/profiles/quick-generate.md@@ -42,6 +42,23 @@ enable any ordinary capability when the request or deck benefits; use itsnormal inputs, flags, and prerequisites without asking for approval. Quicknever creates or reads a Design Spec or lock to enable it.+**Mandatory — discover motion before deciding whether to load it**: scan this+compact gate once; do not load the full execution reference when the defaults+already fit.++| Signal | Action |+|---|---|+| The same semantic object or scene continues across adjacent pages | Load [`animations.md`](../../references/animations.md) before SVG authoring; prepare both visible endpoints and use its Morph contract |+| Page- or object-specific reveal, renewed emphasis, meaningful movement, or same-page removal clarifies the message | Load [`animations.md`](../../references/animations.md) before SVG authoring; preserve the required units/states, then run [`customize-animations`](../stages/customize-animations.md) after the final checker |+| One deck-wide entrance policy supplies all required staged reveal | Load [`animations.md`](../../references/animations.md) before export and use an exporter flag such as `-a auto`; do not run the custom stage |+| A directional/section boundary benefits from a non-default transition | Load [`animations.md`](../../references/animations.md) before export and select from its §3 playbook |+| No earlier signal applies | Keep `fade` transitions and object animation `none`; do not load the motion reference |++This gate activates capability discovery, not motion coverage. Keep the+defaults when no row supplies a concrete communication job. When several+signals apply, perform every required action and use the earliest required load+point; a before-authoring signal always overrides a before-export-only timing.+---## 2. Source and Resource Preparationdiff --git a/skills/ppt-master/workflows/stages/customize-animations.md b/skills/ppt-master/workflows/stages/customize-animations.mdindex 1f93cfb8..d3ef68e2 100644--- a/skills/ppt-master/workflows/stages/customize-animations.md+++ b/skills/ppt-master/workflows/stages/customize-animations.md@@ -140,10 +140,12 @@ There is no target group count. Granularity follows the page's actual claims,comparisons, sequence, causality, and narration beats.After any regrouping, rerun the final SVG quality gate because `svg_output/`-changed:+changed. Use the owning route's checker form; Quick Generate must add its+lockless profile flag:```bashpython3 skills/ppt-master/scripts/svg_quality_checker.py <project_path> --stage final --json+# Quick Generate: insert --quick-generate before --stage.```Then list the **post-regroup** anchors:@@ -195,19 +197,11 @@ relevant transition, object effects, order, and timing. Use`design_spec.md` for slide role, `spec_lock.md` for rhythm and visual style,speaker notes for narration order, and SVG group ids for target validity.-**Mandatory — lifecycle before effect selection**:--| Duty | State contract | Effect family |-|---|---|---|-| `enter` | absent → introduce → present | `entrance_*`; modes only for generic reveal |-| `emphasize` | present → redirect attention → present/altered | Explicit `emphasis_*` |-| `move` | state/position A → progress → state/position B | Explicit `path_*`, or endpoint pages + Morph |-| `exit` | present → retire → absent | Explicit `exit_*` |-| `static` | present → hold as reference → present | Omit; use legacy `effect: none` only to suppress inheritance |--A unit may carry several duties as ordered `effects[]` rows. There is no-category quota; never reverse-engineer a communication job from an available-effect.+**Mandatory — select from meaning, not catalog coverage**: run the+page-relationship and lifecycle selection playbooks in+[`animations.md`](../../references/animations.md) §3 and §4 before choosing any+specific effect. Their candidates are recall aids, not coverage targets; this+stage binds the selected duties to real targets.**Title motion decision**: when a title participates, classify its lifecycle,then choose immediate, delayed, synchronized, post-hero, or narration-cued@@ -392,12 +386,18 @@ run:python3 skills/ppt-master/scripts/animation_config.py validate <project_path>```-After validation succeeds, return to-[`generate-pptx.md`](../generate-pptx.md) Step 7.1. Generate owns note-splitting, `finalize_svg.py`, native export, and the published postflight-receipt; Step 7.3 reads `<project_path>/animations.json` automatically. If §2-changed `svg_output/`, complete its required final SVG quality rerun before-returning. Do not finalize or export independently from this stage.+After validation succeeds, return to the owning export path:++- Default Generate → [`generate-pptx.md`](../generate-pptx.md) Step 7.1, which+ owns note splitting, `finalize_svg.py`, native export, and the published+ postflight receipt.+- Quick Generate → [`quick-generate.md`](../profiles/quick-generate.md) §4,+ which skips finalization and exports with `--quick-generate`.++Both exporters read `<project_path>/animations.json` automatically. If §2+changed `svg_output/`, complete the owning route's required final SVG quality+rerun before returning. Do not finalize or export independently from this+stage.**Validation**: The later native export must reflect the per-slide andper-object overrides. `--animation none` still disables all per-element