Deskclaw PPTX

PPT 演示文稿生成器

工作流选择

执行须知 (减少不必要的工具调用):

• python bootstrap.py 只需执行一次，它会自动检测已安装的依赖并跳过，输出所有可用路径
• compile.py 会自动创建输出目录，不需要提前 mkdir
• write_file 直接写文件即可，不需要先 ls 检查或 mkdir 创建目录
• 简单任务不需要读 reference 文件，SKILL.md 本身包含足够的示例

命令速查表

参考文档 (按需读取)

根据任务需要选择读取对应文件，不需要全部读。

两个核心工作流

工作流 A: 从零创建 (PptxGenJS)

用于没有现成模板的场景。用 JavaScript 生成原生 PPTX 文件。

工作流 B: 模板编辑 (OOXML)

用于基于现有演示文稿的场景。解包 PPTX 为 XML，直接编辑后重新打包。

工作流 A: 从零创建

第 1 步: 理解需求

了解主题、受众、用途、风格基调和内容深度。

第 2 步: 选择色彩方案与字体

从 色彩方案 中选择匹配主题的方案。 从 字体配对 中选择字体组合。

色彩方案应该为这个特定主题而选择。如果把你的颜色换到一个完全不同的演示中还能"成立"，说明选择不够具体。

第 3 步: 选择设计风格

从 风格配方 中选择视觉风格:

• Sharp & Compact: 数据密集、财务报告
• Soft & Balanced: 企业商务、通用场景
• Rounded & Spacious: 产品介绍、营销
• Pill & Airy: 品牌发布、高端展示

第 4 步: 规划幻灯片大纲

将每张幻灯片归类为 5 种页面类型 之一:

内容页 6 种子类型: 文字型、图文混排、数据可视化、对比型、时间线/流程、图片展示。

确保视觉多样性 — 不要在多张幻灯片上重复同一布局。

第 5 步: 生成幻灯片 JS 文件

每张幻灯片一个 JS 文件 (slides/slide-01.js, slides/slide-02.js, ...)。

每个文件必须导出同步 createSlide(pres, theme) 函数。不需要 require pptxgenjs — pres 对象由 compile.js 传入:

// slides/slide-01.js
function createSlide(pres, theme) {
  const slide = pres.addSlide();
  slide.background = { color: theme.bg };

  slide.addText("标题", {
    x: 0.5, y: 2, w: 9, h: 1.2,
    fontSize: 48, fontFace: "Microsoft YaHei",
    color: theme.primary, bold: true, align: "center"
  });

  return slide;
}

module.exports = { createSlide };

第 6 步: 编写 compile.js 并编译

在 slides/ 目录下创建 compile.js，汇编所有幻灯片:

// slides/compile.js
const pptxgen = require('pptxgenjs');
const pres = new pptxgen();
pres.layout = 'LAYOUT_16x9';

const theme = {
  primary: "2b2d42",    // 深色，标题和背景
  secondary: "8d99ae",  // 次深色，正文和装饰
  accent: "ef233c",     // 强调色
  light: "edf2f4",      // 浅色调
  bg: "ffffff"           // 背景色
};

// 按顺序加载所有幻灯片 (修改数量以匹配实际幻灯片数)
for (let i = 1; i <= 3; i++) {
  const num = String(i).padStart(2, '0');
  require(`./slide-${num}.js`).createSlide(pres, theme);
}

// 输出路径由 compile.py 通过环境变量传入
const output = process.env.PPTX_OUTPUT || './output.pptx';
pres.writeFile({ fileName: output });

编译命令 (compile.py 自动处理 node 路径和模块查找):

python scripts/compile.py slides/ ~/Desktop/testout/deskclaw-pptx/output.pptx

第 7 步: QA 质量检查

详见 QA 流程。

输出结构:

slides/
├── slide-01.js ... slide-NN.js
├── imgs/
└── compile.js
→ python scripts/compile.py slides/ <目标路径>.pptx

Theme 对象协议 (必须遵守)

所有幻灯片通过 compile.js 接收同一个 theme 对象，包含且仅包含以下 5 个键:

不要使用其他键名 (如 background, text, muted)，因为编译脚本只传递这 5 个键。

页码徽章 (非封面页必须添加)

除封面外的所有幻灯片都必须在右下角添加页码。

位置: 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"
});

工作流 B: 模板编辑

详见 editing.md 的完整工作流。

简要步骤:

1. 分析: python scripts/thumbnail.py template.pptx + python -m markitdown template.pptx
2. 解包: python scripts/office/unpack.py template.pptx unpacked/
3. 操作: 在 ppt/presentation.xml 的 <p:sldIdLst> 中删除/复制/重排幻灯片
4. 编辑: 修改各 slide{N}.xml 中的文本和元素
5. 清理: python scripts/clean.py unpacked/
6. 打包: python scripts/office/pack.py unpacked/ output.pptx --original template.pptx
7. 验证: python scripts/office/validate.py unpacked/ --original template.pptx

设计原则

不要做无聊的幻灯片

白色背景加项目符号是最低标准。每张幻灯片都应该有视觉元素 — 图片、图表、图标或形状。

排版规范

正文左对齐 (不要居中)。标题可以居中。中文正文不加粗 — 粗体仅用于标题。

布局建议

• 双栏布局 (文字左，图片右)
• 图标 + 文字行 (图标在彩色圆圈中)
• 2x2 或 2x3 网格
• 半出血图片 + 内容叠加
• 大数字标注 (60-72pt 数字 + 小标签)

常见错误 (必须避免)

• 不要在多张幻灯片上重复同样的布局
• 不要居中正文 — 正文左对齐
• 不要使用 # 前缀的 hex 颜色 (会导致文件损坏)
• 不要把透明度写进 8 位 hex 颜色字符串 — 用 opacity 属性
• 不要在 createSlide() 中使用 async/await — 必须同步
• 不要复用选项对象 — PptxGenJS 会原地修改，用工厂函数代替
• 不要在标题下加装饰线 — 这是 AI 生成幻灯片的明显标志
• 不要使用低对比度的文字或图标

QA 检查 (必须执行)

假设第一次渲染有问题。你的任务是找到它们。

内容检查

python -m markitdown output.pptx

检查内容缺失、错别字、顺序错误。

模板编辑时检查残留占位文本:

python -m markitdown output.pptx | grep -iE "\bx{3,}\b|lorem|ipsum|\bTODO|\[insert"

验证循环

1. 生成 → markitdown 检查内容
2. 列出发现的问题
3. 修复
4. 重新验证
5. 重复直到无新问题

图标 (react-icons)

使用 react-icons 将 SVG 图标栅格化为 PNG，提升视觉效果。

const React = require("react");
const ReactDOMServer = require("react-dom/server");
const sharp = require("sharp");
const { FaCheckCircle } = require("react-icons/fa");

function renderIconSvg(IconComponent, color = "#000000", size = 256) {
  return ReactDOMServer.renderToStaticMarkup(
    React.createElement(IconComponent, { color, size: String(size) })
  );
}

async function iconToBase64Png(IconComponent, color, size = 256) {
  const svg = renderIconSvg(IconComponent, color, size);
  const pngBuffer = await sharp(Buffer.from(svg)).png().toBuffer();
  return "image/png;base64," + pngBuffer.toString("base64");
}

图标库: react-icons/fa (Font Awesome), react-icons/md (Material), react-icons/hi (Heroicons)。

注意: 图标渲染是异步的，应该在 createSlide() 之前预处理好，将 base64 数据传入同步函数。

中文本地化

生成中文内容时:

• 字体: 微软雅黑 (Microsoft YaHei)
• 正文字号: 16-18pt (比英文大 2pt)
• 行高: 1.5-1.8x
• 每行中文字符: 15-20 个
• 中英文/数字之间加半角空格: 会议有 12 位参与者

依赖安装

运行 python bootstrap.py 自动安装所有依赖。

手动安装:

# Python
pip install "markitdown[pptx]" Pillow defusedxml lxml -i https://pypi.tuna.tsinghua.edu.cn/simple

# Node.js
npm install pptxgenjs react-icons react react-dom sharp --registry=https://registry.npmmirror.com