PPTX Slide Specification：用坐标显式 layout_tree 契约驱动可编辑 PPTX 生成

导读

本指南围绕 pptx-slide-specification 技能展开，讲解如何为可编辑的 PPTX 演示文稿编写“坐标显式”（coordinate-explicit）的 JSON 规格说明书。其核心思想是：把最终版面中的每个对象边界框（bbox）、层级、样式与层级关系直接写入 layout_tree，让规格文档成为生成与审计的共同契约，而不是交给渲染器自动排版。读完本文，你将掌握 layout_tree 的字段契约、编写规则、构建契约（build contract）以及出现版面问题时的修复顺序，并能结合本仓库 pptx-deck-creation 插件中其它技能与审计清单完成从规格到成品的全链路把关。

一、为什么需要坐标显式的 Slide Specification

1.1 传统自动布局的隐患

在常见的自动排版方案中，Agent 只给出“标题+若干要点”的松散意图，由渲染器或库自动决定文字大小、换行与位置。这带来几个问题：

• 渲染器拥有最终决定权：文字缩排、裁剪、对象重叠都由渲染器临时决定，作者无法精确控制最终效果；
• 审计无据可依：缺少一份与生成物可对照的“契约”，质量审计只能靠人工目测；
• 不可复现：同一份内容在不同工具中可能生成完全不同的版面，难以做回归对比。

1.2 规格优先的解决思路

pptx-slide-specification 技能给出的答案是：由作者在 layout_tree 中直接写入最终坐标，并规定“任何渲染器都不得在审计之后自行决定位置、缩小文字或推断布局”（见 SKILL.md）。于是：

• 规格成为审计契约（audit contract），而非渲染提示（rendering hint）；
• 版面决策权完全回归作者；
• 后续可以“重新打开生成的 PPTX，把实际对象边界与规格逐项比对”。

这一思路与插件整体“spec-first workflow”一脉相承：pptx-deck-creation-builder Agent 明确要求“把最终的、以英寸为单位的 JSON layout_tree 视为唯一事实来源（source of truth）”，并且“绝不使用整页图片作为幻灯片的有效内容”（见 agents/pptx-deck-creation-builder.md）。

二、规格的整体结构与核心字段

2.1 根对象：summary 与 slides

规格 JSON 的根节点只包含两个键：summary 与 slides。summary 描述整份演示的策略与元数据；slides 是幻灯片的数组，每一张幻灯片都自带完整的 layout_tree。

2.2 summary 中的 layout_policy 与无障碍元数据

生产环境的 summary 必须包含显式的 layout_policy（版面策略）与无障碍元数据。layout_policy 通常包含四个数值：

字段	含义	示例值
safe_margin	安全边距（英寸），正文内容不得越出	0.5
content_bottom	内容区下边界（英寸），正文内容不得低于此线	6.7
footer_top	页脚栏上边界（英寸），正文内容不得侵入页脚区	6.85
minimum_gap	对象间最小间距（英寸），用于规避内容碰撞	0.12

无障碍元数据至少包含 language（如 en-US）与 presentation_title（演示文稿标题）。完整示例见 references/layout-contract.md。

2.3 slides 的必填字段

每张幻灯片必须包含：

• id：稳定、可读的幻灯片 ID（如 s01_overview）；
• title：以信息为导向（message-led）的标题，先陈述结论再展开；
• accessibility.reading_order：无障碍阅读顺序，例如 ["title"]；
• layout_tree：完整的布局树，声明幻灯片尺寸、根分组、按 ID 索引的分组与对象、最终英寸 bbox、样式、z-index 与分类。

2.4 layout_tree 的组成

一份 layout_tree 由四个顶层字段组成：

字段	说明
slide_size	幻灯片尺寸，width 与 height 均以英寸为单位（如 16:9 的 13.333 × 7.5）
root_group_id	根分组 ID（通常为 root）
groups	按 ID 索引的分组字典，声明分组的 role、layout_mode、object_ids、group_ids 与自身 bbox
objects	按 ID 索引的对象字典，描述每个有意义的对象

2.5 每个有意义对象的九要素

规格要求每个有意义的对象都必须具备以下九个字段：

1. id：稳定可读的对象 ID（如 title）；
2. kind：对象类型（text、shape、line、table、image 等原生类型）；
3. role：角色（如 title、label、value、footer）；
4. classification：分类，正文为 content，背景装饰为 layout_design；
5. content：内容，如文本对象的 { "text": "..." }；
6. style：样式，如 font_size、color；
7. bbox：最终边界框，x、y、width、height 均以英寸为单位且必须为正数；
8. z_index：层级，控制对象的前后覆盖关系。

以下是最小可运行的完整规格示例（引自 references/layout-contract.md）：

{
  "summary": {
    "layout_policy": {
      "safe_margin": 0.5,
      "content_bottom": 6.7,
      "footer_top": 6.85,
      "minimum_gap": 0.12
    },
    "accessibility": {
      "language": "en-US",
      "presentation_title": "Quarterly operating review"
    }
  },
  "slides": [{
    "id": "s01_overview",
    "title": "Operating margin improves after the cost reset",
    "accessibility": { "reading_order": ["title"] },
    "layout_tree": {
      "slide_size": { "width": 13.333, "height": 7.5 },
      "root_group_id": "root",
      "groups": { "root": { "id": "root", "role": "slide", "layout_mode": "absolute", "object_ids": ["title"], "group_ids": [], "bbox": { "x": 0, "y": 0, "width": 13.333, "height": 7.5 } } },
      "objects": { "title": { "id": "title", "kind": "text", "role": "title", "classification": "content", "content": { "text": "Operating margin improves after the cost reset" }, "style": { "font_size": 30, "color": "#111827" }, "bbox": { "x": 0.75, "y": 0.55, "width": 10.8, "height": 0.65 }, "z_index": 2 } }
    }
  }]
}

注意：示例中 title 对象位于 x: 0.75, y: 0.55，宽度 10.8 英寸——它严格落在 safe_margin: 0.5 的安全区之内，且远高于 footer_top: 6.85 的页脚栏，符合版面策略。

三、Authoring Rules：六条编写规则

技能明确给出六条编写规则，逐条解读如下：

1. 使用稳定可读的 ID、绝对分组与正英寸尺寸：所有尺寸必须是正数，分组采用绝对定位（layout_mode: "absolute"），不使用相对浮动布局；
2. 正文保持在安全边距内、页脚栏之上：只有分类为 layout_design 的背景装饰对象可以出血（full bleed，即铺满整页），普通内容一律遵守 layout_policy；
3. 使用原生 text/shape/line/table/image 对象：任何支撑性视觉素材中的标签与数值都必须以原生对象重建，严禁把整页截图或整页图片当作有效内容；
4. 为有意义的图片提供 alt 文本，并为有来源的主张记录 source_ref：图片 alt 文本服务无障碍需求，source_ref 服务来源可追溯（lineage）需求；
5. 正文字号不低于 9 pt：内容过密时先缩短文案、调整尺寸或拆分幻灯片，最后才考虑缩小字号；
6. 使用共享网格、一致间距、显式颜色、显式字号与有意的 z-order：让版面具有统一的视觉节奏。

这些规则与插件的其它技能互相咬合：pptx-deck-context 负责在动笔写坐标前锁定叙事框架、来源清单（source manifest）与设计方向（design lock），并把它们写进 summary（见 skills/pptx-deck-context/SKILL.md）；pptx-visual-assets 则规定了支撑性素材的放置方式：图片放在保留原生宽高比的显式 bbox 内、说明文字放在图片相邻空白处而非压在图上、素材在 z-order 中低于可读文本（见 skills/pptx-visual-assets/SKILL.md）。

四、Build Contract：任务级构建器的强制约束

4.1 构建器的职责

当用户确实需要生成 PPTX 时，技能要求在任务本地生成一个小型、针对该次任务的 python-pptx 构建脚本（不随插件捆绑通用渲染器）。构建器必须：

• 从空白幻灯片版式（blank slide layout）开始构建，不克隆模板；
• 用 Inches(...) 映射所有 bbox，保证英寸单位一致；
• 显式设置：文字换行（wrapping）、禁用自动尺寸（auto-size）、文本框内边距（insets）、锚点（anchor）、对齐（alignment）、字体（fonts）、颜色（colors）、线条设置（line settings）、图片宽高比（image aspect ratio）与隐藏幻灯片状态（hidden-slide state）；
• 在添加对象之前拒绝零或负几何尺寸（reject zero or negative geometry）。

这条约束把“规格写什么，构建器就做什么”落到了实处：所有视觉决策在构建器中被显式指定，杜绝了库默认值悄悄改变版面的可能。

4.2 为什么是 python-pptx 而不是通用渲染器

从仓库层面看，插件的边界非常明确（见 README.md）：

This plugin creates a small task-specific python-pptx builder only when a PPTX is requested. It does not ship a general renderer, clone templates, require a browser, use an MCP server, or require credentials or an online service.

也就是说，生成物是原生可编辑的 PowerPoint 对象，而不是把幻灯片画成一张图片再塞进页面。这与 Authoring Rule 第 3 条的精神完全一致——可编辑性（editability）是整套方案的核心交付属性。

4.3 与参考稿分析技能的衔接

如果用户提供了参考 PPTX，pptx-reference-deck-analysis 技能以只读方式抽取设计信号（版式节奏、主题 token、字体、颜色、母版与版式使用情况），绝不复制、克隆或修改源稿；只有当高层级抽取无法覆盖原始主题、关系、备注、批注、动画与媒体时，才使用捆绑的 OOXML 工具（inspect.py、validate_package.py、unpack.py），并且解析不可信 XML 时必须使用 defusedxml、禁止实体展开、DTD 加载与网络访问（见 skills/pptx-reference-deck-analysis/SKILL.md）。抽取到的设计信号最终也要被翻译成 layout_tree 中的显式填充色、字体、间距与 bbox，而不是依赖自动布局引擎去“猜”。

五、Repair Order：修复顺序与回环

当构建后的成品与规格不一致，或审计失败时，按以下顺序修复（引自 references/layout-contract.md）：

1. 移动或调整 bbox、改变 z-order、或拆分过密的幻灯片——先动布局结构；
2. 缩短文案或放大可用文本 bbox——再动内容；
3. 只有万不得已才调整字号，且正文永远不得低于 9 pt；
4. 重建并比对实际对象边界与契约——修复后必须重新验证。

修复是一个“改规格 → 重建 → 再比对”的闭环。在 pptx-deck-creation-builder 的六步工作流中，第 6 步明确要求“如果生成失败则修复规格或构建器并重跑检查，直到通过或留下书面豁免”（见 agents/pptx-deck-creation-builder.md）。确定性失败（deterministic failures）被视为需要修复的工作，而不是可接受的例外——这是 pptx-quality-gates 技能的开篇原则（见 skills/pptx-quality-gates/SKILL.md）。

六、与质量门禁（Quality Gates）的联动

layout_tree 规格最终要通过 skills/pptx-quality-gates/references/audit-checklist.md 的审计才能交付。与规格直接相关的关键检查项包括：

• 内容碰撞：内容 bbox 不得重叠，判定式为 A.x < B.x + B.w && B.x < A.x + A.w && A.y < B.y + B.h && B.y < A.y + A.h；
• 文本容量：预计溢出时缩短、调整或拆分；CJK/全角文本按每行字符数减半估算；
• 字号下限：内容文本 ≥ 9 pt；
• 版面策略：内容在安全边距内且高于页脚栏，只有 layout_design 可出血；
• 包含关系：子对象必须适配父分组，形状上的文本尊重内边距；
• 表格：列宽之和等于表格 bbox 宽度，换行文本放得下，长表拆分；
• 原生可编辑性：标题、标签、数值、图表与说明保持原生对象，图片仅作支撑；
• 来源可追溯：有来源的主张具备可解析的 source ID、定位符、主张类型与校验状态；
• 正几何：每个对象尺寸为正，行（line）的端点在建前归一化。

构建后还需重新打开包，比对实际幻灯片数、边界、隐藏幻灯片状态与规格是否一致，并检查可访问标题、语言、阅读顺序、有意义图片 alt 文本与表头；生产环境还需运行 pptx-reference-deck-analysis/scripts/validate_package.py 并保存 JSON 报告，用于发现畸形 XML、断裂的关系、content-type 缺失与重复的布局链接。

交付标准是：零内容碰撞、零文本溢出、零越界内容、零非法正几何、零包完整性错误；任何书面豁免都必须注明幻灯片 ID、对象 ID、原因、负责人与复核日期。

七、从规格到成品：完整链路速览

综合插件内各技能，一份 PPTX 的生成链路可以概括为：

1. 语境准备（pptx-deck-context）：确认受众、决策、来源、语言与品牌要求，锁定叙事框架与设计方向，生成 summary 中的策略与元数据；
2. 坐标编写（pptx-slide-specification，即本文）：为每张幻灯片编写完整、坐标显式的 layout_tree 契约，遵守六条 Authoring Rules；
3. 素材把关（pptx-visual-assets）：选择已获授权的支撑图片/图标，记录来源与 alt 文本，按原生宽高比放入显式 bbox；
4. 只读参考分析（pptx-reference-deck-analysis，可选）：若提供参考稿，只读抽取设计信号并翻译为显式样式；
5. 构建：按需生成任务级 python-pptx 构建器，从空白版式出发，以 Inches(...) 映射全部 bbox 并显式设置所有排版属性；
6. 审计与修复（pptx-quality-gates）：依据审计清单逐项核对规格与成品，命中修复顺序回环，直至通过或留下豁免记录。

这套流程保证交付物是原生可编辑、坐标可控、无障碍友好、来源可追溯的 PPTX，而 layout_tree 规格正是贯穿全流程、可被机器与人类共同验证的“单一事实来源”。