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): convert literal page numbers to slide-number fields
hugohe3f6cf8486caad
diff --git a/docs/technical-design.md b/docs/technical-design.mdindex 123e3ca7..81b8ff95 100644--- a/docs/technical-design.md+++ b/docs/technical-design.md@@ -427,7 +427,7 @@ These direct routes share some analysis primitives with the main pipeline, espec**Why compatibility fallback belongs to the SVG snapshot path, not native shapes.** Native PPTX export translates supported SVG elements into DrawingML shapes and explicitly disables PNG+SVG compatibility mode in native-shapes mode. The PNG fallback is used only by the legacy SVG-image path (`--svg-snapshot` / `--only legacy`) when a renderer is available, because that path embeds SVG media that older Office builds may not display. Legacy compatibility is therefore an optional snapshot deliverable, not a fallback bundled inside the primary editable native deck.-**Why the default native deck has a baseline master, not inferred templates.** `svg_to_pptx.py` keeps the actual blank slide layout relationship from the base package and defaults to `--pptx-structure baseline`. Baseline promotes only low-risk shared structure: identical slide backgrounds, plus a common leading prefix of repeated top-level SVG chrome whose exact id tokens say `logo`, `footer`, `header`, `watermark`, `chrome`, `pageNumber`, or `slideNumber`. Chrome promotion also requires identical generated OOXML, no slide-timing reference, and the same leading z-order across every slide sharing the master; overlay chrome stays slide-local. Image relationships for promoted chrome are copied to the slide master, and base-template slide layouts no generated slide references are pruned from the package. This gives ordinary decks real master/layout structure without guessing reusable layouts or placeholders from visual similarity.+**Why the default native deck has a baseline master, not inferred templates.** `svg_to_pptx.py` keeps the actual blank slide layout relationship from the base package and defaults to `--pptx-structure baseline`. Baseline promotes only low-risk shared structure: identical slide backgrounds, plus a common leading prefix of repeated top-level SVG chrome whose exact id tokens say `logo`, `footer`, `header`, `watermark`, `chrome`, `pageNumber`, or `slideNumber`. Chrome promotion also requires identical generated OOXML, no slide-timing reference, and the same leading z-order across every slide sharing the master; overlay chrome stays slide-local. Image relationships for promoted chrome are copied to the slide master, base-template slide layouts no generated slide references are pruned from the package, and `pageNumber`/`slideNumber` chrome whose text exactly equals the slide's display number (honoring `firstSlideNum`) becomes an auto-updating slide-number field so reordering slides in PowerPoint renumbers pages. This gives ordinary decks real master/layout structure without guessing reusable layouts or placeholders from visual similarity.**Why native-object reconstruction uses markers, not automatic object replacement.** The standalone `pptx_to_svg.py` importer can emit SVG fallback content plus `data-pptx-native` metadata for supported unmerged tables and conservative classic-chart caches. It retains source table-style inheritance, supported solid cell fills/basic text formatting, chart title/legend/axis titles, and plot-level data-label flags for area/bar/column/line charts when the current schema can represent them. Exporter-canonical classic charts also recover canonical solid series/slice colors and exact one- or two-paragraph title metadata. The default export still consumes fallback children as regular DrawingML shapes; only `--native-objects` activates editable PowerPoint tables/charts. Unsupported table cases — including merged cells, direct borders, non-solid fills, and mixed rich text — keep the rendered SVG table. Unsupported chart cases — including ChartEx, rotated/flipped/3D/combo charts, unsupported data-label scopes/types, custom axis semantics, trendlines/error bars, unsupported subtype options, sparse or non-finite caches, and date/formatted category axes — keep a baked preview when one exists, otherwise an explicit placeholder. Both carry `data-pptx-native-status`; the quality checker and native-object export report them as fallback-only warnings. This importer/exporter pairing is a reconstruction aid, not a preservation-route substitute for `template-fill-pptx` or `native-enhance-pptx`.diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.mdindex db3d4657..728e4386 100644--- a/docs/zh/technical-design.md+++ b/docs/zh/technical-design.md@@ -427,7 +427,7 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。Executor 在一份**为什么兼容 fallback 属于 SVG snapshot 路径,而不是 native shapes。** Native PPTX 导出会把受支持的 SVG 元素翻译成 DrawingML 形状,并在 native-shapes 模式下显式关闭 PNG+SVG 兼容模式。PNG fallback 只在 legacy SVG-image 路径(`--svg-snapshot` / `--only legacy`)且本地 renderer 可用时使用,因为那条路径嵌入的是旧版 Office 可能无法显示的 SVG media。因此,旧版兼容是一份可选 snapshot 交付物,不是捆在主 editable native deck 里的兜底层。-**为什么默认 native deck 使用基线母版,而不推断模板。** `svg_to_pptx.py` 会保留基础 package 中空白版式的真实关系,并默认使用 `--pptx-structure baseline`。Baseline 只提升低风险共享结构:完全一致的页面背景,以及各页共同位于 shape 序列开头(视觉后层)、且 id 精确 token 为 `logo`、`footer`、`header`、`watermark`、`chrome`、`pageNumber` 或 `slideNumber` 的重复 SVG chrome。Chrome 还必须在共享同一母版的所有页面上生成完全一致的 OOXML、没有被页面动画引用,并保持相同的前置 z-order;覆盖在正文之上的 chrome 继续留在 slide 本地。被提升 chrome 的图片关系会复制到 slide master,基础模板中没有任何页面引用的 slide layout 也会从 package 中裁剪掉。这样普通 deck 能获得真实的 master/layout 结构,同时不根据视觉相似度猜测可复用版式或占位符。+**为什么默认 native deck 使用基线母版,而不推断模板。** `svg_to_pptx.py` 会保留基础 package 中空白版式的真实关系,并默认使用 `--pptx-structure baseline`。Baseline 只提升低风险共享结构:完全一致的页面背景,以及各页共同位于 shape 序列开头(视觉后层)、且 id 精确 token 为 `logo`、`footer`、`header`、`watermark`、`chrome`、`pageNumber` 或 `slideNumber` 的重复 SVG chrome。Chrome 还必须在共享同一母版的所有页面上生成完全一致的 OOXML、没有被页面动画引用,并保持相同的前置 z-order;覆盖在正文之上的 chrome 继续留在 slide 本地。被提升 chrome 的图片关系会复制到 slide master,基础模板中没有任何页面引用的 slide layout 也会从 package 中裁剪掉;`pageNumber`/`slideNumber` chrome 的文本若恰好等于该页应显示的页码(尊重 `firstSlideNum`),会转换为自动更新的 PowerPoint 页码字段,此后在 PowerPoint 中调整页序页码自动重算,其他编号方案保持字面文本不动。这样普通 deck 能获得真实的 master/layout 结构,同时不根据视觉相似度猜测可复用版式或占位符。**为什么原生对象重建使用 marker,而不是自动替换对象。** 独立的 `pptx_to_svg.py` 导入器会为受支持的未合并表格和保守 classic-chart cache 输出 SVG fallback,并附加 `data-pptx-native` 元数据;当现有 schema 能表达时,还会保留源表格样式继承、受支持的单元格纯色填充 / 基础文字格式,以及图表标题、图例、坐标轴标题和面积图 / 条形图 / 柱形图 / 折线图的 plot 级数据标签开关。由本 exporter 生成的规范 classic chart 还会回读规范纯色系列 / 切片,以及精确的单段或双段标题元数据。默认导出仍把 fallback 子元素当普通 DrawingML shape 处理;只有 `--native-objects` 才会启用可编辑的 PowerPoint 表格 / 图表。合并单元格、直接边框、非纯色填充、混合富文本等不支持的表格场景继续保留实际渲染的 SVG table。ChartEx、旋转 / 翻转 / 3D / 组合图表、不受支持的数据标签作用域或类型、自定义坐标轴语义、趋势线 / 误差线、不受支持的子类型参数、稀疏或非有限 cache、日期 / 格式化类别轴等不支持的图表场景,则在有 baked preview 时保留预览,否则给出明确占位符。两类对象都会写入 `data-pptx-native-status`;质量检查器和 native-object 导出将其报告为 fallback-only warning。这对 importer/exporter 是重建辅助能力,不能替代 `template-fill-pptx` 或 `native-enhance-pptx` 的保留型路线。diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.mdindex acb1ab65..20a30de1 100644--- a/skills/ppt-master/SKILL.md+++ b/skills/ppt-master/SKILL.md@@ -680,8 +680,11 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>> chrome stays slide-local. Image relationships for promoted chrome are copied to> the master. Baseline also prunes base-template slide layouts no generated> slide references, so the PowerPoint new-slide picker only offers layouts that-> belong to the deck. Add `--pptx-structure flat` only for debugging/comparison-> when all generated backgrounds and chrome must remain slide-local.+> belong to the deck, and converts `pageNumber` / `slideNumber` chrome whose+> text exactly equals the slide's display number into an auto-updating+> PowerPoint slide-number field (other numbering schemes keep their literal+> text). Add `--pptx-structure flat` only for debugging/comparison when all+> generated backgrounds and chrome must remain slide-local.> **Paragraph editability vs line fidelity** — by default, mergeable dy-stacked> paragraph blocks collapse into one editable PowerPoint text frame with multiplediff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.mdindex a8800f94..b75b6cec 100644--- a/skills/ppt-master/scripts/README.md+++ b/skills/ppt-master/scripts/README.md@@ -116,7 +116,7 @@ python3 scripts/svg_to_pptx.py <project_path>`finalize_svg.py` optimizes raster images by default using `2x` display pixels and max `2560px`. Native `svg_to_pptx.py` defaults to `--image-sizing cap`: only oversized full source images are reduced to max `2560px`, so later PowerPoint resizing keeps more image detail. Use `svg_to_pptx.py --image-sizing display --image-scale 2` only for aggressive size reduction, or `--no-image-optimize` when the native PPTX must embed original image bytes.-Native `svg_to_pptx.py` also defaults to `--pptx-structure baseline`: the generated deck keeps a standard master/layout relationship and promotes identical native slide backgrounds into the slide master. A shared leading prefix of top-level SVG elements with exact chrome id tokens such as `logo`, `footer`, `header`, `watermark`, `chrome`, `pageNumber`, or `slideNumber` may also be promoted when its generated OOXML is identical, it is not referenced by slide timing, and moving it behind slide-local content preserves z-order; image relationships are copied to the master. Baseline additionally prunes base-template slide layouts that no generated slide references. Use `--pptx-structure flat` when all generated backgrounds and chrome must remain slide-local for debugging or comparison.+Native `svg_to_pptx.py` also defaults to `--pptx-structure baseline`: the generated deck keeps a standard master/layout relationship and promotes identical native slide backgrounds into the slide master. A shared leading prefix of top-level SVG elements with exact chrome id tokens such as `logo`, `footer`, `header`, `watermark`, `chrome`, `pageNumber`, or `slideNumber` may also be promoted when its generated OOXML is identical, it is not referenced by slide timing, and moving it behind slide-local content preserves z-order; image relationships are copied to the master. Baseline additionally prunes base-template slide layouts that no generated slide references, and swaps `pageNumber`/`slideNumber` chrome text for an auto-updating slide-number field when the text exactly equals the slide's display number. Use `--pptx-structure flat` when all generated backgrounds and chrome must remain slide-local for debugging or comparison.`pptx_to_svg.py` annotates supported unmerged tables and conservative classic-chart caches with `data-pptx-native` metadata. Source table-style inheritance, supported solid cell fills/basic text formatting, chart title/legend/axis titles, and plot-level data-label flags for area/bar/column/line charts are retained when the current schema can represent them. Tables with direct borders, non-solid fills, or mixed rich-text formatting remain fallback-only, as do charts with unsupported label scopes/types, custom axis semantics, trendlines/error bars, or subtype options. Unsupported tables keep their rendered SVG table; unsupported charts keep a baked preview or explicit placeholder. Both carry `data-pptx-native-status`, which `svg_quality_checker.py` and `svg_to_pptx.py --native-objects` report as a warning.diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/builder.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/builder.pyindex 7470e8e7..672bb43b 100644--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/builder.py+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/builder.py@@ -671,6 +671,120 @@ def _promote_common_chrome_shapes_to_masters(return promoted+_PAGE_NUMBER_TOKENS = {"pagenumber", "pagenum", "slidenumber"}+++def _first_slide_number(extract_dir: Path) -> int:+ """Read firstSlideNum from presentation.xml (defaults to 1)."""+ presentation_path = extract_dir / "ppt" / "presentation.xml"+ try:+ root = ET.parse(presentation_path).getroot()+ except (OSError, ET.ParseError):+ return 1+ raw = root.attrib.get("firstSlideNum")+ if raw is None:+ return 1+ try:+ return int(raw)+ except ValueError:+ return 1+++def _shape_with_id(root: ET.Element, shape_id: str) -> ET.Element | None:+ """Find a p:sp anywhere in the slide tree by its cNvPr id."""+ for shape in root.iter(f"{{{PML_NS}}}sp"):+ cnv = shape.find(f"{{{PML_NS}}}nvSpPr/{{{PML_NS}}}cNvPr")+ if cnv is not None and cnv.attrib.get("id") == shape_id:+ return shape+ return None+++def _replace_literal_run_with_slidenum_field(+ shape: ET.Element,+ expected_text: str,+ field_guid: str,+) -> bool:+ """Swap a single literal page-number run for an a:fld slidenum field."""+ tx_body = shape.find(f"{{{PML_NS}}}txBody")+ if tx_body is None:+ return False+ a_t = f"{{{DML_NS}}}t"+ total_text = "".join(t.text or "" for t in tx_body.iter(a_t))+ if total_text.strip() != expected_text:+ return False+ text_runs = [+ (paragraph, run)+ for paragraph in tx_body.iter(f"{{{DML_NS}}}p")+ for run in paragraph.findall(f"{{{DML_NS}}}r")+ if (run.findtext(a_t) or "").strip()+ ]+ if len(text_runs) != 1:+ return False+ paragraph, run = text_runs[0]+ if (run.findtext(a_t) or "").strip() != expected_text:+ return False++ fld = ET.Element(f"{{{DML_NS}}}fld", {"id": field_guid, "type": "slidenum"})+ r_pr = run.find(f"{{{DML_NS}}}rPr")+ if r_pr is not None:+ fld.append(ET.fromstring(ET.tostring(r_pr, encoding="utf-8")))+ fld_text = ET.SubElement(fld, a_t)+ fld_text.text = expected_text+ index = list(paragraph).index(run)+ paragraph.remove(run)+ paragraph.insert(index, fld)+ return True+++def _convert_page_number_texts_to_fields(+ extract_dir: Path,+ slide_count: int,+ conversion_traces: list[dict[str, Any]] | None,+ *,+ verbose: bool = False,+) -> int:+ """Replace literal page-number chrome text with auto-updating fields.++ Only converts when the traced pageNumber/slideNumber shape's whole text+ equals the slide's expected display number (honoring firstSlideNum), so+ schemes like content-only numbering keep their literal text untouched.+ """+ if not conversion_traces:+ return 0+ trace_by_slide = {+ int(trace.get("slide_num", 0)): trace+ for trace in conversion_traces+ if trace.get("slide_num") is not None+ }+ first_slide_number = _first_slide_number(extract_dir)+ field_guid = f"{{{str(uuid.uuid4()).upper()}}}"++ converted = 0+ for slide_num in range(1, slide_count + 1):+ tokens = _trace_chrome_shape_ids(trace_by_slide.get(slide_num))+ shape_ids = sorted({+ shape_id+ for token, ids in tokens.items()+ if token in _PAGE_NUMBER_TOKENS+ for shape_id in ids+ })+ if len(shape_ids) != 1:+ continue+ slide_path = extract_dir / "ppt" / "slides" / f"slide{slide_num}.xml"+ tree = ET.parse(slide_path)+ shape = _shape_with_id(tree.getroot(), shape_ids[0])+ if shape is None:+ continue+ expected_text = str(first_slide_number + slide_num - 1)+ if _replace_literal_run_with_slidenum_field(shape, expected_text, field_guid):+ _write_xml_tree(slide_path, tree)+ converted += 1++ if verbose and converted:+ print(f" Baseline slide-number fields: converted {converted} page number(s)")+ return converted++def _remove_relationship(rels_path: Path, rel_id: str) -> None:"""Remove one relationship entry by rId."""rels_content = rels_path.read_text(encoding="utf-8")@@ -1928,6 +2042,12 @@ def create_pptx_with_native_svg(and pptx_structure == "baseline"and success_count == len(svg_files)):+ _convert_page_number_texts_to_fields(+ extract_dir,+ len(svg_files),+ conversion_trace if conversion_trace is not None else structure_trace,+ verbose=verbose,+ )_promote_common_slide_backgrounds_to_masters(extract_dir,structure,