MiniMax pptx-generator 技能介绍

一、架构总览

MiniMax pptx-generator 是一套基于 PptxGenJS（v3.12+）的演示文稿自动化生成技能，运行于 Node.js 运行时环境。其核心设计理念是以程序化脚本取代传统 GUI 编辑，通过精确的 API 调用实现演示文稿的从零创建与模板编辑。技能体系分为三个层次：底层为设计系统（Design System），提供配色、排版、间距等视觉约束；中间层为页面类型系统（Slide Type System），定义 5 种标准页面类型及各类型下的多种布局选项；顶层为生成工作流（Generation Workflow），封装从信息采集到成品交付的完整管线。三层之间通过 Theme Object Contract 传递设计参数，该契约包含 5 个精确字段（primaryColor、secondaryColor、backgroundColor、fontFamily、borderRadius），确保各模块间的视觉一致性与可复现性。技能根目录下的 references/ 目录包含 5 份参考文档（slide-types.md、design-system.md、editing.md、pitfalls.md、pptxgenjs.md），分别对应各子模块的完整技术规范。整篇技能中，生成（Create）和编辑（Edit）两条路径并行，使用者可根据内容是否已有现成模板进行选择，二者共享同一套设计系统和页面类型定义。

二、设计系统

2.1 调色板体系

技能内置 18 套预定义调色板，分别是 Elegant、Ocean、Forest、Sunset、Rose、Sky、Lavender、Teal、Coral、Slate、Amber、Mint、Plum、Sage、Ruby、Ivory、Midnight、Blush。每套调色板以 5 色基础色（主色加 4 辅助色）构成，通过 Agent Design System 扩展为完整的 10 级色阶体系（色号 50 至 950），覆盖从浅色背景到深色强调的全域需求。Agent Design System 的色阶生成算法基于 HSL 色彩空间，通过对色相偏移和明度梯度的数学计算，确保相邻色阶之间的视觉跳跃感均匀。配色严格遵循 6:3:1 法则——背景色占 60%、主色占 30%、强调色占 10%。所有配色组合均经过 WCAG 2.1 AA 级对比度验证，确保正文文字与背景之间的对比度不低于 4.5:1。设计文档中明确禁止使用渐变填充和动画效果，此约束保证了生成的 PPTX 在不同平台（Microsoft PowerPoint、WPS、Google Slides）间渲染结果一致。

2.2 风格配方

技能定义了 4 种可量化的设计风格配方，每种配方以结构化的 JSON 参数表达。Sharp 采用直角设计，圆角半径 0pt，边框宽度 1.5pt，无阴影投影，适用于技术文档和学术报告。Soft 采用圆角设计，圆角半径 8pt，边框宽度 1pt，轻度阴影（透明度 0.15），适合各类通用场景。Rounded 采用大圆角设计，圆角半径 16pt，边框宽度 0.75pt，中度阴影（透明度 0.12），面向非技术受众的演示。Pill 采用全椭圆设计，圆角半径 48pt，无边框，轻度阴影（透明度 0.1），搭配加粗强调字号，适用于营销和品牌展示场景。

2.3 排版与间距

排版系统以 10pt 至 40pt 的字号层级覆盖从正文到标题的全部需求。标题区域默认使用 32pt 至 40pt，正文使用 14pt 至 18pt，注释信息使用 10pt 至 12pt。正文字体遵循无加粗规则，仅标题和数字标签可使用加粗样式。间距系统以 6pt 为最小基准单位，所有内边距、段间距、元素间距均为 6pt 的整数倍。字体搭配方面推荐 Sans-Serif 体系，标题使用系统无衬线字体，正文使用易读性优先的常规字重，禁止使用衬线字体和装饰性字体。

三、页面类型与布局

技能定义了 5 种标准页面类型，每种提供 3 至 4 种布局选项。Cover（封面页）包含 3 种布局变体：中心布局（大标题居中，副标题和日期依次排布）、左对齐布局（标题位于画布左侧三分之一处，装饰线分割）、全幅背景布局（背景图覆盖全页，文字叠加于半透明遮罩层）。封面页不显示页码徽章。Section（章节页）包含 3 种布局：纯文字章节页（仅章节编号和标题）、图标式章节页（章节图标与标题并排）、色块章节页（大面积色块作为视觉锚点）。章节页在右下角显示页码徽章。Content（内容页）包含 6 种子类型：纯文字内容页、图文混排页、表格数据页、图表展示页、代码展示页、对比分栏页。每种子类型对应 2 至 3 种布局预设，可通过 layout 参数切换，其中纯文字页使用单栏宽排版、图文混排页采用左文右图或左图右文两种变体、表格数据页固定在画布中央区域。内容页显示页码徽章。Quote（引用页）包含 3 种布局：纯引文布局（居中展示，左右引号装饰）、引文加来源布局（底部标注出处）、全幅引文布局（引用文字占据画布主体区域）。引用页不显示页码徽章。End（封底页）包含 3 种布局：联系方式页、感谢语页、二维码页，封底页不显示页码徽章。页面编号徽章统一显示在幻灯片右下角，格式为当前页码与总页数之比，字号 10pt，颜色取自辅助色。

四、从零创建工作流

从零创建演示文稿遵循 7 步标准流程。

Step 1 信息收集：通过用户输入或外部数据源（API、文件）收集演示文稿所需内容，包括标题结构、各章节要点、数据表格和引用资料。

Step 2 大纲生成：基于收集的信息生成结构化大纲，确定页面总数、每页类型归属和内容分布，大纲以 JSON 格式存储，包含 pageType、title、content、layout 等关键字段。

Step 3 设计规格锁定：根据内容类型和受众特征，从 18 套调色板中选择配色方案，从 4 种风格配方中选择布局风格，设计参数通过 Theme Object Contract 传递给生成引擎。

Step 4 平台选择：确认 PptxGenJS 版本兼容性（v3.12 以上）和 Node.js 运行时版本（v18 以上）。

Step 5 多文件并行生成：生成器根据 JSON 清单文件逐一创建幻灯片，每页依次调用 addSlide 方法创建新幻灯片，然后设置背景层（setBackground）、构建标题区（addText 自定义配置）、按类型构建内容区（选择 addText、addTable、addChart 或 addImage）、添加页码徽章（addText 固定右下角），页间自动继承主题参数。

Step 6 QA 验证循环：输出文件后立即执行三项自动化检查——grep 占位符文本检测（禁止输出中含有占位符残留）、布局校验（检查幻灯片元素是否超出安全区域或发生重叠）、嵌套结构检查（表格单元格和分组形状的父子层级校验）。

Step 7 交付：验证通过的 PPTX 文件输出至目标路径，同时返回包含输出路径、页面总数、配色标识和耗时统计的结果摘要。

五、模板编辑工作流

当需要以现有 PPTX 文件为基底进行修改时，技能提供独立的模板编辑管线，封装为 7 阶段流程。Copy 阶段复制模板文件到工作区，确保原始文件不被修改。Analyze 阶段分析模板结构，识别占位符（标识为 {{variable}} 格式）、母版布局和颜色方案。Plan 阶段根据分析结果规划编辑操作类型——替换文本、更新图表数据源或交换图片资源。Unpack 阶段将 PPTX（ZIP 压缩包）解压到临时目录，暴露 XML 源文件。Build 阶段构建替换映射表，将占位符与新内容一一对应。Edit 阶段执行 XML 级别的精确替换操作：修改 a:t 元素的文本值以替换文字内容、更新 a:srgbClr 的 val 属性以修改颜色、替换 media 目录下的图片文件后重新打包。Clean 阶段清理临时文件并优化 XML 结构。Pack 阶段重新打包为 PPTX 文件。此工作流的优势在于完全保留了模板中字体嵌入、动画设置、母版布局等复杂特性，弥补了从零创建方式在这些方面的不足。需要特别注意的是，XML 操作对标签结构的完整性要求极高，错误的节点插入可能导致整个 PPTX 文件无法打开，因此 Edit 阶段内置了 XML Schema 校验步骤。

六、图标管线

技能集成了双引擎图标管线。首选引擎为 react-icons 库，内置 1.5 万余个流行图标（覆盖 Font Awesome、Material Design、Ionicons、Feather Icons 等主流合集），通过字符串引用即可在幻灯片中插入图标。降级引擎为 Iconify API，当 react-icons 中找不到目标图标时，自动从 Iconify CDN 获取 SVG 数据。获取后的 SVG 经 SVGO 优化器压缩（去除冗余 XML 属性、合并路径指令）后转换为 PptxGenJS 可识别的格式注入幻灯片。若 Iconify 也失败，则回退为文本占位符而非进一步降级至几何形状，此设计避免了视觉降级后的不一致性。图标大小统一为当前页面字号对应比例的 1.2 倍，颜色取自主题色，确保了图标与整体视觉风格的一致性。

七、质量保障与陷阱

QA 环节执行三项自动化验证。grep 占位符检测扫描输出文件 XML 源中是否存在未经替换的占位符标记（如 {{company_name}}、{{date}}），此类残留是模板编辑中最常见的质量事故。布局校验通过计算每页元素的位置坐标，检查是否超出幻灯片安全区域或发生元素重叠。嵌套结构检查确保表格单元格、分组形状等复合元素的父子层级完整，防止因结构错乱导致渲染异常。根据 pitfalls.md 文档归总，常见错误分为 10 类和 5 条致命陷阱。10 类错误涵盖字体未嵌入导致的跨平台渲染差异、图片路径错误导致红叉、表格列宽分配不均、图表数据系列未正确定义、形状锚点偏移、渐变残留、层叠顺序错乱、母版引用丢失、超链接目标失效、导出格式不兼容。5 条致命陷阱特指 PptxGenJS 的 API 边界行为：addShape 不支持所有 PowerPoint 形状类型，仅支持 rect、ellipse、triangle、line、arrow 等基础形状；addText 的 vertical alignment 属性在 v3.11 以下存在适配 bug；addChart 的数据点数量超过 100 时自动降级到默认样式；表格单元格不支持跨行合并操作；页面尺寸在创建后不可修改，必须在初始化时确定。在编写生成脚本时，应将这些边界条件纳入前置检查，在调用对应 API 之前验证数据类型和数量范围。

八、技术栈总览

核心技术栈以 PptxGenJS（v3.12+）为主引擎，负责 PPTX 文件的底层生成和渲染。辅助依赖包括 react-icons（图标资源的本地化管理）、markitdown（从 Markdown 源文本提取结构化内容）、SVGO（图片资源优化降低文件体积）。运行环境要求 Node.js v18 以上，支持 CommonJS 和 ES Module 两种模块系统。与 Anthropic 的 PPTX 技能（侧重 XML 模板编辑和现有文件修改）和本地 python-pptx 技能（侧重 Python 生态集成与数据处理管线）相比，MiniMax 方案在从零创建的灵活性、设计系统的完备性和跨平台渲染一致性上具有独特优势。三套技能形成互补关系，覆盖演示文稿自动化的全部场景，使用者可根据实际需求选择：需要完全控制设计参数选 MiniMax，需要深度编辑现有模板选 Anthropic，需要与 Python 数据处理管线集成选 python-pptx。