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(technical-design): define the project-canonical SVG boundary

hugohe37faf15bf4713
diff --git a/docs/technical-design.md b/docs/technical-design.md
index 500e7751..1030536d 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -10,6 +10,28 @@ The generated PPTX is a **design draft**, not a finished product. Think of it li
**A tool's ceiling is your ceiling.** PPT Master amplifies the skills you already have — if you have a strong sense of design and content, it helps you execute faster. If you don't know what a great presentation looks like, the tool won't know either. The output quality is ultimately a reflection of your own taste and judgment.
+### SVG Is a Project-Specific Intermediate Language
+
+PPT Master does not aim to convert arbitrary SVG into PPTX. `svg_output/` uses a **project-canonical SVG intermediate language**: it borrows SVG's XML syntax and two-dimensional graphics model, while the project contract closes the allowed elements, attributes, units, metadata, structural contracts, and DrawingML mappings. The direction is intentional: **SVG adapts to PPT Master; PPT Master does not expand to follow the entire SVG standard**.
+
+The intermediate language distinguishes three input states:
+
+| State | Definition | Handling |
+|---|---|---|
+| Canonical authoring input | The single recommended expression generated by prompts, templates, and examples | Validate and compile through registered mappings without alias warnings |
+| Compatible input | An explicitly documented historical or manual spelling with one safe, deterministic normalization | The checker emits a non-blocking warning; the converter normalizes it without feeding the alias back into prompts |
+| Invalid or unsupported input | An expression with no mapping, ambiguous meaning, a broken structural contract, or a risk of invalid DrawingML/PPTX | The checker or converter reports an error and stops publication |
+
+For example, project typography uses SVG px semantics, with finite unitless values such as `font-size="24"` as the canonical spelling. Another unit may be compatible input only when the compatibility contract explicitly documents a deterministic conversion; it must not become a new generated spelling. Compatible reads are a controlled migration boundary, not permission to widen the authoring language.
+
+The three layers have separate responsibilities and cannot substitute for one another:
+
+| Layer | Single responsibility | Explicit non-responsibility |
+|---|---|---|
+| Prompts, templates, and examples | State the project-canonical spelling precisely and reduce drift and warnings at the source | They are not a correctness or safety boundary |
+| `svg_quality_checker.py` | Enforce the project contract on authoring state; errors block and non-blocking warnings pass | It does not silently rewrite pages or guess design intent |
+| `svg_to_pptx.py` | Defensively validate every call path, normalize documented compatible forms, and prevent publication of known-invalid packages | It does not promise arbitrary-SVG conversion or hide unknown/ambiguous input behind defaults |
+
---
## System Architecture
@@ -33,15 +55,15 @@ User Input (PDF/DOCX/XLSX/PPTX/URL/Markdown/topic text)
↓
[Executor]
├── Live preview starts and stays available during generation
- ├── Visual construction: generate SVG pages sequentially → svg_output/
- ├── [Quality Check] svg_quality_checker.py (mandatory — must pass with 0 errors)
+ ├── Visual construction: generate project-canonical SVG pages sequentially → svg_output/
+ ├── [Quality Check] svg_quality_checker.py (mandatory — 0 errors; warnings are non-blocking)
└── Notes generation: complete speaker notes → notes/total.md
↓
[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)
↓
-[Post-processing] → total_md_split.py (split notes) → finalize_svg.py → svg_to_pptx.py
+[Post-processing] → total_md_split.py (split notes) → finalize_svg.py → svg_to_pptx.py (defensive validation, then compilation)
↓
Output:
svg_final/
@@ -58,15 +80,16 @@ Output:
└── svg_output/ ← Archived Executor SVG source (rerun finalize_svg → svg_to_pptx to rebuild)
```
-### SVG as the Page-Design Language
+### SVG as a Constrained Page-Design Language
-For every workflow that authors or redesigns visual slides through SVG, `svg_output/` is the complete page-design authority. Every visible text, image, shape, diagram, chart/table fallback, background, and template-derived layout element that should appear on a slide must already exist in that page SVG or be explicitly referenced by it. Templates, `design_spec.md`, and `spec_lock.md` guide SVG authoring; the exporter does not use them as a second visual layer that fills in missing page content.
+For every workflow that authors or redesigns visual slides through SVG, `svg_output/` is the complete page-design authority, but SVG here means project-canonical SVG accepted by the project contract—not any SVG a browser can render. Every visible text, image, shape, diagram, chart/table fallback, background, and template-derived layout element that should appear on a slide must already exist in that page SVG or be explicitly referenced by it. Templates, `design_spec.md`, and `spec_lock.md` guide SVG authoring; the exporter does not use them as a second visual layer that fills in missing page content.
Minimal semantic markers do not weaken that closure. Free-design and brand-only pages use `pptx_structure.mode: flat`: every represented object stays Slide-local and no Master/Layout identity, layer, or placeholder metadata is authored. Export materializes one clean project-owned Master plus one Blank Layout from the current color/typography lock, removes stock content placeholders and unused built-in Layouts, and retains only the standard date/footer/slide-number capability hooks without promoting Slide content. On structured deck/layout-template routes, every new page declares its Master/Layout identity from the first SVG draft. Fixed Master/Layout visuals are direct atomic root children, while reusable content slots are top-level groups with explicit design-zone bounds and one compatible carrier; composite `object` regions use an explicit proxy fallback, and zero-slot Layouts are valid. `data-pptx-role` is reserved for the few structural page-frame objects whose package or animation behavior is not already expressed by specialized metadata. Legacy structured/template projects whose structure contract is missing or uses an old form first run `restore-pptx-structure`; a flat project is intentionally unmapped, not legacy. Export never infers Master/Layout structure or placeholders.
| Domain | Authority |
|---|---|
| Visible page content and layout on SVG-authoring routes | Final page SVG in `svg_output/` |
+| Project-canonical SVG syntax, compatible forms, and mapping boundary | [`references/shared-standards.md`](../skills/ppt-master/references/shared-standards.md) |
| Master/Layout/Slide packaging and native-object mapping | SVG-to-PPTX translation; it may reorganize represented content but does not invent visible content |
| Animations, transitions, speaker notes, and narration | Dedicated sidecars/assets and PPTX package post-processing |
| Direct native-PPTX editing | The selected native workflow's PPTX/OOXML contract |
@@ -175,20 +198,11 @@ SVG wins because it shares the same world view as DrawingML: both are absolute-c
| `linearGradient` / `radialGradient` | `<a:gradFill>` |
| `fill-opacity` / `stroke-opacity` | `<a:alpha>` |
-This table shows conceptual counterparts, not an authoring allowlist or a
-promise of lossless semantics. Restricted or approximate mappings are owned by
-[`shared-standards.md`](../skills/ppt-master/references/shared-standards.md).
+This table shows conceptual counterparts, not a commitment to the entire SVG standard or a promise of lossless semantics. Every supported capability must have an explicit mapping in [`shared-standards.md`](../skills/ppt-master/references/shared-standards.md) that identifies its project-canonical spelling, accepted compatible inputs, target DrawingML expression, fidelity, and rejection boundary; capabilities that support PPTX import must also identify the source PPTX/OOXML semantics. A mapping may be exact, deterministically normalized, an explicit fallback, a sidecar, or unsupported. Package semantics such as notes, animations, and relationships do not need to be forced into SVG, but their owning route must be explicit.
-The boundary deliberately uses **recommended narrow writes and broad reads**.
-New `svg_output/` and reusable templates default to one paint spelling:
-uppercase opaque `#RRGGBB`, with transparency carried by the matching
-`fill-opacity`, `stroke-opacity`, `stop-opacity`, `flood-opacity`, or atomic
-element `opacity`. The converter still accepts named colors, functional CSS
-colors, short/alpha HEX, and other documented historical forms at import or
-direct-read boundaries. The checker may recommend the default spelling, but a
-supported alternative remains valid and does not block export.
+The main generation route uses **canonical narrow writes and controlled compatible reads**. New `svg_output/` and reusable templates use only project-canonical spellings—for example, uppercase opaque `#RRGGBB`, with transparency carried by the matching `fill-opacity`, `stroke-opacity`, `stop-opacity`, `flood-opacity`, or atomic-element `opacity`. Historical or manual input proceeds only when the compatibility contract documents it, the conversion has one meaning, and the output is valid. The checker emits a non-blocking warning for such input, and the converter normalizes it at the compilation boundary. Anything that requires guessing, lacks a mapping, or could produce a damaged PPTX is an error.
-The conversion is a translation between two dialects of the same idea — not a format mismatch.
+Conversion is therefore not format guessing between arbitrary SVG and DrawingML. It is a registered, fidelity-described, testable compilation from project-canonical SVG to DrawingML.
SVG is also the only format that simultaneously satisfies every role in the pipeline: **AI can reliably generate it, humans can preview and debug it in any browser, and scripts can translate it under an explicit compatibility contract** — all before a single line of DrawingML is written.
@@ -386,18 +400,20 @@ The catalog of *how an image is placed on a slide* (full vocabulary in [`referen
---
-## SVG Compatibility Boundary
+## Project-Canonical SVG and the Compatibility Boundary
-PowerPoint's DrawingML is a strict subset of what SVG can express. Within the converter's implemented vocabulary, ordinary SVG is allowed by default. Only rejected constructs and features that require constrained mappings are enumerated in [`references/shared-standards.md`](../skills/ppt-master/references/shared-standards.md), the sole authority for their accepted forms and limits; this architecture document deliberately does not reproduce them.
+PowerPoint's DrawingML is a strict subset of what SVG can express, so the main compiler route does not treat “the browser can render it” as “the project can export it.” Input is accepted only when [`references/shared-standards.md`](../skills/ppt-master/references/shared-standards.md) registers a project-canonical expression or an explicit compatible form with a deterministic DrawingML mapping. That file is the sole authority for syntax, structure, units, metadata, compatible aliases, fidelity, and rejection conditions; this architecture document defines the layering principle without duplicating individual rules.
**Why local reuse is compile-time reuse, not a retained PowerPoint object.** The canonical contract defines accepted authoring forms, and the shared validator enforces them. After validation, the pipeline recursively materializes each referenced subtree and rewrites clone-local IDs before export. PPTX-to-SVG import therefore returns expanded primitives rather than reconstructing the authoring-time reuse graph.
The architectural reasons worth knowing here:
-- **Why an exception list, not an allowlist.** SVG is a wide specification; enumerating every allowed feature would require constant maintenance as the converter grows. A centralized exception list leaves ordinary implemented constructs available by default.
+- **Why mappings are closed instead of accepting ordinary SVG by default.** Project-canonical SVG is a compiler intermediate language, not a browser compatibility layer. Adding an element, attribute, or value requires corresponding input semantics, output mapping, validation, and regression verification; unregistered capabilities do not enter the main compiler route.
+- **Why compatible input is not authoring permission.** A documented historical alias may be normalized deterministically and receive a non-blocking checker warning; prompts, templates, and examples still generate only the project-canonical spelling. Migration and manual-input compatibility must not widen generated syntax.
+- **Why warnings may pass.** A warning is limited to a recommended spelling, deterministic normalization, known fidelity reduction, or visual-quality risk when legal output remains guaranteed. It does not change page semantics or require Executor re-authoring; any condition that must be corrected for delivery is an error.
- **Why empirical, not derived from spec.** The compatibility boundary grew from real PPT export failures, not from reading the OOXML specification. Some theoretically representable effects remain unreliable across PowerPoint versions, so the contract reflects the actually shippable subset.
- **XML well-formedness remains a precondition.** Malformed SVG fails before DrawingML compatibility matters. The canonical contract owns the accepted authoring forms so XML guidance cannot drift across architecture and prompt documents.
-- **Compatibility validation runs before post-processing.** `svg_quality_checker.py` evaluates `svg_output/`; post-processing rewrites SVG and could mask source-level violations. Blocking errors are re-authored by the Executor; warnings do not trigger a rewrite, and there is intentionally no auto-fix mode (see Quality Gate).
+- **Compatibility validation runs before post-processing.** `svg_quality_checker.py` evaluates `svg_output/`; post-processing rewrites SVG and could mask source-level violations. Blocking errors are re-authored by the Executor, warnings do not trigger a rewrite, and the converter rechecks critical publication conditions under the responsibility defined in the design philosophy.
---
@@ -407,7 +423,16 @@ The architectural reasons worth knowing here:
**Why placed before post-processing, not after.** Post-processing rewrites SVG (icon embedding, image inlining), which would mask source-level violations. Reading `svg_output/` directly catches the Executor's actual output, before any cleanup that might paper over a bug.
-**Severity model: errors block, warnings don't, and there is intentionally no auto-fix.** Errors require the Executor to re-author the offending page in context — a compatibility violation is not necessarily a mechanical patch, because the replacement must preserve the same design intent. Warnings never require a return modification or acknowledgement: recommendation warnings expose the generated default, while fidelity/quality warnings describe optional review. Auto-fix would silently overwrite valid user intent and can ship a worse-looking page.
+**Severity model: errors block, warnings do not, and there is intentionally no auto-fix.** Severity is determined by whether the input maps deterministically and legally, not merely by whether it uses the recommended spelling:
+
+| Severity | Classification | Pipeline behavior |
+|---|---|---|
+| `error` | A structural contract is broken; the input has no mapping or is ambiguous; required metadata is missing; a value is invalid; conversion may violate DrawingML/PPTX constraints; or PowerPoint may need to repair the file | The Executor must re-author and revalidate; the converter must also fail closed |
+| `warning` | A unique, safe, legal conversion exists, but the input is not project-canonical or carries a documented normalization, fidelity reduction, or visual-quality risk | Record the diagnostic and allow publication; no acknowledgement or mandatory rewrite is required |
+
+The gate follows the three-layer responsibility defined in the design philosophy. It intentionally has no auto-fix: a mechanical patch can silently overwrite valid design intent and ship a worse page.
+
+If the same warning repeatedly appears in newly generated pages, fix the prompt, template example, or specification so default output returns to the project-canonical spelling. That is a generation-quality issue, not a reason to turn otherwise safe compatible input into an error. Conversely, if practice shows that a warning can produce an invalid file or ambiguous meaning, update the contract and checker together to classify it as an error.
**Why chart coordinate verification hangs off the same gate.** Chart pages have geometric correctness requirements (bar heights / pie sweep angles / axis tick positions) that aren't structural and aren't caught by SVG validity rules. The natural place to catch them is the same gate where the AI is asked to revisit its output — bundling the cognitive context "look at what you generated and fix it" into one phase, rather than splitting structural and geometric review into separate review rounds.
@@ -471,6 +496,8 @@ These direct routes share some analysis primitives with the main pipeline, espec
## Native PPTX Conversion Internals
+`svg_to_pptx.py` implements the final defensive layer defined in the design philosophy; this section explains only the internal structure of that constrained compiler route.
+
**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 imported and authored shape metadata are separate.** A lossless imported SVG may need native-shape metadata, hidden carriers, and preview fingerprints to recover an advanced PowerPoint shape. That representation stays in the temporary analysis workspace. `svg_authoring_view.py` creates a lightweight inspection projection without opaque payload or duplicate hidden carriers; the projection is never an export source. `standard` / `fidelity` use compact canonical metadata. Mirror materializes from the lossless source and may reuse converter-supported metadata on unchanged Slide-local/slot objects; fixed structural layers remain direct atoms, and unsupported or edited objects keep their current SVG fallback.
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index 95add1c8..faa6f798 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -10,6 +10,28 @@
**工具的上限是你的上限。** PPT Master 放大的是你已有的能力——你有设计感和内容判断力,它帮你快速落地;你不知道一个好的演示文稿应该长什么样,它也没法替你知道。输出的质量,归根结底是你自身品味与判断力的映射。
+### SVG 是项目的规范中间语言
+
+PPT Master 不以“任意 SVG 都能转成 PPTX”为目标。`svg_output/` 使用的是**项目规范化 SVG 中间语言**:它借用 SVG 的 XML 语法和二维图形模型,但允许的元素、属性、单位、metadata、结构合同与 DrawingML 映射都由项目规范封闭定义。这里的方向是 **SVG 适应 PPT Master,而不是 PPT Master 追随整个 SVG 标准扩张**。
+
+这套中间语言区分三种输入状态:
+
+| 状态 | 定义 | 处理方式 |
+|---|---|---|
+| 规范创作输入 | 提示词、模板和示例应生成的唯一推荐表达 | 按注册映射校验和编译,不因表达别名产生 warning |
+| 兼容输入 | 已明确登记、可确定且安全归一化的历史或人工写法 | Checker 给出非阻塞 warning;转换器确定性归一化后编译,不把别名反向扩散到提示词 |
+| 非法或不支持输入 | 缺少映射、存在歧义、破坏结构合同,或可能生成非法 DrawingML / PPTX 的表达 | Checker 或转换器报 error 并停止发布 |
+
+例如,项目字号统一采用 SVG px 语义,规范写法是有限的无单位数值(如 `font-size="24"`);其他单位只有被兼容合同明确登记且能够确定性换算时才可能作为兼容输入,不能成为生成提示词的新写法。兼容读取是一条受控迁移边界,不是放宽创作语言的理由。
+
+三层职责必须分开,不能用其中一层替代另一层:
+
+| 层级 | 单一职责 | 不承担的职责 |
+|---|---|---|
+| 提示词、模板与示例 | 精确表达项目规范写法,从源头减少偏差和 warning | 不作为正确性或安全边界 |
+| `svg_quality_checker.py` | 在作者状态上执行项目合同;error 阻塞,非阻塞 warning 放行 | 不静默改写页面,也不猜测设计意图 |
+| `svg_to_pptx.py` | 对所有调用路径防御校验;归一化已登记兼容形式;阻止已知非法 package 发布 | 不承诺转换任意 SVG,不用默认值掩盖未知或歧义输入 |
+
---
## 系统架构
@@ -33,15 +55,15 @@
↓
[Executor] 执行师
├── 生成开始前启动 live preview,并在生成期间保持可用
- ├── 视觉构建:按页顺序连续生成 SVG 页面 → svg_output/
- ├── [Quality Check] svg_quality_checker.py(强制通过,0 错误)
+ ├── 视觉构建:按页顺序连续生成项目规范化 SVG 页面 → svg_output/
+ ├── [Quality Check] svg_quality_checker.py(强制通过,0 错误;warning 非阻塞)
└── 讲稿生成:完整讲稿 → notes/total.md
↓
[图表校准(条件触发)] → verify-charts 工作流(含数据图表的 deck 必须在此步骤校准坐标)
↓
[视觉自检(可选,opt-in)] → visual-review 工作流(仅在用户明确请求时触发)
↓
-[后处理] → total_md_split.py(拆分讲稿)→ finalize_svg.py → svg_to_pptx.py
+[后处理] → total_md_split.py(拆分讲稿)→ finalize_svg.py → svg_to_pptx.py(防御校验后编译)
↓
输出:
svg_final/
@@ -57,15 +79,16 @@
└── svg_output/ ← Executor 原始 SVG 备份(重跑 finalize_svg → svg_to_pptx 即可重建 pptx)
```
-### SVG 是页面设计语言
+### SVG 是受约束的页面设计语言
-凡是通过 SVG 创作或重新设计页面的工作流,`svg_output/` 都是完整的页面设计权威。最终幻灯片中应出现的文字、图片、形状、图示、图表 / 表格 fallback、背景和模板派生布局元素,都必须已经存在于对应页面 SVG 中,或被它明确引用。模板、`design_spec.md` 和 `spec_lock.md` 负责指导 SVG 创作;导出器不能把它们当成第二层画面来源,在导出阶段补入 SVG 缺失的页面内容。
+凡是通过 SVG 创作或重新设计页面的工作流,`svg_output/` 都是完整的页面设计权威,但这里的 SVG 专指通过项目合同校验的项目规范化 SVG,而不是任意浏览器可渲染的 SVG。最终幻灯片中应出现的文字、图片、形状、图示、图表 / 表格 fallback、背景和模板派生布局元素,都必须已经存在于对应页面 SVG 中,或被它明确引用。模板、`design_spec.md` 和 `spec_lock.md` 负责指导 SVG 创作;导出器不能把它们当成第二层画面来源,在导出阶段补入 SVG 缺失的页面内容。
最小语义标记不会削弱这条闭包。自由设计与 brand-only 页面使用 `pptx_structure.mode: flat`:所有已表达对象保持 Slide 本地,不创作任何 Master/Layout 身份、分层或 placeholder metadata。导出器根据当前配色/字体 lock 生成一个属于本项目的干净 Master 和一个 Blank Layout,删除 title/body 等内置内容占位符与未使用的内置 Layout,仅保留标准日期、页脚和页码能力钩子,但不提升任何 Slide 内容。结构化 deck/layout 模板路线上,每张新页面从第一版 SVG 起就声明 Master/Layout 身份。固定 Master/Layout 视觉是根节点直接原子元素;可复用内容槽位是顶层 group,带显式设计区域 bounds 和一个兼容 carrier;复合 `object` 区域走显式 proxy 降级,Layout 也允许零槽。`data-pptx-role` 只补充专用 metadata 尚未表达的少量页面框架、package 或动画行为。结构合同缺失或使用旧形态的 legacy structured/template 项目必须先运行 `restore-pptx-structure`;flat 项目是有意不带 mapping,不算 legacy。导出器不做 Master/Layout 结构或 placeholder 推断。
| 领域 | 权威来源 |
|---|---|
| SVG 创作路线中的可见页面内容与布局 | `svg_output/` 中的最终页面 SVG |
+| 项目规范化 SVG 的语法、兼容形式与映射边界 | [`references/shared-standards.md`](../../skills/ppt-master/references/shared-standards.md) |
| Master/Layout/Slide 打包与原生对象映射 | SVG 到 PPTX 的翻译;可以重组 SVG 已表达的内容,但不能创造新的可见内容 |
| 动画、转场、讲稿和旁白 | 各自的 sidecar / 资源与 PPTX package 后处理 |
| 直接原生 PPTX 编辑 | 所选原生工作流自己的 PPTX / OOXML 契约 |
@@ -176,11 +199,11 @@ SVG 胜出,因为它与 DrawingML 拥有相同的世界观:两者都是绝
| `linearGradient` / `radialGradient` | `<a:gradFill>` |
| `fill-opacity` / `stroke-opacity` | `<a:alpha>` |
-这张表只展示概念对应关系,不是创作允许清单,也不承诺语义无损。受限或近似的映射统一由 [`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md) 定义。
+这张表只展示概念对应关系,不是对整个 SVG 标准的承诺,也不承诺所有映射语义无损。每项受支持能力都必须在 [`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md) 中拥有明确的映射记录,说明项目规范写法、允许的兼容输入、目标 DrawingML 表达、保真度和拒绝条件;涉及 PPTX 回导的能力还要说明来源 PPTX / OOXML 语义。映射状态可以是精确、确定性归一化、显式 fallback、sidecar 或 unsupported;讲稿、动画、relationships 等 package 语义不必强行塞进 SVG,但必须明确由哪条路线承载。
-这条边界明确采用**推荐窄写入、兼容宽读取**。新生成的 `svg_output/` 与可复用模板默认使用一种颜色写法:不透明的六位大写 `#RRGGBB`,透明度放在对应的 `fill-opacity`、`stroke-opacity`、`stop-opacity`、`flood-opacity` 或原子元素 `opacity` 中。转换器在导入或直接读取边界仍兼容命名色、CSS 函数色、短 HEX、带 alpha 的 HEX 及其他已记录的历史形式。Checker 可以提示推荐写法,但受支持的替代写法仍然有效,也不会阻断导出。
+主生成路线采用**规范窄写入、受控兼容读取**。新生成的 `svg_output/` 与可复用模板只使用项目规范写法,例如不透明的六位大写 `#RRGGBB`,透明度放在对应的 `fill-opacity`、`stroke-opacity`、`stop-opacity`、`flood-opacity` 或原子元素 `opacity` 中。历史或人工输入只有在兼容合同明确登记、转换结果唯一且输出合法时才可继续导出;Checker 对这类写法给出非阻塞 warning,转换器在编译边界统一归一化。任何需要猜测、没有映射或可能产生损坏 PPTX 的表达都必须报 error。
-转换不是格式错配,而是在两种结构相近的方言之间做翻译。
+因此,转换不是在任意 SVG 和 DrawingML 之间做格式猜测,而是在项目规范化 SVG 与 DrawingML 之间执行有注册表、有保真度说明、可测试的编译。
SVG 也是唯一同时满足流程中所有角色需要的格式:**AI 能可靠地生成它,人能在任意浏览器里直接预览和调试,脚本能按明确的兼容合同转换它**——在生成任何 DrawingML 之前,设计稿就已经完全透明可见。
@@ -379,18 +402,20 @@ Strategist 阶段产出两份看起来冗余但服务不同对象的产物:
---
-## SVG 兼容性边界
+## 项目规范化 SVG 与兼容性边界
-PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。在转换器已实现的词汇内,普通 SVG 默认允许。只有导出拒绝项与需要受限映射的能力才集中枚举在 [`references/shared-standards.md`](../../skills/ppt-master/references/shared-standards.md);它是接受形式与限制的唯一权威,本架构文档有意不再复述。
+PowerPoint 的 DrawingML 是 SVG 表达力的严格子集,因此主编译路径不把“浏览器可以渲染”视为“项目可以导出”。只有在 [`references/shared-standards.md`](../../skills/ppt-master/references/shared-standards.md) 中登记了项目规范表达或显式兼容形式,并且拥有确定 DrawingML 映射的词汇,才属于可接受输入。该文件是语法、结构、单位、metadata、兼容别名、保真度和拒绝条件的唯一权威;本架构文档只定义分层原则,不复制具体规则。
**为什么本地复用是编译期复用,不是 PowerPoint 保留对象。** 接受的创作形式由权威合同定义、共享校验器执行。校验通过后,流水线会递归实体化引用子树并重写克隆局部 ID 后再导出;PPTX 回导因此只返回展开后的原语,不重建创作期复用图。
值得在架构层标记的理由:
-- **为什么是例外清单,不是允许清单。** SVG 是个宽规范;穷举所有允许能力会随着转换器演进而持续增加维护成本。集中维护例外,才能让已实现的普通构造默认可用。
+- **为什么需要封闭映射,而不是默认接受普通 SVG。** 项目规范化 SVG 是编译器中间语言,不是浏览器兼容层。新增元素、属性或取值必须同时补齐导入语义、导出映射、校验规则和回归验证;未登记能力默认不进入主编译路径。
+- **为什么兼容输入不等于创作许可。** 已登记的历史别名可以由转换器确定性归一化,并由 Checker 给出非阻塞 warning;提示词、模板和示例仍只生成项目规范写法。兼容面只能服务迁移和人工输入,不能反向扩大生成语法。
+- **为什么 warning 可以放过。** warning 只表示合法输出前提下的推荐写法、确定性归一化、已知保真度下降或视觉质量风险。它不改变页面语义,不要求 Executor 回改,也不阻断发布;如果某项必须修正才能交付,它就应被定义为 error。
- **为什么是经验性,不是从规范推导。** 兼容性边界从真实的 PPT 导出失败长出来,不是读 OOXML 规范推导出来的。有些理论上能表达的效果跨 PowerPoint 版本仍不可靠,因此合同反映的是实际能交付的子集。
- **XML 良构性仍是前置条件。** SVG 一旦不是合法 XML,尚未进入 DrawingML 兼容性阶段就会失败。接受的创作形式集中在权威合同中,避免架构与提示文档分别维护后发生漂移。
-- **兼容性校验在后处理之前执行。** `svg_quality_checker.py` 在 `svg_output/` 上执行;后处理会重写 SVG,可能掩盖源级别违规。阻断性 error 由 Executor 重新写,warning 不触发回改;系统有意不提供 auto-fix 模式(见 § 质量门)。
+- **兼容性校验在后处理之前执行。** `svg_quality_checker.py` 在 `svg_output/` 上执行;后处理会重写 SVG,可能掩盖源级别违规。阻断性 error 由 Executor 重新写,warning 不触发回改;转换器按设计哲学中定义的职责再次校验关键发布条件。
---
@@ -400,7 +425,16 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。在转换器已实
**为什么放在后处理之前,而不是之后。** 后处理会重写 SVG(图标嵌入、图片内联),会掩盖源级别违规。直接读 `svg_output/` 抓的是 Executor 的实际输出,先于任何可能掩盖 bug 的清理动作。
-**严重性模型:error 阻塞、warning 不阻塞,且有意没有 auto-fix。** error 要求 Executor 在上下文里重新写出错的页面——兼容性违规不一定能机械 patch,因为替代方案必须重新承载同样的设计意图。Warning 不要求返回修改或逐条确认:推荐性 warning 说明生成默认写法,保真度 / 质量 warning 只提供可选复核信息。Auto-fix 会静默覆盖有效的用户意图,也可能交付一个更差的页面。
+**严重性模型:error 阻塞、warning 不阻塞,且有意没有 auto-fix。** 严重性不按“是否符合推荐写法”划分,而按“能否确定、合法地映射”划分:
+
+| 严重性 | 判定条件 | 流水线行为 |
+|---|---|---|
+| `error` | 结构合同被破坏;输入无映射或有歧义;必要 metadata 缺失;数值非法;转换后可能违反 DrawingML / PPTX 约束;或可能导致 PowerPoint 修复文件 | Executor 必须重写并重新校验;转换器也必须拒绝发布 |
+| `warning` | 已有唯一、安全、合法的转换结果,但输入不是项目规范写法,或存在已知的确定性归一化、保真度下降、视觉质量风险 | 记录诊断后允许发布;不要求逐条确认或强制回改 |
+
+质量门沿用设计哲学中定义的三层职责。这里有意不提供 auto-fix:机械修补可能静默覆盖有效的设计意图,也可能交付一个更差的页面。
+
+如果同一种 warning 持续出现在新生成页面中,应优先修正提示词、模板示例或规范说明,使默认输出回到项目规范写法;这属于生成质量问题,不需要把本来安全的兼容输入升级成阻塞错误。反过来,如果实践证明某个 warning 可能产生非法文件或不确定语义,就必须把合同和 Checker 同步升级为 error。
**为什么图表坐标验证挂在同一道 gate。** 图表页面有几何正确性需求(柱高、饼图扇角、坐标轴刻度位置),这些不是结构问题,SVG 合法性规则也抓不到。最自然的捕捉位置就是已经要求 AI 回看自己输出的那道 gate——把「看一眼你刚生成的东西然后修」的认知上下文打包到一个阶段,比把结构和几何审查分到两轮 review 更高效。
@@ -464,6 +498,8 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。在转换器已实
## Native PPTX 转换器内部
+`svg_to_pptx.py` 执行设计哲学中定义的最终防线;本节只解释这条受约束编译路线的内部结构。
+
**为什么是逐元素派发而不是整体翻译。** SVG 的层级模型干净地映射到 DrawingML 的 group / shape / picture 类型——不需要一个全局优化器去重新规划幻灯片。每种形状都有自己窄的翻译器,简单到能单独调试和单元测试。一张幻灯片的最终质量等于这些独立局部转换之和;这个性质在整体翻译下脆弱,在元素派发下稳健。
**为什么导入型与生成型 metadata 分层。** 导入 PPTX 时,完整 SVG 可以携带高级形状所需的 metadata、隐藏 carrier 和预览指纹,但这类载荷不适合直接进入模型上下文。authoring projection 会非破坏性地移除大体积载荷,只保留可见几何和紧凑意图,而且永远不是导出源。`standard` / `fidelity` 使用 compact canonical metadata。Mirror 从无损来源物化,可在未改的 Slide-local/slot 对象上复用转换器已经支持的 metadata;固定结构层保持直接原子,不支持或已修改的对象保留当前 SVG fallback。