ppt-master 的 PowerPoint 功能 ↔ 项目 SVG 映射指南:可编辑 PPTX 导出的能力边界与保真度契约

原创2026-10-12 11:22:141,961 阅读
文章标签:人工智能AI 应用AI 技能语音图像处理媒体生成

ppt-master 的 PowerPoint 功能 ↔ 项目 SVG 映射指南:可编辑 PPTX 导出的能力边界与保真度契约

本文是 ppt-master 项目的核心能力地图:它以 PowerPoint 用户视角回答一个问题——每一项 PowerPoint 功能,在项目 SVG 中由什么表达承载,导出成 PPTX 或从 PPTX 回导时能保留什么、归一化为什么、何时必须烘焙成图片。读完本文,你将掌握项目规范化 SVG 与 DrawingML/PPTX 包语义之间的完整映射表、七档保真度术语(Native-stable / Native-normalized / Approximate / Bake-required 等)、flat 与 structured 两种包结构路线的边界,以及容错导入与 --strict 严格模式的差异,从而在编写 SVG 页面或排查导出/导入异常时准确判断"哪些能做、哪些做不到、边界在哪"。

目的与权威边界

这份《PowerPoint 功能 ↔ 项目 SVG 映射指南》(源文档:docs/powerpoint-svg-mapping.md,中文版见 docs/zh/powerpoint-svg-mapping.md)是一份公开的能力与导入行为映射表,而不是第二份生成 SVG 语法规范,也不承诺转换任意 SVG 或任意 OOXML。它有明确的权威分层:

  • 规范生成合同由 shared-standards.md 路由到拆分权威集(核心合同在 shared-standards-core.md,条件模块按路由表按需加载);
  • 生成语法出现差异时,以适用模块为准;
  • PPTX 导入的容错模式与用户可见降级由本文 §12 与 转换命令文档 负责,精确 parser 行为始终以实现代码为真值;
  • 本指南未列出的功能,不会被默认为受支持。

主路线编译的是项目规范化 SVG(project-canonical SVG),而不是通用浏览器 SVG,其链路为:

PowerPoint 意图
    ↔ 项目规范化 SVG 或显式 sidecar
    ↔ DrawingML / PPTX 包语义

有些 PowerPoint 功能没有诚实的 SVG 等价表达。对于这些功能,映射表会明确标为 sidecar/打包层功能、直接 PPTX 保留功能或不支持,而不是强行塞进装饰性 SVG metadata——这正是"可以给 Agent 与 LLM 引用的诚实边界"所在。

如何阅读映射表:七档术语与基数关系

每行只对应一项 PowerPoint 能力。映射的基数不一定是一个对象对一个对象:一个 SVG 文本节点可能生成多个 PowerPoint run,一个原生图表 marker 组可能收敛为一个 p:graphicFrame,一个导入的 PowerPoint 对象也可能重建为多个 SVG 元素。表头的保真度术语含义如下:

术语 含义
Native-stable 在文档化边界内,导出使用对应的可编辑 DrawingML 属性或对象。
Native-normalized 导出结果仍可编辑,但源表达会被归一化为等价的 DrawingML 结构。
Approximate PowerPoint 没有完全对应的能力;效果具有实质意义时必须复核生成的 PPTX。
Bake-required 必须预渲染为图片,或使用受支持的显式几何重建。
Sidecar/package 该能力属于项目 sidecar 或 PPTX 打包器,而不是 SVG 页面设计。
Direct preservation 直接 PPTX 工作流可以保留源 OOXML;主 SVG 编译器不重建它。
Unsupported 主生成路线没有已登记映射,不得猜测。

下文中的"回导"(import)是指 PPTX-to-SVG 路线生成的语义投影,不是恢复原始 SVG 语法或补造缺失设计意图;它不承诺恢复原始 <defs> 图、<use> 结构、path 命令或 <tspan> 排版。

值得强调的是:映射表的基数并非一一对应,同一保真度术语在不同功能上代表不同深度的承诺,阅读时务必以"校验边界"列为准。

1. 演示文稿、幻灯片与坐标模型

PowerPoint 功能 项目表达 PPTX 结果 回导与保真度 校验边界
演示文稿页面尺寸 根 SVG viewBox="0 0 W H",通过项目画布合同选择 演示文稿宽高;96 DPI 下 1 SVG px = 9,525 EMU Native-stable;回导的自定义 PPTX 尺寸可使用兼容的正小数 数值必须有限、原点为零且尺寸为受支持的正值;所有公开页和内部 Layout 原型必须匹配锁;禁止根 transform
幻灯片 一个完整的 svg_output/<slide>.svg 页面 一个 p:sld 及其 relationships 重建为一张完整 SVG 页面 SVG 是可见页面权威;备注和包行为单独承载
对象位置与尺寸 SVG 绝对坐标与元素边界 a:xfrm 偏移和范围 经坐标换算后为 Native-normalized 数值必须有限,并使用已登记坐标语法
Z 顺序 SVG 源码顺序,由后到前 PowerPoint shape tree 顺序 按 shape tree 顺序重建 不得依赖浏览器专属堆叠行为
旋转、缩放、平移与镜像 受支持的 SVG transform 形式 DrawingML transform 或归一化几何 Native-normalized;matrix 可能被分解 已登记 transform 合同以外的倾斜与错切不可接受
主题颜色与字体 Default 使用 spec_lock.md 锚定的稳定角色;Quick 在当前上下文维持临时设计锚点,但不持久化 lock Default 派生包内 Theme,并在精确匹配锚点角色时保留 theme token,否则写直接 DrawingML 值。Flat Quick 使用转换器默认 Theme 脚手架;structured Quick 在工作区提供时保留逐 Master 源 Theme,并从语义 slot carrier 推导 Master 标题/正文字号默认值;SVG 页面颜色与字体仍写成直接值 已登记角色与直接值为 Native-stable Default 校验 lock 对齐,Quick 跳过该比较;两者都拒绝非法值;字体可移植性与目标系统可用性仅作提示
PowerPoint 包身份 spec_lock.md 结构声明与打包器 Presentation、Master、Layout、relationship 与 content type 注册 从包结构读回,不从页面外观推断 最终包读回必须与声明的 roster 一致

坐标换算的核心事实是 1 SVG px = 9,525 EMU(96 DPI 下),导出时一次性量化。受支持的画布格式定义在 canvas-formats.md:包括 ppt169(1280x720)、ppt43(1024x768)、xiaohongshu(1242x1660)、moments(1080x1080)、story(1080x1920)、wechat(900x383)、banner(1920x1080)、a4(1240x1754),均使用 viewBox="0 0 W H" 的正整数像素原点零起点;只有回导的自定义 PPTX 尺寸才接受小数画布作为兼容输入。根 viewBox 的规范合同(禁止根 transform、所有页面共享同一数值画布)见 shared-standards-core.md §4.1。

2. Master、Layout、背景与占位符功能

路线边界:flat 与 structured 是两条互不迁移的路线

映射表先划出最重要的边界:自由生成与 brand-only 项目在主 SVG 流程中从规划到导出始终使用 pptx_structure.mode: flat;flat 不是等待导出器自动升级的临时状态。即使多个页面出现相同 Logo、页脚或排版,导出器也不得据此切换到 structured,不得自动提升到 Master/Layout,不得推断占位符或去重。若输出需要可复用的原生 Master、Layout 或占位符,Step 3 必须消费一个已校验的 deck/layout 模板工作区;没有该工作区时,先走 create-template 工作流,再返回主流程。flat 导出创建的最小 Master 和 Blank Layout 只是 PPTX 格式必需的包结构,不是从页面总结出的设计母版。保留原设计并向原始 PPTX 填充新内容时,走 edit-native-pptx 工作流。

关键映射行

PowerPoint 功能 项目表达 PPTX 结果 校验边界
自由设计演示文稿结构 pptx_structure.mode: flat;页面内容保持 Slide-local 一个干净的项目 Master 和一个 Blank Layout,已表达对象留在 Slide 禁止编写 Master/Layout/layer/placeholder metadata
基于模板的演示文稿结构 pptx_structure.mode: structured 加显式 Master/Layout/页面分配 声明的 p:sldMaster、p:sldLayout、注册与 Slide 父子关系 导出器绝不猜测 Master、Layout 或占位符拓扑
幻灯片母版 根 Master 身份加原子级 data-pptx-layer="master" 对象;一个校验通过的 compact authored-preset <g> 计为一个 semantic atom 可复用 Master part 与 picker 身份 Master atom 必须为直接、稳定对象,并在所属页面间一致
幻灯片版式 根 Layout 身份加原子级 data-pptx-layer="layout" 对象 某个 Master 下的可复用 Layout part 仅当固定 atom 和 slot 合同完全相同时才复用 Layout key
回导的继承图形可见性 分层分析记录规范化源布尔值;物化后的 structured mirror 在根写入精确小写的 data-pptx-show-inherited-shapes 与 data-pptx-show-master-shapes 写入 p:sld@showMasterSp 与 p:sldLayout@showMasterSp 省略即 true;使用同一 Layout key 的页面必须使用相同 Layout 值
Slide 背景填充(structured 以外) 第一个合格的全幅 <rect>(可直接位于根下或位于简单单子组中),使用已登记纯色、线性/径向渐变或预设图案填充 Slide 的原生 p:bg transform、filter、clip、圆角、可见 stroke 或未映射 fill 会阻止提升
structured 模式的背景填充 声明结构层中一个直接铺满画布的纯色 <rect> Master、Layout 或 Slide 层级的原生 p:bg 显式 scoped background 所有权只支持纯色
图片背景 声明在 Master/Layout 层的普通项目 <image>,或 Slide-local 内容 所属 part 上的可编辑 p:pic image 元素绝不提升为 p:bg
标题/副标题/正文占位符 含一个文本 carrier 的结构化 slot 组 title / subTitle / body 类型 p:ph carrier 数量、边界、类型与有效 index 必须与 Layout 合同一致
日期、页脚与页码占位符 结构化文本 slot dt、ftr 与 sldNum 类型 p:ph 占位符 index 必须唯一且合法
图片/图表/表格/媒体/通用对象占位符 含一个匹配载体的结构化 slot pic / chart / tbl / media / obj 类型 p:ph 图表表格占位符需要 --native-charts-and-tables;media 不合成视频或音频
空文本占位符 空或仅空白的已标记 text carrier 使用合法 1 pt 下限的不可见 U+200B run 不得添加假破折号、小于 1 pt 的文字或与背景同色的可见字符
页面角色(cover/content/ending) flat 路线根 data-pptx-page-role 编译提示 路由/校验提示;不是 PowerPoint 原生页面类型 structured 页面改用显式 Master/Layout 身份
幻灯片节与自定义放映 无 SVG 映射 主生成路线不编写 不得编码为可见 metadata

精确的结构 metadata 与 slot 语法由 PPTX 结构接口 拥有,包括根身份属性(data-pptx-master、data-pptx-layout 及对应 name)、层 atom(data-pptx-layer="master|layout|slide")、slot 组(data-pptx-placeholder + data-pptx-bounds + data-pptx-carrier="true"),以及复合 object slot 的 data-pptx-binding="proxy" 降级。语义 marker 的完整词汇见 semantic-svg.md:data-pptx-role 只用于 background、decoration、header、footer、logo、watermark、chrome、page-number 等无专门 marker 的结构角色,且"专门 metadata 优先"——Master/Layout/placeholder 结构与 data-pptx-replace-with 原生替换 marker 绝不重复用 data-pptx-role 表达。

从源码看,structured 校验会拒绝缺失或与 lock 不匹配的根身份、普通 Master/Layout <g>、嵌套结构 marker、无正 bounds 或非单一兼容 carrier 的 slot 等(semantic-svg.md §5 验证与迁移)。

3. PowerPoint 形状与绘图对象

PowerPoint 功能 项目表达 PPTX 结果 回导与保真度 校验边界
矩形 <rect> 可编辑 p:sp 与 a:prstGeom prst="rect" Native-stable;可能时回导为原语 仅使用已登记 paint、line 与 transform 属性
对称圆角矩形 圆角半径相等且受支持的 <rect> a:prstGeom prst="roundRect" 加 adjustment Native-stable 不对称圆角按 freeform 行处理
圆或椭圆 <circle> 或 <ellipse> a:prstGeom prst="ellipse" Native-stable bounds 和 radius 必须有限且为正
直线 <line> 可编辑 line/freeform shape Native-normalized 拒绝浏览器专属 line 效果
带箭头的线 带已登记 triangle、stealth、arrow、diamond 或 oval 起点/终点 marker 的 <line> 或受支持 path 原生 DrawingML 线首/线尾 Native-normalized;marker 大小为近似 marker 定义必须遵循条件 marker 合同
原生连接符 带 connector metadata 和直接可见 path 的项目创作 compact preset 组 p:cxnSp 导入 connector 保留源拓扑往返所需的 expanded 证据 已登记 preset/connector schema 内为 Native-stable
任意多边形 <path> 带 a:custGeom 的 p:sp 导入自定义几何重建为 path Native-normalized;SVG arc 转为三次曲线段
已物化的合并形状结果 shape_boolean_svg.py 输出的普通 <path>;"拆分"返回多个同级 path 每个返回 path 对应一个带 a:custGeom 的 p:sp Native-normalized;回导为最终自由形状几何,不保留可重放的操作历史 不输出 clip、mask 或显式 fill rule
多边形/折线 <polygon> / <polyline> 闭合/开放自定义几何 Native-normalized points 必须有限且合法
PowerPoint 预设形状 由 registry 生成的 compact <g>,承载 preset 意图与基础 paint,可选直接引用一个已登记的阴影/发光 filter,并直接包含可见 <path> 子元素 一个可编辑 preset p:sp,最多一个原生效果写入 p:spPr/a:effectLst preset 身份与 adjustment 可以经导入/导出保留 质检与导出动态重渲染 registry;创作型 preset 不含隐藏 carrier、preview wrapper 或已存储 preview hash
导入的预设形状 含隐藏原生 carrier、可见 preview 证据与新鲜度 metadata 的 expanded 导入/往返组 payload 合法且未改变时重新接入 preset 在导入合同内为 Native-stable 不支持的 preset 保留为显式诊断 fallback
动作按钮形状 compact authored actionButton* preset 组 仅生成可见 preset 几何 形状几何可往返 不创建单击动作、导航目标或超链接
组 <g> p:grpSp,或对特殊 carrier 执行文档化的 flatten/collapse 分组内容可重建为 <g> 结构 atom 与 placeholder 合同优先于普通分组
复用本地 symbol 已登记的同文档 <use> 合同或项目 icon placeholder 在生成 Slide 中展开为可编辑 shape 回导不承诺恢复原 symbol 图 拒绝外部 use、不受支持的 symbol 能力和结构 metadata 复用
图标 / 导入向量 由项目图标管线解析的 <use data-icon="library/name">;create-template 导入统一使用 imported/<name> 展开后的可编辑矢量原语/组 重建几何,不恢复原图标库引用 标识区分大小写;导入素材仅在工作区根目录 icons/imported/<name>.svg 保留一份
SmartArt / DiagramML 无主 SVG 对象映射 主重设计路线可以用普通 shape 重建语义 原生/模板路线中为 Direct preservation,否则为 preview 或显式 fallback 不得将装饰性组标记为原生 SmartArt

项目创作 preset 有意采用 compact 表达,而 PPTX 导入继续保留无损往返裁决所需的 expanded 证据。preset 选择与创作行为见 native-shape-authoring.md,其核心是两条确定性 helper:

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(一个 §6.4 filter id,已在 <defs>)
python3 ${SKILL_DIR}/scripts/shape_boolean_svg.py render <svg-file> \
  --operation subtract --source body --source cutout --id result

render 输出一个 compact 原子 <g data-pptx-authoring="preset">(preset、frame、adjustment、基础 paint 各写一次,registry 生成的可见 path 为子元素);shape_boolean_svg.py 消费闭合 path/polygon/rect/circle/ellipse、一个未过滤 compact preset,或受支持的横向直接 <text>(文本转为字形几何),union/combine/intersect/subtract 各输出一个 <path>,fragment 输出 <id>-1、<id>-2……结果使用 nonzero winding,永不输出 fill-rule、clip-rule、clip-path、mask 或 Merge Shapes metadata——因为 PPTX 存储的是最终自由形状而非可重放的操作历史。线段箭头 marker 的精确机器合同在 svg-contract.md §1.1:只有 triangle(3 顶点闭合多边形)、stealth(简单凹 4 顶点闭合多边形)、arrow(开放 3 顶点 path)、diamond(简单凸 4 顶点闭合多边形)、oval(一个 <circle>/<ellipse>)五种可映射,且三角形/箭头/菱形/椭圆用与父线条同色的填充、开放箭头用 fill="none" + 同色 stroke。

4. PowerPoint 文本功能

PowerPoint 功能 项目表达 PPTX 结果 回导与保真度 校验边界
文本框 <text> 带 p:txBody 的可编辑 p:sp 重建为 <text>,需要时含 <tspan> 文本必须是良构 XML,且仅使用已登记属性
行内混合格式 不带定位的 <tspan> run 同一文本框内的 DrawingML run Native-normalized;已登记 run 格式仍可编辑 改变文本框几何的定位可能会拆分结果
作者断行与多段落文本 一个 <text> 加直接定位的 <tspan> 行 默认在一个禁用自动换行的文本框中保留作者断行;语义段落边界仍为 a:p Native-normalized --reflow-text 允许 PowerPoint 重排;--no-merge 为每一视觉行生成一个形状
有意义的文本空白 <text>/<tspan> 上精确的 xml:space="default" 或 xml:space="preserve" 归一化或保留的 U+0020 文本 Native-normalized;保留行内 run 所有权 LF/TAB 转为空格,default 跨 run 折叠,preserve 全部保留;CSS white-space 不在映射内
字体 解析为 spec_lock 结构角色或可安全导出的上下文选择的规范 font-family 直接 typeface 或已登记 theme font 在安装字体/替换边界内为 Native-stable 报告不可用或不安全的字体;安全的上下文字体只记录信息
字号 有限、无单位的 SVG px,例如 font-size="24" DrawingML 百分之一磅;1 px = 0.75 pt 单位转换后为 Native-stable 生成创作只使用无单位 px;已登记历史单位是 warning 兼容输入;DrawingML 下限为 1 pt
字重 <text>/<tspan> 上已登记的 font-weight DrawingML 常规/粗体 run 开关 Native-normalized;数值字重折叠到布尔边界 精确取值语法与别名属于 svg-effects.md §6.7
斜体、下划线与删除线 已登记的 font-style / text-decoration DrawingML 斜体、下划线与删除线 run 属性 已登记 token 为 Native-stable 拒绝未知 token
普通文本上标与下标 <tspan> 上精确的直接属性 `baseline-shift="super sub"` 可编辑普通文本 a:rPr@baseline,取值为 30000 / -25000;不会自动缩小字号 前向导出为原生能力;PPTX-to-SVG 不在可见 SVG 中重建 baseline shift
纯色/渐变文本填充与透明度 规范纯色/渐变 fill 加 run alpha DrawingML run fill 与 alpha Native-normalized 使用语义 alpha 通道
图片或纹理文本填充 <text> / 不带定位的 <tspan> 的 fill 引用一个带注解的单图 pattern 可编辑 DrawingML run a:blipFill,使用原生 stretch 或 tile 正向导出为原生能力;stretch 为 Native-normalized,tile 的缩放/相位可能归一化;回导暂不重建该填充 要求 data-pptx-text-image-fill="stretch|tile"、一个直接有效的 <image>,且 <image> 不带 clip-path/filter/mask/transform
文本轮廓 文本上已登记 stroke DrawingML run outline Native-normalized 轮廓承载精细视觉意义时需复核
文本对齐 已登记的 text-anchor 与段落语义 段落对齐加归一化文本框位置 Native-normalized 不支持 run 级锚定与浏览器 baseline 启发式
文本框垂直对齐 无规范生成 SVG 控制;生成文本框使用顶部对齐 顶部对齐的 DrawingML text body 导入的垂直锚定可能被归一化 不得从 SVG baseline 推断垂直对齐
东亚竖排文字 没有已登记的生成 SVG 控制;writing-mode 为非法属性 主生成路线不创作 a:bodyPr@vert 回导把 eaVert、vert、wordArtVert 与 wordArtVertRtl 归一化为正立字形逐字堆叠的 SVG 文本 手工堆叠字形不会产生原生标点朝向、自动续排或多栏行为
字符间距 已登记 letter-spacing DrawingML 字符间距 Native-normalized 拒绝不受支持的 CSS 排版、超出 DrawingML 范围的间距及导致非正 advance 的负字距
项目符号段落 已识别的前导项目符号形式 原生 DrawingML bullet Native-normalized 仅提升已登记 bullet 语法
旋转文本 文本对象上受支持的 transform 旋转文本 shape Native-normalized 倾斜文本与浏览器专属 transform 不受支持
文本阴影或发光 受支持 filter/effect 合同 一个原生外阴影或发光 Approximate 仅支持一个已登记效果图
WordArt、文本变形或沿路径文本 装饰文字使用已准备的图片资产,或用普通 <text> 作为可编辑兜底 图片或普通文字;不新建原生 WordArt Direct preservation 或 Bake-required 不登记任何生成 SVG 的 WordArt/变形/路径文字属性

文本是"可编辑性"承诺最密集的区域。从 shared-standards-core.md §4.2 看,"一个可编辑 PPT 文本框 + 混合格式或长段落"的规范形式是:每个逻辑段落一个 <text>、行内 run 用不带定位的 <tspan> 子元素;首行直接写字面文本,后续行用重复父 x 的正相对 dy 定位 <tspan>。同时存在一个硬性字符合同:SVG 严格 XML,& < > 必须用 &amp; &lt; &gt;,而 — © → 等排版字符必须写原始 Unicode 而非 &mdash; 这类 HTML 命名实体。生成创作是 fail-closed 的:未知 inline 视觉属性与未映射条件合同是 error,已记录兼容拼写是 warning(见 svg-contract.md §1)。

文本图片/纹理填充是一个值得注意的亮点:在 <defs> 中定义一个单图 <pattern> 并标注 data-pptx-text-image-fill="stretch"(或 "tile"),导出为 PowerPoint run 图片填充且文字保持可编辑——图形字只显示图片、填充必须读作单一值(近均匀纹理/材质),见 svg-effects.md §6.3。

5. PowerPoint 图片功能

PowerPoint 功能 项目表达 PPTX 结果 回导与保真度 校验边界
图片 具有显式正尺寸且只含一个项目资产或图片 data URI 源的 <image> p:pic、media part 与 relationship 重建为 <image> 源必须可解析、采用已登记格式,并包含与 MIME/扩展名相符的可解码字节;非法 frame 或媒体在封装前失败
显式复杂 SVG 图片 create-template 归一化期间,由 extract_svg_pictures.py 从一个精确 <g id> 生成紧边界、自包含 .svg,再以直接 <image> 引用 一个以 SVG media 为源的 p:pic 回导为一个 <image>;内部 path 不会提升成独立 PowerPoint 形状 仅允许 standard/fidelity 显式选择;任何导入、重复检测、Master/Layout、finalize 与 export 都不得自动把组转换成这种表达
图片拉伸填满框 preserveAspectRatio="none" 原生拉伸 picture frame Native-stable none 必须单独出现;它会有意改变源宽高比
图片裁剪填充 一个已登记对齐值加显式 slice 原生 a:srcRect 裁剪 源尺寸可读时为 Native-stable 对齐值区分大小写;未知模式与额外 token 为 error
图片适应框 省略时使用默认值,或一个已登记对齐值加显式 meet 原生 fitted picture frame Native-normalized 仅写对齐值是兼容输入,Checker 会给出规范化建议
图片透明度 原子 image opacity 原生 a:alphaModFix Native-stable 值必须有限,并在可接受 opacity 语法内
图片阴影或发光 未裁剪 <image> 直接承载一个已登记效果 filter;裁剪图片或导入 crop 使用精确单图片外层载体 原生 p:pic/p:spPr/a:effectLst Approximate;单一效果以一个可编辑图片往返 filter 与 clip-path 不得同挂一个 <image>;普通组 filter、效果 DAG 与多个独立效果仍不支持
图片裁成形状 作用于 image/crop wrapper 且只含一个 SVG 命名空间形状的已登记 clip-path picture preset 或 custom geometry Native-normalized circle/ellipse/rect preset 必须覆盖完整图片 frame;局部或偏移轮廓使用 path/polygon;不接受任意 mask 或依赖绕组规则的轮廓
导入的裁剪图片 导入器产生的精确 SVG 命名空间嵌套 crop wrapper,在可视根/g 树中内含一个直接 unit-frame image 重新导出为原生 signed a:srcRect crop 合同内为 Native-stable,包括负裁剪值 拒绝通用嵌套 viewport、额外可视子元素、不可表示的 crop window 等
图片重着色、艺术滤镜、模糊或复杂 mask 无通用创作映射 使用受支持 overlay 重建或预渲染 Bake-required 未登记 SVG filter 和 blend mode 违反主合同

图片裁剪到形状的机器合同在 svg-contract.md §1.2:clip-path 仅在 <image> 上映射,指向 <defs> 中恰好一个直接 SVG 命名空间形状子元素(<circle>/<ellipse>/<rect>/<path>/<polygon>),不允许 clip-rule/fill-rule;circle/ellipse/rect 必须恰好覆盖完整图片 frame 并成为 preset 图片几何,path/polygon 成为 frame 内的 custom geometry——因此"局部或偏移轮廓"必须用 path/polygon。图片的 preserveAspectRatio 处理在 svg-effects.md §6.5 有实现表:slice → 原生 srcRect(Native-stable)、meet → fitted frame(Native-normalized)、none 单独出现 → 原生拉伸 frame。

6. PowerPoint 填充、线条与效果功能

PowerPoint 功能 项目表达 PPTX 结果 回导与保真度 校验边界
无填充 fill="none" a:noFill Native-stable 生成 SVG 使用小写规范拼法
纯色填充 规范 fill="#RRGGBB",可以是具名 lock 锚点或上下文页面颜色 a:solidFill;当锚点角色可精确复用时使用 theme token Native-stable 兼容颜色拼法可产生 warning;格式错误会失败
填充透明度 不透明 fill 加 fill-opacity 原生 alpha Native-stable 生成值为 0 到 1 的有限无单位数
线性渐变填充 <defs> 中已登记 <linearGradient> 原生 a:gradFill Native-normalized stop、坐标、transform 与引用必须遵循封闭合同
径向渐变填充 已登记 <radialGradient> 可偏心单点焦点的圆形 DrawingML 渐变 Approximate;有效焦点可往返,外圆中心与半径会归一化 有效焦点必须落在中心 (0.5,0.5)、半径 0.5 的规范圆内
图案填充 带注解的项目 pattern 定义 原生 a:pattFill Native-normalized 仅支持已登记 PowerPoint 预设 pattern
无轮廓 stroke="none" 或已登记线缺省 a:ln 内的 a:noFill Native-stable 不得用零线宽模糊 CSS 模拟缺省
实线轮廓 已登记 stroke 与宽度 原生 a:ln Native-stable 宽度与 paint 必须使用规范单位/语法
复合轮廓线 无已登记的单一 SVG stroke 表达 显式几何替代或烘焙资产 复合线身份为 Bake-required 容错回导省略并报告;严格回导拒绝非 sng 的 cmpd
内侧对齐轮廓 无已登记的普通 SVG stroke 表达 显式内缩几何或烘焙资产 精确轮廓对齐为 Bake-required 严格回导拒绝非 ctr 的 algn
图案/图片/组派生轮廓 paint 无已登记的线条 paint SVG 映射 显式几何替代或烘焙资产 Bake-required 严格回导拒绝该输入,不虚构纯色线
transform 下的轮廓缩放 精确的 vector-effect="none" 或 vector-effect="non-scaling-stroke" 选择被解析为原生线宽 Native-normalized 拒绝其他取值;生成拼法必须精确且为小写
虚线或点线轮廓 已登记 dash array 预设或自定义 DrawingML dash Native-normalized 拒绝不支持的 dash 语义
线端与连接样式 已登记 cap/join 值 原生 line cap/join 属性 固定 join 合同内为 Native-stable 回导仅接受一个 join;miter 必须精确使用 lim="800000"
线条箭头 已登记起点/终点 marker 原生 head/tail end 属性 marker 大小为 Approximate 仅 triangle、stealth、arrow、diamond、oval 遵循条件 marker 合同
外阴影 一个受支持 shadow filter 图 a:effectLst 中的原生外阴影 Approximate;仅当非零偏移可稳定分类时才重建 outerShdw 非中性的 sx/sy/kx/ky、旋转对象随形旋转、零偏移均产生阻塞诊断
发光 一个受支持 glow filter 图 a:effectLst 中的原生发光 Approximate;单一来源发光保持已登记半径换算 发光承载语义强调时需复核
导入的文字 run 效果 逻辑 shape 上未变更的 metadata[data-pptx-part="txbody"] p:txBody 内原始的 slide-local 原生 run 效果 仅在原始 payload 仍可用时为 Native-stable 不是公开创作语法;表格单元格 run 效果还会禁用原生 Table 替换 payload
整个对象透明度 原子元素 opacity alpha 分发至受支持原生通道 Native-normalized 除非整个原子对象需要淡出,否则优先通道专属 alpha
组透明度 兼容 <g opacity> 后代归一化近似 Approximate,并产生 warning 生成 SVG 应优先后代 alpha
内阴影、柔化边缘、倒影、模糊、湍流、混合模式或任意 mask 无已登记原生映射 显式几何替代或栅格资产 Bake-required;回导保留基础对象并对不支持效果产生阻塞诊断 已处理的对象效果不能被静默省略

阴影/发光的创作形式是 <defs> 中一个直接 filter(feDropShadow,或 blur + flood + composite + merge 图),直接以 filter="url(#id)" 挂在 <rect>、<circle>、<polygon>、<image>、<path>、<text> 或 helper 创作的 preset 组上:有意义的非零偏移 → 一个原生外阴影,零偏移(即便 feDropShadow dx="0" dy="0")→ 一个原生发光。完整 filter 图示例与"每页一个光源"的默认(dx="0"、dy="4"–dy="8",光从上前方来)见 svg-effects.md §6.4。线条 dash 映射为五个预设(4,4 / 6,3 dash、2,2 sysDot、8,4 lgDash、8,4,2,4 lgDashDot)或一个自定义 dash gap 对;cap 为 butt/round/square,join 为 miter/round/bevel,见 svg-effects.md §6.6。

7. PowerPoint 表格

PowerPoint 功能 项目表达 PPTX 结果 回导与保真度 校验边界
视觉绘制表格 普通 SVG shape、line 与 text 相互独立的可编辑 PowerPoint shape 保真度遵循各组件对应行 它不是原生表格,也没有 PowerPoint 表格编辑模型
PowerPoint 原生表格 一个带 ppt-master.semantic-table.v2 JSON metadata 和可见 fallback 的 <g data-pptx-replace-with="table"> 启用原生 Chart/Table 替换时产生含 a:tbl 的 p:graphicFrame 导入时把重复的单元格、段落和 run 格式归纳为默认值及命名单元格样式;导出时在内存中展开 metadata 必须形成已登记矩形 schema;拒绝无版本 payload;需要 --native-charts-and-tables
合并表格单元格 规范原生表格 merge metadata 原生水平/垂直合并语义 封闭 schema 内为 Native-stable 拒绝重叠、歧义或非矩形合并
表格单元格格式 已登记原生表格单元格格式字段 原生单元格 fill、border、text 与 alignment Native-normalized 不猜测封闭 schema 以外的字段
不受支持的原生表格功能 SVG fallback 或直接源保留 保留可见 fallback,或在直接路线保留源 OOXML 显式 fallback / Direct preservation 不得临时扩展 JSON

关键事实是:PowerPoint 原生 Chart/Table 对象是可选功能(opt-in)。默认导出保留 SVG fallback,并转换为仍可独立编辑的 DrawingML shape,以保持视觉稳定;原生导出(--native-charts-and-tables)才提供对象的数据源以及图表/表格专属编辑模型,并可能归一化外观。原生表格的 JSON schema 是 ppt-master.semantic-table.v2:columns 放可选表头行、rows 放正文行,column_widths/row_heights 是相对权重;单元格可以是字符串或带 text(或 paragraphs)、fill、color、align(l/ctr/r)、valign(top/middle/bottom)、bold、font_size、padding、按边 borders 的对象;合并单元格在 anchor 上用正 row_span/col_span、被覆盖格写 {"merge_continuation": true};重复格式可归纳进 defaults.cell/defaults.paragraph/defaults.run 与命名 cell_styles。完整 schema 见 native-data-interface.md 与 native-data.md。

8. PowerPoint 图表

PowerPoint 功能 项目表达 PPTX 结果 回导与保真度 校验边界
视觉绘制图表 普通 SVG 几何与文本 相互独立的可编辑 PowerPoint shape 保真度遵循各组件对应行 没有"编辑数据"工作簿
PowerPoint 原生经典图表 一个带 <metadata type="application/json"> 已登记 JSON 数据和可见 fallback 的 <g data-pptx-replace-with="chart"> p:graphicFrame、经典 chart part 与嵌入工作簿 受支持的导入重建 fallback 加替换 metadata chart type 与数据必须匹配封闭 schema;需要 --native-charts-and-tables
原生 ChartEx 图表 具有受支持 ChartEx family 的相同 marker 接口 cx:chart part 与嵌入工作簿 受支持 family 可按语义重建 仅接受已登记 family/field 组合
图表标题、图例、坐标轴、标签与系列格式 已登记原生图表 metadata 原生 chart 属性 Native-normalized 精确字段与受支持 family 以 native-data-interface.md 为规范
图表说明、来源或脚注 replacement marker 之外的普通伴随 SVG text 图表旁边可编辑的 Slide 文本框 作为文本时为 Native-stable 不得把 Slide 文案隐藏在 chart JSON 里
已编辑 SVG fallback 与过期替换 metadata 更新后的可见 SVG 加过期 hash 默认导出保留可见 SVG;原生替换失败 显式安全行为 编译器绝不默默丢弃更新的视觉编辑
不支持的 3D 或延后图表 family SVG 绘制图表、烘焙资产或直接源保留 不猜测原生图表 fallback / Direct preservation 不支持的 alias 必须使原生校验失败

原生图表 marker 的规范示例(来自 native-data-interface.md §2):

<g id="p03-revenue-chart" data-pptx-replace-with="chart">
  <metadata type="application/json">
    {
      "x": 120, "y": 150, "width": 520, "height": 320,
      "name": "p03-revenue-chart",
      "type": "column",
      "title": "Revenue by Segment",
      "categories": ["Q1", "Q2", "Q3"],
      "series": [
        {"name": "Cloud", "values": [12, 15, 19]},
        {"name": "Services", "values": [8, 9, 11]}
      ]
    }
  </metadata>
  <!-- 可见 SVG fallback:用于实时预览与非原生导出,必须与 JSON 表达同一数据。 -->
</g>

受支持的 type 值包括 column、bar、line、area(各带 grouping)、pie、doughnut、pieOfPie、barOfPie、radar、radarMarkers、radarFilled、scatter、bubble、combo、treemap、sunburst、histogram、pareto、boxWhisker、waterfall、funnel、stock;3D alias 与 surface 不支持,exploded pie、map、heatmap、bullet、gantt 快速失败。权威分两块:SVG-first(默认) 的可见子树是设计权威、JSON 是其派生的投影,作者在可见 fallback 与 JSON 同步后通过 stamp_native_fallbacks.py --write 记录 data-pptx-fallback-sha256;JSON-first(模板/原生来源) 的 inline JSON 是权威、可见子树是近似派生的 preview(仅合法用于 data-pptx-native-authority="json" 的活动 chart/table 替换组)。data-pptx-replace-with 标记组禁止 rotate/skew/matrix,只允许 translate/scale,因为原生 frame 无法携带任意 SVG transform。

导入侧:受支持的图表组用 data-pptx-fallback-kind="source-preview|normalized|placeholder" 对可见 fallback 分类,placeholder 表示仅重建的 fallback;data-pptx-replacement-status 记录 fallback-only 导入无法提出有效替换声明的原因(详见 conversion.md)。旧 data-pptx-native*、data-pptx-visual-status 与 data-pptx-route-status 写法仍可读,但不再是规范创作格式。

9. PowerPoint 公式(LaTeX → 可编辑 OMML)

PowerPoint 功能 项目表达 PPTX 结果 兼容性 校验边界
LaTeX 输入档位 规范 marker 源不写外层定界符;也接受一对完整的 $...$、$$...$$、\(...\) 或 \[...\] 锁定的 Microsoft 365 2606 / Mac 16.110 档位中所有明确点名的输入,以及 2605 / 16.109 mhchem 档位,均编译为可编辑 OMML 档位锁定到这些 Microsoft 文档版本;产出的 OMML 保持 PowerPoint 2010+ 包目标 未知或明确不支持的输入直接失败,不把 LaTeX 字面量漏进页面
可编辑块级公式 一个带显式边界、在 <metadata type="application/json"> 中保存源 LaTeX、并含可见 SVG 预览子元素的 <g data-pptx-replace-with="formula"> 含 a14:m > m:oMathPara > m:oMath 的 PowerPoint 文本 shape 见输入档位行 矩阵、多行推导等独立高结构公式使用块级合同
可编辑行内公式 普通文本 run 中的叶子 <tspan data-pptx-inline-formula="规范 LaTeX body">preview text</tspan> 同一 DrawingML a:p 保留前后 run,并插入 a14:m > m:oMath 见输入档位行 只允许非空直接预览文本;禁止子元素、x/y/dx/dy、结构化 placeholder 归属、保留的导入 txBody 或原生替换祖先
PPTX 公式反向导入 通过校验的 m:oMathPara 变为块级 marker;通过校验的 m:oMath 保留为行内 marker 再导出时把规范化 LaTeX 编译回可编辑 OMML 对 PPT Master 自有封闭 OMML 词汇为 Native-normalized 无法恢复原 LaTeX 写法;未知第三方 OMML 产生 formula-not-reconstructed
浏览器 / 实时预览 块级 marker 内的普通 SVG 子元素,或行内 marker 的直接文本 写入原生公式时只丢弃已登记预览 原始 LaTeX 不能直接在 SVG 中渲染 预览必须表达同一公式
公式字体 块级 payload 样式,或行内文本 run 的计算样式 公式继承字号与可见纯色填充,并使用项目文本语言和 Cambria Math;局部 \color/\textcolor 覆盖继承填充,\boldsymbol/\bm 也样式化结构控制字形 PowerPoint 2010+ OMML 高结构或多行数学内容仍使用块级形式
非 PowerPoint 客户端播放 同一类原生 marker;没有图片分支 不附加兼容兜底 Keynote、WPS、LibreOffice 等客户端不在公式合同内 不宣称跨客户端显示或编辑能力

公式替换始终启用,不使用 --native-charts-and-tables;该路径不创建 formula_manifest.json、公式 PNG、media relationship 或 mc:Fallback 图片。可执行闭合集与锁定的 Microsoft 来源修订记录在 formula_profile.py(skills/ppt-master/scripts/svg_to_pptx/native_objects/formula_profile.py);pptx_to_svg.py 只对通过同一封闭校验器的 OMML 执行窄反向导入,产出的是规范化 LaTeX 而非作者原始写法,不宣称任意 Office Math 转换。

10. PowerPoint 播放与打包功能(sidecar / package)

这些能力要么从规范页面 SVG 编译,要么由表中点名的包级 sidecar 提供;当所有者一栏写的是 SVG 时,不另设 sidecar。

PowerPoint 功能 项目中的所有者 PPTX 结果 回导与保真度 校验边界
演讲者备注 notes/<slide>.md sidecar Notes Slide part 与 relationship Sidecar/package 备注不是 SVG 文本,不影响页面几何
幻灯片切换 CLI 选项或 animations.json p:transition Sidecar/package;PPTX 回导把当前注册表内的精确切换重建到 animations.json 未知效果或不精确 carrier 会失败或保留诊断;不默默 fallback 到 fade
对象动画(进入/强调/动作路径/退出) animations.json,目标为稳定的顶层 SVG group ID;effects[] 可让一个锚点拥有多条记录 根 p:timing 动画树 Sidecar/package;PPTX 回导把当前注册表内具有精确时长的记录重建到 sidecar target 与可选 trigger shape 必须唯一映射
旁白音频 audio/ 资产加 recorded-narration 导出选项 media relationship、audio carrier 与 timing Sidecar/package 必须校验资产、Slide 关联与时序
幻灯片自动换页 显式 transition timing 或旁白派生时长 advTm/换页行为 Sidecar/package 单击驱动动画与录制旁白不兼容
整体对象超链接 标准 SVG <a href="..."> 包裹一个可见元素或组 每个可点击叶子上的 p:cNvPr/a:hlinkClick,共用一个 relationship 受支持外链与 deck 内目标为 Native-stable;PPTX 回导重建 anchor 多对象卡片/按钮的间隙也要可点时,需显式加入背景形状
行内文字超链接 普通 SVG 文字中的 <a href="..."><tspan>可见文字或行内公式 marker</tspan></a> 同一 DrawingML 段落或 Office Math 叶子 run 中的 a:rPr/a:hlinkClick 受支持外链与 deck 内目标为 Native-stable anchor 不承载位置属性;嵌套链接会失败
deck 内跳转 任一受支持 carrier 使用精确的 1-based href="#slide-N" 内部 Slide relationship 加 ppaction://hlinksldjump 按最终 presentation roster 重建 缺失、越界、孤儿或歧义目标直接失败
导入形状 click 与内部 run link 并存 仅供 importer 使用的逻辑 <g data-pptx-shape-hyperlink="...">,内部仍保留标准行内 anchor 同时还原 p:cNvPr/a:hlinkClick 与 run 级 click 这一 source-only 重叠可无损运输 作者不得写该 metadata;标准 SVG 禁止嵌套 <a>
其他动作设置 无 SVG 创作映射 不创建 仅当拥有它的原生路线不改源 OOXML 时为 Direct preservation 鼠标悬停、custom show、macro/OLE/file 与任意 ppaction:// 动作不在超链接合同内
批注或审阅线程 无 SVG 或生成侧映射 不编写 仅在其他路线明确拥有时为 Direct preservation 不自动将审阅 metadata 转为可见 Slide 内容
不属于已映射功能的 relationship 无通用 SVG 逃生口 不生成 适用时为 Direct preservation 不支持任意 relationship 注入

动画 sidecar 的记录规则:对于一个目标 group,完全兼容的旧对象表示一条效果记录,非空 effects<a href="https://link.gitcode.com/i/0d8a8bf8622eb275a6642880cb88229d" target="_blank">] 表示多条记录,两种形式互斥;每条记录可独立设置 trigger、序列 order、delay、duration 与 trigger_shape,页面动画 trigger 只提供继承的 Start 值。auto、mixed 与 random 只解析通用进入效果;显式规范效果覆盖进入、强调、PowerPoint 原生动作路径预设和退出。该映射不推断段落/文字范围 build、自定义自由动作路径、原生 Chart/SmartArt build 序列或媒体播放命令。sidecar 工作流详见 [转场与动画(技术规范源为 references/animations.md)与 音频旁白。

11. 其他 PowerPoint 原生功能:明确的不支持清单

PowerPoint 功能 主路线状态 受支持的替代方案 边界
SmartArt / DiagramML 无原生 SVG 编译器映射 使用 shape 重建语义,或通过原生/模板路线保留 截图或 fallback 必须是显式的
OLE 或嵌入 Office 对象 SVG 路线不支持 直接保留或渲染 preview 不得通过 SVG metadata 制造包 relationship
视频 不支持作为 SVG 创作媒体对象 直接保留,或使用带普通受支持超链接的显式封面 media 占位符不创建视频
3D 模型 不支持 直接保留或烘焙 preview 不将浏览器 SVG 近似当作原生 3D
宏 / VBA 不支持 仅通过感知宏的直接工作流保留 普通生成 .pptx 路线不生成 VBA
任意 Office 扩展 XML 不支持 Edit Native PPTX 在所属来源对象不变时直接保留 SVG 编译器不提供通用 OOXML 透传

12. 反向映射:PPTX 到项目 SVG 与导入运行模式

导入器将受支持的 PowerPoint 语义重建为与导出相同的项目词汇:

PowerPoint 源对象 项目 SVG 重建
预设形状 受支持时重建为含原生 carrier 与可见 preview 证据的 expanded preset 组
自定义几何 <path>
文本体 <text> 与 <tspan> run/段落
受支持文字 run 超链接 包含已链接 <tspan> run 的行内 <a href>
受支持形状/图片/group 超链接 包裹重建后可见对象的规范 <a href>
同一形状同时有 shape click 与内部 run link 逻辑 <g data-pptx-shape-hyperlink="..."> transport 加规范行内 anchor
图片 <image>,或已登记嵌套 crop 表达
同时带栅格兼容预览的 SVG 图片 优先使用 asvg:svgBlip relationship 重建 <image>;仅当 SVG relationship 或 media part 不可用时才使用普通 a:blip
连接符 expanded 线/path preview 加 connector/frame/topology 证据
组 <g>
受支持原生表格/图表 可见 fallback 加原生对象 metadata
当前注册表内受支持的页面切换 规范 animations.json 记录(有效选项、精确时长、可选自动换页、受支持 WAV 声音)
受支持的精确时长对象动画序列 规范 animations.json group 记录(效果/选项、顺序、触发、时长、相对延迟、可选 trigger_shape)
不支持的 graphic frame 或 SmartArt 显式 preview、placeholder 或 unsupported 状态

这是语义投影,不是语法往返。只有 Create Template mirror 可把来源包中已验证的 Master/Layout 事实保留到新工作区;普通视觉导入不会从 Slide 外观推断可复用拓扑。

导入运行模式与错误恢复边界

pptx_to_svg.py(入口:skills/ppt-master/scripts/pptx_to_svg.py)默认采用容错导入,因为输入来自用户或第三方 PPTX;--strict 用于 parser 开发、合同核验和复现第一个源文件违规点。生成 SVG 的严格校验与导出边界保持不变。

python3 scripts/pptx_to_svg.py deck.pptx --inheritance-mode both    # 默认:svg/ 分层视图 + svg-flat/ 自包含幻灯片
python3 scripts/pptx_to_svg.py deck.pptx --inheritance-mode layered # 仅分层 svg/ 与继承 metadata
python3 scripts/pptx_to_svg.py deck.pptx --inheritance-mode flat    # 每页一个自包含 slide SVG
python3 scripts/pptx_to_svg.py deck.pptx --strict                   # 在第一个不支持/格式错误源结构处停止
源文件情况 默认容错导入 --strict 诊断结果
可识别颜色语义带无关源 metadata 规范化已识别颜色与 modifier 拒绝非规范结构 warning;可用时包含 part、Slide 与 shape 上下文
不支持的填充、轮廓、效果、图片填充、文字体或样式属性 保留对象,只省略不支持的属性或功能 在第一个违规点停止 warning 说明省略内容与 fallback
无法按属性映射的不支持对象 只把该对象替换为可见诊断占位;没有可用 frame 时才省略 在第一个违规点停止 warning 标识源对象
不支持的 Slide 或 part 背景 省略该背景,继续当前页面/part 在第一个违规点停止 warning 标识所属 part
损坏的包/XML 或缺失必需包结构 停止;不存在安全的页面级容错 停止 整洁的命令错误,不输出裸 Python traceback

每次成功转换都会写入 <output>/conversion-report.json 和以 none 为基线切换的规范 <output>/animations.json。报告的稳定顶层字段是 schemaVersion、source、mode、summary、artifacts 与 diagnostics;每条诊断记录 reason code、source message、chosen fallback、package part_path,以及可用时的 slide_index、shape_id、shape_name、shape_kind(conversion.md)。未知或不精确的切换 carrier 保留明确的 transition-not-reconstructed 诊断。因此容错导入不是静默吞错:它尽可能保留可用输出,同时让每一次合同降级都可复核。

conversion.md 还提供了两个可执行的维护冒烟检查:健康生成 deck 往返(期望 1 slide、0 warnings)与 tolerant/strict 颜色结构探针——容错导入应产生一条 color-structure-normalized 诊断并保留 #4472C4 与 #ED7D31 两个颜色,--strict 则应退出码 1、输出 Error: PPTX-to-SVG conversion failed: Invalid DrawingML sRGB color structure 且无 traceback。这两个探针直接验证了 §12 容错矩阵的行为。

13. 校验职责:四层分工

四层有意承担不同职责:

层 职责
提示词、模板与示例 对每项 PowerPoint 功能只生成规范表达
svg_quality_checker.py 拒绝非法/不支持映射;对已登记兼容拼法或保真风险给出 warning 但允许继续
svg_to_pptx.py 与最终包读回 归一化兼容输入、编译 DrawingML,并拒绝任何会产生歧义、结构不一致或非法结果的输出
pptx_to_svg.py 默认容错模式在最窄安全边界保留可用 deck 并报告源内容降级;--strict 模式在第一个不支持或格式错误的源结构处停止

生成 SVG 的 warning 不是猜测许可:它只适用于拥有唯一结果的受支持映射、但其拼法或保真度值得注意的情况。缺失映射、非法单位、格式错误 metadata、破损的结构合同,以及可能触发 PowerPoint 修复的生成 DrawingML 仍是 error。导入诊断描述对源内容的显式丢失或规范化,绝不授权导入器虚构不支持的语义。从源码结构看,svg_quality_checker.py(skills/ppt-master/scripts/svg_quality_checker.py)是 svg_quality/ 包的稳定 CLI 入口,其校验器与导出器 preflight 共享同一套 validator(svg-contract.md 明确说明 checker 导入与 exporter 相同的 svg_to_pptx/drawingml/utils.py、converter.py、text_properties.py),因此"check 通过"与"export 接受"边界一致。

14. 新增或修改映射:七步编译器变更流程

映射变更应视为编译器变更,而不是宽松 SVG parser 调整:

  1. 命名 PowerPoint 能力与预期的可编辑 DrawingML 结果。
  2. 在 shared-standards.md 路由到的适用权威模块中定义一种规范项目 SVG 或 sidecar 表达。
  3. 将可接受兼容输入与生成创作分开声明。
  4. 实现导出;仅当支持语义重建时实现导入。
  5. 增加 Checker 分类:非法/歧义输入为 error,只有结果确定的兼容或近似输入可为 warning。
  6. 对生成 SVG、PPTX 包、PowerPoint 渲染,以及适用时的反向导入执行聚焦回归验证。
  7. 同步更新本指南中对应的英文与中文行(docs/powerpoint-svg-mapping.md 与 docs/zh/powerpoint-svg-mapping.md)。

实现入口:

小结:如何把这份映射表当作工程契约使用

总结起来,这份映射指南的工程价值在于它把"可编辑 PPTX"拆成了可逐行核对的合同:

  • 对创作侧(Agent 编写 SVG):它定义了唯一的规范表达——一个 PowerPoint 功能只能对应一种已登记 SVG 形态(如背景提升只认第一个合格的全幅 <rect>、原生表格只认 data-pptx-replace-with="table" 加 ppt-master.semantic-table.v2 JSON、文本图片填充只认 data-pptx-text-image-fill="stretch|tile"),超出即 fail-closed。
  • 对保真度判断:七档术语给出了"保留原样 / 归一化 / 近似 / 必须烘焙 / sidecar / 直接保留 / 不支持"的完整刻度,Approximate 项(如径向渐变、阴影、发光、图片裁形)在效果承载实质语义时必须人工复核生成 PPTX。
  • 对导入侧:默认容错 + --strict 的双模式矩阵保证了用户 PPTX 尽可能被保留可用输出,同时每一次降级都以 conversion-report.json 中的稳定 reason code 可复核;"容错不是静默"是这条路线的底线。
  • 对演进:新增或修改任何映射都必须走七步编译器变更流程并在中英两份文档同步登记——这也意味着本文档本身与实现代码共同构成项目的能力真值来源。
登录后查看全文
ppt-master