ppt-master 可视化模板编写指南：Chart 与 Table 模板库的中性预览合同、结构规则与验证流程

ppt-master 可视化模板编写指南：Chart 与 Table 模板库的中性预览合同、结构规则与验证流程

【免费下载链接】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

本文基于 ppt-master 仓库中的维护者指南VISUALIZATION_TEMPLATE_AUTHORING.md展开，系统讲解templates/charts/与templates/tables/两个 Visualization catalog family 的编写合同：模板的所有权边界、中性预览规范、语义压缩要求、data-pptx-bounds分组约定、Native Chart/Table 替换标记，以及占位内容注册与迁移边界。读完后你将能够独立编写或修改一个符合该库结构合同、可通过svg_quality_checker.py与visualization_recall.py validate双验证的可视化模板，并理解“Structure 是方法而非目录”“Visualization 不是 Layout”这两条贯穿全库的设计决策。

1. 文档定位与两条硬规则

templates/charts/和templates/tables/共同组成 ppt-master 的 page-local Visualization 模板库。模板只负责数据编码或单元格关系，不负责最终项目风格；它们必须保持源码可读、独立可渲染，并允许 Executor 根据项目 Design Spec 与spec_lock.md重做字体、配色和装饰。

先给出 family 判定表，这是后续一切编写决策的分流依据：

在此之上，文档确立了两条贯穿全文的硬规则：

• Structure 是一种方法，不是目录。定性顺序、层级、角色、分区和关系由 executor-structure.md 在当前页面现场构形，不登记固定structure/<key>、SVG roster 或 index。Default 和 Quick 路径都先判断页面真实信息模型；需要定性拓扑时都必须采用这套 Structure 方法。删除 catalog 只删除固定示例，不删除 Quick 或 Default 的 Structure 能力。
• Visualization 不是 Layout。Chart/Table 模板和运行时 Structure 都不拥有data-pptx-master、data-pptx-layout、data-pptx-layer或data-pptx-placeholder。跨页 Master/Layout、page type、slot geometry 和 placeholder 合同属于 layouts/ 或 decks/ workspace；两者共存时，仅由 Layout 覆盖 Deck 的结构分段。

2. 上游规范：不重复定义第二套 SVG 规范

本指南只定义 Chart/Table 两个 catalog family 的结构与中性预览合同。通用 SVG 语法、效果、原生数据接口和 PowerPoint 结构分别由以下权威文件定义，冲突时一律以上游为准：

这条规则的实操意义是：编写模板时不要在模板文件内“就地发明”语法细节，所有语法争议回到上表四个文件裁决。

3. 所有权边界

3.1 作者合同与项目消费

所有权划分只约束库内单个模板工件的维护，不把工件变成项目页面的布局锁：

由此派生两条硬规则：

• 编写完整性：维护某个库模板时必须保持该模板自身的 family 与信息模型（Chart 的数值映射、Table 的行 × 列事实网格）。若修改结果属于定性关系拓扑，不新增第三类模板，而由 runtime Structure 方法构建；若仍属于另一 catalog family，应登记到正确 family，不能保留错误标签。最终视觉样式来自使用它的项目，而不是模板的示例审美。
• 灵活的项目引用：Executor 选中的family/key仍只是灵活的页内引用。Default 的 §IX 或 Quick 的页面决策拥有最终结构；选中引用不会锁死页面的可视化类型、几何、分组数、项目数或组合方式。项目若实际采用某一信息模型，必须保持其真实数据与关系准确；仅有引用本身不构成页面结构权威。

3.2 保留判断

对模板里的每个视觉元素按顺序判断：

默认——信息优先：优先使用清楚的线、面、标签和留白，装饰不能成为理解信息的前提（语义需要时可以覆盖）。

3.3 保真优先：先保真，再瘦身

三条硬规则约束模板瘦身行为：

1. 先保真，再瘦身：瘦身不得改写或删除原有可见标题、标签、说明、数值、单位、状态、来源、顺序、容量和关系。占位内容保持原文；只有明确重复的信息可以删除，并记录理由。
2. 显式迁移例外：经明确批准的 family/key 合并、重组或退役可以用中性占位内容重建 canonical SVG，或移除不再存活的工件——这不是普通模板瘦身。迁移必须在第 8 节记录 catalog 边界和仍可读取的 legacy 语义；未列入批准迁移的模板仍受逐字保真约束。
3. 保留结构框架：框线、底色、分隔、标签页或面板只要表达真实的信息单元、父子层级、阶段范围、绘图区或输出区，就属于结构。可以减少叠加效果，但不得为了 token 数字把有效层级压平。

禁止通过改写压缩：不用缩写、概括、换词或删句降低 token。体积优化只能来自属性继承、重复样式合并和非语义效果简化，不来自内容编辑。

4. 中性预览

4.1 独立可渲染

硬规则：每个模板保持完整<svg>、viewBox="0 0 1280 720"和一个直接的白色全画布背景，使文件无需外部样式即可打开审阅：

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 720" width="1280" height="720" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Microsoft YaHei', sans-serif"> <rect width="1280" height="720" fill="#FFFFFF"/> <!-- semantic content --> </svg>

白色背景是预览基线，不是项目背景指令；Executor 必须按当前页面风格处理最终背景。这一要求可以直接在现有模板中得到验证，例如 line_chart.svg 第 1–8 行完整遵循了该骨架：viewBox、系统字体栈、白色背景 rect、带data-pptx-bounds的header组。

4.2 中性参考色

以下色值只保证模板独立展示时清晰，它们不是最终项目调色板：

硬规则：多系列数据必须可区分；正负、完成/计划等语义状态必须可辨认。颜色承担这些信息时保留，颜色只承担装饰时移除。禁止固定目录调色板：不要求每个卡片、步骤或能力点使用不同 Tailwind hue，项目配色不从模板示例反向推导。

4.3 页面 chrome

5. 装饰与效果

5.1 减少冗余效果

默认原则是“一种清楚的处理方式”（结构需要深度时可以覆盖）：中性模板避免阴影、发光、纹理、渐变和多层框同时叠加，只保留能帮助读者识别真实边界、重叠或空间关系的最少效果。

硬规则划定了“哪些视觉效果属于信息”：Heatmap 色阶、Sankey 流量宽度、系列区分、Isometric 面向关系和真实模块边界属于信息编码或结构；而普通卡片阴影、气泡高光、无含义色带和不承担顺序的大号淡色编号通常不属于——但删除前仍需确认没有弱化层级。

5.2 容器克制

硬规则：每个真实信息单元保留至少一种清楚的边界表达——留白、分隔线、描边或底色。通常只需一种；父级区域与子级内容确实表达两个层级时可以保留两层。不要同时叠加无语义的描边、阴影、渐变和多层圆角框。

参考说明（不是约束）：项目最终可能采用强装饰风格，那是 Executor 根据 Design Spec 重建的项目决策，不是共享模板的默认形态。

6. 源码可读性与体积

6.1 语义压缩

硬规则：缩小模板时保留正常换行、缩进、语义id和必要分区注释。压缩目标是减少重复信息，不是把 XML 变成一行。具体做法：

6.2 禁止的压缩

以下做法被明确禁止：

• 单行 minify、随机缩写 ID 或删除结构注释；
• 为省字符把核心构图拆成难以追踪的深层<symbol>/<use>图；
• 把模板必要信息藏进外部 CSS、脚本或未登记依赖；
• 用 Base64、压缩字符串或生成器说明替代可读的可视几何。

静态同文档<use>只在重复原语保持清晰、且满足上游条件合同时使用；它不是默认瘦身手段。

6.3 文本可读性

硬规则：所有文本font-size >= 12，使用有限无单位数值。需要成为一个 PowerPoint 文本框的多格式逻辑行使用一个<text>加非定位<tspan>；独立文本框使用独立<text>。

7. SVG 分组与边界

7.1 语义分组

硬规则：使用描述性顶层<g id>表达页面级逻辑单元（Header、Chart、Legend、Card Grid、Process 等），不要为每条文字、图标或数据点建立一个直属根组。

禁止工作区元数据：两个 catalog family 都不得写入 Master/Layout/placeholder 所有权标记。运行时 Structure 即使占满整个1280×720画布也仍是 Slide-local 构形，不会因此成为 Layout workspace。

7.2data-pptx-bounds

硬规则：每个可见直属根<g>都声明正数、根坐标系的data-pptx-bounds="x y width height"。即使该组已有 native chart/table frame，也保留 bounds：

<g id="header"><!-- chart-plot-area: 140,150,1160,550 -->

Pie、Donut、Radar 使用对应中心和半径格式。该注释是工具输入，不得作为“清理注释”删除。以 line_chart.svg 为例，chart-plot-area: 140,150,1160,550正好落在网格与坐标轴之后、第一个数据系列之前——这正是合同规定的唯一合法位置。

Catalog 模板本身只有一个主 Chart，可保留上述 unscoped marker 与id="chartArea"。Executor 在项目页面组合多个已验证 Chart 对象时，改用 executor-chart.md 定义的 semantic object key 和 scoped marker；不能在同一 SVG 中复制多个chartAreaid。

8.2 Native Chart/Table 替换标记

硬规则：只有 native-data-interface.md 支持的真实 Chart 或纯文本 Table 使用 replacement marker。JSON metadata 与可见 fallback 必须表达同一份数据。运行时构建的 Structure 永远不使用 Chart/Table replacement marker。

<g id="line-chart" >"line_chart": { "summary": "Pick for 1-3 time-series on a continuous axis showing direction. Skip if cumulative volume matters (use area_chart)." }

summary保留Pick for ... Skip if ...句式，供可选的机器召回诊断使用；规划主路径不读取这些记录。两份 index 的meta.summaryGrammar都把它固化为机器合同：'Pick for <content shape + scale>. Skip if <reason → alternative>'。Chart 与 Table 的规划词汇表必须完整列出各自同一组 canonicalfamily/<key>，只说明信息关系，不写 SVG 实现、布局参数或选择结论。

硬规则：key与同 family 文件名一致，meta.total与该 family catalog 数量一致（当前 charts_index.json 中meta.total为 33，tables_index.json 中为 6）；每份 planning vocabulary 与 owning index 的成员集合必须精确一致。除此以外不要建立跨 family 的第二份成员清单。

summary的句式不是风格偏好，而是召回算法的输入格式。从 visualization_recall.py 的_score_candidate实现看：工具用正则skip (?:if|for)把 summary 切分为 pick 子句与 skip 子句，tag 命中 key/pick 子句分别记正分（20/14/9/5），命中 skip 子句记负分（12/6）；也就是说Pick for / Skip if句式直接决定了召回诊断的正负证据。该工具只读这两份 index 并维护不了第二份索引，详见 visualization-recall.md。

10. 迁移边界

本指南是新建和修改 Chart/Table 模板的目标合同。当前两个 catalog family 共39 个 SVG：Chart 33 个、Table 6 个。各 live index 是成员清单的唯一权威；Structure 不再有固定 SVG roster、index 或 canonical key。

硬规则——拓扑由现场生成，不从目录召回：从来源 deck 吸收的是 Shape grammar 和构形思维，而不是页面示例清单。先还原顺序、层级、分组、分区、连接、交叠等真实关系，再由executor-structure.md使用区域、节点、主轴、连接、标签与装饰等角色现场组合。Default 在 §IX 描述该关系，Quick 在当前上下文作同一判断；两条路径都不依赖structure/<key>或固定 SVG，不能因 Quick 跳过 §VII/lock 就跳过 Structure 载体判断。

已批准的图表容量迁移：

规范 Table 集合：

硬规则——先判定语义分类，再看物理对象：PowerPoint 中的物理 Table 对象不自动属于tablefamily。只有行头与列头的交点可寻址为一个事实时才是 Table；日期或持续时间决定x/width的排期是chart/gantt_chart；阶段与泳道只表达定性活动位置时由 runtime Structure 构建。这条规则与 family 判定表首尾呼应，也是gantt_chart从旧project_schedule_table迁移到 chart family 的依据。

规范目录别名（只服务旧page_charts读取，不是新模板命名候选）：

上述别名与两份 index 的aliases字段一一对应：tables_index.json的aliases覆盖了前六个裸 key，charts_index.json的aliases覆盖project_schedule_table → gantt_chart。新文档、§VII 和page_visualizations只写 canonicalchart|table/<key>。此前 36 个 canonical Structure bare key 只在旧page_charts读取时保留为legacy-structure-intent：它没有 canonical SVG、path 或 reference，不参与 recall，也不能写入新 §VII/lock；消费方把该意图投影为定性关系提示，再交给 runtime Structure 构形，不得把它伪装成仍存活的模板。

迁移收尾还有一条硬规则：修改一个仍属 canonical 的模板时先冻结可见文本、数据和结构层级，再简化确认无语义的效果、补齐直属根 bounds，并完成文本差异、独立渲染与双路线验证。经本节明确登记的 catalog 合并/重组/退役不要求保留旧示例文案；除此之外，未经说明的文本删除、改写或结构边界丢失都会阻断变更。

11. 检查清单

11.1 结构与可读性

• SVG 独立可渲染，viewBox为0 0 1280 720。
• 源码有正常缩进、语义 ID 和必要结构注释。
• 原有可见文本、数值、单位、来源、状态和关系保持不变；删除项只有审核过的重复信息。
• 真实信息单元、父子层级、阶段范围和输出区仍有清楚边界。
• 每个可见直属根<g>有准确的data-pptx-bounds；嵌套组不滥加 bounds。
• 模板只保留结构、数据编码和必要中性预览。
• 字体在根或清楚父组继承，文本字号不小于 12。

11.2 风格归属

• 无固定项目调色板、品牌字体或品牌 chrome。
• 纯装饰效果已减少，但没有以“去装饰”为由删除结构框线或压平层级。
• 颜色差异确实表达 series、state、positive/negative 等语义。
• 标题、副标题和来源只用于展示必要结构或容量。

11.3 分类与 PowerPoint

• 分类判定正确：Chart 为数值驱动、Table 为行 × 列事实网格；定性拓扑退出 catalog 并由 runtime Structure 构建。
• Chart/Table 模板不含 Master/Layout/layer/placeholder ownership metadata。
• Calculator-supported Chart 保留准确chart-plot-area标记。
• Eligible Chart/Table 的 metadata 与可见 fallback 数据一致。
• 默认 Shape-first 导出通过。
• 存在 replacement marker 时，显式 native Chart/Table 导出通过。
• svg_quality_checker.py无 error；warning 已人工判断。

11.4 目录

• 新模板只登记到 owning family index，index object、meta.total与 SVG roster 一致。
• 修改 key/summary 后通过visualization_recall.py validate和 recall 烟测。
• 前后可见文本差异已审阅，非重复内容没有意外丢失或改写。
• 前后渲染对比确认结构仍可读。
• 记录 bytes/tokens 变化，但不以牺牲源码可读性换取数字。

12. 验证命令

指南为每次变更规定了两条机器验证命令：

# 单文件 SVG 合同 python3 skills/ppt-master/scripts/svg_quality_checker.py \ skills/ppt-master/templates/<family-directory>/<key>.svg \ --canonical-authoring # Canonical family/key python3 skills/ppt-master/scripts/visualization_recall.py validate \ <family>/<key>

两条命令的作用边界不同：

• svg_quality_checker.py负责单文件的 SVG 合同检查（独立可渲染、bounds、文本字号等）。作者态必须已紧凑——Checker 只读验证，不在检查后重写，这与第 6 节“坐标在写入时就使用必要精度”的硬规则是同一条约束的两端。
• visualization_recall.py validate负责引用解析：它只读地把family/key解析到登记的 SVG，全部解析成功时退出码为0，否则为1；--legacy-bare开关仅用于验证旧page_charts映射中的未限定裸 key，且每个 key 必须唯一解析（见 visualization_recall.py 的参数定义）。

最终验证要求：修改后至少完成XML 解析、独立 SVG 渲染、Checker、默认 Shape-first 导出，以及 marker 模板的 native Chart/Table 导出——即 Shape 路线与 native 路线双验证，两条路线都必须可验证后才能提交变更。

13. 总结

这套编写指南的核心思想可以概括为三层分离：模板层只承诺信息模型与中性预览（family、数据映射、data-pptx-bounds、chart-plot-area），项目层拥有全部视觉风格（配色、字体、chrome、背景），方法层（Structure）不落在目录里而落在 Executor 的现场判断中。39 个 canonical SVG 的存活合同是“源码可读、独立可渲染、保真优先、Shape-first、双路线可验证”；任何瘦身或迁移都必须先冻结可见文本与结构层级，再以属性继承和非语义效果简化换取体积，并以第 11 节检查清单和两条验证命令收口。掌握这份合同后，你可以直接上手扩展charts/或tables/任一 family，或在维护现有模板时不破坏其 canonical 语义。

【免费下载链接】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