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
fix(workflow): prepare image layouts for semantic motion
hugohe35c4a84c964fc
diff --git a/skills/ppt-master/references/executor-image.md b/skills/ppt-master/references/executor-image.mdindex 372525e2..0696bdd6 100644--- a/skills/ppt-master/references/executor-image.md+++ b/skills/ppt-master/references/executor-image.md@@ -25,6 +25,10 @@ Handle images by their status in the Design Spec's Image Resource List. Status e**Reference — preferred pattern, flexible realization**: Read [`image-layout-patterns.md`](./image-layout-patterns.md) once when this branch loads, then resolve every primary/modifier id in each active §VIII/lock row so the Strategist's recommendation is understood. Use it as a strong starting point, but adapt its geometry or choose another catalog/ordinary composition when the actual page can communicate better. Preserve the resource role, file/source, must-use status, crop policy, content, and explicit user/template constraints; a pattern-only change needs no upstream rewrite. Avoid generic left/right repetition.+**Reference — motion-ready image layering, not a constraint**: When the Executor adopts a §IX `Motion suggestion`, or an explicit user requirement calls for focus, comparison, evidence, or reveal order, decide during main SVG authoring whether the fully revealed composition benefits from separate visible semantic units. Useful splits include a stable image field plus annotation/hotspot groups, base and comparison images, a full view plus same-source crop/lens, atmosphere plus evidence, or a static field plus cutout foreground. For ordinary Slide-local content, keep stable framing/background static and wrap each independently revealable unit in a descriptive direct-root `<g id>`. Structured atoms/slots keep their declared boundaries and may serve as units only as-is. If existing legal units or a page transition already carry the communication job, add nothing. Effects, order, and timing belong to the later motion stage.++**Hard rule — visible-layer timing**: Any crop, lens, scrim, comparison, evidence, or annotation layer required by an adopted motion plan MUST already exist in the final SVG without violating structural contracts. The later stage may regroup ordinary Slide-local content visual-equivalently, but cannot invent or modify missing visible content. If no legal existing unit can serve a non-binding suggestion, simplify it to available units, a page transition, or `none`; an explicit requirement that cannot be represented follows failure recovery.+**No semantic re-reading**: §VIII owns image identity, purpose, and focus / crop constraints. Executor uses its `Reference` plus regenerated dimensions; it never opens source images to rediscover subjects, substitute assets, or invent focus. For `adaptive` without reliable focus, use `meet`; missing or contradictory required constraints return upstream.**Placeholder**: Dashed border `<rect stroke-dasharray="8,4" .../>` + description textdiff --git a/skills/ppt-master/references/image-layout-patterns.md b/skills/ppt-master/references/image-layout-patterns.mdindex fa2c9716..9ab59c1c 100644--- a/skills/ppt-master/references/image-layout-patterns.md+++ b/skills/ppt-master/references/image-layout-patterns.md@@ -362,6 +362,8 @@ A page is built by layering. Pick one or more **Primary Structures** (Part 1) as**Cross-primary combinations are encouraged.** A side-by-side comparison (#48) where each side is annotated with Shape-first leader cards (#38) is one page, not a violation. A 3×3 grid (#9) whose center cell is upgraded to an image-as-canvas with KPI overlay (#40) reads as one composition. The old reflex "one primary per page" tends to under-use the catalog — combine when the page asks for it.+**Reference — motion-aware layer vocabulary, not a constraint**: When focus, comparison, evidence, or reveal order serves the page, the Image-as-Canvas + Native Overlay and Multi-Image Compositions families may expose independently meaningful visible units. `#62` can separate full view from same-source detail; `#63` can isolate a cutout foreground; `#74` / `#77` / `#78` / `#80` can separate image-led navigation or evidence units. These are composition layers, not effect assignments, and no pattern owes animation. `#72` is a static image blend in the fully revealed page, not a PowerPoint page transition.+**Modifier stacking pattern that works in practice** — observed on real content pages combining one Primary with four Modifiers:- one Primary from Part 1 (e.g. #48 side-by-side comparison)diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.mdindex 863e2185..a25d8737 100644--- a/skills/ppt-master/references/strategist.md+++ b/skills/ppt-master/references/strategist.md@@ -283,10 +283,10 @@ and intent; explicit user/template requirements remain binding.| Capability | Opportunity signal | Design Spec handoff ||---|---|---|-| Image composition | Image-as-canvas plus native overlay, editorial crop, collage, cutout, or another image-led composition carries the page better than an adjacent rectangle | Propose a permitted image source; when selected, load [`strategist-image.md`](./strategist-image.md) and record an exact catalog §VIII `Layout pattern` as the preferred composition |+| Image composition | Image-as-canvas plus native overlay, editorial crop, collage, cutout, or independently meaningful focus / comparison / evidence units carry the page better than an adjacent rectangle | Propose a permitted image source; when selected, load [`strategist-image.md`](./strategist-image.md), record each resource's exact catalog §VIII `Layout pattern`, and describe the page-level image/overlay relationship in §IX `Layout` / `Images` || Native shape / Merge Shapes | A literal Office symbol, a stock bent/curved relationship contour, or a compound silhouette, negative-space cutout, overlap-only region, or meaningful fragmentation strengthens the visual idea | Add an optional §IX `Native shape suggestion` with the semantic result plus a candidate preset/Connector family or Boolean operation/operands || Page transition | A section/state change, spatial continuity, or recorded/self-running flow benefits from motion between pages | Add an optional §IX `Motion suggestion` describing the communication job; leave effect and timing to Executor |-| Object animation | Progressive reveal clarifies sequence, causality, comparison, hierarchy, or narration order | Add an optional §IX `Motion suggestion` describing reveal units/order; leave group ids, effect, and timing to Executor |+| Object animation | Progressive reveal clarifies sequence, causality, comparison, hierarchy, narration order, full-view → detail, atmosphere → evidence, or hotspot/annotation order | Add an optional §IX `Motion suggestion` describing semantic units/order and any visible image-state relationship; leave group ids, effect, and timing to Executor |Review planned pages through two lenses:diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.jsonindex 5d13d083..184a771a 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": 368700+ "max_tokens": 370000},"file_budgets": {"AGENTS.md": 2350,@@ -20,7 +20,7 @@"skills/ppt-master/references/executor-base.md": 7925,"skills/ppt-master/references/executor-structured.md": 5300,"skills/ppt-master/references/executor-chart.md": 3100,- "skills/ppt-master/references/executor-image.md": 900,+ "skills/ppt-master/references/executor-image.md": 1200,"skills/ppt-master/references/executor-web-image.md": 500,"skills/ppt-master/references/executor-notes.md": 900,"skills/ppt-master/references/shared-standards.md": 250,@@ -28,10 +28,10 @@"skills/ppt-master/references/svg-effects.md": 11725,"skills/ppt-master/references/native-data-interface.md": 6200,"skills/ppt-master/references/pptx-structure-interface.md": 4300,- "skills/ppt-master/references/strategist.md": 13975,+ "skills/ppt-master/references/strategist.md": 14025,"skills/ppt-master/references/strategist-image.md": 2300,"skills/ppt-master/references/strategist-template.md": 2100,- "skills/ppt-master/templates/design_spec_reference.md": 3000,+ "skills/ppt-master/templates/design_spec_reference.md": 3125,"skills/ppt-master/templates/spec_lock_reference.md": 2350,"skills/ppt-master/workflows/generate-pptx.md": 12700,"skills/ppt-master/workflows/stages/apply-template-workspace.md": 1800@@ -322,7 +322,7 @@"stage.generate.executor.notes"],"files": [],- "max_tokens": 84200+ "max_tokens": 84500},"route.generate.flat-ai-two-types": {"description": "Generate-PPTX context with AI images, representative multi-source custom rendering, and two local types.",@@ -335,7 +335,7 @@"stage.generate.image.ai-two-types"],"files": [],- "max_tokens": 124850+ "max_tokens": 125600},"route.generate.flat-in-hand-image": {"description": "Generate-PPTX context with provided, placeholder, or formula images and no acquisition role.",@@ -347,7 +347,7 @@"stage.generate.executor.notes"],"files": [],- "max_tokens": 98175+ "max_tokens": 98875},"route.generate.flat-web-image": {"description": "Generate-PPTX context with web image acquisition.",@@ -360,7 +360,7 @@"stage.generate.image.web"],"files": [],- "max_tokens": 105400+ "max_tokens": 106125},"route.enhance-native-pptx.audio": {"description": "Enhance Native PPTX with the shared narration-audio stage.",@@ -380,7 +380,7 @@"profile.generate.beautify-pptx"],"files": [],- "max_tokens": 91100+ "max_tokens": 91400},"route.generate.flat-no-image-chart": {"description": "Default flat Generate-PPTX path with chart authoring, native-data replacement, and verification.",@@ -393,7 +393,7 @@"stage.generate.verify-charts"],"files": [],- "max_tokens": 108550+ "max_tokens": 108825},"route.generate.brand-flat-no-image": {"description": "Brand-preset flat Generate-PPTX path without image acquisition.",@@ -405,7 +405,7 @@"stage.generate.template.brand"],"files": [],- "max_tokens": 91225+ "max_tokens": 91500},"route.generate.deck-structured-no-image": {"description": "Deck-preset structured Generate-PPTX path without image acquisition.",@@ -417,7 +417,7 @@"stage.generate.template.deck"],"files": [],- "max_tokens": 101150+ "max_tokens": 101450},"route.generate.layout-structured-no-image": {"description": "Layout-preset structured Generate-PPTX path without image acquisition.",@@ -429,7 +429,7 @@"stage.generate.template.layout"],"files": [],- "max_tokens": 101600+ "max_tokens": 101900},"route.generate.topic-only-flat-no-image": {"description": "Topic research followed by the default flat no-image Generate-PPTX path.",@@ -439,7 +439,7 @@"route.generate.flat-no-image"],"files": [],- "max_tokens": 85600+ "max_tokens": 85900},"stage.generate.executor.flat": {"description": "Incremental flat Executor core with representative multi-source custom mode/style execution.",@@ -549,7 +549,7 @@"stage.generate.executor.image"],"files": [],- "max_tokens": 59950+ "max_tokens": 60525},"stage.generate.topic-research": {"description": "Gap-targeted factual intake stage.",@@ -619,7 +619,7 @@"skills/ppt-master/scripts/docs/pptx-transitions.md","skills/ppt-master/scripts/docs/svg-pipeline.md"],- "max_tokens": 22875+ "max_tokens": 23050},"stage.generate.video-motion-plan": {"description": "Conditional resolved animation-to-video handoff contract.",@@ -685,7 +685,7 @@"stage.generate.strategist.template"],"files": [],- "max_tokens": 61200+ "max_tokens": 61500},"route.generate.planning-template-ai": {"description": "Explicit template workspace plus confirmed AI-image planning.",@@ -695,7 +695,7 @@"route.generate.planning-ai"],"files": [],- "max_tokens": 73775+ "max_tokens": 74200},"stage.generate.executor.chart": {"description": "Conditional chart/table page execution rules.",@@ -722,7 +722,7 @@"files": ["skills/ppt-master/references/image-layout-patterns.md"],- "max_tokens": 8350+ "max_tokens": 8500},"stage.generate.strategist.template": {"description": "Conditional Strategist module for an explicitly installed template workspace.",@@ -749,7 +749,7 @@"skills/ppt-master/references/image-layout-spec.md","skills/ppt-master/references/svg-image-embedding.md"],- "max_tokens": 11725+ "max_tokens": 12150},"stage.generate.executor.web-image": {"description": "Conditional sourced-image attribution layered on image execution.",@@ -760,7 +760,7 @@"files": ["skills/ppt-master/references/executor-web-image.md"],- "max_tokens": 12150+ "max_tokens": 12575},"stage.generate.executor.notes": {"description": "Post-SVG speaker-notes generation rules.",diff --git a/skills/ppt-master/templates/design_spec_reference.md b/skills/ppt-master/templates/design_spec_reference.mdindex 84e3a575..5876f7a8 100644--- a/skills/ppt-master/templates/design_spec_reference.md+++ b/skills/ppt-master/templates/design_spec_reference.md@@ -168,6 +168,8 @@ For every independent data chart or pure text-grid table, add `- **Native-ready*In §VIII, author every planned or explicitly required resource from the confirmed source boundary. Copy the recommended `Layout pattern` id/name and modifiers verbatim as a preferred composition; set `Crop Policy` to `adaptive` or `no-crop`; set `Acquire Via` to `ai`, `web`, `user`, `formula`, `placeholder`, or `slice`. Preserve unresolved required assets as `Pending` or `Needs-Manual` instead of dropping or reclassifying them.+§VIII `Layout pattern` is a per-resource preference. When a page uses several images, repeats one image in multiple views, or combines an image with native overlays, describe the page-level relationship and participating resources in §IX `Layout` / `Images`; do not duplicate an unchanged resource row merely to encode animation sequencing.+### 2.4 Complete page roster and notesWrite one ordered Slide block per page. Slide count and order must equal §I `Page Count`; `Content` is a complete page brief, not a skeleton.@@ -202,7 +204,7 @@ never write an empty or `none` placeholder:- **Motion suggestion**: <communication job plus desired page-entry or reveal relationship/order>```-Add `Visualization` and `Images` to a Slide block when it consumes §VII/§VIII rows or uses a page-local visualization. State whether `Visualization` is data-driven when source values determine geometry; this page-level declaration remains authoritative even when no catalog reference fits. Add `Native shape suggestion` only when a literal PowerPoint preset, a stock bent/curved Connector contour, or a compound silhouette/cutout/intersection/fragment may strengthen the page; describe the semantic object/result and candidate family or Boolean operation/operands, not coordinates, paths, exact preset keys, endpoint/site metadata, or attachment promises. Executor chooses the actual basic primitive, preset, Boolean construction, or necessary freeform. Add `Motion suggestion` only when a page transition or progressive reveal would strengthen communication; describe its purpose and semantic order/relationship in natural language, not registry keys, Effect Options, durations, group ids, or coverage. It remains a recommendation: Executor owns the exact native behavior and may simplify it or choose no motion unless that would violate an explicit user requirement. Add `Native-ready: yes|no` only for independent data charts or pure text-grid tables. Add `Fact IDs` for sourced claims and `Data class: scenario` for invented demo values. Add `Cover impact` to P01 except on preservation paths; add `Closing impact` only when the final page genuinely resolves the deck. Roster ids/count/order and final content are authoritative. §VIII image patterns are preferred composition references; chart rows only offer page-local references. Executor owns geometry, hierarchy, treatment, and sparse local garnish.+Add `Visualization` and `Images` to a Slide block when it consumes §VII/§VIII rows or uses a page-local visualization. State whether `Visualization` is data-driven when source values determine geometry; this page-level declaration remains authoritative even when no catalog reference fits. Add `Native shape suggestion` only when a literal PowerPoint preset, a stock bent/curved Connector contour, or a compound silhouette/cutout/intersection/fragment may strengthen the page; describe the semantic object/result and candidate family or Boolean operation/operands, not coordinates, paths, exact preset keys, endpoint/site metadata, or attachment promises. Executor chooses the actual basic primitive, preset, Boolean construction, or necessary freeform. Add `Motion suggestion` only when a page transition or progressive reveal would strengthen communication; describe its purpose and semantic order/relationship in natural language, not registry keys, Effect Options, durations, group ids, or coverage. When it depends on visible image states, describe those fully revealed units in the same page's `Layout` / `Images`; the suggestion does not create missing visual content. It remains a recommendation: Executor owns the exact native behavior and may simplify it or choose no motion unless that would violate an explicit user requirement. Add `Native-ready: yes|no` only for independent data charts or pure text-grid tables. Add `Fact IDs` for sourced claims and `Data class: scenario` for invented demo values. Add `Cover impact` to P01 except on preservation paths; add `Closing impact` only when the final page genuinely resolves the deck. Roster ids/count/order and final content are authoritative. §VIII image patterns are preferred composition references; chart rows only offer page-local references. Executor owns geometry, hierarchy, treatment, and sparse local garnish.For free-design pages, describe `Layout` through relationships, hierarchy, regions, and column spans; do not prescribe element-level `x`, `y`, `width`, or `height` or duplicate the global geometry in §II/§V. Exact coordinates belong to Executor SVG authoring. Preserve literal geometry only when the user explicitly requires it or a mirror/template preservation contract owns it.diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.mdindex 673fe3aa..d51d340f 100644--- a/skills/ppt-master/workflows/generate-pptx.md+++ b/skills/ppt-master/workflows/generate-pptx.md@@ -388,6 +388,8 @@ python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live --daemonEach completed SVG MUST be a standalone, complete representation of that slide's visible design. Template SVGs and locked planning artifacts may guide construction, but export must not reach back to them to add visible objects omitted from `svg_output/`. Speaker notes, animation, narration, transitions, and direct native-PPTX workflows remain separately owned artifacts/capabilities. Treat §IX `Native shape suggestion` as a candidate, not a command: inspect the actual page construction, then choose the highest-level faithful construction in this order — editable basic primitive, exact Office preset, Merge Shapes Boolean result, and only then a necessary freeform. Load and apply [`native-shape-authoring.md`](../references/native-shape-authoring.md) before materializing an adopted native treatment. Diagram relationships follow the same Shape-first order; do not infer a preset from contour similarity.+**Motion-ready image composition**: When an adopted §IX `Motion suggestion` or explicit user requirement depends on distinct in-slide image states, author those visible states now under [`executor-image.md`](../references/executor-image.md). Give each independently revealable ordinary Slide-local unit a descriptive direct-root `<g id>`; structured atoms/slots retain their declared boundaries and are targetable only when that contract permits. Do not defer required visible content or reshape structure for the later stage. This is SVG preparation, not early animation authoring: effects, order, and timing remain in the conditional custom stage after notes. A page-transition-only suggestion requires no extra SVG layer.+`template_reuse_scope: mirror|layout` pages MUST start from the complete `page_layouts` SVG, keep inherited visible objects, and preserve root Master/Layout identity plus stable atoms/slots. Strict preserves that reusable contract; under `layout`, the once-loaded Design Spec's `Template Application` may still authorize carrier text/tspan reflow inside unchanged slot bounds. Adaptive uses the current or new Layout key/name already declared by Strategist. If construction proves that fixed atoms or slot topology/bounds must change, stop and return upstream for Strategist to repair the owning plan and lock, validate and read back the affected fragments, then resume; Executor never mutates `spec_lock.md`. `mirror` changes only visible text values while preserving text/tspan topology and attributes. `style` follows the flat paragraph below without structure metadata.`template_reuse_scope: style`, free-design, and brand-only pages use `pptx_structure.mode: flat`. Draw the complete page directly: keep backgrounds, repeated chrome, headings, text, images, and decoration as ordinary Slide-local SVG content. Do not plan `pptx_masters` / `pptx_layouts` / `page_pptx_layouts`, do not add root Master/Layout identity, and do not add `data-pptx-layer` or `data-pptx-placeholder` metadata. Group logical content normally with top-level `<g id>` elements. Export materializes one clean project-owned Master plus one Blank Layout, applies the locked theme colors/fonts/title-body defaults, removes stock content placeholders and unused built-in Layouts, and retains only the standard date/footer/slide-number capability hooks. It does not promote or deduplicate page content.@@ -437,7 +439,8 @@ python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path> --stage final> **Visual self-check (opt-in)?** If the user explicitly asked for a per-page visual re-pass on the SVGs ("跑一下视觉自检 / 视觉回看", "visual review", "check pages visually", etc.), run the [`visual-review`](stages/visual-review.md) quality-gate stage before Step 7. Do NOT run it by default and do NOT recommend it based on inferred model capability or deck size — trigger is user request only.-> **Motion capability (conditional)?** After `notes/total.md` exists, inspect §IX+> **Motion execution (conditional)?** Visible-layer preparation belongs to the+> main SVG pass above. After `notes/total.md` exists, inspect §IX> `Motion suggestion` rows, explicit user motion requirements, and an existing> `<project_path>/animations.json`. With none of the three, keep the exporter> defaults (`fade` page transition, per-element animation `none`) and load nodiff --git a/skills/ppt-master/workflows/stages/customize-animations.md b/skills/ppt-master/workflows/stages/customize-animations.mdindex c0a2abff..145d71ca 100644--- a/skills/ppt-master/workflows/stages/customize-animations.md+++ b/skills/ppt-master/workflows/stages/customize-animations.md@@ -68,6 +68,8 @@ mandatory. Executor maps an adopted suggestion to the native registry, mayadjust its effect/order/timing or choose `none` when motion would reduceclarity, and never changes page content merely to justify animation.+**Hard rule — existing visible-layer boundary**: This stage may regroup existing content only under §2 visual equivalence; it MUST NOT create or modify a crop, comparison layer, scrim, lens, hotspot, annotation, or other visible image state to satisfy motion intent. When a required state is missing and ordinary Slide-local authoring can supply it, return to Generate Step 6, rerun the final SVG gate and notes, then resume here. If a structural boundary prevents that repair, simplify a non-binding suggestion to legal existing units, a page transition, or `none`; an explicit requirement follows failure recovery instead of changing structure.+**No-op is complete**: Evaluate suggestions before regrouping SVG content. Ifno `animations.json` exists, every page should retain the normal `fade`transition and no object builds, and no explicit user requirement remains@@ -235,6 +237,8 @@ four-spoke amount.effects implicitly. Select an explicit canonical key when the plan calls forone.+**Hard rule — explicit semantic choreography**: When an adopted image-led plan depends on a specific reveal relationship or order, target its real groups with explicit canonical effects and order; do not delegate those material decisions to `auto`, `mixed`, or `random`. Those modes remain valid when generic entrance treatment is sufficient.+**Start modes**:| Trigger | Behavior |