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

feat(svg_to_pptx): make SVG snapshot pptx opt-in via --svg-snapshot

hugohe302d4ad659a47
diff --git a/README.md b/README.md
index 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.md
index 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.md
index 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.md
index 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 consumers
diff --git a/docs/zh/faq.md b/docs/zh/faq.md
index 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.md
index 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.md
index 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>
```bash
python3 ${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.md
index 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 PPTX
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/references/shared-standards.md b/skills/ppt-master/references/shared-standards.md
index 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.md
index 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 audio
Behavior:
- 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.py
index 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.py
index 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 = None
if 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