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): decouple svg_output backup from --svg-snapshot

hugohe3d0ab9ca61110
diff --git a/README.md b/README.md
index 4ff0cba0..4d58f619 100644
--- a/README.md
+++ b/README.md
@@ -236,7 +236,7 @@ AI: Sure. Let's confirm the design spec:
The AI handles everything — content analysis, visual design, SVG generation, and PPTX export.
-> **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+.
+> **Output:** Native-shapes `.pptx` (directly editable) saved to `exports/<name>_<timestamp>.pptx`. A copy of `svg_output/` is always snapshotted to `backup/<timestamp>/svg_output/` for re-export / archival. Pass `--svg-snapshot` to additionally emit an SVG-image preview pptx alongside the native pptx in `exports/` (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 2ffa7fe1..a61be109 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -244,7 +244,7 @@ AI:好的,先确认设计规范:
AI 全程处理——内容分析、视觉设计、SVG 生成、PPTX 导出。
-> **输出说明:** 原生形状版 `.pptx`(可直接编辑)保存至 `exports/<name>_<timestamp>.pptx`。加 `--svg-snapshot` 可额外生成 SVG 快照版 pptx + `svg_output/` 副本到 `backup/<timestamp>/`(默认关闭,详见[常见问题](./docs/zh/faq.md))。需要 Office 2016+。
+> **输出说明:** 原生形状版 `.pptx`(可直接编辑)保存至 `exports/<name>_<timestamp>.pptx`;`svg_output/` 始终镜像到 `backup/<timestamp>/svg_output/`,便于归档或后续重跑。加 `--svg-snapshot` 时,额外在 `exports/` 内并排生成 SVG 快照版 pptx(详见[常见问题](./docs/zh/faq.md))。需要 Office 2016+。
> **AI 迷失上下文?** 让它先读 `skills/ppt-master/SKILL.md`。
diff --git a/docs/faq.md b/docs/faq.md
index 37829f4f..842a444b 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. 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.
+Yes. The main `.pptx` (native PowerPoint shapes — all text, graphics, and colors directly editable without any conversion) is saved to `exports/` with a timestamp. A copy of `svg_output/` (the Executor's raw SVG source) is always written to `backup/<timestamp>/svg_output/` so you can rebuild via `finalize_svg → svg_to_pptx` without re-running the LLM. Pass `--svg-snapshot` to additionally emit an SVG-image preview pptx alongside the native pptx in `exports/` — handy for cross-platform distribution as a single file; 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 86747953..391cb3cb 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -40,11 +40,11 @@ User Input (PDF/DOCX/XLSX/URL/Markdown)
↓
Output:
exports/
- └── presentation_<timestamp>.pptx ← Native shapes (DrawingML) — canonical output, edit & deliver from here
+ ├── presentation_<timestamp>.pptx ← Native shapes (DrawingML) — canonical output, edit & deliver from here
+ └── presentation_<timestamp>_svg.pptx ← SVG snapshot pptx — pixel-perfect visual reference (opt-in via --svg-snapshot)
- # Opt-in via --svg-snapshot (e.g. for distribution / frozen-state archive)
+ # Always written in default-flow mode (no -o)
backup/<timestamp>/
- ├── presentation_svg.pptx ← SVG snapshot pptx — pixel-perfect visual reference
└── svg_output/ ← Archived Executor SVG source (rerun finalize_svg → svg_to_pptx to rebuild)
```
@@ -240,7 +240,8 @@ 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, 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 |
+| `exports/<name>_<ts>_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 |
+| `backup/<ts>/svg_output/` (always written in default-flow mode) | re-export from frozen SVG sources without re-running the LLM, archival | the only persisted copy of the Executor's raw SVG source after the project has been edited downstream |
### The `svg_finalize/` package has TWO consumers
diff --git a/docs/zh/faq.md b/docs/zh/faq.md
index 6153ea30..48ff0c7e 100644
--- a/docs/zh/faq.md
+++ b/docs/zh/faq.md
@@ -44,7 +44,7 @@ PPT Master 可以在任何能读取文件和执行命令的 AI 编程代理中
## Q: 生成的 PPT 可以编辑吗?
-可以。主 `.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** 或更高版本。
+可以。主 `.pptx`(原生 PowerPoint 形状,文字、图形、颜色均可直接编辑,无需转换)以时间戳命名保存至 `exports/`。Executor 的原始 SVG 源(`svg_output/` 副本)始终镜像到 `backup/<timestamp>/svg_output/`,便于归档或基于该版重跑 `finalize_svg → svg_to_pptx` 重建 pptx,无需再走 LLM。加 `--svg-snapshot` 会额外在 `exports/` 内并排生成 SVG 快照版 pptx,便于跨平台单文件分发;默认关闭——日常开发/诊断场景中 live preview 已经提供了 SVG 视觉参考。需要 **Office 2016** 或更高版本。
## Q: 三种执行师有什么区别?
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index 6a0a8b35..ffb4c3f2 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -40,11 +40,11 @@
↓
输出:
exports/
- └── presentation_<timestamp>.pptx ← 原生形状版(DrawingML)— 唯一标准产物,编辑/交付从这里走
+ ├── presentation_<timestamp>.pptx ← 原生形状版(DrawingML)— 唯一标准产物,编辑/交付从这里走
+ └── presentation_<timestamp>_svg.pptx ← SVG 快照版 pptx — 像素级视觉参考(加 --svg-snapshot 时生成)
- # 显式 --svg-snapshot 才生成(用于分发 / 冻结快照存档)
+ # 默认流程(未指定 -o)始终写入
backup/<timestamp>/
- ├── presentation_svg.pptx ← SVG 快照版 pptx — 像素级视觉参考
└── svg_output/ ← Executor 原始 SVG 备份(重跑 finalize_svg → svg_to_pptx 即可重建 pptx)
```
@@ -240,7 +240,8 @@ 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,需 `--svg-snapshot` 显式开启) | 跨平台单文件分发、整体多页浏览、邮件附件 | 自包含、多页、PowerPoint / Keynote / WPS / LibreOffice 都能直接打开;`svg_final/` 是文件夹,分发不便。默认关闭——live preview 已经覆盖 dev / 诊断场景的 SVG 视觉参考需求 |
+| `exports/<name>_<ts>_svg.pptx`(preview,需 `--svg-snapshot` 显式开启) | 跨平台单文件分发、整体多页浏览、邮件附件 | 自包含、多页、PowerPoint / Keynote / WPS / LibreOffice 都能直接打开;`svg_final/` 是文件夹,分发不便。默认关闭——live preview 已经覆盖 dev / 诊断场景的 SVG 视觉参考需求 |
+| `backup/<ts>/svg_output/`(默认流程下始终生成) | 不重跑 LLM 的前提下从冻结 SVG 源重建 pptx、长期存档 | 项目下游被改动后,Executor 原始 SVG 唯一的留存副本 |
### `svg_finalize/` 包有**两种**消费者
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index e24e4783..4ea67a72 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -375,21 +375,22 @@ python3 ${SKILL_DIR}/scripts/finalize_svg.py <project_path>
**Step 7.3** — Export PPTX (embeds speaker notes by default):
```bash
python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
-# Output:
+# Output (default-flow mode):
# exports/<project_name>_<timestamp>.pptx ← native pptx (canonical output, reads svg_output/)
+# backup/<timestamp>/svg_output/ ← Executor SVG source backup (always written)
#
-# 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
+# Add --svg-snapshot to additionally emit the SVG-image preview pptx alongside the native pptx:
+# exports/<project_name>_<timestamp>_svg.pptx ← SVG preview pptx (reads svg_final/)
```
> 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.
+> → `srcRect`, rounded rect `rx/ry` → `prstGeom roundRect`). The `svg_output/`
+> snapshot in `backup/<timestamp>/` is always written so the project can be
+> re-exported from frozen SVG sources without re-running the LLM. The SVG-rendered
+> preview pptx is opt-in via `--svg-snapshot` — live preview already provides the
+> SVG visual reference, so it's only needed when you want a self-contained file
+> to share. 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 2e93626d..2253f9a7 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -404,10 +404,10 @@ python3 scripts/finalize_svg.py <project_path>
# 3. Export PPTX
python3 scripts/svg_to_pptx.py <project_path>
-# Output:
+# Output (default-flow mode):
# exports/<project_name>_<timestamp>.pptx ← native pptx (canonical output)
+# backup/<timestamp>/svg_output/ ← Executor SVG source backup (always written)
#
-# Add --svg-snapshot to also emit:
-# backup/<timestamp>/<project_name>_svg.pptx ← SVG snapshot pptx
-# backup/<timestamp>/svg_output/ ← Executor SVG source backup
+# Add --svg-snapshot to additionally emit:
+# exports/<project_name>_<timestamp>_svg.pptx ← SVG snapshot pptx (sibling of native pptx)
```
diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.md
index 90d79c1d..c59fee38 100644
--- a/skills/ppt-master/references/shared-standards.md
+++ b/skills/ppt-master/references/shared-standards.md
@@ -302,12 +302,12 @@ 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:
+# Output (default-flow mode):
# exports/<project_name>_<timestamp>.pptx ← native pptx (canonical output)
+# backup/<timestamp>/svg_output/ ← Executor SVG source backup (always written)
#
-# Add --svg-snapshot to also emit:
-# backup/<timestamp>/<project_name>_svg.pptx ← SVG snapshot pptx
-# backup/<timestamp>/svg_output/ ← Executor SVG source backup
+# Add --svg-snapshot to additionally emit:
+# exports/<project_name>_<timestamp>_svg.pptx ← SVG snapshot pptx (sibling of native pptx)
```
**Optional animation flags** (only when the user asks):
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index 22cfd47a..0b460518 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -44,11 +44,11 @@ python3 scripts/svg_to_pptx.py <project_path> --recorded-narration audio
```
Behavior:
-- Default output:
+- Default output (default-flow mode, no `-o`):
- `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
+ - `backup/<timestamp>/svg_output/` — copy of Executor SVG source, always written so the pptx can be rebuilt via `finalize_svg → svg_to_pptx` without re-running the LLM
+- `--svg-snapshot` (opt-in) additionally emits:
+ - `exports/<project_name>_<timestamp>_svg.pptx` — SVG snapshot pptx for visual reference, sibling of the native pptx
- 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/`
diff --git a/skills/ppt-master/scripts/project_manager.py b/skills/ppt-master/scripts/project_manager.py
index 59feeda1..053f02f5 100644
--- a/skills/ppt-master/scripts/project_manager.py
+++ b/skills/ppt-master/scripts/project_manager.py
@@ -163,8 +163,8 @@ class ProjectManager:
"- `notes/`: speaker notes\n"
"- `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 (created only when exported with `--svg-snapshot`; safe to delete old timestamps)\n"
+ "- `exports/`: main native pptx (timestamped); `_svg.pptx` sibling added when exported with `--svg-snapshot`\n"
+ "- `backup/<timestamp>/`: svg_output/ archive (always written in default-flow mode; 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 b170e1bc..51baab31 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py
@@ -72,8 +72,8 @@ def main() -> None:
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog=f'''
Examples:
- %(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 -s final # Default: native pptx -> exports/, svg_output -> backup/<ts>/
+ %(prog)s examples/ppt169_demo --svg-snapshot # Also emit SVG-rendered snapshot pptx alongside native in exports/
%(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/)
@@ -152,9 +152,11 @@ Recorded narration:
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.')
+ help='Also emit the SVG-rendered snapshot pptx alongside the native pptx in exports/ '
+ '(named <project>_<ts>_svg.pptx). Off by default — the native pptx is the '
+ 'canonical output; live preview already provides the SVG visual reference. '
+ 'Note: the svg_output/ source snapshot is always written to backup/<ts>/ '
+ 'regardless of this flag.')
def non_negative_float(value: str) -> float:
try:
@@ -291,10 +293,13 @@ Recorded narration:
exports_dir = project_path / "exports"
exports_dir.mkdir(parents=True, exist_ok=True)
native_path = exports_dir / f"{project_name}_{timestamp}.pptx"
+ # svg_output/ snapshot always goes under backup/<ts>/ in default-flow
+ # mode (no -o). --svg-snapshot only controls the optional legacy
+ # SVG-rendered pptx, which now sits alongside the native pptx in
+ # exports/ rather than nested inside backup/.
+ backup_dir = project_path / "backup" / timestamp
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"
+ legacy_path = exports_dir / f"{project_name}_{timestamp}_svg.pptx"
native_path.parent.mkdir(parents=True, exist_ok=True)
if legacy_path is not None:
@@ -525,19 +530,23 @@ Recorded narration:
)
success = success and ok
- if ok and backup_dir is not None:
- svg_output_src = project_path / "svg_output"
- if svg_output_src.is_dir():
- svg_output_dst = backup_dir / "svg_output"
- try:
- shutil.copytree(svg_output_src, svg_output_dst)
- if verbose:
- print(f" svg_output backup: {svg_output_dst}")
- except Exception as exc:
- if verbose:
- print(f" [warn] svg_output backup skipped: {exc}")
- elif verbose:
- print(f" [info] svg_output/ not found, backup skipped")
+ # svg_output/ snapshot — runs once per export in default-flow mode,
+ # decoupled from --svg-snapshot. Preserves the AI-generated SVG sources
+ # under backup/<ts>/svg_output/ for later inspection / re-export.
+ if success and backup_dir is not None:
+ svg_output_src = project_path / "svg_output"
+ if svg_output_src.is_dir():
+ backup_dir.mkdir(parents=True, exist_ok=True)
+ svg_output_dst = backup_dir / "svg_output"
+ try:
+ shutil.copytree(svg_output_src, svg_output_dst)
+ if verbose:
+ print(f" svg_output backup: {svg_output_dst}")
+ except Exception as exc:
+ if verbose:
+ print(f" [warn] svg_output backup skipped: {exc}")
+ elif verbose:
+ print(f" [info] svg_output/ not found, backup skipped")
if success and cache_dir is not None and cache_dir.is_dir() and not args.keep_cache:
try: