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
feat(svg_to_pptx): make SVG snapshot pptx opt-in via --svg-snapshot
hugohe302d4ad659a47
diff --git a/README.md b/README.mdindex 4935990f..ce1be7c0 100644--- a/README.md+++ b/README.md@@ -221,7 +221,7 @@ AI: Sure. Let's confirm the design spec:The AI handles everything — content analysis, visual design, SVG generation, and PPTX export.-> **Output:** Main native-shapes `.pptx` (directly editable) saved to `exports/<name>_<timestamp>.pptx`. The SVG snapshot `_svg.pptx` and a copy of `svg_output/` are archived to `backup/<timestamp>/` for visual reference and pptx rebuild without re-running the LLM. Requires Office 2016+.+> **Output:** Native-shapes `.pptx` (directly editable) saved to `exports/<name>_<timestamp>.pptx`. Pass `--svg-snapshot` to also emit an SVG-image preview pptx + `svg_output/` copy under `backup/<timestamp>/` (off by default; see [FAQ](./docs/faq.md)). Requires Office 2016+.> **AI lost context?** Ask it to read `skills/ppt-master/SKILL.md`.diff --git a/README_CN.md b/README_CN.mdindex d0cd60a4..a2b242ac 100644--- a/README_CN.md+++ b/README_CN.md@@ -229,7 +229,7 @@ AI:好的,先确认设计规范:AI 全程处理——内容分析、视觉设计、SVG 生成、PPTX 导出。-> **输出说明:** 原生形状版主 `.pptx`(可直接编辑)保存至 `exports/<name>_<timestamp>.pptx`;SVG 快照版 `_svg.pptx` 与 `svg_output/` 副本归档至 `backup/<timestamp>/`,便于回溯视觉参考或免去 LLM 重跑直接重建 pptx。需要 Office 2016+。+> **输出说明:** 原生形状版 `.pptx`(可直接编辑)保存至 `exports/<name>_<timestamp>.pptx`。加 `--svg-snapshot` 可额外生成 SVG 快照版 pptx + `svg_output/` 副本到 `backup/<timestamp>/`(默认关闭,详见[常见问题](./docs/zh/faq.md))。需要 Office 2016+。> **AI 迷失上下文?** 让它先读 `skills/ppt-master/SKILL.md`。diff --git a/docs/faq.md b/docs/faq.mdindex 176ccdad..37829f4f 100644--- a/docs/faq.md+++ b/docs/faq.md@@ -44,7 +44,7 @@ For better contemporary stock photography, set `PEXELS_API_KEY` and/or `PIXABAY_## Q: Can I edit the generated presentations?-Yes. The main `.pptx` (native PowerPoint shapes — all text, graphics, and colors directly editable without any conversion) is saved to `exports/` with a timestamp. The SVG snapshot `_svg.pptx` plus a copy of `svg_output/` (the Executor's raw SVG source) are archived to `backup/<timestamp>/`, so you can revisit the visual reference or rebuild the pptx via `finalize_svg → svg_to_pptx` without re-running the LLM. `backup/<timestamp>/` directories can be deleted manually when no longer needed. Requires **Office 2016** or later.+Yes. The main `.pptx` (native PowerPoint shapes — all text, graphics, and colors directly editable without any conversion) is saved to `exports/` with a timestamp. Pass `--svg-snapshot` to also emit a SVG-image preview pptx plus a copy of `svg_output/` (the Executor's raw SVG source) into `backup/<timestamp>/` — handy for cross-platform distribution as a single file or rebuilding via `finalize_svg → svg_to_pptx` without re-running the LLM. The snapshot is off by default because live preview already serves as the SVG visual reference for day-to-day work. Requires **Office 2016** or later.## Q: What's the difference between the three Executors?diff --git a/docs/technical-design.md b/docs/technical-design.mdindex f562162b..86747953 100644--- a/docs/technical-design.md+++ b/docs/technical-design.md@@ -40,9 +40,11 @@ User Input (PDF/DOCX/XLSX/URL/Markdown)↓Output:exports/- └── presentation_<timestamp>.pptx ← Native shapes (DrawingML) — recommended for editing & delivery+ └── presentation_<timestamp>.pptx ← Native shapes (DrawingML) — canonical output, edit & deliver from here++ # Opt-in via --svg-snapshot (e.g. for distribution / frozen-state archive)backup/<timestamp>/- ├── presentation_svg.pptx ← SVG snapshot — pixel-perfect visual reference backup+ ├── presentation_svg.pptx ← SVG snapshot pptx — pixel-perfect visual reference└── svg_output/ ← Archived Executor SVG source (rerun finalize_svg → svg_to_pptx to rebuild)```@@ -238,7 +240,7 @@ The post-processing stage produces four artifacts. Each one serves a workflow th| `svg_output/` | source of truth, manual editing, `update_spec.py`, `svg_quality_checker.py` | only directory whose contents are authored, not derived || `svg_final/` | IDE inline preview (VSCode/Cursor open `.svg` directly), browser open of a single page | `.pptx` is not openable in IDEs; `svg_output/` won't render fully because of external icon / image refs || `exports/<name>_<ts>.pptx` (native) | primary deliverable — editable in PowerPoint with DrawingML shapes | only artifact whose shapes the user can resize / recolor / restyle natively in PowerPoint |-| `backup/<ts>/<name>_svg.pptx` (preview) | cross-platform single-file distribution, multi-page browse, email attachment | self-contained, multi-page, opens in PowerPoint / Keynote / WPS / LibreOffice; an `svg_final/` folder is harder to distribute |+| `backup/<ts>/<name>_svg.pptx` (preview, opt-in via `--svg-snapshot`) | cross-platform single-file distribution, multi-page browse, email attachment | self-contained, multi-page, opens in PowerPoint / Keynote / WPS / LibreOffice; an `svg_final/` folder is harder to distribute. Off by default — live preview already provides the SVG visual reference for dev/diagnostic work |### The `svg_finalize/` package has TWO consumersdiff --git a/docs/zh/faq.md b/docs/zh/faq.mdindex ff1da1fe..6153ea30 100644--- a/docs/zh/faq.md+++ b/docs/zh/faq.md@@ -44,7 +44,7 @@ PPT Master 可以在任何能读取文件和执行命令的 AI 编程代理中## Q: 生成的 PPT 可以编辑吗?-可以。主 `.pptx`(原生 PowerPoint 形状,文字、图形、颜色均可直接编辑,无需转换)以时间戳命名保存至 `exports/`。SVG 快照版 `_svg.pptx` 与 Executor 原始 SVG 源(`svg_output/` 副本)一同归档至 `backup/<timestamp>/`,便于回溯视觉参考或基于该版重跑 `finalize_svg → svg_to_pptx` 重建 pptx,无需再走 LLM。`backup/<timestamp>/` 目录可手动清理。需要 **Office 2016** 或更高版本。+可以。主 `.pptx`(原生 PowerPoint 形状,文字、图形、颜色均可直接编辑,无需转换)以时间戳命名保存至 `exports/`。加 `--svg-snapshot` 可以额外生成 SVG 快照版 pptx 与 Executor 原始 SVG 源(`svg_output/` 副本)到 `backup/<timestamp>/`,便于跨平台单文件分发或基于该版重跑 `finalize_svg → svg_to_pptx` 重建 pptx,无需再走 LLM。默认关闭——日常开发/诊断场景中 live preview 已经提供了 SVG 视觉参考。需要 **Office 2016** 或更高版本。## Q: 三种执行师有什么区别?diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.mdindex 461ae93c..6a0a8b35 100644--- a/docs/zh/technical-design.md+++ b/docs/zh/technical-design.md@@ -40,9 +40,11 @@↓输出:exports/- └── presentation_<timestamp>.pptx ← 原生形状版(DrawingML)— 推荐用于编辑与交付+ └── presentation_<timestamp>.pptx ← 原生形状版(DrawingML)— 唯一标准产物,编辑/交付从这里走++ # 显式 --svg-snapshot 才生成(用于分发 / 冻结快照存档)backup/<timestamp>/- ├── presentation_svg.pptx ← SVG 快照版 — 像素级视觉参考备份+ ├── presentation_svg.pptx ← SVG 快照版 pptx — 像素级视觉参考└── svg_output/ ← Executor 原始 SVG 备份(重跑 finalize_svg → svg_to_pptx 即可重建 pptx)```@@ -238,7 +240,7 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。Executor 在一份| `svg_output/` | 唯一源、手工编辑入口、`update_spec.py`、`svg_quality_checker.py` | 流水线中唯一**手写**而非派生的目录 || `svg_final/` | IDE 内即时预览(VSCode/Cursor 直接打开 `.svg`)、浏览器单页预览 | `.pptx` 在 IDE 里打不开;`svg_output/` 因图标 / 图片是外部引用,IDE 中渲染不完整 || `exports/<name>_<ts>.pptx`(native) | 主交付物——PowerPoint 中以 DrawingML 形状形态可编辑 | 唯一一份用户可在 PowerPoint 中原生改尺寸 / 改色 / 改样式的产物 |-| `backup/<ts>/<name>_svg.pptx`(preview) | 跨平台单文件分发、整体多页浏览、邮件附件 | 自包含、多页、PowerPoint / Keynote / WPS / LibreOffice 都能直接打开;`svg_final/` 是文件夹,分发不便 |+| `backup/<ts>/<name>_svg.pptx`(preview,需 `--svg-snapshot` 显式开启) | 跨平台单文件分发、整体多页浏览、邮件附件 | 自包含、多页、PowerPoint / Keynote / WPS / LibreOffice 都能直接打开;`svg_final/` 是文件夹,分发不便。默认关闭——live preview 已经覆盖 dev / 诊断场景的 SVG 视觉参考需求 |### `svg_finalize/` 包有**两种**消费者diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.mdindex 83882262..e24e4783 100644--- a/skills/ppt-master/SKILL.md+++ b/skills/ppt-master/SKILL.md@@ -376,18 +376,20 @@ python3 ${SKILL_DIR}/scripts/finalize_svg.py <project_path>```bashpython3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path># Output:-# exports/<project_name>_<timestamp>.pptx ← main native pptx (reads svg_output/, high fidelity)+# exports/<project_name>_<timestamp>.pptx ← native pptx (canonical output, reads svg_output/)+#+# Add --svg-snapshot to also emit the SVG-image preview pptx + svg_output/ backup:# backup/<timestamp>/<project_name>_svg.pptx ← SVG preview pptx (reads svg_final/)# backup/<timestamp>/svg_output/ ← Executor SVG source backup```-> The two products now read from different sources by design: native pptx-> consumes `svg_output/` so the converter can preserve high-fidelity primitives-> (icon `<use>` placeholders, image `preserveAspectRatio` → `srcRect`, rounded-> rect `rx/ry` → `prstGeom roundRect`). The legacy/preview pptx still consumes-> `svg_final/` because PowerPoint's internal SVG parser cannot handle those-> primitives. Pass `-s output` or `-s final` to force a single source on both-> products if you need the older single-source behaviour.+> The native pptx consumes `svg_output/` directly so the converter can preserve+> high-fidelity primitives (icon `<use>` placeholders, image `preserveAspectRatio`+> → `srcRect`, rounded rect `rx/ry` → `prstGeom roundRect`). The SVG snapshot is+> opt-in via `--svg-snapshot` — live preview already provides the SVG visual+> reference, so the snapshot pptx is only needed when you want a self-contained+> file to share or to rebuild without re-running the LLM. Pass `-s output` or+> `-s final` to force a single source if you need it.**Optional animation flags** (the defaults already enable rich entrance animations — adjust only when the user asks for something different):- `-t <effect>` — page transition. Default `fade`. Options: `fade` / `push` / `wipe` / `split` / `strips` / `cover` / `random` / `none`.diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.mdindex acdfd8cd..2e93626d 100644--- a/skills/ppt-master/references/executor-base.md+++ b/skills/ppt-master/references/executor-base.md@@ -405,7 +405,9 @@ python3 scripts/finalize_svg.py <project_path># 3. Export PPTXpython3 scripts/svg_to_pptx.py <project_path># Output:-# exports/<project_name>_<timestamp>.pptx ← main native pptx-# backup/<timestamp>/<project_name>_svg.pptx ← SVG snapshot+# exports/<project_name>_<timestamp>.pptx ← native pptx (canonical output)+#+# Add --svg-snapshot to also emit:+# backup/<timestamp>/<project_name>_svg.pptx ← SVG snapshot pptx# backup/<timestamp>/svg_output/ ← Executor SVG source backup```diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.mdindex ff86fbf1..90d79c1d 100644--- a/skills/ppt-master/references/shared-standards.md+++ b/skills/ppt-master/references/shared-standards.md@@ -303,8 +303,10 @@ python3 scripts/finalize_svg.py <project_path># 3. Export PPTX (from svg_final/, embeds speaker notes by default)python3 scripts/svg_to_pptx.py <project_path># Output:-# exports/<project_name>_<timestamp>.pptx ← main native pptx-# backup/<timestamp>/<project_name>_svg.pptx ← SVG snapshot+# exports/<project_name>_<timestamp>.pptx ← native pptx (canonical output)+#+# Add --svg-snapshot to also emit:+# backup/<timestamp>/<project_name>_svg.pptx ← SVG snapshot pptx# backup/<timestamp>/svg_output/ ← Executor SVG source backup```diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.mdindex 83224215..22cfd47a 100644--- a/skills/ppt-master/scripts/docs/svg-pipeline.md+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md@@ -45,10 +45,12 @@ python3 scripts/svg_to_pptx.py <project_path> --recorded-narration audioBehavior:- Default output:- - `exports/<project_name>_<timestamp>.pptx` — main native editable pptx- - `backup/<timestamp>/<project_name>_svg.pptx` — SVG snapshot for visual reference+ - `exports/<project_name>_<timestamp>.pptx` — native editable pptx (canonical output)+- `--svg-snapshot` (opt-in) adds:+ - `backup/<timestamp>/<project_name>_svg.pptx` — SVG snapshot pptx for visual reference- `backup/<timestamp>/svg_output/` — copy of Executor SVG source, so the pptx can be rebuilt via `finalize_svg → svg_to_pptx` without re-running the LLM-- Explicit `-o/--output` keeps the legacy side-by-side `_svg.pptx` next to the chosen path and skips `backup/`+ - Live preview already serves as the SVG visual reference for day-to-day use; the snapshot pptx is for distribution or frozen-state archival+- Explicit `-o/--output` skips `backup/`; pair with `--svg-snapshot` to also emit the side-by-side `_svg.pptx` next to the chosen path- Recommended source directory: `svg_final/`- For PPTX template-import workspaces, use `-s svg-flat` when you need a visual round-trip check. The layered `svg/` tree is the machine-readable template source and intentionally does not inline inherited master / layout decoration into each slide.- Native mode is strict about unsupported visual SVG elements: if a visual element cannot be represented or safely preserved, export fails with the SVG file, element tag, and position instead of silently dropping content.@@ -75,7 +77,7 @@ Behavior:- `--animation-duration` controls per-element entrance length (default `0.4`); `--animation-stagger` adds gap between elements in `after-previous` mode (default `0.5`)- Optional object-level overrides live in `<project>/animations.json` or a path passed via `--animation-config`; build and validate them with `animation_config.py scaffold|validate`-Performance (legacy `_svg.pptx` PNG fallback):+Performance (legacy `_svg.pptx` PNG fallback, only when `--svg-snapshot` or `--only legacy`):- SVG→PNG is pre-rendered in a process pool before the main loop. Default workers = `min(cpu, pages, 8)`; override with `--workers N` (set `1` for sequential, `0` is treated as sequential).- Results are cached at `<project>/.cache/svg_png/` keyed by SVG content hash + size + active renderer (`cairosvg` vs `svglib`). Switching renderers naturally invalidates the cache; nothing to clean by hand.- `--cache-dir <path>` relocates the cache; `--no-cache` forces re-render without writing/reading the cache (handy when debugging rendering).diff --git a/skills/ppt-master/scripts/project_manager.py b/skills/ppt-master/scripts/project_manager.pyindex 8e3d2d59..59feeda1 100644--- a/skills/ppt-master/scripts/project_manager.py+++ b/skills/ppt-master/scripts/project_manager.py@@ -164,7 +164,7 @@ class ProjectManager:"- `templates/`: project templates\n""- `sources/`: source materials and normalized markdown\n""- `exports/`: main native pptx (timestamped)\n"- "- `backup/<timestamp>/`: SVG snapshot pptx + svg_output/ archive (auto-created on export; safe to delete old timestamps)\n"+ "- `backup/<timestamp>/`: SVG snapshot pptx + svg_output/ archive (created only when exported with `--svg-snapshot`; safe to delete old timestamps)\n"),encoding="utf-8",)diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.pyindex a5faf50b..b170e1bc 100644--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py@@ -72,10 +72,10 @@ def main() -> None:formatter_class=argparse.RawDescriptionHelpFormatter,epilog=f'''Examples:- %(prog)s examples/ppt169_demo -s final # Default: main pptx -> exports/, SVG snapshot + svg_output -> backup/<ts>/- %(prog)s examples/ppt169_demo --only native # Only native shapes version- %(prog)s examples/ppt169_demo --only legacy # Only SVG image version- %(prog)s examples/ppt169_demo -o out.pptx # Explicit path (SVG ref -> out_svg.pptx)+ %(prog)s examples/ppt169_demo -s final # Default: native pptx -> exports/ only+ %(prog)s examples/ppt169_demo --svg-snapshot # Also emit SVG snapshot + svg_output -> backup/<ts>/+ %(prog)s examples/ppt169_demo --only legacy # Only SVG image version (skips native)+ %(prog)s examples/ppt169_demo -o out.pptx # Explicit path (no backup/)# Disable transition / change transition effect%(prog)s examples/ppt169_demo -t none@@ -151,6 +151,10 @@ Recorded narration:help='Only generate one version: native (editable shapes) or legacy (SVG image)')mode_group.add_argument('--native', action='store_true', default=False,help='(Deprecated, now default) Convert SVG to native DrawingML shapes')+ parser.add_argument('--svg-snapshot', action='store_true', default=False,+ help='Also emit SVG snapshot pptx + svg_output/ copy under backup/<ts>/. '+ 'Off by default — the native pptx in exports/ is the canonical output; '+ 'live preview already provides the SVG visual reference.')def non_negative_float(value: str) -> float:try:@@ -233,14 +237,17 @@ Recorded narration:if canvas_format is None and detected_format and detected_format != 'unknown':canvas_format = detected_format- # Determine which versions to generate+ # Determine which versions to generate.+ # Default is native-only; SVG snapshot is opt-in via --svg-snapshot.+ # --only native / --only legacy still force a single version explicitly.only_mode = args.only- gen_native = only_mode in (None, 'native')- gen_legacy = only_mode in (None, 'legacy')-- # --native flag (deprecated) maps to --only native- if args.native and only_mode is None:- gen_legacy = False+ if only_mode == 'native':+ gen_native, gen_legacy = True, False+ elif only_mode == 'legacy':+ gen_native, gen_legacy = False, True+ else:+ gen_native = True+ gen_legacy = args.svg_snapshot# Pipeline split: native pptx gets the high-fidelity svg_output/ source# (icons, preserveAspectRatio, rounded-rect rx/ry are all preserved by the@@ -273,22 +280,25 @@ Recorded narration:timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")backup_dir: Path | None = None+ legacy_path: Path | None = Noneif args.output:output_base = Path(args.output)native_path = output_base- stem = output_base.stem- legacy_path = output_base.parent / f"{stem}_svg{output_base.suffix}"+ if gen_legacy:+ stem = output_base.stem+ legacy_path = output_base.parent / f"{stem}_svg{output_base.suffix}"else:exports_dir = project_path / "exports"exports_dir.mkdir(parents=True, exist_ok=True)native_path = exports_dir / f"{project_name}_{timestamp}.pptx"-- backup_dir = project_path / "backup" / timestamp- backup_dir.mkdir(parents=True, exist_ok=True)- legacy_path = backup_dir / f"{project_name}_svg.pptx"+ if gen_legacy:+ backup_dir = project_path / "backup" / timestamp+ backup_dir.mkdir(parents=True, exist_ok=True)+ legacy_path = backup_dir / f"{project_name}_svg.pptx"native_path.parent.mkdir(parents=True, exist_ok=True)- legacy_path.parent.mkdir(parents=True, exist_ok=True)+ if legacy_path is not None:+ legacy_path.parent.mkdir(parents=True, exist_ok=True)verbose = not args.quiet