slide-making-skill

PptxGenJS 幻灯片制作技能

本技能将教你如何使用 PptxGenJS（JavaScript）生成原生 .pptx 幻灯片。

PptxGenJS 参考

阅读 pptxgenjs.md，查看完整的 PptxGenJS API 参考，包括：

• 设置与基本结构
• 文本与格式
• 列表与项目符号
• 形状与阴影
• 图片与图标
• 幻灯片背景
• 表格与图表

---

字体规则

字体系列标准

语言	默认字体	备选字体
中文	Microsoft YaHei (微软雅黑)	—
英文	Arial	Georgia、Calibri、Cambria、Trebuchet MS

fontFace: "Microsoft YaHei"  // Chinese text
fontFace: "Arial"            // English text (or approved alternative)

使用系统安全字体，以确保跨平台兼容性。标题和正文可以使用不同字体（例如，Georgia + Calibri）。

正文不使用粗体

普通正文和说明文字／图例文字不得使用粗体。

• 正文段落、描述 → 常规字重
• 说明文字、图例、脚注 → 常规字重
• 粗体仅用于标题和小标题

// ✅ Correct
slide.addText("Main Title", { bold: true, fontSize: 36, fontFace: "Arial" });
slide.addText("Body text here.", { bold: false, fontSize: 14, fontFace: "Arial" });

// ❌ Wrong
slide.addText("Body text here.", { bold: true, fontSize: 14 });

---

配色规则（强制）

严格遵循调色板

仅使用提供的调色板。不得创建或修改颜色。

• 所有颜色必须来自用户提供的调色板
• 不得使用调色板之外的颜色
• 不得修改调色板中的颜色（亮度、饱和度、混色）
• 唯一例外：使用 transparency 属性添加透明度（0-100）

// ✅ Correct: Using palette colors
slide.addShape(pres.shapes.RECTANGLE, { fill: { color: theme.primary } });
slide.addText("Title", { color: theme.accent });

// ❌ Wrong: Colors outside palette
slide.addShape(pres.shapes.RECTANGLE, { fill: { color: "1a1a2e" } });

不使用渐变

禁止使用渐变。仅使用纯色。

// ✅ Correct: Solid colors
slide.background = { color: theme.bg };

// ✅ Correct: Solid + transparency for overlay
slide.addShape(pres.shapes.RECTANGLE, { fill: { color: theme.accent, transparency: 50 } });

不使用动画

**禁止使用动画和转场效果。**所有幻灯片都必须是静态的。

---

页码徽标（必需）

除封面页外，所有幻灯片都必须在右下角放置页码徽标。

• 位置：x: 9.3", y: 5.1"
• 仅显示当前页码（例如 3 或 03），不要显示“3/12”
• 使用调色板中的颜色，保持低调

圆形徽标（默认）

slide.addShape(pres.shapes.OVAL, {
  x: 9.3, y: 5.1, w: 0.4, h: 0.4,
  fill: { color: theme.accent }
});
slide.addText("3", {
  x: 9.3, y: 5.1, w: 0.4, h: 0.4,
  fontSize: 12, fontFace: "Arial",
  color: "FFFFFF", bold: true,
  align: "center", valign: "middle"
});

胶囊形徽标

slide.addShape(pres.shapes.ROUNDED_RECTANGLE, {
  x: 9.1, y: 5.15, w: 0.6, h: 0.35,
  fill: { color: theme.accent },
  rectRadius: 0.15
});
slide.addText("03", {
  x: 9.1, y: 5.15, w: 0.6, h: 0.35,
  fontSize: 11, fontFace: "Arial",
  color: "FFFFFF", bold: true,
  align: "center", valign: "middle"
});

---

主题对象约定（强制）

编译脚本会传入一个主题对象，其中包含以下确切键名：

键	用途	示例
theme.primary	最深颜色、标题	"22223b"
theme.secondary	深色强调色、正文文本	"4a4e69"
theme.accent	中间色调强调色	"9a8c98"
theme.light	浅色强调色	"c9ada7"
theme.bg	背景颜色	"f2e9e4"

切勿使用其他键名，例如 background、text、muted、darkest、lightest。

---

子 Agent 输出格式

每个子 Agent 都会输出一个完整、可运行的 JS 文件：

// slide-01.js
const pptxgen = require("pptxgenjs");

const slideConfig = {
  type: 'cover',
  index: 1,
  title: 'Presentation Title'
};

// ⚠️ MUST be synchronous (not async)
function createSlide(pres, theme) {
  const slide = pres.addSlide();
  slide.background = { color: theme.bg };

  slide.addText(slideConfig.title, {
    x: 0.5, y: 2, w: 9, h: 1.2,
    fontSize: 48, fontFace: "Arial",  // English text uses Arial
    color: theme.primary, bold: true, align: "center"
  });

  return slide;
}

// Standalone preview - use slide-specific filename (slide-XX-preview.pptx)
if (require.main === module) {
  const pres = new pptxgen();
  pres.layout = 'LAYOUT_16x9';
  const theme = {
    primary: "22223b",
    secondary: "4a4e69",
    accent: "9a8c98",
    light: "c9ada7",
    bg: "f2e9e4"
  };
  createSlide(pres, theme);
  // Replace XX with actual slide index (01, 02, etc.) to avoid conflicts
  pres.writeFile({ fileName: "slide-01-preview.pptx" });
}

module.exports = { createSlide, slideConfig };

---

关键注意事项

切勿在 createSlide() 中使用 async/await

// ❌ WRONG - compile.js won't await
async function createSlide(pres, theme) { ... }

// ✅ CORRECT
function createSlide(pres, theme) { ... }

切勿在十六进制颜色中使用“#”

color: "FF0000"      // ✅ CORRECT
color: "#FF0000"     // ❌ CORRUPTS FILE

切勿在十六进制字符串中编码不透明度

shadow: { color: "00000020" }              // ❌ CORRUPTS FILE
shadow: { color: "000000", opacity: 0.12 } // ✅ CORRECT

防止标题文字换行

// ✅ Use fit:'shrink' for long titles
slide.addText("Long Title Here", {
  x: 0.5, y: 2, w: 9, h: 1,
  fontSize: 48, fit: "shrink"
});

---

快速参考

• 尺寸：10" × 5.625"（LAYOUT_16x9）
• 颜色：不带 # 的 6 位十六进制值（例如，"FF0000"）
• 英文字体：Arial（默认）或获准使用的备选字体
• 中文字体：Microsoft YaHei
• 页码徽标位置：x: 9.3", y: 5.1"

---

QA（必需）

假设存在问题。你的任务是找出问题。

首次渲染几乎从来都不正确。进行 QA 时要像排查 Bug 一样，而不是只做确认。如果首次检查时没有发现任何问题，那就说明检查得还不够仔细。

内容 QA

python -m markitdown slide-XX-preview.pptx

检查是否有内容遗漏、拼写错误或顺序错误。

检查是否残留占位文本：

python -m markitdown slide-XX-preview.pptx | grep -iE "xxxx|lorem|ipsum|placeholder"

如果 grep 返回结果，请先修复，再宣布成功。

验证循环

1. 生成幻灯片 → 使用 python -m markitdown slide-XX-preview.pptx 提取文本 → 检查内容
2. 列出发现的问题（如果没有发现问题，就更仔细地再检查一次）
3. 修复问题
4. 重新验证——一次修复往往会引发另一个问题
5. 重复以上步骤，直到验证没有发现新问题

至少完成一轮修复与验证循环后，才能宣布成功。

---