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

docs(routing): clarify which route to use for an existing PPT

hugohe34893453f7616
diff --git a/AGENTS.md b/AGENTS.md
index e1c93519..8c674e55 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -14,7 +14,7 @@ PPT Master is an AI-driven presentation generation system. Multi-role collaborat
>
> Template fill: when the user provides an existing `.pptx` template plus text materials or a topic and asks to reuse the original PPT design or fill content back into it (for example, "fill this deck with the new content", "fill this back into the template", or "reuse this deck's design"), run the standalone [`template-fill-pptx`](skills/ppt-master/workflows/template-fill-pptx.md) workflow. This route edits PPTX directly and must not enter the SVG generation pipeline.
>
-> Beautify / re-layout: when the user provides an existing `.pptx` and asks to beautify or re-layout it while keeping the content (for example, "把这份 PPT 美化一下", "重新排版,内容别动", or wants to paste the regenerated elements back into the original deck), run the standalone [`beautify-pptx`](skills/ppt-master/workflows/beautify-pptx.md) workflow. Mirror of template-fill: content is preserved verbatim, the source's palette/fonts are inherited as truth, only layout is redesigned. Unlike template-fill, it regenerates a native deck through the SVG pipeline (Strategist → Executor → export), one source slide to one page; it does not edit the source in place.
+> Beautify / re-layout: when the user provides an existing `.pptx` and asks to beautify or re-layout it while keeping the content (for example, "把这份 PPT 美化一下", "重新排版,内容别动", or wants to paste the regenerated elements back into the original deck), run the standalone [`beautify-pptx`](skills/ppt-master/workflows/beautify-pptx.md) workflow. Mirror of template-fill: content is preserved verbatim, the source's palette/fonts are inherited as truth, only layout is redesigned. Unlike template-fill, it regenerates a native deck through the SVG pipeline (Strategist → Executor → export), one source slide to one page; it does not edit the source in place. Routing boundary — beautify is for "keep this deck, just lay it out better": page count and page order are preserved 1:1. If the original page breakdown itself should be reconsidered (merge / split / reorder pages, re-outline the structure), that is NOT beautify: convert the deck with [`ppt_to_md`](skills/ppt-master/scripts/source_to_md/ppt_to_md.py) and run the main SKILL.md pipeline, where the Strategist re-architects the outline freely from the extracted content. Decide by one question: is the source's page split information to preserve, or just the previous author's structure to improve?
>
> Phase B resumption (split-mode execution): when the user opens a fresh chat and says "继续生成 projects/<x>" or similar, run the standalone [`resume-execute`](skills/ppt-master/workflows/resume-execute.md) workflow to enter Phase B (SVG generation + export) without re-running Phase A.
>
diff --git a/CLAUDE.md b/CLAUDE.md
index 1bbd1498..87f25d0b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -14,7 +14,7 @@ PPT Master is an AI-driven presentation generation system. Multi-role collaborat
>
> Template fill: when the user provides an existing `.pptx` template plus text materials or a topic and asks to reuse the original PPT design or fill content back into it (for example, "fill this deck with the new content", "fill this back into the template", or "reuse this deck's design"), run the standalone [`template-fill-pptx`](skills/ppt-master/workflows/template-fill-pptx.md) workflow. This route edits PPTX directly and must not enter the SVG generation pipeline.
>
-> Beautify / re-layout: when the user provides an existing `.pptx` and asks to beautify or re-layout it while keeping the content (for example, "把这份 PPT 美化一下", "重新排版,内容别动", or wants to paste the regenerated elements back into the original deck), run the standalone [`beautify-pptx`](skills/ppt-master/workflows/beautify-pptx.md) workflow. Mirror of template-fill: content is preserved verbatim, the source's palette/fonts are inherited as truth, only layout is redesigned. Unlike template-fill, it regenerates a native deck through the SVG pipeline (Strategist → Executor → export), one source slide to one page; it does not edit the source in place.
+> Beautify / re-layout: when the user provides an existing `.pptx` and asks to beautify or re-layout it while keeping the content (for example, "把这份 PPT 美化一下", "重新排版,内容别动", or wants to paste the regenerated elements back into the original deck), run the standalone [`beautify-pptx`](skills/ppt-master/workflows/beautify-pptx.md) workflow. Mirror of template-fill: content is preserved verbatim, the source's palette/fonts are inherited as truth, only layout is redesigned. Unlike template-fill, it regenerates a native deck through the SVG pipeline (Strategist → Executor → export), one source slide to one page; it does not edit the source in place. Routing boundary — beautify is for "keep this deck, just lay it out better": page count and page order are preserved 1:1. If the original page breakdown itself should be reconsidered (merge / split / reorder pages, re-outline the structure), that is NOT beautify: convert the deck with [`ppt_to_md`](skills/ppt-master/scripts/source_to_md/ppt_to_md.py) and run the main SKILL.md pipeline, where the Strategist re-architects the outline freely from the extracted content. Decide by one question: is the source's page split information to preserve, or just the previous author's structure to improve?
>
> Phase B resumption (split-mode execution): when the user opens a fresh chat and says "继续生成 projects/<x>" or similar, run the standalone [`resume-execute`](skills/ppt-master/workflows/resume-execute.md) workflow to enter Phase B (SVG generation + export) without re-running Phase A.
>
diff --git a/docs/faq.md b/docs/faq.md
index 01fe859e..0036e2ad 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -154,6 +154,21 @@ Yes. You can **interrupt the workflow at any time** — after the first few page
For post-generation fixes, simply tell the AI: "Page 3 has a layout issue — the title overlaps the chart" and it will fix that specific SVG.
+## Q: I have an existing PPT and want to build on it — which route should I use?
+
+Think of "using an existing PPT" as two questions: **keep its content or not**, and **keep its design (layout + visuals) or not**. The four combinations map to four routes:
+
+- **Keep content + redo layout** → **beautify (re-layout)**: text stays verbatim, page count and order are preserved 1:1, only the layout is redone while inheriting the original palette/fonts. Say "make this deck look better" / "re-layout this, keep the wording". See the [beautify workflow](../skills/ppt-master/workflows/beautify-pptx.md).
+- **Replace content + keep design** → **template-fill**: keep the original design, pour new content back into the native slides (next question).
+- **Keep only content, redo design and pagination** → **main pipeline (free re-architecture)**: treat the PPT as an ordinary source document — extract it to Markdown with `ppt_to_md`, then run the standard generation flow, where the Strategist re-architects the outline freely (merge / split / reorder pages). Say "build a better deck from this one's content".
+- **Keep content + keep design** → no generation needed; just use the original file.
+
+The one-line test between beautify and the main pipeline: **is the source's page split information to preserve, or just the previous author's structure to improve?** Preserve → beautify; improve → main pipeline.
+
+There is also one orthogonal route: if you don't want to produce a deck right now but want to **harvest the design into a reusable template** for future use, use **create-template** (see "How do I create a custom template?" below).
+
+---
+
## Q: I already have a finished `.pptx` — can I reuse its design and just fill in new content?
Yes — this is the **template fill** route, separate from the SVG generation pipeline. Give the AI your existing `.pptx` plus your material (or a topic) and ask it to "fill this deck with the new content" or "fill this back into the template". It treats your deck as a native slide library, lets you pick only the pages that fit the new story (reorder freely, and reuse one page for several output slides), and writes the new text — plus native table cells and chart data — straight into the original OOXML.
diff --git a/docs/zh/faq.md b/docs/zh/faq.md
index 4342f177..492d584f 100644
--- a/docs/zh/faq.md
+++ b/docs/zh/faq.md
@@ -156,6 +156,21 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation-trigger o
生成后的修正也一样简单,直接告诉 AI:"第 3 页布局有问题——标题和图表重叠了",它会修正那个特定的 SVG。
+## Q: 我手上有一份现成的 PPT,想基于它做东西,该走哪条路?
+
+把「用一份已有 PPT」拆成两个问题:**留不留它的内容**、**留不留它的设计(版式 + 视觉)**。四种组合对应四条路:
+
+- **留内容 + 重做版式** → **beautify(美化 / 重排)**:文字逐字不动、页数页序 1:1 保留,只重排版式并继承原配色字体。说「把这份 PPT 美化一下 / 重新排版,内容别动」。见 [beautify 工作流](../../skills/ppt-master/workflows/beautify-pptx.md)。
+- **换内容 + 留设计** → **template-fill(套模板)**:保留原设计,把新内容灌回原生页面(见下一问)。
+- **只留内容,设计与页数都重来** → **主管线(自由重构)**:把 PPT 当普通源文档,用 `ppt_to_md` 抽成 Markdown 再走标准生成流程,Strategist 会自由重排大纲(合页 / 拆页 / 换序)。说「用这份 PPT 的内容重做一份更好的」。
+- **留内容 + 留设计** → 不必生成,直接用原文件即可。
+
+beautify 和主管线的一句话判别:**原来的分页是要保留的信息,还是只是前一作者的结构、可以推翻?** 保留 → beautify;推翻 → 主管线。
+
+还有一条正交的路:如果你不是要现在产出一份 deck,而是想把这套设计**收成可复用模板**供以后反复用,走 **create-template**(见下面「如何制作自定义模板」)。
+
+---
+
## Q: 我已经有一份做好的 `.pptx`,能不能复用它的设计、只填新内容?
可以——这就是 **套模板(template fill)** 路径,独立于 SVG 生成管线。把你现成的 `.pptx` 连同素材(或一个主题)给 AI,说「套模板 / 把这些填回去」。它会把你的 deck 当作原生页面库,只挑适合新内容的页面(可乱序、可重复),把新文字——以及原生表格单元格、图表数据——直接写回原始 OOXML。