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(pptx): merge paragraphs by default
hugohe337dabd3feb41
diff --git a/docs/faq.md b/docs/faq.mdindex dedcadab..96a787bc 100644--- a/docs/faq.md+++ b/docs/faq.md@@ -48,19 +48,19 @@ Yes. The main `.pptx` (native PowerPoint shapes — all text, graphics, and colo## Q: Why is one paragraph split into multiple text boxes? Can I get one text box per paragraph instead?-By default yes — every visual line of body text becomes its own PowerPoint text frame. This preserves the SVG's exact line layout pixel-for-pixel, which matters for covers, charts, tables, and any page with tight typographic alignment.+By default, mergeable body-text paragraphs export as one editable PowerPoint text frame with multiple paragraphs. Resizing the box reflows text inside it.-If you'd rather edit body text as whole paragraphs, re-export with `--merge-paragraphs`:+If you need strict line-layout fidelity, re-export with `--no-merge`:```bash-python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> --merge-paragraphs+python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> --no-merge```-Mergeable paragraph blocks (same x, dy clustered around one line-height, optional larger gap for paragraph breaks) collapse into one editable text frame with multiple `<a:p>` and precise line-spacing. Resizing the box reflows text inside it.+With `--no-merge`, every visual line becomes its own PowerPoint text frame. This preserves the SVG's exact line layout pixel-for-pixel, which matters for covers, charts, tables, and any page with tight typographic alignment.-**Trade-off**: PowerPoint may wrap the merged paragraphs to a different line count than the SVG source — so the page won't match the original layout exactly. Best for long-form body text (abstracts, multi-paragraph sections, reference lists); keep the default for layout-tight pages. The detection is conservative — mixed-layout `<text>` falls through to the default per-line path automatically.+**Trade-off**: default paragraph merging lets PowerPoint wrap merged paragraphs to a different line count than the SVG source. Best for long-form body text (abstracts, multi-paragraph sections, reference lists); use `--no-merge` for layout-tight pages. The detection is conservative — mixed-layout `<text>` falls through to the per-line path automatically.-When you're chatting with the AI, you can also just ask: "I want to edit the abstract as one block" / "make text boxes resizable" — the AI will turn this on for you. Defaults stay off so existing decks aren't affected.+When you're chatting with the AI, you can also just ask for strict line fidelity on layout-sensitive pages — the AI will add `--no-merge` when re-exporting.## Q: What's the difference between the three Executors?diff --git a/docs/zh/faq.md b/docs/zh/faq.mdindex d4fca82d..0e54c482 100644--- a/docs/zh/faq.md+++ b/docs/zh/faq.md@@ -48,19 +48,19 @@ PPT Master 可以在任何能读取文件和执行命令的 AI 编程代理中## Q: 为什么一段正文被拆成了好几个文本框?能不能一段一个文本框?-默认就是按行拆框——SVG 里的每一视觉行都会变成一个独立的 PowerPoint 文本框。这样做是为了**逐像素保留 SVG 的版式**,对封面、图表、表格、以及任何对版式精度敏感的页面来说是必要的。+默认会把可合并的正文段落导出成一个可编辑的 PowerPoint 文本框,内部保留多个段落。**拉伸框时文字会在框内自动重排**。-如果你希望按整段编辑正文,重新导出时加上 `--merge-paragraphs`:+如果你需要严格保持逐行版式,重新导出时加上 `--no-merge`:```bash-python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> --merge-paragraphs+python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> --no-merge```-可合并的段落块(同 x、dy 围绕同一行距聚集、段间允许更大间距)会合并成一个可编辑的文本框,内部为多个 `<a:p>`,并精确保留行距。**拉伸框时文字会在框内自动重排**。+使用 `--no-merge` 时,SVG 里的每一视觉行都会变成一个独立的 PowerPoint 文本框。这样能**逐像素保留 SVG 的版式**,适合封面、图表、表格、以及任何对版式精度敏感的页面。-**代价**:PowerPoint 自动换行后,行数可能与原 SVG 不一致——页面版式会与原 SVG 有偏差。适合正文密集型页面(abstract、多段落章节、参考文献等);版式敏感的页面继续用默认。判定足够保守——非段落型 `<text>` 会自动落回默认的按行拆框路径。+**代价**:默认段落合并后,PowerPoint 自动换行的行数可能与原 SVG 不一致。默认更适合正文密集型页面(abstract、多段落章节、参考文献等);版式敏感页面使用 `--no-merge`。判定足够保守——非段落型 `<text>` 会自动落回按行拆框路径。-跟 AI 对话时也可以直接说:"我想整段编辑 abstract" / "让文本框能自适应" —— AI 会替你打开这个开关。默认关闭,不影响已有项目。+跟 AI 对话时也可以直接说:"这个页面要严格保持逐行版式" —— AI 重新导出时会加上 `--no-merge`。## Q: 三种执行师有什么区别?diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.mdindex aab4ada1..05f05a93 100644--- a/skills/ppt-master/SKILL.md+++ b/skills/ppt-master/SKILL.md@@ -497,13 +497,12 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>> 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.-> **Paragraph editability vs line fidelity** — by default every dy-stacked line is-> its own PowerPoint text frame, preserving exact SVG layout. Add `--merge-paragraphs`-> only when the user explicitly asks for an editable / wrap-friendly export (e.g.-> "I want to edit the abstract as one block", "make text boxes resizable / reflow"):-> mergeable paragraph blocks collapse into one editable text frame with multiple-> `<a:p>`, at the cost of PowerPoint re-wrapping inside each box. Default off keeps-> pixel-fidelity; turn it on per the user's request, not on your own judgement.+> **Paragraph editability vs line fidelity** — by default, mergeable dy-stacked+> paragraph blocks collapse into one editable PowerPoint text frame with multiple+> `<a:p>`, improving body-text editing and resize/reflow behavior. Add `--no-merge`+> only when the user explicitly asks for strict line-layout fidelity or when a+> layout-tight page must keep every dy-stacked line as its own text frame. The+> merge detector is conservative; mixed-layout text falls back to per-line frames.**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/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.mdindex 2c4ea366..7b36b18a 100644--- a/skills/ppt-master/scripts/docs/svg-pipeline.md+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md@@ -39,7 +39,7 @@ python3 scripts/svg_to_pptx.py <project_path> --no-notespython3 scripts/svg_to_pptx.py <project_path> -t nonepython3 scripts/svg_to_pptx.py <project_path> --auto-advance 3python3 scripts/svg_to_pptx.py <project_path> --animation mixed --animation-duration 0.8-python3 scripts/svg_to_pptx.py <project_path> --merge-paragraphs # editability-first mode (see below)+python3 scripts/svg_to_pptx.py <project_path> --no-merge # strict line-fidelity mode (see below)python3 scripts/notes_to_audio.py <project_path> --voice zh-CN-XiaoxiaoNeuralpython3 scripts/svg_to_pptx.py <project_path> --recorded-narration audio```@@ -52,10 +52,10 @@ Behavior:- `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-- `--merge-paragraphs` (opt-in) trades SVG line-layout fidelity for PowerPoint editability:- - Default: every dy-stacked `<tspan>` becomes its own text frame — exact SVG line layout is preserved but a 12-line paragraph is 12 separate textboxes- - With the flag: mergeable paragraph blocks (same x, dy clustered around one base line-height, optional larger gap for paragraph breaks) collapse into one editable text frame with multiple `<a:p>` and precise `<a:lnSpc>` / `<a:spcBef>`. Resizing the box reflows text inside it.- - Side effect: PowerPoint may wrap merged paragraphs to a different line count than the SVG source. Pages with tight typographic alignment (covers, charts, tables) usually want the default; long body text (abstracts, multi-paragraph sections, reference lists) usually benefits from the flag+- Paragraph merging is enabled by default and trades some SVG line-layout fidelity for PowerPoint editability:+ - Default: mergeable paragraph blocks (same x, dy clustered around one base line-height, optional larger gap for paragraph breaks) collapse into one editable text frame with multiple `<a:p>` and precise `<a:lnSpc>` / `<a:spcBef>`. Resizing the box reflows text inside it.+ - With `--no-merge`: every dy-stacked `<tspan>` becomes its own text frame — exact SVG line layout is preserved but a 12-line paragraph is 12 separate textboxes+ - Side effect: PowerPoint may wrap merged paragraphs to a different line count than the SVG source. Long body text (abstracts, multi-paragraph sections, reference lists) usually benefits from the default; pages with tight typographic alignment (covers, charts, tables) usually want `--no-merge`- Mergeable detection is conservative: only fires when the children form a clean paragraph block; mixed-layout `<text>` falls through to the default per-line 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.diff --git a/skills/ppt-master/scripts/svg_to_pptx/drawingml_context.py b/skills/ppt-master/scripts/svg_to_pptx/drawingml_context.pyindex 36476c9e..373cb3b5 100644--- a/skills/ppt-master/scripts/svg_to_pptx/drawingml_context.py+++ b/skills/ppt-master/scripts/svg_to_pptx/drawingml_context.py@@ -47,10 +47,9 @@ class ConvertContext:# Top-level <g id="..."> groups, recorded as (shape_id, svg_id) in z-order.# Used by the PPTX builder to emit per-element entrance timing.anim_targets: list = field(default_factory=list)- # Opt-in flag (default off): merge mergeable paragraph blocks into one- # editable text frame with multiple <a:p>. Off preserves the original- # one-line-per-textbox behavior and the SVG's exact pixel layout.- merge_paragraphs: bool = False+ # Default-on flag: merge mergeable paragraph blocks into one editable+ # text frame with multiple <a:p>. Disable it for strict line fidelity.+ merge_paragraphs: bool = True# Optional per-element conversion diagnostics. Shared by child contexts so# callers can inspect native / skipped / unsupported decisions per slide.trace_events: list[dict[str, Any]] | None = Nonediff --git a/skills/ppt-master/scripts/svg_to_pptx/drawingml_converter.py b/skills/ppt-master/scripts/svg_to_pptx/drawingml_converter.pyindex bb69d0f8..b58245b3 100644--- a/skills/ppt-master/scripts/svg_to_pptx/drawingml_converter.py+++ b/skills/ppt-master/scripts/svg_to_pptx/drawingml_converter.py@@ -420,7 +420,7 @@ def convert_svg_to_slide_shapes(svg_path: Path,slide_num: int = 1,verbose: bool = False,- merge_paragraphs: bool = False,+ merge_paragraphs: bool = True,trace_out: list[dict[str, Any]] | None = None,) -> tuple[str, dict[str, bytes], list[dict[str, str]], list]:"""Convert an SVG file to a complete DrawingML slide XML.@@ -429,10 +429,10 @@ def convert_svg_to_slide_shapes(svg_path: Path to the SVG file.slide_num: Slide number (for naming).verbose: Print progress info.- merge_paragraphs: Opt-in. When True, mergeable paragraph blocks- (same x, dy clustered around one base line-height) become a- single editable text frame with multiple <a:p>. Default False- preserves the SVG's exact line layout (one textbox per line).+ merge_paragraphs: When True, mergeable paragraph blocks (same x,+ dy clustered around one base line-height) become a single+ editable text frame with multiple <a:p>. Disable it to preserve+ the SVG's exact line layout (one textbox per line).trace_out: Optional list populated with one per-slide trace dictionary.Returns:@@ -469,8 +469,8 @@ def convert_svg_to_slide_shapes(# and an x-anchored tspan would render in the wrong column. finalize_svg# does the same flattening on disk; doing it here keeps native pptx output# correct when reading raw svg_output/.- # merge_paragraphs (opt-in) additionally folds mergeable paragraph blocks- # into a single annotated <text> for downstream multi-<a:p> conversion.+ # merge_paragraphs additionally folds mergeable paragraph blocks into a+ # single annotated <text> for downstream multi-<a:p> conversion.from .tspan_flattener import flatten_positional_tspansflattened = flatten_positional_tspans(tree, merge_paragraphs=merge_paragraphs)if flattened:diff --git a/skills/ppt-master/scripts/svg_to_pptx/drawingml_elements.py b/skills/ppt-master/scripts/svg_to_pptx/drawingml_elements.pyindex 9304543e..28a55572 100644--- a/skills/ppt-master/scripts/svg_to_pptx/drawingml_elements.py+++ b/skills/ppt-master/scripts/svg_to_pptx/drawingml_elements.py@@ -1050,7 +1050,7 @@ def convert_text(elem: ET.Element, ctx: ConvertContext) -> ShapeResult | None:# <a:p> so the paragraph survives as a single editable text frame.# Per-line data-paragraph-space-before encodes paragraph gaps (extra dy# above the base line-height) for the corresponding <a:p>.- # Paragraph mode is opt-in via ctx.merge_paragraphs. When off, ignore+ # Paragraph mode is controlled by ctx.merge_paragraphs. When off, ignore# any data-paragraph-* markers and fall through to the original# one-text-per-tspan path so the SVG's pixel layout is preserved.line_height_attr = elem.get('data-paragraph-line-height') if ctx.merge_paragraphs else Nonediff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_builder.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_builder.pyindex 9bc427cc..42cddb98 100644--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_builder.py+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_builder.py@@ -350,7 +350,7 @@ def create_pptx_with_native_svg(narration_padding: float = 0.5,cache_dir: Path | None = None,workers: int | None = None,- merge_paragraphs: bool = False,+ merge_paragraphs: bool = True,conversion_trace_path: Path | None = None,) -> bool:"""Create a PPTX file with native SVG.diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.pyindex 32a6bd1d..cb30db77 100644--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py@@ -154,13 +154,14 @@ 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('--merge-paragraphs', action='store_true', default=False,- help='Opt-in: merge mergeable paragraph blocks (same x, dy clustered '- 'around one base line-height) into a single editable text frame '- 'with multiple <a:p>. Improves editability of paragraph text in '- 'PowerPoint (one textbox per paragraph instead of per line) at '- 'the cost of strict SVG line layout fidelity — PowerPoint re-wraps '- 'merged paragraphs to fit the box width. Off by default.')+ merge_group = parser.add_mutually_exclusive_group()+ merge_group.add_argument('--merge-paragraphs', action='store_true', dest='merge_paragraphs',+ help='Compatibility no-op: mergeable paragraph blocks are merged '+ 'by default.')+ merge_group.add_argument('--no-merge', action='store_false', dest='merge_paragraphs',+ help='Disable paragraph merging. Every dy-stacked line becomes '+ 'its own text frame for strict SVG line-layout fidelity.')+ parser.set_defaults(merge_paragraphs=True)parser.add_argument('--conversion-trace', action='store_true', default=False,help='Write a JSON diagnostics report next to the native PPTX ''(<output>.trace.json). Records per-slide SVG element '