企业官网建设流程全解析

PPT Master 共享 SVG 技术标准解析：从条件路由到 fail-closed 导出的完整作者契约

【免费下载链接】ppt-masterAI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations,>项目地址: https://gitcode.com/GitHub_Trending/ppt/ppt-master

导读

shared-standards.md是 PPT Master 项目（AI 将文档或主题生成为原生 PowerPoint 演示文稿的开源仓库）中拆分式 SVG 规范的兼容性路由器，其真正的技术主体位于同目录下的shared-standards-core.md。本文以这两份文档为核心骨架，结合仓库内的校验器、导出器与辅助脚本源码，系统讲解：哪些条件模块在什么触发条件下被加载、Native-stable/Native-normalized/Approximate/Bake-required四档保真度标签如何约束作者预期、生成式 SVG 写作的封闭语法（XML 文本规则、内联样式白名单、页面契约、强制分组），以及校验器与导出器如何共享同一套验证器实现 fail-closed。读完本文，你将掌握用 PPT Master 手写一张能通过质量门禁、并忠实映射为原生 PPTX 对象的页面 SVG 的全部边界与套路。

1. 路由器文件：shared-standards.md 的定位与分模块架构

1.1 一份指针，而不是运行时权威

shared-standards.md全文极短，却定义了整个文档体系的分层方式：

• 常开契约：shared-standards-core.md（SVG 写作的规范性作者契约）是所有"创作或再生成幻灯片视觉"的路由必须参考的文件；
• Default / Quick Generate 两条主路径：通过executor-base.md的路由表按需加载全部条件模块；
• 其他 SVG 写作路由（Create Template、Edit Native PPTX 等）：只加载shared-standards-core.md顶部路由表指定的模块。

文档明确声明："此文件是指针，不是组合式运行时权威（a pointer, not a combined runtime authority）"。这意味着一份规范的完整性由"被选中的路由"决定，而不是把全部条件模块默认加载进来——阅读者必须跟随所选路由的必需模块清单。

1.2 条件模块路由表（核心标准 § 开头）

shared-standards-core.md为除 Default / Quick 之外的 SVG 写作路由提供了一张三行路由表，触发条件与加载模块一一对应：

Default 与 Quick 两条主路径则在executor-base.md的路由表中全量列出触发条件，包括pptx_structure.mode: structured→executor-structured.md、任何图表/表格 family/key 引用 →executor-visualization.md、任何值驱动几何 →executor-chart.md、任何语义化单元格网格 →executor-table.md、页面轮廓超出基础图元 →native-shape-authoring.md、视觉任务超出日常块 →svg-effects.md、任意图片 →executor-image.md+image-layout-spec.md+image-layout-patterns.md+svg-image-embedding.md、任意数学表达式 →native-formula.md、任意超链接 →native-hyperlinks.md等。路由评估以每个对象的实际信息模型为准，而不是只看图表/表格引用，且"目录族只选择构建指导，绝不代表原生就绪"（executor-base.md）。

从源码角度看，这种"先扫全单、批量读模块"的机制与svg_quality/checker.py的模块化导入结构一致：校验器通过大量try/except ImportError包裹的可选导入，把语义标记（svg_to_pptx.semantic_markers）、原生对象标记（svg_to_pptx.native_objects）、模板结构（svg_to_pptx.pptx_package.template_structure）、主题字体/颜色（theme_fonts/theme_colors）等能力按需接入同一进程（checker.py）。

2. 保真度标签：四个词约束作者的导出预期

核心标准给出了一套"保真度词汇表"，任何涉及"导出后是什么样"的讨论都必须使用这四档标签：

文档特别强调：保真度标签只描述svg_output/→ PPTX 这一条正向导出路径，不覆盖 PPTX 导入后的重建、也不承诺 PowerPoint / LibreOffice / Keynote / WPS 之间的像素级一致。也就是说，Native-stable是对"导出器读取我们生成的 SVG"这一单向管道做出的承诺，而不是对生态互操作性的承诺。

3. 阅读规则与 fail-closed 硬规则

核心标准开篇给出三条阅读规则，用于区分规范的强制性等级：

• Required / Forbidden 陈述是不可协商的技术边界；
• Conditional 契约仅在对应特性被使用时生效；
• Reference — not a constraint 段落只暴露能力与配方，不要求每页或每种视觉风格都使用它们；
• 已锁定的visual_style只控制"兼容效果是否使用、用多强"，永不扩大技术边界。

紧接着是一条全局硬规则——生成式创作 fail-closed：svg_output/与可复用模板 SVG 只能使用本文件或路由表触发模块中明确列出的属性与条件接口。svg_quality_checker.py与导出器 preflight 共享同一个验证器：未知的内联视觉属性和未映射的条件契约一律视为错误；文档化的兼容拼写仍是合法输入，只会收到"建议类"警告（recommendation warning），既不强求修改也不阻断导出。配方永远不能扩大转换器支持范围。

这一点在源码中得到直接印证：svg_quality_checker.py 是稳定的 CLI 入口（用法python3 scripts/svg_quality_checker.py <svg_file>/<directory>/--roundtrip/--all projects），其实现体svg_quality/checker.py显式说明"失败检查报告的就是导出会拒绝的同一边界"——因为检查器直接导入导出器共享的验证器（svg_to_pptx/drawingml/utils.py、converter.py、text_properties.py），详见 svg-contract.md 开篇。

4. 文本与 XML：第一道也是致命的一道关

4.1 字符两分法

SVG 是严格 XML。所有文本与属性值只有两种合法写法：

一个违规字符就会使文件失效并中止导出。

4.2 结构性黑名单

以下语法被穷尽式禁用（这是一份全局禁用清单，不是正向白名单）：

4.3 内联样式白名单与默认写法

内联style只能携带以下属性族：绘制/线条（fill、stroke、stroke-width、stroke-dasharray、stroke-linecap、stroke-linejoin、fill-opacity、stroke-opacity、vector-effect）、文本（font-family、font-size、font-weight、font-style、text-anchor、letter-spacing、text-decoration）、alpha 与定义画笔（opacity、stop-color、stop-opacity、flood-color、flood-opacity）、§2.1 的字面几何属性，以及仅预览用shape-rendering。而filter、clip-path、marker-start/marker-end、<tspan>上的baseline-shift="super|sub"必须是直接属性，永远不能进内联样式。

普通生成画笔的默认写法是：大写六位#RRGGBB；fill/stroke也可用小写none或精确的本地url(#id)。普通文本要求非空font-family、有限正的单位无后缀 pxfont-size、font-weight取normal/bold/整百数值、font-style取normal/italic、text-anchor取start/middle/end且只能放在<svg>/<g>/<text>上（<tspan>上非法）。这些值域与 svg-contract.md §1 的注册属性表完全对应，并进一步明确font-weight的兼容输入（medium→500、semibold→600）与 DrawingML 映射（100–500 归 regular、600–900 置b="1"）。

4.4 紧凑继承式写作与 --canonical-authoring

核心标准要求"紧凑继承式创作"：把公共排版表现属性放在<svg>根上、有可见文本处直接给出font-family、根画笔/特效禁用；把共享排版或画笔放在最近的语义化<g>上，真正的子级覆盖保持显式。源码提供了配套工具：svg_quality_checker.py的--canonical-authoring开关会把"偏离紧凑形式"报告为建议类警告，svg-contract.md §1 还提到compact_svg_styles.py --inplace可对已创作的项目页面（而非结构化模板花名册）自动做同样的归一化。

5. 五个条件契约（§1.1–§1.5）：什么时候能用、长什么样

5.1 线端标记（§1.1）

marker-start/marker-end只允许用在<line>与<path>上，引用<defs>中一个本地<marker>，orient="auto"（或auto-start-reverse），其唯一子元素必须是五种 DrawingML 线端之一：

• triangle：3 顶点闭合多边形；
• stealth：简单凹 4 顶点闭合多边形；
• arrow：开口 3 顶点路径；
• diamond：简单凸 4 顶点闭合多边形；
• oval：一个<circle>/<ellipse>。

闭合形状的填充必须与父线条描边一致；开口箭头用fill="none"且描边与父线条一致。任何其他形状的 marker 都会阻断导出（而不是被静默丢弃）。映射表与导入行为细节见 svg-contract.md §1.1。

5.2 图片裁剪（§1.2）

clip-path只在<image>上原生映射：<defs>中一个本地<clipPath>，恰好包含一个<circle>、<ellipse>、<rect>（可带rx/ry）、<path>或<polygon>，不允许clip-rule/fill-rule。圆形、椭圆、矩形裁剪必须精确覆盖图片外框并成为预设图片几何；路径/多边形则成为框内的自定义几何。clip-path用在形状、组或文本上是禁止的——应直接创作目标几何。详细映射见 svg-contract.md §1.2。

5.3 静态同文档<use>（§1.3）

可引用<symbol>（有限正viewBox、内部有作品、实例width/height为正无单位值）或基元、<g>、<text>、<image>。核心标准给出了完整示例：

<svg xmlns="http://www.w3.org/2000/svg"> <defs> <symbol id="statusDot" viewBox="0 0 20 20" preserveAspectRatio="xMidYMid meet"> <circle cx="10" cy="10" r="8" fill="#16A34A"/> </symbol> <g id="legendRow"> <rect width="120" height="32" rx="8" fill="#F1F5F9"/> <text x="42" y="22" font-size="16" fill="#0F172A">Ready</text> </g> </defs> <use href="#statusDot" x="80" y="120" width="32" height="32"/> <use href="#legendRow" x="120" y="120"/> </svg>

该管道与浏览器 SVG 有两个关键差异：finalize 与原生导出会把被引用的基元克隆进每个实例（PowerPoint 不保留符号图，PPTX 导入也从不重建<use>）；被复用的子树不得携带 layer、placeholder 或图表/表格替换元数据。安全上限为：一条可达引用链最多 64 个实例，单个 SVG 最多展开 10,000 个本地<use>；外部/文件/data URL、缺失目标、循环引用、重复 id 均为禁止形式（svg-contract.md §1.3）。

5.4 导入的原生 PowerPoint 形状（§1.4）

pptx_to_svg.py为源自p:sp、p:cxnSp、p:grpSp的对象输出渲染中立的元数据（data-pptx-object、data-pptx-shape-id、data-pptx-frame、data-pptx-prst、data-pptx-av-*、data-pptx-part、载荷与效果诊断）。该契约只适用于无损导入 SVG 与"导入、镜像、往返"路由上未修改的导入对象；普通作者 SVG 永不写这些属性，导出也绝不把未知预设或不受支持的效果静默降级。元数据细节与表示层拆分见 svg-contract.md §1.4。

5.5 作者手写的原生 PowerPoint 预设（§1.5）

新 SVG 页面与项目自有规范模板可以通过确定性片段助手把一个完整几何对象选入原生 DrawingML 预设。选择逻辑在 native-shape-authoring.md；助手只打印一个紧凑原子<g>python3 ${SKILL_DIR}/scripts/preset_shape_svg.py render rightArrow \ --id p03-growth-arrow \ --frame 160 210 320 112 \ --fill "#2563EB" \ --stroke none \ --adjust "adj1=val 50000"

--filter-id softShadow只有在那个 id 已命名了页面级 svg-effects.md §6.4 滤镜定义时才追加。对应的 CLI 实现在 preset_shape_svg.py 中：render子命令接受--id、--frame（四参数 X Y WIDTH HEIGHT）、--object-kind shape|connector、--fill/--stroke（none或六位实心 HEX）、--fill-opacity/--stroke-opacity（0–1）、--stroke-width、--stroke-linecap、--stroke-linejoin、--filter-id与可重复的--adjust NAME=FORMULA；另有render-batch --input -从 stdin 读 UTF-8 JSON 数组，原子输出多个片段，任一项非法则一个都不打印。

硬规则——仅限助手的元数据：预设、外框、调整量、填充、描边、描边宽度或滤镜引用任一变化，都必须用助手重新生成整个片段；需要自由轮廓编辑时则换成普通 SVG。助手只接受none或六位实心 HEX 画笔、可选通道不透明度、描边宽度、cap、join 与一个仅限形状的滤镜；渐变、图案与其他处理留在普通 SVG，文本永远留在原子片段之外。校验器与导出器会从元数据重渲每个片段，任何漂移都 fail-closed。

6. 条件兼容映射：几何与组透明度（§2）

6.1 字面几何长度语法（§2.1）

硬规则：x、y、width、height、rx、ry、cx、cy、r、x1…y2、dx、dy与stroke-width必须写成页面viewBox坐标系中的有限无单位普通小数（如x="120"、stroke-width="2"），尺寸与半径非负。px后缀可读但会告警；其他任何单位、百分比、表达式或奇异数值拼写都是错误，且"显式非法值永不回退到默认值"。同样的几何属性可以出现在元素自身style中、写成px字面量（如style="x:120px"），管道会将其物化为 XML 属性。行端点、文本位置、路径数据与 points 必须保持为 XML 属性。完整语法见 svg-contract.md §2.1。

6.2 组透明度（§2.2）

默认做法：把 alpha 放在受影响的子孙画笔、文本 run、图片或受支持特效上。<g opacity>仍被接受（Approximate，乘入子孙、仅有保真度警告），因为 DrawingML 没有隔离的组 alpha 模型。校验器将其报告为非阻断的保真度警告，且--native-charts-and-tables会拒绝带透明度的原生表格/图表标记。

7. 画布格式与页面契约（§3–§4）

7.1 画布：viewBox 是唯一权威

§3 明确：使用已锁定的画布 id 与精确 viewBox；格式选择权属于 canvas-formats.md，本核心标准只负责"在该画布上的 SVG 合规性"。无锁的quick-generate档案用它的第一张 SVG 确立画布，其后每一页必须使用完全相同的 viewBox。画布清单（摘自 canvas-formats.md）：ppt169（1280×720）、ppt43（1024×768）、xiaohongshu（1242×1660）、moments（1080×1080）、story（1080×1920）、wechat（900×383）、banner（1920×1080）、a4（1240×1754）。导出在1 SVG px = 9,525 EMU上一次性量化；所有页面与内部 Layout 原型共享同一数值画布，并须落在 PowerPoint 每边 914,400–51,206,400 EMU（约 96–5,376 SVG px）的合法范围内。

7.2 完整页面设计契约（§4.0）

页面设计封闭硬规则：最终页面 SVG 完整，但不拥有整个 PPTX 包。其普通内容与 SVG-first 图表/表格标记是权威；对于data-pptx-native-authority="json"，内联 JSON 是权威，可见子树是派生的（可能近似的）预览，权威永不转移到 sidecar。

7.3 语义标记契约（§4.1）

语义标记是最小的编译提示。平面页只声明一个根data-pptx-page-role，并省略 Master/Layout/layer/placeholder 标记；结构化页从创作开始就携带最终根身份、layer 原子、slot 与原生对象元数据，并省略data-pptx-page-role。只有在没有专门标记能表达页面框架行为时，才用带稳定id的data-pptx-role。词汇表由 semantic-svg.md 拥有，其边界规则包括：平面路由（free-design、brand-only、template_reuse_scope: style）声明一个根data-pptx-page-role（cover/toc/section/content/ending），并省略全部 Master/Layout/layer/placeholder 标记；data-pptx-role的取值background/decoration/header/footer/logo/watermark/chrome/page-number用于包、页码或动画行为，且"专门化元数据优先"——Master/Layout/placeholder 元数据、data-pptx-replace-with、§1.4–1.5 形状元数据永不与data-pptx-role重复。

字体可移植性：先解析显式用户/模板交付目标；否则默认 Windows Microsoft PowerPoint、语言跟随演示文稿主语言。导出使用的拉丁/东亚字体必须在该目标上已安装或获准；作者主机的字体只影响 SVG 预览与度量，绝不选择 PPTX 字体。@font-face仍被禁止，字体族选择属于规划角色（plan-core.md §6.2）。

7.4 可编辑性、包提升与行距（§4.2）

只有在意特定 PPT 行为时才需要下列形式：

行距默认值（按角色与密度，可为用户、模板、字体、可读性或锁定视觉风格覆盖）：定位<tspan>行的多行标题约1.2–1.3 × font-size；密集/小号正文约1.4–1.5 ×；普通正文约1.5–1.6 ×；大号/稀疏/呼吸感正文约1.6–2.0 ×。这些是起始区间而非检查配额；行距用正相对dy编写，而不是 CSS/SVGline-height（后者没有注册的 DrawingML 映射）。

7.5 元素分组：强制契约（§4.3）

硬规则——根组保护正文排版布局：除紧凑助手预设原子外，每个可见直接根<g>都必须声明根坐标data-pptx-bounds="x y width height"，尺寸为预期模块区。平面页上最大化普通区、不重叠；检查器对超过1px的根组重叠判错，对模块文本溢出 5% 以内告警、以上判错，任何更大的根viewBox文本溢出判错。Bounds 不裁剪也不重排。压在一张图片上的原生 plate、caption 或 label 属于该图片的根组（不占独立区、不产生根组重叠）；裁剪图片的区是其可见区域。

每个逻辑 Slide-local 正文单元包进一个描述性顶层<g id>；组数量跟随页面的语义单元，每组成启用动画时的一个稳定动画目标。嵌套实现组可以匿名、无需 bounds、不产生动画步骤。标题、直接原子 Master/Layout 元素、画布级静态框架（背景图与全画布 scrim/装饰矩形）可以保持根基元；平面页上给这类框架稳定id加data-pptx-role="background"/"decoration"，且不要仅为消除未分组元素告警而加<g>。

核心标准给出的"每组一个单元"分组表：

禁止：整个幻灯片套一个大<g>（塌缩为单个动画步骤）；大量未分组的 Slide-local<rect>/<text>/<path>原子；每图标/每文本行一个顶层组；匿名顶层组——每个顶层语义组都要有描述性、页内唯一的id（如card-1、step-discover、header、footer）。

完整示例：

<g id="card-benefits-1" contenteditable="false">【免费下载链接】ppt-masterAI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations,>项目地址: https://gitcode.com/GitHub_Trending/ppt/ppt-master