PPTX 视觉素材治理指南：为可编辑 PPTX 幻灯片选择与放置图标、图片、SVG、图表与信息图

PPTX 视觉素材治理指南：为可编辑 PPTX 幻灯片选择与放置图标、图片、SVG、图表与信息图

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

本篇技术指南以plugins/pptx-deck-creation插件中的pptx-visual-assets技能（Skill）为主体，系统讲解在"可编辑 PPTX 幻灯片"生产流程中如何选择、验证与放置辅助性视觉素材：从素材类型判定、来源与版权核查，到基于英寸 bbox 的精确放置、z-index 层级控制，以及"素材服务于信息、绝不替代原生内容"这一核心纪律。读者学完后，将掌握一套可直接落地的视觉素材放置流程、判定规则与质量红线，能够在 pptx-deck-creation 插件 的 spec-first 工作流中产出既专业美观又保持完全可编辑的演示文稿。

一、技能定位：素材是"支持"而非"替代"

pptx-visual-assets技能的开篇即给出其存在前提：

Use visual assets to support a slide's message, never to flatten or replace editable content.

这句话是整个技能的灵魂。在pptx-deck-creation插件所定义的"可编辑、生产级 PowerPoint 交付"边界内，插件 README 明确承诺提供 "Native editable PowerPoint text, shapes, lines, tables, connectors, and supporting images"——即文本、形状、线条、表格、连接符以及作为支持的图片。可见图片（及图标、SVG、图表、信息图）从一开始就被限定为supporting角色：

• 标题、说明、标签、指标、表格、图表与示意图必须使用原生 PowerPoint 对象承载；
• 图片只负责增强表达、辅助理解，不得把关键信息"拍扁"进一张图里，从而牺牲可编辑性、可检索性与无障碍性。

这与构建器 Agent 的硬性规则一脉相承：pptx-deck-creation-builder.md 中同样写明 "Use native objects for titles, explanations, labels, metrics, tables, charts, and diagrams. Images are supporting visuals only." 可以推断，该技能正是这条全局纪律在"素材放置"环节的具体执行细则。

二、四步工作流：从判定到放置

SKILL.md将素材处理收敛为清晰的四步流程，任何一次素材引入都必须依次走过：

第 1 步：仅在提升理解时选择素材类型

可选素材类型共五种：icon（图标）、image（图片）、SVG、diagram（图表）、infographic（信息图）。选择标准是"是否提升理解"（improves comprehension），而非"页面是否太素"。若素材不能帮助受众更快、更准地理解信息，就不应该被引入。

第 2 步：放置前确认四项元信息

• 本地路径（local asset path）：素材在文件系统中的确切位置；
• 来源（source）：素材出处（来源 URL 或提供方）；
• 使用权限（usage rights）：是否允许在此场景使用；
• 简洁的替代文本（concise alt text）：无障碍描述。

这四项信息在放置之前就必须确认完毕，而不是放置之后再补。这与技能规则中"Record provider or source details in the source manifest"（记录到 source manifest 中）的要求衔接。

第 3 步：带精确几何的放置

放置时必须给出三个关键参数：

• 最终英寸 bbox（final inch bbox）：以英寸为单位的最终边界框，对应layout_tree契约中每个对象的bbox字段；
• 有意的 z-index（deliberate z-index）：明确的层叠顺序；
• 分类（classification）：归入content（内容）或layout_design（布局设计）。

这些参数并非随意的实现细节，而是pptx-slide-specification技能的硬性契约。在 布局契约示例 中可以看到，layout_tree中每个对象都要求携带id、kind、role、classification、content、style、bbox、z_index八个字段；其中classification直接决定对象是否可出血（full bleed）——规范要求"只有背景layout_design对象可以全出血，普通内容必须保持在安全边距内、页脚轨道之上"（见 pptx-slide-specification/SKILL.md）。

第 4 步：放置后校验

• 保持宽高比（preserve aspect ratio）：不得随意拉伸变形；
• 不得遮挡可读文本：任何素材不得覆盖可读文字；
• 不得把关键信息锁死在图片里：如果一张图承载了观众必须看到的数据或结论，就必须用原生对象重建这些信息。

四步流程形成一个闭环：判定 → 核验 → 精确放置 → 校验。后文将逐一展开每一条背后的规则与依据。

三、六条放置规则详解

规则 1：图标必须简单、可读，并与文字标签并排

Use simple, legible icons alongside text labels.

图标的价值在于快速识别。复杂花哨的图标在 0.5 英寸的占位内往往无法辨认，反而制造认知负担。图标应与文字标签并排（alongside）出现，形成"图形 + 文字"的互补，而不是让图标孤零零地自证含义。

规则 2：说明文字放在图片旁边，而不是压在图片上

Place captions beside images rather than over them.

说明文字叠压在图片上会同时伤害两件事：文字的可读性（背景图案干扰）与图片的完整性。正确做法是在图片相邻的空间放置说明文字。这与 asset-guidance.md 的 Placement 章节完全一致："Put a caption in adjacent space, not over the image." 这也意味着在规划layout_tree时，要为图片和说明文字分别预留独立的 bbox，而不是共用一个区域。

规则 3：只使用"真 SVG"，严禁栅格图套 SVG 冒充矢量

Use true SVG sources only when they are clean vectors; never wrap a raster image in SVG and call it editable.

SVG 的价值在于可缩放、可编辑的矢量。如果一张 PNG 只是被塞进一个<svg>包装里，那么它仍然是栅格图——放大依然会糊、信息依然无法以文本形式被检索。这种"伪 SVG"绝不能标注为可编辑视觉。判断标准很直接：该 SVG 内部是否是干净的路径、形状等矢量指令；凡是承载了必须可读的文字、图例、数值的内容，都应改用原生 PowerPoint 对象重建。

规则 4：关键标签、图例、数值与流程步骤必须用原生对象重建

Recreate essential labels, legends, values, and process steps with native PowerPoint objects.

这是"绝不 flatten 内容"原则在具体对象类型上的展开。即使引入了一张信息图或参考图表，其承载的关键信息也必须以原生 text / shape / line / table 对象的形式重建到幻灯片上。这样：

• 观众可以选中并阅读每一个数字与标签；
• 屏幕阅读器可以通过阅读顺序访问这些信息（对齐 pptx-quality-gates 中的无障碍检查）；
• 信息可以被修订、翻译、更新，而不必重新出图。

在 asset-guidance.md 的 SVG constraints 与 Infographics 两节中，这一要求被重复强调："Recreate essential text, legend entries, metric values, and process labels with native PowerPoint objects"，以及"recreate their essential information as native objects"。

规则 5：权限不明或素材不可得时，宁可省略并上报缺口，绝不占位

If rights, provenance, or a suitable asset are unavailable, omit the asset and report the gap. Never add a placeholder as a finished visual.

这条规则同时约束了两个错误倾向：

1. 硬塞：没有合适的素材也要凑一个——禁止；
2. 占位：用 "image placeholder" 之类的占位框充当最终视觉——同样禁止。

正确动作是：省略素材，并明确上报缺口（report the gap）。这与构建器 Agent 的规则 "Do not invent missing brand, source, license, or accessibility facts. State the gap and request a decision." 完全同构——不知道的事实就如实申报，请用户决策，而不是自行编造。

规则 6：来源必须记入 source manifest，机密绝不在对话中出现

Record provider or source details in the source manifest. Never request secrets in chat.

每一条素材的提供方 / 来源信息都要记录进 source manifest（来源清单）。在 asset-guidance.md 的 Provenance 一节中，要求记录四项：本地路径、来源 URL 或提供方、使用权限、简洁 alt text；"If rights are unknown, do not use it"（权限不明即不用）。同时，"Never request secrets in chat" 意味着素材获取过程中涉及的任何凭据都不应通过对话传递——需要保密的信息走受控渠道，而非聊天明文。

四、来源管理与版权红线：Provenance 四要素

references/asset-guidance.md将素材的溯源（Provenance）作为放置的第一前置条件。引入任何外部素材前，必须先记录：

这一要求与 pptx-deck-context 的设计纪律相互呼应——该技能要求 "Do not copy external fonts, images, icons, or logos without recorded licensing evidence"（未经记录的许可证据，不得复制外部字体、图片、图标或 Logo）。也就是说，素材的版权核验从叙事与设计准备阶段就已开始，视觉素材技能是在放置环节做最终把关。

五、与 layout_tree 契约的衔接：bbox、z-index 与 classification

pptx-visual-assets的放置规则不是孤立约定，而是直接对应 layout-contract.md 中的 JSON 契约。以下面这个契约片段为例，可以直观看到素材对象在layout_tree中的形态：

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

对照此契约，素材对象应遵循以下映射关系：

• final inch bbox→ 对象上的bbox字段，单位英寸，正值且不越界。pptx-slide-specification明确要求 "Reject zero or negative geometry before adding an object"（加入对象前拒绝零或负几何）。
• deliberate z-index→z_index字段。放置素材时，要保证素材低于可读文字的 z 值，从而"不遮挡文字"。asset-guidance.md 原文："Keep visual assets below overlapping readable text in z-order."
• classification→classification字段，取值content或layout_design。背景装饰类素材可归为layout_design从而允许全出血；承载信息的素材归为content，必须待在安全边距内。

此外，构建契约要求任务本地构建器从空白版式出发，以Inches(...)映射全部 bbox，并显式设置图片宽高比（image aspect ratio）、隐藏幻灯片状态等（见 pptx-slide-specification/SKILL.md 的 Build contract）。可见"放置素材"最终落到构建器对image对象的显式参数设置，而非依赖自动布局引擎的推断。

六、空间约束：素材不得挤占剩余空间

asset-guidance.md 的 Placement 部分还给出了一条容易被忽略的空间守恒规则：

If an asset produces zero or negative remaining space, omit it and repair the layout.

即：如果引入素材后，幻灯片剩余空间变为零甚至为负，那么宁可舍弃该素材并修复布局，也不要压缩其他内容去硬塞。这保证了版面始终有呼吸感，也直接支持 layout-contract.md 中layout_policy.minimum_gap（最小间距）这类参数的成立——间距与留白是契约的一部分，不是可牺牲项。

七、质量门禁与验证：素材如何被审计

素材放置完成后，交付前的审计由pptx-quality-gates技能接管。该技能在验证阶段会检查（详见 pptx-quality-gates/SKILL.md）：

• 有意义图片的 alt text：对应素材技能要求的"concise alt text"，缺失或空泛会被视为缺陷；
• 阅读顺序（reading order）：确保标题、正文与图片说明的可访问顺序合理；
• 零内容碰撞（zero content collisions）：任何素材不得与文本或其他对象发生重叠冲突；
• 图片是支持而非替代：通过审计确认 "meaningful slide content must remain native editable objects; images support rather than replace it"。

同时，生产级交付还会运行 validate_package.py 对 OOXML 包做完整性校验（成员数量、成员大小、总解压大小、压缩比、符号链接、关系完整性等），并输出 JSON 报告。这些检查保证了含图片的最终.pptx是一个结构合法、可被 PowerPoint 正常打开的包，而不是只"看着像"的产物。

八、素材类型速查与决策清单

将全篇规则浓缩为一张决策表，便于在实际放置时逐项对照：

九、总结：一条可执行的核心纪律

pptx-visual-assets技能的全部内容可以归结为一句话：视觉素材是用来"支持"幻灯片信息传达的，永远不能用来"替代"可编辑内容。围绕这句话，它给出了从类型判定、来源核验、精确几何放置（英寸 bbox + z-index + classification）、宽高比保持、空间守恒，到"权限不明即弃用、缺口如实上报"的完整执行链路，并与插件内的 layout 契约、质量门禁 和 OOXML 包校验 形成相互咬合的治理体系。

在实际项目中使用时，只需沿着本指南第八节的决策清单逐项核对，即可保证每一次素材放置都同时满足：信息可编辑、来源可追溯、布局无碰撞、包结构合法。这就是在 spec-first 的可编辑 PPTX 生产流程中，让"美观"与"可编辑"不再冲突的关键所在。

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