企业官网建设流程全解析

PPTX Deck Layout Contract 详解：用 JSON 坐标契约驱动可编辑 PPTX 演示文稿的布局审计

【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents

导读

本指南聚焦于pptx-deck-creation插件中pptx-slide-specification技能所定义的Layout Contract（布局契约）。它是一份坐标显式的 JSON 规范：生成演示文稿的最终根 JSON 中同时包含summary（摘要）与slides（幻灯片数组），其中的layout_tree（布局树）是审计契约而非渲染提示。读完本文，你将掌握契约的完整字段语义、各字段的度量单位与取值范围、build 阶段 builder 的映射要求，以及"修复顺序"（Repair order）这一从几何调整到字号降级的四级排错路径，并能在构建后回读 PPTX 实际边界与契约比对。

契约的定位：审计契约，而非渲染提示

Layout Contract 的核心论断只有一句：A generated deck uses a JSON root withsummaryandslides. The final tree is an audit contract, not a rendering hint.（生成的数据包使用含summary和slides的 JSON 根；最终的树是审计契约，而不是渲染提示。）

这句话区分了两种截然不同的工作方式：

• 传统自动布局（auto-layout）：渲染器在绘制时自行决定位置、自行缩放文字、自行推断布局，作者无法预知最终坐标。
• 坐标契约式（coordinate-explicit）：作者直接在layout_tree中写明最终坐标，任何渲染器在审计之后都不得再决定位置、不得缩小文字、不得推断布局。

在 SKILL.md 中，这一原则被表述为：

Author final coordinates directly inlayout_tree. No renderer may decide placement, shrink text, or infer layout after the audit.

也就是说，Layout Contract 是一份逐对象、逐坐标、逐样式的完整规格，它同时充当三份角色：给 builder 的构建指令、给审计工具的核对基准、以及给后续维护者的可读文档。该插件的 README.md 也强调这一点——插件提供的是"final inch-basedlayout_treecontracts rather than implicit auto-layout"（基于英寸的最终布局树契约，而非隐式自动布局）。

契约的整体结构：summary+slides

根 JSON 由两个顶层键组成：

{ "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 } } } }] }

summary：全局策略与可访问性元数据

summary承载整个数据包的全局约束。其中生产环境（production）数据包必须包含显式的layout_policy与可访问性元数据（见 SKILL.md 的 Required contract 一节）。

layout_policy是构建与审计阶段的硬约束，四个字段的语义如下：

以 13.333 × 7.5 英寸的宽屏为例：content_bottom: 6.7与footer_top: 6.85之间形成了 0.15 英寸宽的页脚轨道；正文内容必须保持在 6.7 英寸线以上，页脚元素从 6.85 英寸线开始。在 audit-checklist.md 的"Layout policy"检查项中，这一约束被精确表述为：内容保持在安全边距内、位于页脚轨道之上；只有layout_design类对象可以 full bleed（出血全幅）。

accessibility记录全局可访问性信息：

此外，从仓库的配套技能可见，summary还可以承载更丰富的设计上下文：pptx-deck-context技能要求在编写坐标前，将叙事框架、假设、来源清单、调色板、排版、间距与标志性元素记录进summary；design-profiles.md（references/design-profiles.md）则要求把锁定的设计档案（如fluent-ui-design-tokens、primer-primitives、editorial-minimal）记录在summary.design_context中，并在 audit-checklist.md 的"Design context"检查项中要求其必须存在，否则拒绝默认主题式纯标题加项目符号的输出。

slides：逐页契约

slides是幻灯片数组，每一页包含：

• id：稳定可读的标识符（如s01_overview），用于审计报告与异常追踪。
• title：以消息/结论为导向的标题（message-led title）。从 pptx-deck-context/SKILL.md 可知，一页只传达一条消息，且当叙事框架要求时应使用 action-style（行动式）标题。
• accessibility.reading_order：该页的阅读顺序数组（如["title"]），驱动无障碍阅读顺序。
• layout_tree：该页的完整布局树。

layout_tree：坐标、分组与对象的完整声明

layout_tree声明了页面尺寸、根组、以 id 为键的分组与对象、最终英寸 bbox、样式、z 序与分类。它由三个主要成员构成：

1.slide_size：页面物理尺寸

"slide_size": { "width": 13.333, "height": 7.5 }

单位是英寸（inches），与python-pptx的Inches(...)单位体系一一对应。13.333 × 7.5 即标准的 16:9 宽屏页面。build 阶段 builder 会从空白幻灯片版式（blank slide layout）开始，将所有 bbox 用Inches(...)映射（见 SKILL.md 的 Build contract 一节）。

2.groups：以 id 为键的分组表

"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 } } }

字段含义：

根组的 bbox 通常与slide_size一致（从(0, 0)延伸到整页）。audit-checklist 的"Containment"检查项要求子对象必须适配其父组，形状上的文字还需尊重内边距（inner padding）。

3.objects：以 id 为键的对象表

"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 } }

契约要求每个有意义（meaningful）的对象都必须完整具备八个字段（见 SKILL.md 的 Required contract）：

几个值得注意的约束：

• bbox 尺寸均为正英寸数。authoring 规则第 1 条要求使用稳定可读 id、绝对分组与正英寸尺寸；build 契约进一步要求在添加对象前拒绝零或负几何（reject zero or negative geometry）。
• 字号下限 9 pt。authoring 规则第 5 条：内容文字必须 ≥ 9 pt；优先缩短文案、调整 bbox 或拆分密集内容，而不是降低字号。
• 图片必须有有意义的 alt 文本，且带来源的论断要记录source_ref（authoring 规则第 4 条）。
• z 序必须是有意的（intentional z-order）。在 asset-guidance.md 中进一步要求：视觉素材在 z 序上要低于其上可读文本（"Keep visual assets below overlapping readable text in z-order"）。

示例对象中title的 bbox 为x=0.75, y=0.55, width=10.8, height=0.65。对照策略值验证：x=0.75 ≥ safe_margin=0.5，y=0.55 ≥ safe_margin=0.5，x+width=11.55 ≤ 13.333-0.5=12.833，y+height=1.2 ≤ content_bottom=6.7，完全落在安全区内。

Build 契约：把 JSON 坐标映射为真实 PPTX 对象

Layout Contract 不止是一份文档——它定义了 builder 的硬性行为契约。见 SKILL.md 的 Build contract 一节：

A task-local builder starts from a blank slide layout and maps all bboxes withInches(...). Explicitly set wrapping, disabled auto-size, text insets, anchors, alignment, fonts, colors, line settings, image aspect ratio, and hidden-slide state. Reject zero or negative geometry before adding an object.

要点拆解：

1. 从空白版式开始：builder 不使用模板克隆，从 blank slide layout 出发。
2. Inches(...)映射全部 bbox：契约中的英寸值直接映射为python-pptx的Inches(...)度量。
3. 显式设置每一项：换行（wrapping）、禁用自动缩放（disabled auto-size）、文本内边距（insets）、锚点（anchors）、对齐（alignment）、字体、颜色、线条设置、图片宽高比、隐藏页状态，全部显式写入，不依赖渲染器推断。
4. 几何前置校验：添加对象前拒绝零或负几何。

这一点与插件边界一致：README.md 明确说明，插件只会在用户请求 PPTX 时创建一个任务级（task-specific）的小型python-pptxbuilder，不内置通用渲染器、不克隆模板、不需要浏览器、不依赖 MCP 服务器或在线服务。而 pptx-deck-creation-builder.md 将layout_tree定义为唯一事实来源（source of truth），要求标题、解释、标签、指标、表格、图表与图示都必须使用原生（native）PPTX 对象，图片只是辅助视觉（supporting visuals），绝不允许用整页图片充当幻灯片的核心内容。

"禁用 auto-size"与契约的定位直接呼应：正因为 auto-size 会让渲染器自行缩放文字，契约要求关闭它，让最终几何完全由 JSON 决定，从而保证"审计后无任何渲染器可篡改布局"。

Repair order：契约被破坏后的四级修复顺序

当审计发现契约与实际几何不一致时，必须按以下顺序修复（layout-contract.md 的 Repair order 一节）：

1. 移动或调整 bbox、改变 z 序、或拆分内容过密的幻灯片（Move or resize bboxes, change z-order, or split a dense slide）。
2. 缩短文案，或放大可用的文字 bbox（Shorten copy or enlarge the available text bbox）。
3. 仅在万不得已时才改变字号；内容字号永不低于 9 pt（Change type size only as a last resort; content never drops below 9 pt）。
4. 重新构建，并将实际对象边界与契约比对（Rebuild and compare actual object bounds with the contract）。

这一顺序体现了明确的设计优先级：几何与内容优先，字号是最后的杠杆。原因很直接——字号是排版的全局杠杆，一旦降低会影响整页的层级与可读性；而移动 bbox、缩短文案是局部、低风险的修复。第 4 步则强调修复不是一次性的：改完必须重建并重新比对，形成一个"审计 → 修复 → 重建 → 再审计"的闭环。

该闭环在pptx-quality-gates技能中得到完整承接：SKILL.md 的 Workflow 第 7 步即"Repair the spec or task-local builder, rebuild, and rerun the same checks"（修复规范或任务级 builder，重建，并重跑同样的检查），并将确定性失败视为待修复的工作（repair work）而非异常。

构建后审计：用实际几何回读校验契约

契约的最终验证发生在构建之后。pptx-quality-gates技能（SKILL.md）要求：

Reopen the PPTX and compare slide count, actual bounds, hidden slides, and requested geometry with the layout tree.

即重新打开生成的 PPTX，将实际幻灯片数、实际对象边界、隐藏页状态、请求的几何与layout_tree逐一比对。这要求审计工具能够从 OOXML 包中读出真实坐标——仓库中的 validate_package.py 正是这一类只读校验工具的实现样例，它负责 OOXML 包完整性验证，其validate()函数会检查：

• XML 良构性：所有.xml/.relspart 均可被解析。
• 内容类型：[Content_Types].xml必须存在，且每个ppt/slides/slide*.xml都必须有正确的 slide content type override。
• 内部关系完整性：每个内部关系（Relationship）的目标必须存在且不越界。
• 幻灯片顺序唯一性：presentation.xml中sldId不得重复，且必须引用有效的 slide 关系。
• 孤儿 part 告警：未被任何内部关系引用的ppt/media/与 notesSlide 会被标记为告警。

在pptx-quality-gates的 Workflow 第 4 步中，生产级数据包要求运行该脚本并保存 JSON 报告；audit-checklist.md 的"After build"部分则将其列为第 13 项检查：修复畸形 XML、断裂的关系、内容类型缺口与重复的 layout 链接，并对接受的告警做文档化。

通过（Pass）标准：什么样的契约算合格

pptx-quality-gates技能定义了明确的通过标准（SKILL.md 的 Pass criteria 一节）：

Zero content collisions, text overflows, unsafe content bounds, invalid positive geometry, and package-integrity errors. Meaningful slide content must remain native editable objects; images support rather than replace it.

即：零内容碰撞、零文字溢出、零不安全内容边界、零非法正几何、零包完整性错误；且有意义的内容必须是原生可编辑对象，图片只是辅助。若无法完全通过，则每个例外都必须记录幻灯片 id、对象 id、原因、负责人与复审日期（见 audit-checklist.md 的结尾要求）。

其中"内容碰撞"的判定公式在 audit-checklist.md 的 Build 前第 1 项中给出：

A.x < B.x + B.w && B.x < A.x + A.w && A.y < B.y + B.h && B.y < A.y + A.h

当该四条件同时成立时，两个内容 bbox 即发生重叠，属于必须修复的确定性失败。而"文字容量"检查则提示：预估可能溢出的内容应缩短、缩放或拆分，且对于CJK/全角文本，每行可容纳字符数估算减半（halve estimated characters-per-line for CJK/full-width text）——这一条对中文 PPTX 的实战排版尤为重要。

配套技能与文件索引

Layout Contract 是pptx-slide-specification技能的压缩模式参考，它与同一插件下的其他技能协同构成完整的 spec-first 工作流：

• layout-contract.md：本文讲解的契约本体（紧凑 schema 与修复指引）。
• SKILL.md：技能的完整要求，包括 Required contract、Authoring rules 与 Build contract。
• audit-checklist.md：构建前 10 项 + 构建后 4 项的手动审计清单。
• SKILL.md：质量门禁工作流、必备工件与通过标准。
• validate_package.py：只读 OOXML 包完整性校验脚本。
• design-profiles.md：summary.design_context可引用的设计档案。
• asset-guidance.md：图片出处、放置、SVG 与信息图约束。
• pptx-deck-creation-builder.md：负责创建、修复与审计数据包的 Agent 及其非协商规则。

小结

Layout Contract 把 PPTX 制作从"渲染器自由发挥"转变为"坐标显式契约 + 事后几何回读"的闭环：summary.layout_policy锁定安全边距、内容下界、页脚上界与最小间隙；slides[].layout_tree用英寸 bbox、显式样式与 z 序声明每一页的最终形态；builder 从空白版式出发用Inches(...)映射全部坐标并禁用 auto-size；构建后通过回读实际边界、运行 OOXML 校验与逐项审计清单验证契约成立；一旦失败，则按"调几何 → 缩文案 → 降字号（不低于 9 pt）→ 重建再比对"的顺序修复。掌握这份契约，你就能写出可被审计、可被重建、且保持原生可编辑性的 PPTX 坐标规范。

【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents