基于模板生成 PPT

通过从参考模板中提取样式，再结合 PptxGenJS 从零构建全新幻灯片，实现演示文稿的自动生成。

核心原则：绝不修改现有 PPT 的 XML 结构；仅分析其视觉样式，然后完全重新绘制。

模板管理

模板目录

默认模板目录：{workspaceDir}/template/

每次执行时：

1. 扫描 {workspaceDir}/template/ 目录下的所有 *.pptx 文件。
2. 若仅找到 一个 模板 → 自动选用。
3. 若找到 多个 模板 → 列出全部选项，并提示用户手动选择。
4. 若 未找到任何 模板 → 提示用户上传 .pptx 文件或指定路径。

用户上传

支持用户上传 .pptx 文件。处理前需执行以下检查：

• 文件大小校验：拒绝大于 50 MB 的文件，并返回提示：“模板文件超过 50MB 限制，请压缩后重试”。
• 上传成功后，保存至 {workspaceDir}/template/ 以供后续复用。

工作流程

第一阶段：样式提取

# 若为 .pptx 文件，先转为 PDF 用于视觉分析：
python3 {baseDir}/scripts/pptx_to_pdf.py template.pptx /tmp/ppt_style/template.pdf

# 提取每页图像：
bash {baseDir}/scripts/extract_pages.sh /tmp/ppt_style/template.pdf /tmp/ppt_style/ 150

# 从 PPTX XML 中高精度提取样式：
python3 {baseDir}/scripts/extract_style.py template.pptx -o /tmp/ppt_style/style_raw.yaml

读取 style_raw.yaml 获取精确样式数据（十六进制颜色值、字体名称、字号（单位：pt）、位置（单位：英寸）、填充类型、线条样式等）；再读取其中 3–5 页图像，用于语义理解（如元素角色判断、版式分类）。

样式提取分为两个层级：

支持的元素类型包括：text、image、video、shape、line、numbered_list、step_list、tag_group、chart、table。

对于图片与视频：设置 placeholder: true，并附带 description 字段，便于用户后续手动替换。

最终结果写入 style.yaml。Schema 定义见：references/style-schema.md。

第二阶段：PPT 生成

调用 pptx 技能（基于 PptxGenJS）创建幻灯片：

1. 读取 style.yaml 获取视觉参数。
2. 与用户输入内容（主题、页数、大纲）融合。
3. 生成符合所提取样式的 PptxGenJS JavaScript 代码。
4. 执行该 JS 代码，输出 .pptx 文件。
5. 质量验证：将生成的 PPT 转为图像，比对样式保真度。

大型演示文稿策略（＞15 页）

PptxGenJS 本身的生成速度极快（秒级），但为大量幻灯片编写 JS 代码可能触发上下文长度或执行时间限制。应对策略如下：

大型文稿推荐采用幻灯片工厂模式：

// 根据 style.yaml 定义各类版式的工厂函数
function makeCover(pres, content) { /* ... */ }
function makeContent(pres, content) { /* ... */ }
function makeSection(pres, content) { /* ... */ }

// 内容数组 —— 易于扩展
const slides = [
  { layout: "cover", title: "...", subtitle: "..." },
  { layout: "content", title: "...", items: [...] },
  // …… 可达 50+ 条目
];

slides.forEach(s => layoutFactories[s.layout](pres, s));

该方式使代码体积复杂度为 O(版式数)，而非 O(页数)。

输出文件大小控制

目标输出文件小于 20 MB。PptxGenJS 默认输出极小（纯文本类文稿通常为 100–500 KB）。大体积主要源于嵌入的图像资源。当输出接近 20 MB 时，执行以下措施：

1. 在 PptxGenJS 配置中降低图像分辨率/压缩质量。
2. 改用占位符代替嵌入图像。
3. 如确有必要，可将内容拆分为多个 PPT 文件。
4. 向用户发出警告：“PPT 接近 20MB 限制，已使用图片占位符，请手动替换”。

占位符规范

• 图片占位符：深色矩形 + 灰色虚线边框 + 🖼️ + 标签 + 替换建议
• 视频占位符：深色矩形 + 红色虚线边框 + ▶️ + 标签 + 替换建议

关键规则

• 严禁修改原始 PPT 的 XML —— 所有输出均须从零生成。
• style.yaml 具备复用性：一旦提取完成，即可无限次生成同风格 PPT。
• PptxGenJS 中启用 shrinkText: true 实现长文本自动缩放适配。
• 幻灯片尺寸必须严格匹配 style_raw.yaml 中提取的实际值（不可硬编码为 16:9）。

文件约定

{workspaceDir}/
├── template/              ← .pptx 模板目录（自动发现）
│   └── *.pptx             ← 单个文件最大 50 MB
├── output/                ← 生成的 PPT 输出目录
│   └── *.pptx             ← 单个文件最大 20 MB
/tmp/ppt_style/            ← 临时工作目录（非持久化）
├── template.pdf
├── page-*.jpg
├── style_raw.yaml         ← extract_style.py 输出
└── style.yaml             ← 整合后版本（含精确样式 + 语义信息）

故障排查