Bruce PPTX Generator

Bruce 的 PPTX 生成器

任务路由

先判断用户要的到底是生成新 deck还是编辑现有 deck。两条路径的约束不同，不可混用。

路由原则

• 生成路径：用户明确要从零创建、生成、导出、编译新的 PPT / PPTX / slide deck。
• 编辑路径：用户已经提供或明确指定现有 .ppt / .pptx 文件，目标是替换内容、重排结构、删改页面或保留模板风格做更新。
• 不要误触发：如果用户只是写提案、整理汇报思路、润色演讲稿、讨论 presentation 内容，但没有要求生成或编辑幻灯片文件，不使用本 skill。

路由隔离

• 仅在生成路径下使用 createSlide()、compile.js、theme 五键约定、Slide Master / Placeholder、PPT Section、页码徽章、Rich Card 组件和封面/目录/章节分隔页规则。
• 编辑路径默认保留模板结构和视觉语言，除非用户明确要求“整套重建为代码生成版”，否则不要把生成路径的组件规范硬套到 XML 编辑任务上。
• 编辑路径的首要目标是模板兼容、最小必要改动和重新打包后的文件可打开；生成路径的首要目标是新 deck 的叙事、布局和一致性。

执行环境与回退

• 优先使用运行环境里可用的结构化提问工具来一次性收集风格或缺失数据；如果没有该工具，就直接在对话里一次性提问全部必要信息。
• 优先使用运行环境里可用的精确编辑工具修改 XML 或代码；如果没有同名工具，使用当前平台提供的等价精确编辑能力。避免依赖批量替换脚本。
• 文中的命令以流程说明为主，按当前 shell 选择等价写法。Windows PowerShell、bash、zsh 可使用各自原生命令，只要行为一致即可。

风格预设

使用预设时，加载预设文件——其中包含完整的页面布局、组件函数、色板和内容密度规则。

风格选择

如果用户没有指定风格，优先用结构化提问工具询问受众感受（见 workflow.md §2）；如果没有该工具，就直接在对话中一次性提问。默认推荐选项为华为方案（专业权威）。

告知用户推荐的 preset 并说明理由，然后进入工作流。如果用户不满意，允许手动选择。

数据推断原则

演示文稿中禁止出现模糊表述。 每个论点必须有具体数字支撑。当用户输入缺乏数据时：

1. 优先追问：输入中有 1–3 个数据缺口时，优先使用结构化提问工具；若不可用，就在一次消息中追问所有缺失数字，并说明每个数字用在哪张幻灯片。
2. 允许估算：缺口较多或用户明确说"直接生成"时，使用行业典型基准值，并在幻灯片底部注明「参考行业基准，请替换为实际数据」，且须在回复中告知用户哪些是估算。
3. 严禁空占位：禁止写"XX%"、"N 个"、"数十万用户"而不填具体数字。

触发追问的信号词（出现即追问数字）：

"很多用户"、"大幅提升"、"显著降低"、"快速增长"、"大量"、"明显"、"有效"

精装交付标准（强制）

每份演示文稿必须达到「精装房」标准，禁止交付「标题+一句话」的毛坯房幻灯片。

内容富足度（每张内容页必须满足）

1. 数据或统计必须有：每个核心论点必须搭配一个数字、比例、时间或行业数据支撑。例："慢病随访断档率 > 60%"、"覆盖 1.18 亿空巢老人"。
2. Tagline 必须有：每张卡片或每个模块必须有一句 12–20 字的精准定位语，说明「这能解决什么问题」。例："金融级身份认证，数据访问全程可控"。
3. Bullet 必须带视觉前缀：使用小方块/小圆点/编号作为前缀，禁止纯文本堆叠。每条 bullet 应为完整语义句，而非单个关键词。
4. 非文字视觉元素必须有：除苹果极简（Apple Minimal）外，每张内容页至少包含一种非纯文字视觉组件（SVG 图标、数据卡、流程图、进度环、对比矩阵、架构图、KPI 卡）。纯文字列表页视为毛坯房，必须添加视觉元素。苹果极简风格以极简克制为核心，每页视觉元素酌情添加即可。
5. 图形密度上限（防溢出）：
   • 每张幻灯片最多使用一种大型图形组件（流程图 OR 矩阵 OR 进度环组 OR 金字塔，三选一，禁止叠加）
   • 禁止在同一页中同时出现两种大型图形：进度环 + 矩阵、金字塔 + 流程图 = 溢出风险极高
   • 内容区高度仅 3.95"（y:1.05 → y:5.0），大型图形占用后剩余文字空间有限，添加前必须估算文字是否放得下
   • 禁止从零手写以下组件（不在预设库内，需自行实现算法）：漏斗图（funnel）、甘特图（Gantt chart）、雷达图（radar chart）。若当前预设文件中有对应函数则使用预设函数，否则不用。
6. 底部说明/洞察区必须有：每个核心模块底部应有一句 1–2 行的补充说明，强化价值感或给出行动建议。

组件升级原则

每种风格都有对应的精装 Rich Card 组件，优先使用，禁止回退到只有 title + desc 的基础卡片：

• 封面页必须有装饰性视觉元素（几何图形、SVG 装饰、右侧能力卡片等），禁止只有标题和日期。
• 注意：createRichCover 在各风格中参数签名不同（华为版有 metrics/valueSlogan，苹果版有 spotlight，Pitch Deck 版有 traction/stage），使用前必须查阅当前预设文件的调用示例，不可跨风格套用参数。

强制规则

以下规则仅适用于从零代码生成路径，以及用户明确要求按 PptxGenJS 重新生成幻灯片的任务。编辑现有模板时，以模板兼容性、内容适配和最小必要结构改动为准。

尺寸 — 10" × 5.625"（LAYOUT_16x9）。每个元素必须满足 x + w ≤ 10 且 y + h ≤ 5.625。

颜色 — 6 位十六进制，不含 #（例如 "FF0000"）。禁止使用 "#FF0000" — 会导致文件损坏。

字体 — 中文：Microsoft YaHei | 英文：Arial（或当前预设中指定的替代字体）

禁用字体 — 以下字体禁止用作展示/标题字体：宋体、仿宋、Times New Roman。在现代演示文稿中会显得业余。

theme 对象 — 仅在生成路径中使用，两层约定必须区分清楚：

① compile.js / subagent 传入层（严格 5 个键）

compile.js 中定义的 theme 对象只传这 5 个键。subagent 在 DESIGN INTENT 注释里也只声明这 5 个。禁止在此层使用：background、text、muted、darkest、lightest 或其他自造键名。

② 风格预设文件内部层（允许扩展键）

各预设文件（huawei-style.md 等）中的组件函数（addHuaweiRichCard、makePainPointCard 等）可以引用预设文件中定义的扩展 key，如 theme.border、theme.bodyText、theme.mutedText、theme.orangeLight 等。这些 key 在预设文件的 theme const 块中均有定义，不属于违规。

生成骨架（强制） — 生成路径不再把 deck 视为“一堆独立页面”，而是先定义 deck skeleton，再填内容：

1. 先注册 Master，再生成 Slide

   • 在 compile.js 中先调用 pres.defineSlideMaster() 注册母版，再进入 slide 文件循环。
   • 至少准备以下母版：COVER_MASTER、TOC_MASTER、SECTION_MASTER、CONTENT_MASTER、SUMMARY_MASTER。
   • 需要长表格附录时，再额外定义 APPENDIX_MASTER。
   • Logo、页脚、页码带、统一装饰线、固定免责声明等重复 chrome，优先放进 master；不要在每张 slide 文件里重复手写。

2. Placeholder 名称必须稳定

   • 不同风格可以有不同视觉，但同一语义槽位优先复用相同 placeholder 名：title、subtitle、body、chart、table、insight、media。
   • 在 master 中先定义 placeholder，再在 slide 中通过 placeholder 名称填充内容。
   • 禁止每个风格各自发明一套完全不同的槽位命名，否则 compile 阶段无法做统一编排。

3. Section 必须是 deck 的一等结构

   • 每个主要章节都先用 pres.addSection({ title }) 注册，再将对应 slide 通过 sectionTitle 挂入该章节。
   • 封面和目录页可以不属于任何 section；章节分隔页、内容页、总结页、附录页必须明确属于某个 section。
   • TOC 中的章节名称、Section Divider 标题、PPT 内部 section title 三者必须一致。

4. 长表格默认进入 Appendix，而不是硬塞内容页

   • 如果表格超出当前风格的安全密度上限，或为了塞进内容页必须把字号压到不可读，直接移入 appendix。
   • Appendix 表格必须启用 addTable(..., { autoPage: true, autoPageRepeatHeader: true })；多列表头时同步设置 autoPageHeaderRows。
   • 内容页只保留结论摘要、小型对比表或关键 3–6 行；长明细表放到 appendix section。

页码徽章 — 仅适用于生成路径。除封面外每张幻灯片都必须有。只显示页码数字（例如 "3"），禁止使用 "3/12" 格式。具体坐标和形状以当前预设文件中的 addPageBadge 实现为准（qa.md §6 有各预设的参考值）。

createSlide() 必须是同步函数 — 仅适用于生成路径，禁止使用 async。compile.js 不会 await 它。

createSlide() 推荐签名 — 统一使用 createSlide(pres, theme, ctx = {})：

• ctx.masterName：当前页使用的 master 名称
• ctx.sectionTitle：当前页所属 section
• ctx.assets：预生成图标、图片、SVG base64 等
• ctx.meta：页码、目录条目、章节号等编排信息

如果当前 slide 由 placeholder 驱动，应优先写成：

function createSlide(pres, theme, ctx = {}) {
  const slide = pres.addSlide({
    masterName: ctx.masterName,
    sectionTitle: ctx.sectionTitle,
  });

  slide.addText("Quarterly Review", { placeholder: "title" });
  slide.addText("Revenue grew 28% year over year", { placeholder: "subtitle" });
  return slide;
}

禁止事项（常见 AI 生成质量陷阱）

这些是最容易让演示文稿显得低质量的模式，每次生成都要主动避免：

内容密度

• 单张 content slide 超过 6 个 bullet point — 超出就拆成两张
• 每条 bullet 超过 20 个字 — 精简或改用卡片布局
• 连续 3 张以上相同布局类型

视觉

• 各 slide 背景色不一致（content slide 必须统一用 theme.bg）
• 每个元素都加渐变色 — 渐变只用于强调，不滥用
• 所有内容居中对齐 — 会显得呆板，左对齐更有层次感
• 装饰性色块堆砌，没有布局逻辑
• 明明可以放进 master 的固定元素，却在每张 slide 中重复手写

文字

• 标题照抄正文第一句 — 标题应该是结论或主旨，不是描述
• 英文 text 混用宋体/仿宋 — 英文必须用指定英文字体
• # 前缀颜色值（"#1F3864" → 改为 "1F3864"）— 会导致文件损坏
• 长表格强行塞进内容页，导致字号过小、阅读失败；应改为 appendix + auto-paging

依赖安装

先检查依赖是否已可用；缺失时再安装。不要默认每次都重复安装。

必需依赖（生成或编译前确保可用）：

npm install -g pptxgenjs

按需依赖（仅在使用对应功能时）：

# 使用 react-icons 图标时（workflow.md 步骤 4.8）
npm install -g react-icons react react-dom sharp

# 编译后内容提取与 QA 验证时（qa.md 编译后 QA 章节）
pip install markitdown