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.mdSVG 写作的规范性作者契约是所有创作或再生成幻灯片视觉的路由必须参考的文件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 写作路由提供了一张三行路由表触发条件与加载模块一一对应触发条件加载模块非规范/带 alpha 的画笔、高级线条或文字处理、渐变/滤镜/特效、变换、自由形态/径向几何、或构造式样式svg-effects.md预设图案填充或创作/编辑原生图表、表格数据先加载native-data-interface.md再决定资格或输出元数据结构化 Master/Layout/slot 创作pptx-structure-interface.mdDefault 与 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.mdimage-layout-spec.mdimage-layout-patterns.mdsvg-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. 保真度标签四个词约束作者的导出预期核心标准给出了一套保真度词汇表任何涉及导出后是什么样的讨论都必须使用这四档标签标签含义Native-stable生成的 PPTX 使用对应的原生 DrawingML 属性或对象并在该技法限定的范围内保留文档化语义。Native-normalized导出目标是可编辑的 DrawingML 等价物但把 SVG 归一化为另一结构如自由形态、run 属性或简化后的画笔/特效。ApproximateDrawingML 没有精确的 SVG 等价物导出通过文档化的近似手段达到预期效果存在实质差异时需要人工复核输出。Bake-required运行时效果超出原生契约必须先预渲染成图片或用受支持的显式几何重建。文档特别强调保真度标签只描述svg_output/→ PPTX 这一条正向导出路径不覆盖 PPTX 导入后的重建、也不承诺 PowerPoint / LibreOffice / Keynote / WPS 之间的像素级一致。也就是说Native-stable是对导出器读取我们生成的 SVG这一单向管道做出的承诺而不是对生态互操作性的承诺。3. 阅读规则与 fail-closed 硬规则核心标准开篇给出三条阅读规则用于区分规范的强制性等级Required / Forbidden 陈述是不可协商的技术边界Conditional 契约仅在对应特性被使用时生效Reference — not a constraint 段落只暴露能力与配方不要求每页或每种视觉风格都使用它们已锁定的visual_style只控制兼容效果是否使用、用多强永不扩大技术边界。紧接着是一条全局硬规则——生成式创作 fail-closedsvg_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。所有文本与属性值只有两种合法写法字符类别必须写成禁止写成排版与符号em dash、en dash、©、®、→、·、NBSP、全角标点、emoji…原始 Unicode 字符——直接写—–©®→HTML 命名实体——mdash;ndash;copy;reg;rarr;middot;nbsp;hellip;bull;等XML 保留字符仅用 XML 实体——amp;lt;gt;quot;apos;如Ramp;D、error lt; 5%裸如RD、error 5%一个违规字符就会使文件失效并中止导出。4.2 结构性黑名单以下语法被穷尽式禁用这是一份全局禁用清单不是正向白名单禁用特性说明mask蒙版style内嵌样式表classCSS 选择器属性外部 CSS外部样式表链接foreignObject内嵌外部内容textPath沿路径排文font-face自定义字体声明animate*/setSVG 动画script/ 事件属性脚本与交互iframe内嵌框架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-shiftsuper|sub必须是直接属性永远不能进内联样式。普通生成画笔的默认写法是大写六位#RRGGBBfill/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 置b1。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.1marker-start/marker-end只允许用在line与path上引用defs中一个本地markerorientauto或auto-start-reverse其唯一子元素必须是五种 DrawingML 线端之一triangle3 顶点闭合多边形stealth简单凹 4 顶点闭合多边形arrow开口 3 顶点路径diamond简单凸 4 顶点闭合多边形oval一个circle/ellipse。闭合形状的填充必须与父线条描边一致开口箭头用fillnone且描边与父线条一致。任何其他形状的 marker 都会阻断导出而不是被静默丢弃。映射表与导入行为细节见 svg-contract.md §1.1。5.2 图片裁剪§1.2clip-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 xmlnshttp://www.w3.org/2000/svg defs symbol idstatusDot viewBox0 0 20 20 preserveAspectRatioxMidYMid meet circle cx10 cy10 r8 fill#16A34A/ /symbol g idlegendRow rect width120 height32 rx8 fill#F1F5F9/ text x42 y22 font-size16 fill#0F172AReady/text /g /defs use href#statusDot x80 y120 width32 height32/ use href#legendRow x120 y120/ /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.4pptx_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 adj1val 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/--strokenone或六位实心 HEX、--fill-opacity/--stroke-opacity0–1、--stroke-width、--stroke-linecap、--stroke-linejoin、--filter-id与可重复的--adjust NAMEFORMULA另有render-batch --input -从 stdin 读 UTF-8 JSON 数组原子输出多个片段任一项非法则一个都不打印。硬规则——仅限助手的元数据预设、外框、调整量、填充、描边、描边宽度或滤镜引用任一变化都必须用助手重新生成整个片段需要自由轮廓编辑时则换成普通 SVG。助手只接受none或六位实心 HEX 画笔、可选通道不透明度、描边宽度、cap、join 与一个仅限形状的滤镜渐变、图案与其他处理留在普通 SVG文本永远留在原子片段之外。校验器与导出器会从元数据重渲每个片段任何漂移都 fail-closed。6. 条件兼容映射几何与组透明度§26.1 字面几何长度语法§2.1硬规则x、y、width、height、rx、ry、cx、cy、r、x1…y2、dx、dy与stroke-width必须写成页面viewBox坐标系中的有限无单位普通小数如x120、stroke-width2尺寸与半径非负。px后缀可读但会告警其他任何单位、百分比、表达式或奇异数值拼写都是错误且显式非法值永不回退到默认值。同样的几何属性可以出现在元素自身style中、写成px字面量如stylex: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–§47.1 画布viewBox 是唯一权威§3 明确使用已锁定的画布 id 与精确 viewBox格式选择权属于 canvas-formats.md本核心标准只负责在该画布上的 SVG 合规性。无锁的quick-generate档案用它的第一张 SVG 确立画布其后每一页必须使用完全相同的 viewBox。画布清单摘自 canvas-formats.mdppt1691280×720、ppt431024×768、xiaohongshu1242×1660、moments1080×1080、story1080×1920、wechat900×383、banner1920×1080、a41240×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_output/slide.svg必须包含该页打算展示的所有可见文本、图片、形状、图示、图表/表格回退、背景与模板派生布局元素外部视觉资源仅在 SVG 显式引用时合法。模板/控制输入模板、design_spec.md、spec_lock.md只指导创作不得依赖它们在页面 SVG 完成后补加可见元素。PPTX 翻译导出器可以把 SVG 中已表现的内容映射为 DrawingML/原生对象并把已表现元素去重进 Master/Layout/Slide 部件绝不凭空发明 SVG 中不存在的可见内容。排除的包行为演讲者备注、动画、转场、旁白音频、PPTX 关系与直接原生 PPTX 工作流各自独立拥有不属于 SVG 页面设计契约。页面设计封闭硬规则最终页面 SVG 完整但不拥有整个 PPTX 包。其普通内容与 SVG-first 图表/表格标记是权威对于data-pptx-native-authorityjson内联 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-rolecover/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 行为时才需要下列形式期望行为必需形式一个可编辑的 PPT 文本框、含混合格式或多行散文每逻辑段落一个text行内 run 用非定位tspan子元素每 run 的fill/font-weight/font-size被保留导出逐段生成 DrawingML run首行保持直接文本后续行用重复父x、正相对dy的定位tspan首行本身带行内 run 时用全tspan形式、可从dy0开始。默认保留换行--reflow-text可能合并合格行。字体大小变化、列表标记或更大的接受间距会另起段落。兄弟text不是段落的换行——检查器按启发式对疑似情况告警导出前修复。稳定对象分组或对象级动画锚点把目标对象包进g id...。内容分组按 §4.3 是强制的——顶层g id同时是动画锚点不是可选便利。原生 PowerPoint 背景提升非结构化模式下让第一视觉层成为直接全画布rect或简单单子组内的一个填充为实心/线性/径向渐变或预设图案且无变换、滤镜、裁剪、圆角或可见描边导出写为 Slidep:bg。结构化路由遵循 pptx-structure-interface.md。自由设计 / 仅品牌结构用pptx_structure.mode: flat对象全部 Slide-local不创作 Master/Layout 身份、layer 或 slot导出生成一个干净 Master Blank Layout。可复用模板布局Default 通过page_layouts与page_pptx_layouts映射Quick 在每张输出 SVG 中创作所选 Master/Layout/slot 契约其 all-or-none 门推断结构化打包。绝不从重复的 Slide-local 几何推断归属。行距默认值按角色与密度可为用户、模板、字体、可读性或锁定视觉风格覆盖定位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-boundsx y width height尺寸为预期模块区。平面页上最大化普通区、不重叠检查器对超过1px的根组重叠判错对模块文本溢出 5% 以内告警、以上判错任何更大的根viewBox文本溢出判错。Bounds 不裁剪也不重排。压在一张图片上的原生 plate、caption 或 label 属于该图片的根组不占独立区、不产生根组重叠裁剪图片的区是其可见区域。每个逻辑 Slide-local 正文单元包进一个描述性顶层g id组数量跟随页面的语义单元每组成启用动画时的一个稳定动画目标。嵌套实现组可以匿名、无需 bounds、不产生动画步骤。标题、直接原子 Master/Layout 元素、画布级静态框架背景图与全画布 scrim/装饰矩形可以保持根基元平面页上给这类框架稳定id加data-pptx-rolebackground/decoration且不要仅为消除未分组元素告警而加g。核心标准给出的每组一个单元分组表分组单元包含Card / panel背景矩形 可选阴影仅当浮在照片/彩色面板上 图标 标题 正文Process step编号/标记 图标 标签 描述List item项目符号/编号 图标 标题 描述Icon-text combo图标元素 相邻标签Page header标题 副标题 强调装饰Page footer页码 品牌Decorative cluster相关装饰形状环、点、球禁止整个幻灯片套一个大g塌缩为单个动画步骤大量未分组的 Slide-localrect/text/path原子每图标/每文本行一个顶层组匿名顶层组——每个顶层语义组都要有描述性、页内唯一的id如card-1、step-discover、header、footer。完整示例g idcard-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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考