PPT Master 的 Shared SVG Core Standards 深度解析生成式 SVG 编写的强制契约与保真度边界【免费下载链接】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-core.md位于 skills/ppt-master/references/shared-standards-core.md是 PPT Master 中每一条通过 SVG 编写或再生成幻灯片视觉的路线都必须阅读的强制核心标准。它统辖 XML 有效性、封闭的生成式创作表面closed generated-authoring surface、页面闭合page closure、语义分组、共享视觉质量默认值以及保真度词汇。读完本文你将掌握哪些 SVG 写法是生成即合法的、哪些是结构禁用的四个保真度标签Native-stable/Native-normalized/Approximate/Bake-required分别意味着什么以及质量检查器 svg_quality_checker.py 与导出器究竟在预检阶段强制验证哪些边界。1. 标准定位一份模型写作形态的封闭语法在 PPT Master 的文档体系中SVG 相关标准被刻意拆成了两层写作形态层本文所基于的shared-standards-core.md保持的是模型实际书写 SVG 时的规范形态——哪些属性允许、哪些写法是推荐的、哪些是高优先级规则的例外。机器契约层完整的封闭语法——映射表、接受但告警的拼写accepted-but-warned spellings、拒绝边界、导入侧元数据——全部存放在 svg-contract.md。该契约文档的章节号§1.x、§2.x与核心标准一一镜像保证双向引用可以解析。这种分层背后有一个关键的工程事实质量检查器与导出器共享同一套验证器。从 checker.py 的源码可以看到它直接导入svg_to_pptx/drawingml/utils.py、converter.py、text_properties.py中的共享实现from svg_to_pptx.drawingml.utils import ( ... parse_inline_style as _parse_inline_style, parse_project_geometry_length as _parse_project_geometry_length, ... )这意味着一个未通过质量检查的 SVG导出时也会在同一个边界被拒绝——检查失败与导出拒绝报告的是同一条界线不存在检查器宽松、导出器严格或反之的落差。1.1 条件模块路由Conditional Module Routing核心标准并非一个全能大文件。默认路线Default和 Quick Generate 通过 executor-base.md 的路由表加载所有模块其他 SVG 编写路线Create Template、Edit Native PPTX则按下表按需加载触发条件加载模块非规范/alpha 油漆、高级线条或文本处理、渐变/滤镜/效果、变换、自由形/径向几何、或构造风格svg-effects.md使用了预设图案填充或编写/编辑了原生图表/表格数据native-data-interface.md在判定资格或发出元数据之前加载结构化 Master/Layout/slot 编写pptx-structure-interface.md设计默认值无更高权威发声时生效汇总在原标准 §6即本文第 7 节。1.2 保真度标签Fidelity Labels生成式创作中最容易被误读的概念是看起来一样与原生可编辑的差别。核心标准用四个标签来界定 SVG → PPTX 路径上的保真度标签含义Native-stable生成的 PPTX 使用对应的原生 DrawingML 属性或对象并在该技术自身的限制内保留文档化语义。Native-normalized导出目标是一个可编辑的 DrawingML 等价物但将 SVG 归一化为另一种结构如自由形、run 属性或简化油漆/效果。ApproximateDrawingML 没有精确的 SVG 等价物导出通过文档化的近似实现目标效果实质性差异需要人工检查输出。Bake-required运行时效果超出原生契约必须预先渲染为图片或用显式支持的几何重建。关键限定保真度标签只描述svg_output/→ PPTX 这一条路径——不描述PPTX 导入后的重建也不承诺 PowerPoint、LibreOffice、Keynote、WPS 之间的像素一致性。1.3 阅读规则与硬规则Required / Forbidden不可谈判的技术边界。Conditional仅在对应功能被使用时生效。Reference — not a constraint展示能力与配方不要求每页或每种视觉风格都使用。被锁定的visual_style只决定是否使用、用多强地使用兼容效果永不扩大技术边界。硬规则——生成式创作 fail-closedsvg_output/和可复用模板 SVG 只能使用本文件或路由表中被触发模块显式列出的属性与条件接口。未知的内联视觉属性和未映射的条件契约是错误文档化的兼容拼写是合法输入只获得推荐性告警recommendation warnings永不强制修改或阻断导出。2. 基础必备、禁用特性与条件接口§12.1 文本字符必须是良构 XMLSVG 是严格的 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%结构黑名单穷举式禁止语法不是正向允许清单禁用特性说明mask蒙版style内嵌样式表classCSS 选择器属性外部 CSS外部样式表链接foreignObject内嵌外部内容textPath沿路径文本font-face自定义字体声明animate*/setSVG 动画script/ 事件属性脚本与交互iframe内嵌框架2.2 内联视觉属性白名单内联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。注意这些属性必须是直接属性direct attribute绝不能进内联 stylefilter、clip-path、marker-start/marker-end、tspan上的baseline-shiftsuper|sub。契约文档 svg-contract.md §1 进一步明确了拒绝边界!important、未知 CSS 属性、混合模式、isolation、backdrop filters 都会导致质量检查失败。2.3 默认普通生成油漆与文本新生成的纯色油漆使用大写六位#RRGGBBfill/stroke也可以使用小写none或精确的本地url(#id)。alpha 通道、虚线、两段渐变、executor-base.md日常块everyday block的阴影/发光滤镜都不需要额外文件任何其他颜色拼写、cap/join 选择、渐变描边或文本填充、滤镜形态、rotate 之外的变换、或构造油漆/效果都必须先加载 svg-effects.md。普通文本要求非空font-family、有限的正数无单位 pxfont-size、font-weight为normal/bold/ 整数百100–900、font-style为normal/italic、text-anchor为start/middle/end且text-anchor只能出现在svg、g、text上绝不能在tspan上。tracking、下划线/删除线、轮廓、渐变、滤镜文本处理遵循 svg-effects.md §6.7。2.4 紧凑继承式编写与--canonical-authoring硬规则——紧凑继承式编写把通用排版呈现属性放在svg上只要有可见文本就必须有直接font-family根级油漆/效果被禁止共享排版或油漆放在最近的语义g上真正的子级覆盖保持显式。来源保持有效、浏览器可见、语义化、本地可编辑的 SVG绝不使用 class/样式表、别名/私有键、编码负载、精度损失或无关的间接层。这条规则的配套工具是--canonical-authoring检查标志它把偏离紧凑形式报告为咨询性告警。对应的归一化脚本 compact_svg_styles.py 提供--inplace模式可在请求时对已编写的项目页面应用同样的归一化从不作用于结构化模板名册。契约文档还补充说明text-anchor在tspan上非法未知或未映射的声明会让检查器预检和原生导出同时失败。2.5 条件接口一览marker-start/marker-end—— §1.1image上的clipPath—— §1.2静态同文档use—— §1.3导入的原生形状元数据 —— §1.4编写的原生预设片段 —— §1.5内联几何、简单渐变、滤镜、近似组不透明度 —— §2 与 svg-effects.mdPPT 预设图案与原生图表/表格/模板元数据 —— native-data-interface.md 与 pptx-structure-interface.md任意逐像素合成文本挖空、多层图像文本、alpha 合成是 bake-required唯一注册的例外是 svg-effects.md §6.3 的单图文本图片填充。3. 三大条件接口详解§1.1–§1.53.1 线端标记Line-end Markers条件契约line和path上的marker-start/marker-end引用defs中一个带orientauto或auto-start-reverse的本地marker其唯一子元素必须是五种 DrawingML 线端之一triangle3 顶点闭合多边形stealth简单凹 4 顶点闭合多边形arrow开放 3 顶点路径diamond简单凸 4 顶点闭合多边形oval一个circle/ellipse闭合形状用与父描边匹配的填充开放的 arrow 用fillnone 匹配描边。任何其他 marker 形状都会阻断导出而不是被静默丢弃。契约文档 §1.1 补充了严格的路径语法一个顶点一条显式M/L命令triangle/stealth/diamond 以Z结尾arrow 在第三顶点后保持开放路径内不允许H、V、曲线或隐式多顶点L。保真度类型Native-normalized尺寸Approximatesm/med/lg。3.2 图片裁剪Image Clipping条件契约clip-path只在image上原生映射defs中一个本地clipPath恰好包含一个circle、ellipse、rect可选rx/ry、path或polygon且不得带clip-rule/fill-rule。Circle、ellipse、rect 裁剪必须精确覆盖图片框并变成预设图片几何preset picture geometrypath/polygon 变成框内自定义几何custom geometry所以轮廓不完全覆盖整框时应使用它。形状、组、文本上的clip-path被禁止——直接编写目标几何即可。契约文档 §1.2 给出了逐形状的 DrawingML 输出映射circle/ellipse → 全框a:prstGeom prstellipse/带rx的 rect → 全框roundRectpath/polygon →a:custGeom坐标映射进图片框。依赖 even-odd 或其他显式环绕规则的轮廓在映射之外必须重建为单一明确可见轮廓或预渲染。3.3 静态同文档use条件契约可编写href#id指向一个symbol有限正viewBox、内部含作品、实例width/height为正无单位值或指向 primitive、g、text、image。此管线与浏览器 SVG 有两点不同finalization 与原生导出会把被引用的 primitives 克隆到每个实例——PowerPoint 没有 symbol 图symbol graphPPTX 导入也永不重建use被复用的子树不得携带 layer、placeholder 或图表/表格替换元数据。契约文档 §1.3 给出了完整约束引用语法用 SVG 2 的href#id遗留xlink:href保持可读并被 Live Preview 归一化symbol必须有有限四数viewBox支持meet与none禁止slice、refX、refY可达引用链最多 64 个实例一个 SVG 最多展开 10,000 个本地use实例。禁用的不安全本地引用包括外部/文件/data URL、缺失目标、冲突的href/xlink:href、不支持的 target 元素、循环引用链、重复 ID、url(#id)引号变体。核心标准的示例来自 shared-standards-core.md §1.3svg 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/ /svg3.4 导入的原生 PowerPoint 形状条件契约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 以及导入、镜像mirror、往返round-trip路线上未更改的导入对象普通编写的 SVG 永不写这些属性导出也永不把未知预设或不支持效果静默降级。契约文档 §1.4 提供了完整的机器契约细节包括data-pptx-object取值shape/connector/group/picture绝不从路径外观推断对象种类data-pptx-partgeometry是隐藏 carrier 路径作为 frame、基础 fill/line/effect、预设/自定义几何和对象身份的唯一原生导出权威data-pptx-preview-sha256用于检测可见预设路径或油漆的编辑——过期的 preview 会让质量检查/导出停止而不是静默复用旧的原生元数据data-pptx-effect-statusunsupporteddata-pptx-effect-reason记录为何某个源对象的效果无法在不改变语义的前提下进入注册映射——检查器与导出用记录的原因停止这些属性是诊断信息而非效果负载。从源码结构看这类渲染中性元数据 可见预览路径 哈希锁的拆分为的是实现无损往返导入时完整保留原生语义镜像/往返时精确恢复普通页面编写时不受干扰。3.5 编写的原生 PowerPoint 预设条件契约新 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只有在defs中已存在一个直接页面级 svg-effects.md §6.4 滤镜定义时才能追加。从 preset_shape_svg.py 的 CLI 可以确认完整命令面list--search、--grouped、describe--compact、--frame、--adjust、render、render-batch--input。native-shape-authoring.md 还强调多对象选择后应使用render-batch --input -让多个独立片段在一次 stdout 往返中被验证并发射--frame x y w h位于片段插入的坐标空间g transform内的 group-local。硬规则——仅助手可写元数据绝不手写或编辑已编写的预设元数据或注册表路径当 preset、frame、adjustment、fill、stroke、stroke width 或滤镜引用发生变化时重新生成整个片段需要自由轮廓编辑时则替换为普通 SVG。助手只接受none或六位纯色 HEX 油漆、可选通道不透明度、描边宽度、cap、join 和一个仅形状滤镜渐变、图案和其他处理保持普通 SVG。文本永远在原子片段之外。检查器与导出器会从元数据重渲染每一个片段并在任何漂移时 fail-closed机器契约、模板所有权规则与保真度边界见 svg-contract.md §1.5。保真度边界未更改的编写片段是一个Native-stable的p:sp或p:cxnSpv1 只创建未连接unconnected的p:cxnSp不接收手写端点/site 元数据actionButton*预设只映射视觉几何绝不发明连接附件、动作行为、导航目标或超链接。4. 条件兼容映射§24.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 属性。契约文档 §2.1 给出了逐元素/逐表面的完整属性清单与内联几何识别表并明确style、class、选择器规则、外部样式表和导入样式依旧禁止PPT Master不计算 CSS 级联或自定义属性根画布权威始终是viewBox。4.2 组不透明度§2.2默认——后代 alpha可保留兼容组不透明度把 alpha 放在受影响的 descendant 油漆、文本 run、图片或受支持效果上。g opacity仍然被接受Approximate乘入后代仅保真度告警因为 DrawingML 没有孤立的组 alpha 模型。契约文档 §2.2 补充嵌套组/子 alpha 相乘--native-charts-and-tables会拒绝透明原生表格/图表标记新svg_output/改为把 alpha 放在受影响的后代上。5. 画布格式速查与页面契约§3–§45.1 画布格式§3使用已经锁定的 canvas id 和精确 viewBox。格式选择归 canvas-formats.md 所有核心标准只负责该画布上的 SVG 一致性。无锁的 quick-generate.md profile 用它的第一个 SVG 建立画布之后每一页必须使用完全相同的 viewBox。canvas-formats.md 的注册格式速查ID格式尺寸viewBox比例用途ppt169PPT 16:91280x7200 0 1280 72016:9商务演示、会议、现代设备ppt43PPT 4:31024x7680 0 1024 7684:3传统投影仪、学术演讲xiaohongshu小红书1242x16600 0 1242 16603:4图文分享、知识帖moments微信朋友圈/IG1080x10800 0 1080 10801:1方形海报、品牌展示storyStory/TikTok1080x19200 0 1080 19209:16竖版故事、短视频封面wechat微信公众号头图900x3830 0 900 3832.35:1公众号文章封面banner横版横幅1920x10800 0 1920 108016:9Web 横幅、数字屏a4A4 打印1240x17540 0 1240 17541:sqrt(2)打印海报、传单自定义画布同样使用0 0 W H正整数像素同一个导出中的所有页面与内部 Layout 原型共享同一数值画布且必须在 PowerPoint 支持的幻灯片尺寸范围内每边 914,400–51,206,400 EMU约 96–5,376 SVG px。注意ppt169精确等于1280x720同比例的画布如banner是不同的坐标系。画布权威新编写写viewBox0 0 W H正整数像素来自锁或quick-generate的第一个 SVG所有页面与一次构建中的 Layout 原型共享它可选的根width/height永不能覆盖它根svgtransform 被禁止。导出在1 SVG px 9,525 EMU处量化一次。5.2 完整页面设计契约§4.0关注点要求可见幻灯片结果完成的svg_output/slide.svg必须包含该幻灯片所需的全部可见文本、图片、形状、图表、图表/表格 fallback、背景与模板派生布局元素。外部视觉资产仅在 SVG 显式引用时有效。模板/控制输入模板、design_spec.md、spec_lock.md只指导编写页面 SVG 完成后不得依赖它们追加可见元素。PPTX 翻译导出器可以把已表示的 SVG 内容映射为 DrawingML/原生对象并把已表示元素去重进 Master/Layout/Slide parts绝不允许发明 SVG 中不存在的可见幻灯片内容。排除的包行为演讲者备注、动画、转场、旁白音频、PPTX 关系、直接原生 PPTX 工作流各自独立持有不属于 SVG 页面设计契约。硬规则——页面设计闭合最终页面 SVG 是完整的但不拥有整个 PPTX 包。它的普通内容与 SVG-first Chart/Table 标记是权威对data-pptx-native-authorityjson内联 JSON 是权威可见子树是派生的、可能近似的预览——权威永不移动到 sidecar。5.3 语义 SVG 标记契约§4.1语义标记是最小编译器提示平面页面声明一个根data-pptx-page-role省略 Master/Layout/layer/placeholder 标记结构化页面从编写开始就携带最终根身份、layer atoms、slots 与原生对象元数据并省略data-pptx-page-role。只在没有专用标记能表达页面框行为时才使用带稳定id的data-pptx-role。普通可见内容保持为 SVG 属性/文本词汇归 semantic-svg.md 所有。字体可移植性先解析显式的用户/模板交付目标否则默认 Windows Microsoft PowerPointlocale 跟随 deck 主语言。导出的拉丁/East Asian 字体必须在目标上已安装或被批准。编写宿主机的字体只影响 SVG 预览与测量绝不能选择 PPTX 字体本地对应字体只可作为保留相同导出分辨率的预览尾preview tail。font-face仍被禁止字体族选择属于规划角色plan-core.md §6.2Default 与 Quick 共享。图标占位符use>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），仅供参考