PPTX Quality Gates 质量门禁实战可编辑 PPTX 交付前的几何、可访问性与 OOXML 包完整性审计指南【免费下载链接】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-quality-gates技能展开讲解在交付一份可编辑、可用于生产环境的 PowerPoint 演示文稿前如何以一套确定性审计清单对几何布局、可访问性、原生可编辑性、来源追溯source lineage与 OOXML 包完整性进行逐项把关并将确定性失败视为修复工作而非异常跳过。读完本文你将掌握该质量门禁的完整工作流、构建前/构建后共 14 项审计要点、包级验证工具validate_package.py的底层校验逻辑以及如何用修复规格 → 重建 → 重跑同一套检查的闭环方式把 PPTX 提升到可交付状态。一、质量门禁在插件中的定位pptx-quality-gates是 pptx-deck-creation 插件五大技能之一其核心职责是在生成 PPTX 之后、交付之前对产物做最后一道确定性检验。技能描述将其适用场景定义为Use when validating or repairing an editable PPTX deck for geometry, accessibility, native editability, source lineage, and OOXML package integrity.也就是五个维度几何geometry、可访问性accessibility、原生可编辑性native editability、来源追溯source lineage、OOXML 包完整性OOXML package integrity。这一技能与插件内的其他技能形成明确的分工闭环pptx-deck-context负责在写坐标之前准备好商业叙事、来源清单与设计锁定design lockpptx-slide-specification负责产出以英寸为单位的坐标显式 JSON 规格layout_tree布局契约 明确定义了summary与slides的 JSON 结构pptx-reference-deck-analysis以只读方式分析参考 deck 与 OOXML 包pptx-quality-gates则在整个流程的收尾阶段把关质量。关键原则在 SKILL.md 第 8 行即已点明Treat deterministic failures as repair work, not exceptions.把确定性失败当作修复工作而不是异常跳过。这意味着该技能拒绝差不多就行的交付态度凡是能通过确定性规则判定为不合格的项都必须进入修复流程。二、完整工作流七步质量门禁SKILL.md 定义了标准工作流共七步覆盖构建前检查 → 构建 → 构建后复核 → 修复 → 复检的完整闭环确认规格、构建器、PPTX、来源清单source manifest与审计路径spec、builder、PPTX、source manifest、audit paths均已就位。构建前将references/audit-checklist.md应用到坐标契约coordinate contract上——即在真正生成 PPTX 之前先用审计清单审查 JSON 布局规格。重新打开 PPTX将实际幻灯片数量、实际边界actual bounds、隐藏幻灯片状态与请求的几何尺寸同布局树layout tree逐项比对。生产级 deck 必须运行pptx-reference-deck-analysis/scripts/validate_package.py并保存 JSON 报告报告文件与 deck 一起保留。检查文档语言document language、幻灯片标题、有意义图片的替代文本alt text、阅读顺序reading order、表格表头table headers与来源引用source references。仅在兼容的渲染器已经可用时检查预览中的裁切clipping、字体回退font fallback、对比度contrast、裁剪crop与层级hierarchy。严禁为此新增渲染器依赖。修复规格spec或任务局部的构建器task-local builder重建并重跑同一套检查。第 7 步是整个技能的方法论核心修复的对象是规格或构建器而不是在产物上打补丁修复后必须重建 重跑同一套检查确保修复真正生效且没有引入新问题。第 6 步特别值得注意——它把渲染器预览定位为可选增强而非必需环节。仓库明确不内置渲染器README 的 Boundaries 一节指出该插件只会在需要 PPTX 时创建一个小的任务专属python-pptx构建器不携带通用渲染器、不克隆模板、不需要浏览器、不使用 MCP 服务器、不需要凭据或在线服务。预览检查因此被限定为如果环境中已有兼容渲染器才执行避免为审计引入新的基础设施依赖。三、构建前审计十项坐标契约检查references/audit-checklist.md的Before build部分规定了在生成 PPTX 之前必须对布局规格执行的十项检查。这些检查全部作用于坐标层属于可以在构建前静态判定的确定性规则1. 内容碰撞Content collisions内容包围盒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满足该条件即视为两个 bbox 在平面上相交。构建前审计要遍历所有内容对象确保任意两个content分类的对象不发生相交。2. 文本容量Text capacity对可能溢出的文本优先采用缩短文案、调整字号大小或拆分幻灯片三种手段之一。针对 CJK/全角文本清单特别要求将估算的每行字符数减半——因为中文等全角字符的视觉宽度显著大于半角字符按西文经验估算极易溢出。3. 字号体系Type scale正文内容字号不得低于 9 pt。这一底线同时出现在 pptx-slide-specification 的 SKILL.md 中Keep content text at 9 pt or greater并在布局契约的 Repair order 里进一步规定了顺序先调整 bbox再缩短文案最后才是调整字号且永不跌破 9 pt。4. 设计上下文Design contextsummary.design_context必须指明一个样式锁定style lock或经批准的设计来源。拒绝默认主题、纯标题项目符号title-and-bullet的默认输出除非用户明确要求。这与pptx-deck-context技能中设计引用是设计证据而非内容来源的规则相呼应——每一页的坐标与样式都必须独立创作不能依赖自动排版引擎兜底。5. 布局策略Layout policy内容必须保持在安全边距safe margin之内、位于页脚栏footer rail之上只有layout_design分类的背景对象可以出血full bleed。布局契约示例中给出的默认值见 layout-contract.md为safe_margin: 0.5、content_bottom: 6.7、footer_top: 6.85、minimum_gap: 0.12单位均为英寸这是 13.333×7.5 英寸16:9画布下的典型取值。6. 包含关系Containment子对象必须完整落在其父组group之内形状内文本必须尊重内边距inner padding。7. 表格Tables列宽之和必须等于表格整体 bbox 宽度文本自动换行后不得溢出长表格必须拆分split避免超出单页可容纳范围。8. 原生可编辑性Native editability标题、标签、数值、图表与解释文字必须保持为原生 PowerPoint 对象图片只承担辅助support角色。这是该插件区别于整页截图式 PPT的根本要求——构建器 Agent 的 Non-negotiable rules 同样强调绝不使用整页图片作为幻灯片的有意义内容。9. 来源追溯Lineage所有有来源的主张sourced claims必须具备可解析的来源 IDsource ID、定位符locator、主张类型claim type与验证状态verification status。这与pptx-deck-context中为每个指标、引语、图表数值与事实性主张分配稳定来源 ID 并规划source_ref的要求衔接保证审计时可逐条回溯。10. 正向几何Positive geometry每个对象都必须具有正数尺寸构建前必须规范化线条端点normalize line endpoints。构建器在添加对象前要拒绝零尺寸或负尺寸的几何见 pptx-slide-specification 的 Build contract。四、构建后审计四项包级与文档级复核构建完成并重新打开 PPTX 后清单规定了四项复核Audit checklist 第 11–14 项11. 重新打开包并比对规格将实际幻灯片数量、实际边界、隐藏幻灯片状态hidden-slide state与请求的几何同规格逐项比较。注意这里强调重新打开reopen——不是信任构建器内存中的对象模型而是读取磁盘上 PPTX 包的实际内容防止构建过程中对象状态与序列化结果不一致。12. 可访问性检查检查可访问标题accessible titles、文档语言language、阅读顺序reading order、有意义图片的 alt text、表格表头table headers。语言信息在布局契约中通过summary.accessibility.language声明示例为en-USPPTX 包中的语言还关联到主题/主版定义审计需确保声明的语言与实际内容一致。13. 运行 OOXML 包验证器执行validate_package.py修复畸形 XMLmalformed XML、损坏的内部关系broken relationships、内容类型缺失content-type gaps、重复的版式链接duplicate layout links。被接受的警告accepted warnings必须记录在案。14. 渲染器预览条件性当兼容渲染器已安装时检查预览中的裁切、字体回退、对比度、裁剪与层级。再次强调不得为此引入渲染器依赖。构建后审计与构建前审计的分工很清晰前置检查作用于意图规格 JSON后置检查作用于事实序列化后的 OOXML 包。两者都对上交付才有依据。五、源码级解读validate_package.py 的校验逻辑第 4 步与第 13 步反复提到的validate_package.py位于 scripts/validate_package.py。它由pptx-reference-deck-analysis技能提供属于只读 OOXML 工具链。其入口契约python validate_package.py deck.pptx --output report.json下面逐层剖析它的校验实现帮助理解包完整性在代码层面究竟检查什么。5.1 命令行与工作区安全main()使用argparse接收两个参数deck当前工作区内的 PPTX 文件与可选的--output工作区内的 JSON 报告路径。两个路径都经过_workspace_path()处理其实现为将当前工作目录Path.cwd().resolve()作为根对传入路径expanduser().resolve()用is_relative_to(root)校验解析后的路径必须位于工作区内否则抛出ValueError: Path escapes the current workspace。这是第一道安全边界验证器只能读取工作区内的文件防止通过参数逃逸到任意路径。此外还校验deck 必须是存在的.pptx文件且--output不得与输入 deck 相同防止覆盖输入。退出码语义校验通过返回 0发现错误返回 1输入/IO 级异常返回 2。结果统一以 UTF-8 JSON 输出到 stdout_write_stdout直接写字节流规避控制台编码问题指定--output时同时写入报告文件。5.2 归档安全阀防压缩包炸弹_validate_archive()在解压前对 ZIP 归档本身执行四项硬性限制源码第 20 行定义了常量限制项常量值作用最大成员数MAX_MEMBERS 5_000防止海量小文件拖垮解析单成员最大解压尺寸MAX_MEMBER_SIZE 100 MB防止单个超大部件总解压尺寸MAX_TOTAL_SIZE 512 MB防止整体解压炸弹最大压缩比MAX_COMPRESSION_RATIO 1_000防止高压缩比炸弹zip bomb同时检查每个成员的external_attr高位是否为符号链接stat.S_ISLNK发现 symlink 直接报错。这对应 SKILL.md 中脚本拒绝路径穿越、符号链接、超大成员与压缩包炸弹的安全承诺。5.3 XML 良构性检查对所有.xml与.rels成员用defusedxml.ElementTree而不是标准库xml.etree逐一fromstring解析任何解析异常都会被记为xml_well_formed错误。使用defusedxml是关键安全决策——它从底层禁用实体扩展entity expansion与 DTD 加载这正是防御 OOXML 中 XXEXML 外部实体攻击的标准做法。该依赖在 requirements.txt 中锁定为defusedxml0.7,1。5.4 内容类型Content Types校验_content_types()读取[Content_Types].xml分别解析Default按扩展名映射与Override按部件路径映射两类声明。校验逻辑若包中缺少[Content_Types].xml直接报content_types错误对每个ppt/slides/slide*.xml其Override内容类型必须精确等于application/vnd.openxmlformats-officedocument.presentationml.slidexml源码中的SLIDE_CONTENT_TYPE常量否则报content_type错误。这保证了 PowerPoint 打开文件时能正确识别每个幻灯片部件。5.5 内部关系Relationships校验每个.rels部件被解析为{rel_id: {type, target, mode}}映射。对mode ! External的关系_target()将关系目标解析为包内路径绝对路径以/开头直接规范化相对路径按.rels所在部件的父目录拼接后再规范化posixpath.join(posixpath.dirname(source), value)解析结果若为空、.、..或逃逸到包外../前缀返回None。关系目标的解析始终以.rels属主部件为基准——这正对应pptx-reference-deck-analysisSKILL.md 中的规则Resolve relationship targets relative to the.relsowner; never infer slide order from filenames按.rels属主解析关系目标绝不从文件名推断幻灯片顺序。解析后若目标不存在于包内或非法报internal_relationship错误合法目标被收集进referenced集合供后续孤立部件检查使用。5.6 幻灯片顺序与版式关系校验对ppt/presentation.xml遍历所有p:sldId用Counter检查是否存在重复的幻灯片 idslide_id_unique检查每个sldId引用的关系 id 必须存在于ppt/_rels/presentation.xml.rels中且关系类型必须以/slide结尾否则报slide_relationship错误声明到的幻灯片被收集进declared_slides集合。对每个ppt/slides/slide*.xml未在presentation.xml中声明的幻灯片部件记为unlisted_slide警告每张幻灯片的.rels中必须恰好存在一条slideLayout关系len(layouts) ! 1即报slide_layout_relationship错误——这正对应审计清单第 13 项中的重复的版式链接duplicate layout links检查。5.7 孤立部件检查最后对ppt/media/下所有成员与ppt/notesSlides/notesSlide*.xml若不在referenced集合没有任何入站内部关系引用则记为orphaned_media/orphaned_notes警告。孤立部件虽不致命但会增大包体积并可能造成行为不一致因此作为警告而非错误输出。5.8 报告结构validate()返回结构化字典deck路径、ok是否零错误、error_count、warning_count、errors与warnings其中每条记录都含part部件路径、check检查类型名与message可读描述。errors中的check字段覆盖xml_well_formed、content_types、internal_relationship、slide_id_unique、slide_relationship、content_type、slide_layout_relationship、slide_order等。这份 JSON 正是质量门禁工作流第 4 步要求保存的审计产物应随 deck 一起交付归档。六、质量门禁六维通过标准与例外报告SKILL.md 的 Pass criteria 定义了交付判据可归纳为六个维度零内容碰撞Zero content collisions零文本溢出Text overflows零不安全内容边界Unsafe content bounds零无效正向几何Invalid positive geometry零包完整性错误Package-integrity errors原生可编辑性成立有意义的幻灯片内容必须保持为原生可编辑对象图片只起支撑作用images support rather than replace it。在全部通过与存在失败之间还有第三条被显式允许的路径——记录在案的例外documented exception。SKILL.md 的 Required artifacts 一节规定规格spec、PPTX、构建记录build record、几何审计geometry audit、可访问性审计accessibility audit、包报告package report与来源清单source manifest必须保存在一起任何例外都必须注明幻灯片 ID、对象 ID、责任人owner、原因reason与审查日期review date。审计清单的收尾句同样强调交付要求所有检查通过或每个例外都标识出 slide ID、object ID、reason、owner 和 review date。七、修复顺序从最小干预到重建复检当审计发现失败时修复不是随意的pptx-slide-specification的布局契约给出明确的 Repair order先动布局移动或调整 bbox 尺寸、改变 z 顺序、或将内容密集的幻灯片拆分再动文案缩短文案或扩大可用文本 bbox最后动字号仅在万不得已时调整字号且正文永不跌破 9 pt重建并比对重建后将实际对象边界与契约contract重新比对。这一顺序体现了坐标显式、规格优先的设计哲学规格 JSON 是审计契约audit contract而不是渲染提示rendering hint——layout-contract.md 第 3 行的原文即The final tree is an audit contract, not a rendering hint. 修复必须回到规格或任务局部构建器层面重建后重跑同一套质量门禁检查直到通过或例外全部归档。八、配套技能与工具链协作一览质量门禁不是孤立的它依赖插件内其他技能的产物协同工作技能相对路径与质量门禁的关系PPTX Deck Contextskills/pptx-deck-context/SKILL.md提供叙事框架、来源清单与设计锁定支撑design_context与source_ref两项审计PPTX Slide Specificationskills/pptx-slide-specification/SKILL.md定义坐标契约与修复顺序是几何审计的判定基准PPTX Reference Deck Analysisskills/pptx-reference-deck-analysis/SKILL.md提供validate_package.py等只读 OOXML 工具链与安全解析规则PPTX Visual Assetsskills/pptx-visual-assets/SKILL.md约束图片资产仅作支撑、必带 alt text支撑原生可编辑性与可访问性审计Deck Creation Builderagents/pptx-deck-creation-builder.md执行规格先行 → 构建 → 审计 → 修复 → 重建的整体工作流工具链的运行前提同样需要明确validate_package.py依赖defusedxmldefusedxml0.7,1使用前按 requirements.txt 安装任务局部的高层抽取如读取幻灯片文本摘要可额外使用python-pptx。所有 OOXML 脚本都设计为只读——SKILL.md 强调源幻灯片永不复制、克隆或修改质量门禁针对的是新生成的产物参考 deck 始终不可变。结语把 PPTX 交付从看起来对提升到可验证的对pptx-quality-gates给出的是一套可执行、可复现、可归档的质量基线构建前用 10 项坐标契约检查约束意图构建后用 4 项复核与validate_package.py的 8 类包级检查约束事实中间以修复规格 → 重建 → 重跑同一套检查的闭环保证修复质量最终以六维零失败 例外四要素归档作为交付判据。对于需要产出可编辑、生产级 PowerPoint 的 Agent 工作流而言这套门禁把设计质量从主观审美问题转化为可由确定性规则判定的工程问题——这正是它在当前仓库中被定位为交付前强制关卡的原因。【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考