Skip to content

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(native-enhance): align scoped enhancement contract

hugohe3760e59f72bfe
diff --git a/docs/technical-design.md b/docs/technical-design.md
index fa3ab738..5e18e6d5 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -563,9 +563,9 @@ Not every PPTX-related request should regenerate slides. PPT Master now has dire
`template_fill_pptx.py` is a thin CLI wrapper over `scripts/template_fill_pptx/`. Its analyzer extracts a slide library with text slots, tables, charts, and geometry; the fill plan selects source slides, confirms replacements, then the applier clones slides and patches XML parts directly. This route deliberately avoids SVG: a user who supplies a PowerPoint template usually wants those native slide masters, placeholders, tables, and charts to remain PowerPoint-native.
-`native_enhance_pptx.py` is the stable entry point for finished-deck enhancement. It delegates to `native_enhance_pptx_core.py` and patches the PPTX package in place from a project copy: notes, page transitions, recorded narration media, slide timings, and related metadata. The retired `native_narration_pptx.py` name remains only as a thin CLI compatibility shim. The contract is preservation: existing content, layout, and formatting are not regenerated.
+`native_enhance_pptx.py` is the stable entry point for finished-deck enhancement. It delegates to `native_enhance_pptx_core.py` and patches the PPTX package from a project copy: notes, global or per-slide page transitions, recorded narration media, slide timings, and related metadata. Intake records a source hash and ordered slide-part roster; validate/apply reject source drift or incomplete requested material. A read-only delivery check inventories package integrity, fonts, media, hidden slides, size, and existing motion at intake/preflight, then audits the candidate before atomic publication. The retired `native_narration_pptx.py` name remains only as a thin CLI compatibility shim. The contract is preservation: existing content, layout, and formatting are not regenerated.
-These direct routes share some analysis primitives with the main pipeline, but at different depths. Template Fill consumes the standard PPTX intake slide library. Native Enhance uses `ppt_to_md.py` for content understanding and generates its own lightweight `slide_index.json` from the archived package. Neither shares the SVG authoring or post-processing stages. That separation is intentional: SVG generation is a design synthesis path; direct OOXML editing is a preservation path.
+These direct routes share some analysis primitives with the main pipeline, but at different depths. Template Fill consumes the standard PPTX intake slide library. Native Enhance uses `ppt_to_md.py` for content understanding, generates its own lightweight `slide_index.json` from the archived package, and keeps machine delivery reports under `validation/`. Neither shares the SVG authoring or post-processing stages. That separation is intentional: SVG generation is a design synthesis path; direct OOXML editing is a preservation path.
---
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index af694ba6..e3826b04 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -557,9 +557,9 @@ SVG 与 DrawingML 的表达模型并不等价,因此主编译路径不把“
`template_fill_pptx.py` 是 `scripts/template_fill_pptx/` 包的薄 CLI 入口。analyzer 抽取带文本槽位、表格、图表和几何信息的 slide library;fill plan 选择源页面并确认替换内容;applier 克隆幻灯片并直接 patch XML parts。这条路线故意绕开 SVG:用户提供 PowerPoint 模板时,通常期望原生母版、占位符、表格和图表继续保持 PowerPoint-native。
-`native_enhance_pptx.py` 是已完成 deck 原生增强的稳定入口。它委托 `native_enhance_pptx_core.py`,在项目归档副本上直接 patch PPTX package:讲稿、页面转场、录制旁白媒体、页面计时和相关元数据。旧名称 `native_narration_pptx.py` 仅保留为精简的 CLI 兼容包装器。它的契约是保留:已有内容、布局和格式不重新生成。
+`native_enhance_pptx.py` 是已完成 deck 原生增强的稳定入口。它委托 `native_enhance_pptx_core.py`,在项目归档副本上直接 patch PPTX package:讲稿、全局或按页转场、录制旁白媒体、页面计时和相关元数据。intake 会记录来源 hash 与有序 slide-part roster;validate/apply 会拒绝来源漂移或缺少已请求素材。只读 delivery check 会在 intake/preflight 盘点包完整性、字体、媒体、隐藏页、体积与已有 motion,并在原子发布前审计候选文件。旧名称 `native_narration_pptx.py` 仅保留为精简的 CLI 兼容包装器。它的契约是保留:已有内容、布局和格式不重新生成。
-这些直接路线会和主流水线共享部分分析原语,但复用深度不同:Template Fill 消费标准 PPTX intake 的 slide library;Native Enhance 只用 `ppt_to_md.py` 理解内容,并从归档 package 生成自己的轻量 `slide_index.json`。两者都不共享 SVG 作者阶段和后处理阶段。这个分离是有意的:SVG 生成是设计合成路径;直接 OOXML 编辑是保留路径。
+这些直接路线会和主流水线共享部分分析原语,但复用深度不同:Template Fill 消费标准 PPTX intake 的 slide library;Native Enhance 用 `ppt_to_md.py` 理解内容,从归档 package 生成自己的轻量 `slide_index.json`,并把机器 delivery report 放在 `validation/`。两者都不共享 SVG 作者阶段和后处理阶段。这个分离是有意的:SVG 生成是设计合成路径;直接 OOXML 编辑是保留路径。
---
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index e24f2de1..7b243b7e 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -45,7 +45,7 @@ python3 scripts/update_repo.py
| Area | Primary scripts | Documentation |
|------|-----------------|---------------|
| Conversion | `source_to_md.py`, `source_to_md/pdf_to_md.py`, `source_to_md/doc_to_md.py`, `source_to_md/excel_to_md.py`, `source_to_md/ppt_to_md.py`, `source_to_md/web_to_md.py`, `pptx_intake.py`, `pptx_to_svg.py` | [docs/conversion.md](./docs/conversion.md) |
-| Project management | `project_manager.py`, `page_context.py`, `batch_validate.py`, `generate_examples_index.py`, `error_helper.py`, `pptx_template_import.py`, `template_fill_pptx.py`, `native_enhance_pptx.py` | [docs/project.md](./docs/project.md) |
+| Project management | `project_manager.py`, `page_context.py`, `batch_validate.py`, `generate_examples_index.py`, `error_helper.py`, `pptx_template_import.py`, `template_fill_pptx.py`, `native_enhance_pptx.py`, `pptx_delivery_check.py` | [docs/project.md](./docs/project.md) |
| SVG pipeline | `preset_shape_svg.py`, `shape_boolean_svg.py`, `svg_authoring_view.py`, `compact_svg_coordinates.py`, `mirror_template_materialize.py`, `finalize_svg.py`, `svg_to_pptx.py`, `template_preview_pptx.py`, `total_md_split.py`, `svg_quality_checker.py`, `extract_svg_assets.py`, `extract_svg_pictures.py`, `animation_config.py`, `notes_to_audio.py`, `narration_sync.py` | [docs/svg-pipeline.md](./docs/svg-pipeline.md); [native shape authoring](../references/native-shape-authoring.md) |
| PPTX transitions | `pptx_transitions.py` | [docs/pptx-transitions.md](./docs/pptx-transitions.md) |
| PPTX animations | `pptx_animations.py`, `animation_config.py` | [docs/pptx-animations.md](./docs/pptx-animations.md) |
@@ -183,6 +183,7 @@ python3 scripts/native_enhance_pptx.py init <source.pptx> --name <project_slug>
python3 scripts/native_enhance_pptx.py plan <project_path>
python3 scripts/native_enhance_pptx.py validate <project_path>
python3 scripts/native_enhance_pptx.py apply <project_path>
+python3 scripts/pptx_delivery_check.py <finished.pptx>
```
Native preset shape authoring (one registry-backed fragment on stdout):
diff --git a/skills/ppt-master/scripts/docs/pptx-transitions.md b/skills/ppt-master/scripts/docs/pptx-transitions.md
index 1beeec7d..b846e6e1 100644
--- a/skills/ppt-master/scripts/docs/pptx-transitions.md
+++ b/skills/ppt-master/scripts/docs/pptx-transitions.md
@@ -235,9 +235,9 @@ continue to preserve existing object names and transition XML.
| Generated PPTX CLI | fade, 0.4s | click | auto-advance maps to both |
| Recorded narration | Preserve resolved enter | narration | none remains visually none |
| Template Fill v1 | fade, 0.5s | click | keep preserves source; legacy advance_after maps to both |
-| Native Enhance v1 | Confirmed plan effect | Confirmed timing module | Disabled transitions preserve unless the v1 plan explicitly selected none |
+| Native Enhance | Confirmed global/per-slide plan effect | Confirmed timing module | Explicit page entries override scope; disabled global transitions preserve unless the plan selected none |
-Template Fill and Native Enhance keep their v1 route defaults.
+Template Fill and Native Enhance keep their established route defaults.
The public `create_pptx_with_native_svg` Python API also retains its legacy
0.5s default; the CLI explicitly passes 0.4s. Changing a default policy is a
separate migration decision.
diff --git a/skills/ppt-master/scripts/native_enhance_pptx.py b/skills/ppt-master/scripts/native_enhance_pptx.py
index 51bc779d..6aaa5cbe 100644
--- a/skills/ppt-master/scripts/native_enhance_pptx.py
+++ b/skills/ppt-master/scripts/native_enhance_pptx.py
@@ -2,9 +2,9 @@
"""
PPT Master - Native Enhance PPTX Entrypoint
-Public CLI wrapper for native enhancement of existing PPTX decks. V1 delegates
-to the narration/timings implementation while keeping the stable command name
-aligned with the native-enhance workflow.
+Public CLI wrapper for native enhancement of existing PPTX decks. It delegates
+to the shared native core for delivery checks, notes, narration, timings, and
+global or per-slide transitions while keeping the stable workflow command.
Usage:
python3 scripts/native_enhance_pptx.py init <source.pptx> [--name project_name]
diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.json
index 904e50ca..a5403dc9 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": 387200
+ "max_tokens": 388200
},
"file_budgets": {
"AGENTS.md": 2400,
@@ -122,7 +122,7 @@
"files": [
"skills/ppt-master/workflows/native-enhance-pptx.md"
],
- "max_tokens": 8725
+ "max_tokens": 9600
},
"route.fill-native-pptx": {
"description": "Raw-PPTX native fill route.",
@@ -383,7 +383,7 @@
"stage.shared.generate-audio"
],
"files": [],
- "max_tokens": 13650
+ "max_tokens": 14500
},
"route.generate.beautify-flat-no-image": {
"description": "Generate-PPTX 1:1 beautify profile on the flat no-image path.",
@@ -632,7 +632,7 @@
"skills/ppt-master/scripts/docs/pptx-transitions.md",
"skills/ppt-master/scripts/docs/svg-pipeline.md"
],
- "max_tokens": 28725
+ "max_tokens": 28750
},
"stage.generate.video-motion-plan": {
"description": "Conditional resolved animation-to-video handoff contract.",
diff --git a/skills/ppt-master/workflows/native-enhance-pptx.md b/skills/ppt-master/workflows/native-enhance-pptx.md
index 8071cfc4..7ab5dc50 100644
--- a/skills/ppt-master/workflows/native-enhance-pptx.md
+++ b/skills/ppt-master/workflows/native-enhance-pptx.md
@@ -1,10 +1,10 @@
---
-description: Native enhancement platform for existing PPTX files, starting with notes/audio/timings/transitions without SVG conversion
+description: Native enhancement platform for existing PPTX files, with delivery checks and scoped OOXML updates without SVG conversion
---
# Enhance Native PPTX Route
-> Top-level route for enhancing an existing PowerPoint deck without regenerating it. V1 implements the `narration` module: speaker notes, narration audio, slide auto-advance timings, and page transitions.
+> Top-level route for enhancing an existing PowerPoint deck without regenerating it. The current write scope is speaker notes, narration audio, slide auto-advance timings, and global or per-slide page transitions; read-only delivery checks always run.
This route treats a `.pptx` as the artifact to preserve. It archives the source file into a lightweight project, uses `ppt_to_md.py` only to understand slide content, then patches the archived PPTX package directly through OOXML zip operations.
@@ -52,15 +52,15 @@ source.pptx
| `narration.audio` | Enabled | Embed one audio file per slide |
| `narration.timings` | Enabled | Set narrated slides to auto-advance by audio duration |
| `narration.transitions` | Enabled | Add page-level transitions for narrated/selected slides |
-| `delivery.check` | Planned | Font/media/hidden-slide/file-size validation |
+| `delivery.check` | Enabled | Read-only package/font/media/hidden-slide/file-size and existing-motion audit |
| `media` | Planned | Background music, video, media compression |
| `presenter` | Planned | Q&A notes, speaker cues, rehearsal artifacts |
| `animation` | Planned | Explicit object-level animation only |
| `visible-stamp` | Planned | Watermark/footer/logo; requires explicit confirmation |
-**Default — V1 only**: Do not implement planned modules inside this route yet. Keep V1 focused on the narration module.
+**Default — current write scope only**: Do not implement planned write modules inside this route yet. Keep mutations limited to notes, narration audio, timings, and page transitions.
-**Object animation boundary**: Object-level animation is not part of V1. If the user asks for it, treat it as a future module or a separate explicitly confirmed task.
+**Object animation boundary**: `delivery.check` reports existing object-animation presence, and apply proves its fingerprint is unchanged. It does not author or edit object animations. The shared animation writer builds a complete timing tree for generated slides and is not safe to append to an arbitrary native slide.
---
@@ -97,9 +97,11 @@ Project layout:
| `<project>/notes/` | Per-slide spoken notes, named `001.md`, `002.md`, ... |
| `<project>/audio/` | Per-slide narration media, named `001.mp3`, `002.mp3`, ... |
| `<project>/exports/` | Enhanced PPTX copies |
-| `<project>/validation/` | Coverage reports and read-back artifacts |
+| `<project>/validation/` | Delivery checks, readiness reports, and read-back artifacts |
-**Validation**: `project.json` contains `schema: native_pptx_enhancement_project.v1`, `kind: native_pptx_enhancement`, and `modules` containing `notes`, `audio`, `timings`, `transitions`.
+**Validation**: `project.json` contains `schema: native_pptx_enhancement_project.v1`, `kind: native_pptx_enhancement`, and `modules` containing `notes`, `audio`, `timings`, `transitions`, and `delivery.check`.
+
+`init` records the archived source SHA-256 and ordered slide-part roster, then writes the intake audit to `<project>/validation/report.json`. Package-integrity, OPC part/content-type/relationship, XML, slide-inventory, transition, or object-animation errors stop before a project-local source is moved. The only retained historical structural baseline is the narrowly recognized legacy notes-slide relationship to a missing notes master; it remains visible in the report and apply may not add any new structural error.
**Source import rule**: When `<source.pptx>` is inside the repo's `projects/` tree, `init` moves it into `<project>/sources/`. When it is outside `projects/`, `init` copies it into `<project>/sources/`. The mode is recorded in `project.json` as `source_import.mode`.
@@ -123,6 +125,8 @@ If the project already existed or notes/audio coverage changed, refresh the draf
python3 skills/ppt-master/scripts/native_enhance_pptx.py plan "<project>"
```
+Refresh preserves user-owned module enablement, timing padding, global transition settings, and `transitions.slides`; it recomputes file presence/coverage, resets the plan to `draft`, and requires confirmation again. Audio coverage in the plan is explicitly `decodability: unchecked`; `validate` owns the ffprobe gate. CLI flags override only fields explicitly supplied.
+
Present the plan to the user before generating notes or audio:
| Module | Recommended default | Confirmation question |
@@ -131,6 +135,7 @@ Present the plan to the user before generating notes or audio:
| `audio` | Enabled when user wants narration/video/autoplay | Generate one narration audio file per slide? |
| `timings` | Enabled with audio | Set slide auto-advance from audio duration? |
| `transitions` | Enabled, `fade` 0.5s | Add page transitions? Which canonical native effect, Effect Options, and duration? |
+| `delivery.check` | Always on, read-only | No confirmation required; review errors and advisories |
**⛔ BLOCKING**: Stop here and wait for explicit user confirmation. Do not generate notes, generate audio, or patch the PPTX until the user confirms the module plan.
@@ -142,7 +147,7 @@ Present the plan to the user before generating notes or audio:
| Transitions disabled with a non-`none` configured effect | Preserve the source effect, including unknown `AlternateContent` | Preserve unless timings is enabled |
| Explicit `none` | Remove the visual effect | Preserve, or write timing-only advance when timings is enabled |
| Timings enabled with audio | Keep the resolved enter policy | Use audio duration plus narration padding; click disabled |
-| Timings disabled | Apply the confirmed enter policy only | Do not run `ffprobe`; do not add/change `advTm` or `useTimings` |
+| Timings disabled | Apply the confirmed enter policy only | Audio readiness may probe decodability; do not use duration or add/change `advTm` or `useTimings` |
The confirmed `modules.transitions` object may include `effect_options` beside
an explicit canonical `effect`. Use
@@ -150,6 +155,45 @@ an explicit canonical `effect`. Use
Old names remain accepted only when reading compatibility input; a newly
written plan stores the canonical effect and any implied options.
+For explicit page selection or page-specific settings, add `slides` keyed by
+the 1-based `index` in `analysis/slide_index.json`:
+
+```json
+{
+ "modules": {
+ "transitions": {
+ "enabled": false,
+ "effect": "fade",
+ "duration": 0.5,
+ "apply_without_audio": false,
+ "slides": {
+ "2": {},
+ "3": {"duration": 0.8},
+ "4": {
+ "effect": "push",
+ "effect_options": {"direction": "left"}
+ },
+ "5": {"effect": "none"},
+ "6": {"effect": "preserve"}
+ }
+ }
+ }
+}
+```
+
+| Per-slide entry | Behavior |
+|---|---|
+| `{}` | Select the page and inherit the global effect/options/duration |
+| Partial object | Inherit omitted global fields; a new explicit effect uses its own default options |
+| `effect: none` | Remove the visual transition; timings remain independently owned |
+| `effect: preserve` | Preserve the source visual transition; narration timing may still update advance |
+
+An explicit `slides` entry selects a page even when it has no audio and
+`apply_without_audio` is false. With `transitions.enabled: false`, only listed
+pages opt in; unlisted pages preserve their source transition. Morph uses
+PowerPoint's automatic matching only—this route does not rename native objects
+to create deterministic pairs.
+
**Hard rule — no silent downgrade**: a requested native effect must be written with its complete validated Effect Options. Unknown effects or inapplicable options fail; unknown source effects are preserved when the transition module is disabled.
After confirmation, update `<project>/analysis/enhancement_plan.json`:
@@ -200,7 +244,7 @@ Run coverage check:
python3 skills/ppt-master/scripts/native_enhance_pptx.py validate "<project>"
```
-> Note: before audio generation, missing audio returns exit code `2` only when `audio.enabled` is true. Missing notes are not acceptable once this step is complete.
+> Note: missing, empty, unreadable, or undecodable requested material returns exit code `2`. Package, source-drift, plan/module, or duplicate native-enhance narration-carrier errors return `1`.
---
@@ -263,7 +307,20 @@ python3 skills/ppt-master/scripts/native_enhance_pptx.py apply "<project>" \
Without `--apply-transition-without-audio` (or the matching confirmed-plan
field), the resolved enter policy is applied while processing slides with
-audio; slides without audio keep their source transition.
+audio; slides without audio keep their source transition unless explicitly
+listed in `modules.transitions.slides`.
+
+`apply` reruns the same source/readiness/plan checks as `validate`. Enabling
+audio always requires every selected file to be decodable by ffprobe; enabling
+timings additionally consumes that duration for `advTm`. It refuses
+partial requested material, a changed source hash/slide roster, or a source
+that already contains a `native_enhance_audio_*` carrier. New audio/poster
+parts use collision-free names; an existing poster is reused only when its
+bytes match the tool marker exactly. Output must be a new `.pptx` under
+`exports/` or an external location; apply never overwrites either source or
+writes into project control directories. Every apply attempt invalidates the
+previous validation receipt, and a failed preflight records its current errors
+instead of leaving stale passed evidence.
Patch scope:
@@ -279,6 +336,13 @@ Patch scope:
**Hard rule**: Do not modify existing slide shapes, text bodies, images, chart data, master/layout parts, or existing non-target relationships.
+Before publishing the candidate, apply validates transitions, timing/object
+animation structure, ZIP integrity, unique parts, internal relationships,
+slide count, and hidden-slide state. The narrowly allowed legacy missing
+notes-master finding may remain exactly equivalent, but the candidate must not
+introduce any structural error. Apply then writes both audits and the
+introduced-error delta to `<project>/validation/report.json`.
+
---
## 10. Validate Output
@@ -302,13 +366,15 @@ Check:
| Auto-play | Narrated slides advance by audio duration |
| Transition | Requested effect remains exact; preserved `AlternateContent` keeps its primary and fallback branches |
| Timings disabled | Source `advTm` and package `useTimings` are not changed |
+| Delivery check | No newly introduced structural errors; source baseline and font/media/hidden-slide advisories reviewed |
```markdown
## ✅ Native PPTX Enhancement V1 Complete
- [x] Project initialized at `<project>`
- [x] Source PPTX archived into `<project>/sources/`
-- [x] V1 narration module applied
+- [x] Confirmed native enhancement modules applied
- [x] Enhanced PPTX exported to `<project>/exports/<file>.pptx`
+- [x] Delivery postflight written to `<project>/validation/report.json`
- [x] Read-back validation written to `<project>/validation/readback.md`
```