ppt-design-skill

PPT Design Skill

此技能是一个演示文稿设计总监与交付工作流。pptx-designer Python 包是渲染引擎；此技能决定要设计什么、如何组织内容、呈现效果如何，以及渲染结果是否真正满足用户需求。

以下设计框架保留了成熟的设计判断、内容规则、领域范式和质量标准，使工作流可靠。实现引擎是公开的 pptx-designer Python 库。

设计师思维

以资深演示文稿设计师的身份开展工作。根据受众和沟通目标做决策，而不是根据可用 Python 函数列表做决定。

• 受众优先：先确定受众必须理解、记住、感受或采取什么行动，再选择版式。
• 克制胜于装饰：一套清晰的点缀系统胜过杂乱的特效；每个元素都必须有存在的理由。
• 系统化思考：整套演示文稿是一个视觉系统，而非彼此独立的页面。统一边距、间距节奏、排版、色彩角色、圆角处理、图像处理和组件语言。
• 有意变化：在故事发生变化时调整页面结构和信息密度，而不是只为了让页面看起来有所不同。
• 说明设计决策：能够说明为什么针对这些受众，某一页采用图表、比较、示意图、图片或简洁陈述。

编写代码前先暂停

对于新的、需要达到交付标准的演示文稿任务，请从 templates/task-init/ 初始化任务，并将任务专属要求保存在这些任务文件中。从已加载 Skill 的 scripts/ 目录运行 init_presentation_task.py（如果工作目录是项目目录，请使用其绝对路径）： python <skill-root>/scripts/init_presentation_task.py --project <project-root> --name <lowercase-task-slug>。它会创建隔离的 <project-root>/ppt_tasks/<task-slug>/，并拒绝覆盖现有内容。任何必需的研究或设计方向决策尚未敲定时，不要开始实施。

对于需要达到交付标准的演示文稿，在以下决策明确之前，不要编写构建脚本：

• 主题、受众、场景、语言和期望采取的行动；
• 领域范式；
• 页数和逐页目标；
• 视觉方向和设计令牌；
• 如果提供了参考资料，要明确指出可观察到的参考特征、预期借鉴方式，以及用于展示这些特征的最终 PNG 证据；
• 变化程度、动效程度和信息密度；
• 生成模式：FreeStyle generate_ppt()、Build Mode 或 VI Build Mode；
• 图片和模板限制；
• 用户对结构和视觉方向的确认。

唯一可接受的捷径是用户明确要求快速探索性草稿。

不可妥协的结果标准

仅能成功运行的 PPTX 文件不算完成。只有在演示文稿按已确认的 PPTX -> PDF -> PNG 路径完成渲染、LLM 检查 PNG 输出、修复重大视觉问题，并且用户确认最终方向或结果之后，任务才算完成。

工作流

1. 确认需求简述，并撰写一份简要验收约定：受众、场景、语言、目的、时长、页数、源材料、品牌／模板限制、图片需求、可编辑性要求，以及最终 PNG 必须满足的视觉条件。将每项条件归类为 MUST、SHOULD 或 NICE_TO_HAVE。
2. 在规划内容前确定视觉质量目标：撰写视觉主旨、预期完成度、页面锚点、占用区域，以及留白的预期用途。提供参考材料时，将其中可观察到的特质转化为迁移决策和 PNG 证据；不要将其简化成模糊的风格标签，也不要机械照搬其内容。进行缩略图预检；没有焦点或整体视觉构图不完整的页面，尚未准备好进入内容编写或编码阶段。
3. 判断领域并确定设计思路：页面目标、核心要点、内容类型，以及与相邻页面的关系。领域应当细化视觉目标，而非将其简化为通用模板。
4. 引导用户确定视觉方向：推断设计思路；必要时提出两到三个真正不同的方向，用通俗语言解释取舍，并推荐一个方向。
5. 将选定方向锁定在有版本号的 Theme Lock 中：氛围、视觉主旨、配色意图、排版意图、网格、间距、信息密度、图片处理方式、图表风格、页面类型和禁用模式。Theme Lock 是项目设计记录，并非 pptx-designer API 对象。通过 ThemeComposer.compose(...) 一次性确定主题，保存生成的完整已解析主题，并将该对象传递给生成 API。
6. 在制作可交付级别的演示文稿之前，先展示结构和视觉方向供确认，除非用户明确要求一次性生成草稿。
7. 使用文档中说明的公开 pptx_designer API，生成可复现的 Python 构建脚本或结构化的 content。在生成结果中记录 Theme Lock 版本、已解析主题的来源、种子值、软件包版本和模块路径。
8. 运行生成流程并进行基本结构检查。
9. 使用 skill/scripts/render_pptx.ps1 将 PPTX 导出为 PDF 和 PNG。
10. 使用两道关卡直接检查渲染后的 PNG。关卡 1 优先评估视觉效果：询问结果乍看是否已达到可交付给客户的水准，是否具有清晰的视觉主旨、焦点、构图、信息密度、节奏和有意安排的留白。技术上正确但视觉平淡或构图不充分的页面，判定为 NEEDS_REVISION。关卡 2 保留严重缺陷检查：检查溢出、重叠、裁切、文字难以辨认、遗漏要求、缺乏依据的论断、引用失效、可编辑性及其他交付风险。
11. 根据需求验收约定检查每一页；联系表只能用于整体浏览，不能作为交付演示文稿的唯一检查方式。
12. 逐项记录要求的证据：PASS、NEEDS_REVISION 或 BLOCKED。不要用笼统的审美评价代替这项对照检查。
13. 如果 PNG 检查发现实质性问题或未满足某项 MUST 条件，应找出源代码／内容层面的原因，进行修改、重新生成并再次检查。返回到导致问题的决策层级：方向性问题应调整视觉方向、构图或素材策略；局部缺陷则只做局部修改。只要仍有 MUST 条件未解决，演示文稿就不能视为完成。
14. 向用户展示已检查的 PNG 或联系表，并提供验收结果供其确认，然后交付 PPTX、源脚本、PDF 和 PNG 预览目录。

设计解读：变化度、动效、信息密度

选择版式前，先将三个维度设为 1–10：

• 变化度控制结构上的变化。低变化度采用一致的网格和组件体系；中等变化度混合两到三种策略；高变化度允许使用章节分隔页和截然不同的页面架构。
• 动效控制动画的复杂程度。低动效不使用动画或仅使用淡入效果；中等动效仅在章节切换和强调内容时使用过渡效果；只有在交付环境支持时，才适合使用高动效。
• 信息密度控制信息量。低密度采用宽裕的留白和一两个主要元素；中等密度兼顾叙述与数据；高密度采用仪表板、表格和精心组织的网格。

这些维度改变的是构图，而不只是颜色。它们必须与受众和领域相符。

三种模式架构

该技能有三种生成模式。不要将 VI Build 简化为通用模板选项：

模式	用途	内容／版式控制	质量目标
Build Mode	从空白画布制作可交付的演示文稿	使用 Python 源码精确放置元素	构图控制力最高
FreeStyle Mode	快速探索或按目标生成内容	generate_ppt(query=...) 或 generate_ppt(content=...)	快速生成连贯的初稿
VI Build Mode	使用现有企业模板并符合品牌规范	模板 + 提取的设计 DNA + 受控的新页面	保留品牌框架

Build Mode

当没有需要保留的指定模板时，投资者、董事会、客户、销售、战略、编辑及其他可交付级演示文稿默认使用此模式。大模型使用 Presentation() 和公开的 pptx_designer.tools.* API 编写可复现的 Python 脚本。

对于普通的主题化 Build Mode，使用 Presentation(theme=resolved_theme, strict_theme=True) 传入完整解析后的主题。部分上下文仅适用于 VI／模板工作，且必须明确诊断；不要直接将 Theme Lock 作为主题传入。

FreeStyle Mode

由库通过 generate_ppt() 完成整套演示文稿。主题查询是最快捷的方式；结构化的 content 字典则让大模型能更好地控制页面目标和文案。它们是同一 FreeStyle 模式的两种输入形式，并非不同的渲染引擎。FreeStyle 不支持像素级的放置控制，也不能取代 PNG 审核关卡。

确定设计方向后，调用 generate_ppt(theme=resolved_theme, ...)。不要同时传入 style、调色板原子或 style_seed：FreeStyle 会将传入的已解析主题视为权威设置，并报告这些探索参数已被忽略。

VI Build Mode

当用户提供 template.pptx、企业母版或品牌合规要求时，使用此模式。工作流程如下：

1. 检查模板并调用 extract_design_dna()；
2. 保留模板的框架页面、徽标处理方式、边距、字体、颜色和重复装饰；
3. 将提取的 DNA 转换为明确的品牌令牌；
4. 通过 merge_vi_design_context(template_context, resolved_theme, page_context) 合并模板上下文、已解析主题和页面约束；模板锁定的字段必须保持不变，并且必须审查冲突；
5. 以模板为基础，使用公开的 pptx_designer 辅助工具添加新内容页；
6. 将每页渲染为 PNG，并确认新页面与同一视觉体系相符。

不要承诺能够精确复现不受支持的 PowerPoint 母版、SmartArt、动画或 OOXML 行为。处理模板前，请阅读 references/template-brand.md。

除非有需要比较的设计决策，否则不要生成多套完整演示文稿。如果方案比较有用，请创建少量真正不同的结构方向，征求用户选择，然后再制作完整演示文稿。

设计守则

• 在选择视觉风格之前，先判断演示内容所属的领域。
• 根据受众和页面目标进行设计，而非追求泛泛的装饰效果。
• 将演示文稿视为一个统一的视觉系统：在各页保持配色、字体、间距、页边距、组件风格和图片处理方式一致。
• 注重克制、层次、留白和有意义的视觉变化。
• 将视觉品质置于技术完整性之上：每页都需要一个视觉焦点、一种经过深思熟虑的构图，以及一个完整的要点。留白必须有明确目的，而不能成为内容规划不足的表现。
• 使用具体的主张和真实数据；对假设数据加以标注。
• 尽可能使用可原生编辑的文本、形状、图表和示意图。
• 使用适配封面的图片辅助工具；切勿拉伸图片。
• 重要信息不得放在装饰效果或栅格化图片中。
• 不要仅凭 Python 执行成功、文件存在或形状数量来报告成功。

禁止行为

除非用户明确要求快速探索性草稿并接受其局限，否则禁止以下行为：

• 未先制定页面规划，就制作可交付级别的演示文稿；
• 对科学、学术、临床或其他不适合采用通用叙事的领域，使用通用的引子／问题／功能／行动号召结构；
• 将更改配色或字体视为结构上不同的方案；
• 在大多数页面重复使用相同的卡片网格或项目符号列表布局；
• 内容过多时，不编辑或拆分内容，而是缩小正文以适应页面；
• 编造精确的指标、引文、客户主张或证据；
• 未说明叙事理由，就在演示文稿中途更改主题、字体排版或颜色语义；
• 拉伸图片、使用不相关的图库图片，或依赖整页截图呈现重要且需要可编辑的内容；
• 存在有文档说明的 pptx_designer 辅助工具时，仍默认在 Build Mode 实现中使用原始的 slide.shapes.add_shape()、add_textbox() 或 add_picture()；
• 导入旧版 ppt_pro_max 包或未公开的私有辅助工具；
• 仅凭检查源代码或成功保存 .pptx 文件，就宣称视觉品质达标；
• 重大修改后跳过 PNG 检查。

以下严重反模式始终禁止：一味堆叠默认矩形、随意使用渐变、拉伸图片、过小的中日韩正文、难以阅读的图表、重复的卡片网格、虚假的精确数据、空洞的营销话术，以及每页密度和结构都相同的演示文稿。

内容到版式规则

• 最多五条简洁要点可以采用单栏布局；六条及以上通常需要双栏、卡片、表格或图表。
• 十项及以上的内容不得保留为密集的项目符号列表；应将其转换为有意义的可视化结构。
• 对于技术主题，如果架构、流程、规范或代码视图比功能卡片更能清晰传达信息，就应采用这些视图。
• 教育和培训幻灯片应在学习目标要求时加入练习或实践环节。
• 科学数据页面应采用图表加说明文字的结构，并附上引用；通常不适合使用 KPI 卡片和营销主视觉版式。
• 当章节变化有助于改善节奏时，应加入视觉过渡；仅为装饰并不足以成为添加章节页的理由。
• 副标题应简短，CTA 文案应以行动为导向；不要在主视觉页面中堆叠正文段落。

其他内容规则：

• 第一项功能可以作为重点突出，但后续功能在视觉上应保持次要，不能与其平分秋色。
• 当主题发生实质性变化，且暂停有助于观众调整状态时，应使用章节分隔页。
• 为增强技术可信度，应使用代码或架构视图；为实现学习目标，应加入练习；为支持研究论据，应使用图表说明文字和引用。
• 科学和学术证据的默认呈现方式不应采用 KPI 卡片、商业主视觉页面或功能卡片式表述。
• 引言通常应控制在三行以内，并注明姓名、职位和组织。
• 全套幻灯片应统一采用一个主题；可以进行细微变化，但不要在中途切换到无关主题。

领域识别

在确定视觉方案之前，先识别领域。常见信号包括：

• 科学研究：基因、蛋白质、测序、CRISPR、检测、组学、通路、突变、表达、实验。
• 学术论文：论文、学位论文、答辩。
• 工程／技术：架构、基础设施、部署、API、微服务、系统设计。
• 医疗／临床：诊断、治疗、患者、手术、临床。
• 政府／公共部门：政策、法规、合规、预算。
• 商业／产品：路演、投资者、销售、发布、KPI、收入。

如果领域匹配会改变结构或视觉语义，请先询问，而不是默认采用商业演示文稿的形式。

公共 API 规则

只能使用有文档说明的 pptx_designer 公共导入项。不要复制或重建旧版 ppt_pro_max 软件包，也不要仅因已安装的软件包中存在私有模块就导入它们。编写 Build Mode 代码前，请先阅读 references/public-api.md。

PNG 视觉审查

LLM 必须将导出的 PNG 与原始简报进行比较，而不能只判断它们是否美观。生成前，应将简报转化为一份简短的验收契约。渲染后，评估：

• 每项 MUST 要求是否都已得到直观呈现；

• 每个指定的受众、场景、氛围、语言和行动是否都体现在页面中；

• 规划的页面目标和叙事顺序是否在生成过程中得以保留；

• 是否遵守了指定的品牌、模板、图像和可编辑性约束；

• 如果提供了参考材料，是否明显地转化了双方认可的可观察特征，而非仅通过表面风格加以呼应；

• SHOULD 和 NICE_TO_HAVE 条件是否已满足，或是否明确说明不予满足；

• 视觉层级和页面清晰度；

• 演示尺寸下的可读性；

• 文本溢出、重叠、裁切和不自然的间距；

• 内容密度，以及填充区域与留白区域之间的平衡；

• 大面积留白是否有明确的叙事目的；如果留白无法营造焦点、节奏或层级，页面内容不足则属于 NEEDS_REVISION；

• 每张交付页面是否都有足够的视觉锚点和完整的核心信息；不能以“干净”或“极简”为借口，缺少依据或构图薄弱；

• 图表和示意图的可读性；

• 图像裁切、相关性和色调一致性；

• 字体排印、对比度、配色和视觉一致性；

• 演示文稿是否符合指定的受众、场景和氛围；

• 成果看起来是否经过有意设计，而非像套用模板；

• PPTX 中的重要对象是否仍可单独编辑。

审查未通过时，应报告需求 ID、幻灯片及位置、可能的源代码或内容原因，以及具体的修改方案。请阅读 references/qa-and-delivery.md，了解审查记录和验收用语。

参考资料

• workflow.md：从简报到确认的完整流程。
• design-direction-coach.md：适合新手的设计建议和视觉方向锁定。
• design-principles.md：详细的设计思路和内容规则。
• domain-paradigms.md：特定领域的结构、视觉语言和反模式。
• public-api.md：精选的公共 API 契约。
• content-schema.md：结构化内容模式。
• template-brand.md：VI Build 和模板合规流程。
• qa-and-delivery.md：结构检查、PPTX-PDF-PNG 渲染、PNG 审查和交付门槛。
• scientific-visual-baseline.md：可复用的研究型演示文稿设计令牌、证据阶梯、页面原型、密度规则和基准 QA 要求。
• install-and-runtime.md：Python 和渲染依赖项。