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.mdindex 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.mdindex 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.mdindex 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.mdindex 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 consumersdiff --git a/docs/zh/faq.md b/docs/zh/faq.mdindex 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.mdindex 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.mdindex 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):```bashpython3 ${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.mdindex 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 PPTXpython3 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.mdindex 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.mdindex 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.pyindex 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.pyindex 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" / timestampif 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: