> 依赖：pip install python-pptx

PPT 制作专家（八模块编排）

一套把「专业 PPT 制作」拆解为八个职责单一模块、由编排器串成可追溯流水线的技能。核心价值不是"又一个生成器"，而是逻辑先于视觉 + 模块解耦 + 质检回写闭环，使产出在版式、内容结构、视觉风格与叙事逻辑上达到专业水准。

一、八模块总览

二、处理顺序与判断逻辑

①输入解析 ──J1信息充足?──(否→澄清提问 / 自动补全+标注)
         └─(是)→ ②内容提炼 → ③大纲结构 ──J2内容完整?──(否→回② 重新提炼)
                                              └→ ④版式配色 ┐
                                                ⑤图文图表 ┘→ ⑥模板适配
                                                              → ⑦审阅质检 ──J3合格?──(否→回写③重排结构 / 回写④⑤重做视觉)
                                                                               └(是)→ ⑧导出

三个判断分支点（modules/gates.py）：

• J1 信息充足性（①→② 之间）：检查「场景 / 受众 / 篇幅 / 数据」四要素是否齐备。
• 不足 → 暂停流程向用户澄清提问（交互模式）。
• 无法交互（--no-pause）或澄清后仍缺失 → 自动补全默认值，并把每条补全写入 spec["assumptions"]，标注「来源=用户信息不足」+ 鼓励补充提示。
• J2 内容完整性（③ 之后）：检查大纲是否遗漏关键信息（缺封面/总结、存在空内容页）。
• 有遗漏 → 回写 ② 重新提炼，触发 content_gen 兜底填充，直到无空页。
• J3 质量合格（⑦ 之后）：检查排版 / 内容 / 一致性是否达标（P0 阻断）。
• 不达标 → 按 P0 问题类型定向回写：结构类问题回写 ③ 重排结构，视觉类问题回写 ④⑤ 重做视觉；最多迭代 max_iterations 次，仍不过则阻断导出。

信息不足时的自动补充与标注（J1）

当用户未提供场景 / 受众 / 篇幅 / 数据等关键信息时，skill 不会卡住或硬报错，而是：

1. 交互模式下先暂停提问（_ask_clarify）；
2. 无法交互或澄清仍缺 → 用默认值自动补全（场景→商业汇报、受众→公众、篇幅→8-12 页、数据→结构化示例内容）；
3. 每条补全明确标注来源是"用户信息不足"，并写入三处：
   - 运行日志（自动补充项：N 条）；
   - 结果字典 result["assumptions"]；
   - 归档 manifest.json 的 assumptions 字段；
4. 每条补全附带提示："建议补充更多信息与要求，以产出更高质量、更符合预期的 PPT"，鼓励用户追加输入。

三、快速开始

# 纯文本需求（无素材）
python3 scripts/run.py \
  --request "做一份季度商业汇报PPT，10-12页，给CEO看，包含营收增长、市场、下季度计划" \
  --out build/report.pptx

# 带素材文件（txt/md，内容会被提炼进 PPT）
python3 scripts/run.py \
  --request "融资路演PPT，12页，目标投资人" \
  --source material.txt \
  --out build/pitch.pptx

# 非交互（缺信息不提问，直接继续）
python3 scripts/run.py --request "培训课件" --no-pause --out build/train.pptx

# 运行单元测试（固化验收门禁）
python3 scripts/test_pipeline.py

内容提炼三引擎（模块②）

模块② 支持三套提炼引擎，产出完全相同的 Content Graph 契约，可无缝切换：

LLM 引擎通过环境变量配置（OpenAI 兼容接口，零额外 SDK 依赖）：

export PPT_LLM_API_BASE="https://api.openai.com/v1"
export PPT_LLM_API_KEY="sk-..."
export PPT_LLM_MODEL="gpt-4o-mini"   # 可选，默认 gpt-4o-mini

联网检索（DuckDuckGo 免费接口，零 Key）：

export PPT_WEB_SEARCH=1   # 启用联网内容补全

• distill_engine 取值：auto（默认）/ llm / web / regex。
• LLM 或检索不可用/失败时自动回退离线正则，graph 记录 engine、fallback、web_enriched。

无素材内容生成兜底（模块③）

只给一句话需求、未提供素材文件时，模块② 提炼不出足够内容，模块③ 会自动调用内容生成器（content_gen.py），基于「场景 + 每页标题 + 主题词」为每个内容页生成 3~5 条有实质的要点，保证每一页都有内容，不会出现"只有标题没有正文"的空页。

• 触发条件：无素材文件（source_paths 为空）或正文块过少（< 5）。
• 覆盖版式：content / summary / chart / timeline / two_column / quote。
• 特殊版式（如 chart）无数据时，渲染层自动降级为「标题 + 要点」。
• 这是兜底，素材充足时绝不覆盖真实提炼内容。
• 建议：生成后可在此基础上用 llm/web 引擎或人工补充真实数据，进一步充实。

配色方案（17 套）与风格库（18 种）

已完整整合 ppt-generator-skill 的配色与风格资产：

• 配色方案 17 套：商业蓝/路演红/学术白/科技深/极简灰（原有 5 套）+ 午夜商务/科技深空/珊瑚活力/暖陶简约/海洋渐变/炭灰极简/青绿信任/莓果奶油/鼠尾草静/樱桃大胆/渐变科技/抹茶日式（整合 12 套）。
• 风格库 18 种：MBE 插画、复古卡通、极简技术、拟态科技、手绘简笔、喷绘涂鸦、莫兰迪学术、奶茶商务、几何服装、网格产品、手绘儿童、牛油果绿 ins、极简黑白灰、奶黄卡通、奶油黄渐变、MUJI、潮流创意、莫兰迪绿方块。
• 字体风格 4 类：商务/科技/优雅/可爱。
• 用户提及风格关键词（如"MBE插画""复古卡通"）时自动命中风格库并套用对应配色；命中多关键词时取最精确匹配。

四、目录结构

ppt-expert-orchestrator/
├── SKILL.md                     # 本文件
├── workbuddy.json               # 元数据
├── scripts/
│   ├── run.py                   # 编排器入口（串联八模块+回写闭环）
│   ├── test_pipeline.py         # 单元测试回归（27 用例，固化验收门禁）
│   └── modules/
│       ├── __init__.py
│       ├── contracts.py         # 数据契约 + 17 配色 + 18 风格 + 字体 + 排版规范
│       ├── m01_understand.py    # ① 需求理解（含风格关键词识别）
│       ├── m02_distill.py       # ② 内容提炼（三引擎：web + LLM + 离线正则降级）
│       ├── llm_distill.py       # LLM 语义提炼后端（OpenAI 兼容，零 SDK 依赖）
│       ├── web_distill.py       # 联网检索补全后端（DuckDuckGo 免费，零 Key）
│       ├── m03_outline.py       # ③ 大纲结构
│       ├── content_gen.py       # 内容生成兜底（无素材时自动填内容）
│       ├── gates.py             # 判断点模块（J1 信息充足 / J2 内容完整 / J3 质量合格）
│       ├── m04_theme.py         # ④ 版式配色（含风格库匹配）
│       ├── m05_compose.py       # ⑤ 图文图表
│       ├── m06_bind.py          # ⑥ 模板适配
│       ├── m07_review.py        # ⑦ 审阅质检
│       └── m08_export.py        # ⑧ 导出交付（14 版式含大数据/矩阵）
├── references/
│   └── contracts.md             # 中间产物 schema 详解
└── templates/
    ├── material.example.txt     # 示例素材（通用）
    └── yunfan_q3.md             # 示例素材（云帆科技 Q3 汇报，含 Markdown）

五、关键参数配置

六、错误处理约定

1. 缺信息（J1）：不硬编、不报错——交互模式先澄清提问；无法交互则自动补全默认值并写入 assumptions（标注"来源=用户信息不足"）。
2. 内容遗漏（J2）：大纲存在空内容页/缺关键章节时，回写模块② 重新提炼并触发内容兜底。
3. 质检未过（J3）：按 P0 问题类型定向回写（结构→③重排 / 视觉→④⑤重做），最多迭代 max_iterations 次。
4. 达到最大迭代仍 P0：阻断导出，返回 blocked=True，不产出损坏文件。
5. 素材文件缺失：_read_source 抛 FileNotFoundError，编排器捕获并回退为仅用需求文本。
6. 依赖缺失：import pptx 失败时在模块⑧捕获并给出安装提示（pip install python-pptx）。

七、扩展点（复刻/定制）

• 换渲染器：只需替换 m08_export.py 的 _RENDERERS，不影响上游模块。
• 加叙事框架：在 m03_outline.py 的 NARRATIVES 字典追加新场景。
• 加配色方案：在 contracts.py 的 THEMES 追加新主题。
• 接 LLM 做语义提炼：已内置，配置 PPT_LLM_API_BASE/PPT_LLM_API_KEY 即启用；契约不变，离线正则自动降级。

八、验收门禁（回归测试）

scripts/test_pipeline.py 用 Python 内置 unittest 覆盖八模块与编排器，共 39 个用例：

改动任何模块后，必须跑 python3 scripts/test_pipeline.py 确认全部通过，方可打 tag 交付。

九、集成说明（整合自 ppt-generator-skill）

本 skill 已完整整合 ppt-generator-skill 的全部可复用能力，可独立完成其全部功能。整合清单：

已合并的能力：
1. 配色方案 12 套 → 并入 contracts.py 的 THEMES（总计 17 套）。
2. 风格库 22 种 → 归一为 18 种 STYLES（合并语义重复项），含关键词触发与精确匹配。
3. 大数据展示版式 big_number、2x2 矩阵 matrix、装饰圆形 → 并入 m08_export.py。
4. 联网检索补全 → 新增 web_distill.py，作为 m02 第三引擎。
5. 字体搭配规范 4 类 → 并入 contracts.py 的 FONT_STYLES。
6. 排版规则/禁止事项 → 并入 contracts.py 的 TYPOGRAPHY / LAYOUT_RULES。

未合并（刻意排除，因与架构冲突）：
- generate.js（pptxgenjs Node 引擎）：与本 skill 的 python-pptx 统一引擎冲突，已由 python-pptx 等价实现全部版式。
- 一次性硬编码示例脚本（generate_full.py/generate_grand.py/generate_mbe.py）：内容写死、非通用引擎，其版式能力已抽象进通用渲染器。

新增文件：web_distill.py。
修改文件：contracts.py、m01_understand.py、m02_distill.py、m04_theme.py、m08_export.py、__init__.py、test_pipeline.py、SKILL.md。
删除文件：无（源 skill 的 Node 引擎与硬编码脚本不并入，非删除本 skill 文件）。