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(technical-design): align native export architecture
hugohe35cadb12cf7e0
diff --git a/docs/technical-design.md b/docs/technical-design.mdindex 838fe8e2..d205e97b 100644--- a/docs/technical-design.md+++ b/docs/technical-design.md@@ -37,7 +37,7 @@ User Input (PDF/DOCX/XLSX/PPTX/URL/Markdown/topic text)├── [Quality Check] svg_quality_checker.py (mandatory — must pass with 0 errors)└── Notes generation: complete speaker notes → notes/total.md↓-[Chart calibration (optional)] → verify-charts workflow (for decks containing data charts)+[Chart calibration (conditional)] → verify-charts workflow (required for decks containing data charts)↓[Visual self-check (optional, opt-in)] → visual-review workflow (only when the user explicitly requests it)↓@@ -101,7 +101,7 @@ Source documents (PDF/DOCX/XLSX/PPTX/URL/Markdown/topic text) are converted intoThe Executor role generates each slide as an SVG file. The output of this stage is a **design draft**, not a finished product.**Stage 3 — Engineering Conversion**-Post-processing scripts convert SVG to DrawingML. Every shape becomes a real native PowerPoint object — clickable, editable, recolorable — not an embedded image.+Post-processing scripts convert supported SVG vector elements to DrawingML. Text and vector shapes stay native PowerPoint objects — clickable, editable, and restylable — while raster assets are copied as PPT picture media instead of flattening the slide into one image.---@@ -370,9 +370,9 @@ The architectural reasons worth knowing here:> Why each artifact and module exists in the engineering conversion stage, and which workflows would break if you delete it. Read this before considering any simplification of `svg_final/` / `finalize_svg.py` / `svg_to_pptx.py`.-### Five artifacts, five workflows+### Delivery artifacts and workflows-The post-processing stage works with five artifacts. Each one serves a workflow that nothing else in the pipeline can replace.+The post-processing and export stages work with distinct artifacts. Each one serves a workflow that nothing else in the pipeline can replace.| Artifact | Workflow it serves | Why nothing else replaces it || --- | --- | --- |@@ -425,7 +425,7 @@ These direct routes share some analysis primitives with the main pipeline, espec**Why per-element dispatch, not whole-file translation.** SVG's hierarchical model maps cleanly onto DrawingML's group / shape / picture types — there's no need for a holistic optimizer that re-plans the slide. Each shape kind gets its own narrow translator, which keeps each translator simple enough to debug and unit-test in isolation. The output quality of a slide is the sum of independent local conversions; that property is fragile under whole-file translation but robust under element dispatch.-**Why Office compatibility mode is on by default.** PowerPoint versions before 2019 can't render SVG natively. The converter generates a per-slide PNG fallback and embeds it alongside the native shapes — newer Office still shows editable shapes, older Office falls back to the PNG. The default-on choice trades a moderate file-size cost for not silently shipping unopenable decks to users on legacy installs; the escape hatch exists for users who know they're on a modern stack and want the smaller file.+**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.---diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.mdindex 91089ede..46208b28 100644--- a/docs/zh/technical-design.md+++ b/docs/zh/technical-design.md@@ -37,7 +37,7 @@├── [Quality Check] svg_quality_checker.py(强制通过,0 错误)└── 讲稿生成:完整讲稿 → notes/total.md↓-[图表校准(可选)] → verify-charts 工作流(含数据图表的幻灯片在此步骤校准坐标)+[图表校准(条件触发)] → verify-charts 工作流(含数据图表的 deck 必须在此步骤校准坐标)↓[视觉自检(可选,opt-in)] → visual-review 工作流(仅在用户明确请求时触发)↓@@ -101,7 +101,7 @@Executor 角色逐页生成演示文稿的视觉内容,输出为 SVG 文件。这个阶段的产物是**设计稿**,而非成品。**第三阶段:工程化转换**-后处理脚本将 SVG 转换为 DrawingML,每一个形状都变成真正的 PowerPoint 原生对象——可点击、可编辑、可改色,而不是嵌入的图片。+后处理脚本将受支持的 SVG 向量元素转换为 DrawingML。文本和向量形状会保持为 PowerPoint 原生对象——可点击、可编辑、可改样式;位图资源则复制为 PPT picture media,而不是把整页压平成一张图片。---@@ -370,9 +370,9 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。Executor 在一份> 工程化转换阶段中每一份产物和每一个模块为何存在,删除它会破坏哪些工作流。在考虑简化 `svg_final/` / `finalize_svg.py` / `svg_to_pptx.py` 之前,先读这一节。-### 五份产物,五种工作流+### 交付产物与工作流-后处理阶段涉及五份产物。每一份都服务于一种流水线中无法替代的工作流。+后处理与导出阶段涉及几类职责不同的产物。每一份都服务于一种流水线中无法替代的工作流。| 产物 | 服务的工作流 | 为何无可替代 || --- | --- | --- |@@ -425,7 +425,7 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。Executor 在一份**为什么是逐元素派发而不是整体翻译。** SVG 的层级模型干净地映射到 DrawingML 的 group / shape / picture 类型——不需要一个全局优化器去重新规划幻灯片。每种形状都有自己窄的翻译器,简单到能单独调试和单元测试。一张幻灯片的最终质量等于这些独立局部转换之和;这个性质在整体翻译下脆弱,在元素派发下稳健。-**为什么 Office 兼容模式默认开启。** 2019 之前的 PowerPoint 不能原生渲染 SVG。转换器为每页生成 PNG 兜底,与原生形状并存——新版 Office 仍显示可编辑形状,旧版回退到 PNG。默认开启的取舍是:用适度的文件大小代价换取「不会静默地把打不开的 deck 交给跑老版本的用户」;逃生口给那些明确知道自己在新栈上、想要更小文件的用户。+**为什么兼容 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 里的兜底层。---