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.mdindex 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.mdindex 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.mdindex 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.mdindex 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 legacy0.5s default; the CLI explicitly passes 0.4s. Changing a default policy is aseparate migration decision.diff --git a/skills/ppt-master/scripts/native_enhance_pptx.py b/skills/ppt-master/scripts/native_enhance_pptx.pyindex 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.jsonindex 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.mdindex 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 drafpython3 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` besidean explicit canonical `effect`. Use@@ -150,6 +155,45 @@ an explicit canonical `effect`. UseOld names remain accepted only when reading compatibility input; a newlywritten 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-planfield), 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````