Codex PPT

概述

本技能可根据源材料生成基于图像的 PowerPoint 演示文稿。每张幻灯片均为一张完整的 16:9 尺寸生成图像，最终图像通过 scripts/assemble_ppt.py 组装为 .pptx 文件。

当用户需要视觉风格高度统一的演示文稿，且可接受整页为不可编辑图像时，请使用本技能。若要求每处文本框、图表或形状均须保持独立可编辑状态，则不应使用本技能。

优先使用内置图像生成/编辑工具。仅在以下情形下使用 scripts/image_gen.py：内置后端不可用、缺少必需功能，或用户明确要求 API/CLI 模式。

硬性约束

• 每个阶段开始前，必须先阅读对应的 Reference Map 文件。该文件是编排契约；详细规则位于 docs/ 目录中，各工作节点提示词位于 prompts/ 目录中。
• 须严格遵守审批关卡（approval gates）。在 docs/workflow-gates-and-progress.md 中所列审批完成前，不得生成最终版 deck_spec.json、speech.md、提示词任务（prompt jobs）、幻灯片图像或 .pptx 文件。
• 用户批准样例幻灯片并授权全量生成后，只要子代理（subagent）可用，所有剩余幻灯片图像任务均须分发至幻灯片子代理执行。
• 主代理（main agent）负责流程编排、提示词任务调度、状态记录、质量检查（QA）、演讲者备注（speaker notes）及最终组装。不得在子代理可用的情况下，静默切换为串行生成方式。
• 每张最终版 origin_image/slide_XX.png 必须由选定的图像后端生成：即内置图像生成/编辑工具，或 scripts/image_gen.py。
• 本地绘图、Pillow、SVG、HTML/CSS/canvas 截图、python-pptx/PptxGenJS 布局、手动叠加等手段属于失败模式，而非降级方案（fallbacks）。
• 图像后端一经确认，即须全程固定使用。不得允许子代理为图方便而擅自切换后端。
• 样例幻灯片获批后，须准确记录其生成方式，并将完全一致的方法传递给所有幻灯片子代理。
• 幻灯片分发与结果状态必须通过配套脚本进行记录；仅靠聊天消息无法视为幻灯片已分发或已完成。
• 若所需子代理、图像后端或必需图像路径不可用，应立即中止并报告阻塞项（blocker），注明幻灯片 ID 及证据路径；不得生成低质量替代内容。

可见进度

对于非简易演示文稿，需向用户提供一个可视化的检查清单，其中仅有一个步骤处于“进行中”（active）状态。标准完成依据详见 docs/workflow-gates-and-progress.md。

默认可见步骤如下：

1. 准备源材料、大纲、视觉风格及后端选型决策。
2. 生成并批准一张样例幻灯片。
3. 准备幻灯片任务与状态信息。
4. 分发幻灯片子代理任务。
5. 记录已生成的幻灯片结果。
6. 质量检查、修复、撰写演讲者备注及 PPT 组装。

不得仅凭聊天消息标记某步骤完成；必须以实际文件或脚本记录的状态为准。

默认工作流

1. 理解源内容。

   • 识别主题、目标受众、核心目标、幻灯片数量、视觉/品牌约束，以及需包含或排除的章节。
   • 若未指定幻灯片数量，应选择合理数量；典型演示文稿通常为 8–12 张幻灯片。

2. 规划演示文稿大纲。

   • 在编写或更新 outline.md 前，须先阅读 docs/workflow-gates-and-progress.md 和 docs/outline-style-and-sample.md。
   • 草拟各幻灯片角色及所需源图像；获取用户确认后，在风格、后端、样例及下游产物生成前暂停流程，等待审批。

3. 确认统一视觉风格。

   • 在提供风格选项或使用 references/ 中的文件前，须先阅读 docs/outline-style-and-sample.md。
   • 提供 2–3 种具体风格方向，推荐其中一种，待用户确认后，全程保持单一视觉身份（visual identity），仅按幻灯片角色差异化布局。

4. 确认图像后端。

   • 在生成任何幻灯片图像前，须先阅读 docs/backend-selection.md。
   • 检查内置图像工具是否可调用，说明已执行的验证操作，明确命名所选后端，解释备用方案状态，并等待用户确认。
   • 若选用 CLI/API 备用方案，须阅读 docs/cli-api-fallback.md；仅在配置报错或用户显式提出 API 设置请求时，才需阅读 docs/image-model-configuration.md。

5. 生成一张样例幻灯片供审批。

   • 在生成或审批样例幻灯片前，须先阅读 docs/outline-style-and-sample.md。
   • 须在大纲、风格与后端全部确认后，**仅生成一张**具代表性的样例幻灯片；未经批准前，禁止生成整套幻灯片。
   • 获批后，须将 sample_generation_method 记录至 deck_spec.json，确保后续任务与子代理继承相同路径。

6. 创建项目目录。

   • 在初始化文件夹或组装文件前，须先阅读 docs/project-assembly-and-reporting.md。
   • 若未指定目标路径，则默认使用当前工作目录或源文件所在目录。

7. 准备用户提供的素材。

   • 在使用论文插图、图表、截图、Logo 或其他必需素材前，须先阅读 docs/user-supplied-assets.md。
   • 将必需素材视为严格输入项，并在生成前确认幻灯片与素材的映射关系。

8. 生成全部幻灯片图像。

   • 在全量幻灯片图像生成前，须先阅读 docs/slide-generation-and-subagents.md。
   • 使用 scripts/prepare_slide_prompts.py 或已保存的 prompts/slide_XX.json 文件为每张幻灯片创建独立任务。
   • 每张最终图像必须源自已选定的后端，并通过配套状态脚本完成记录。

9. 分发幻灯片子代理任务。

   • 在分发或替换幻灯片工作节点前，须先阅读 docs/slide-generation-and-subagents.md 和 prompts/slide-worker.md。
   • 尽可能为每项剩余幻灯片任务分配一个子代理；若无法启动所需子代理，且用户未变更工作流，则应中止并报告阻塞项。

10. 质量检查与修复。

    • 在 QA 或组装前，须先阅读 docs/project-assembly-and-reporting.md。
    • 组装前须逐张检查幻灯片：文字内容、是否符合大纲、是否截断、风格一致性、是否存在意外页码、元素重叠、必需素材是否呈现等。
    • 对严重缺陷，使用更精确的提示词重新生成；若后端支持局部编辑，则优先采用该方式处理局部问题。
    • 针对 CLI/API 备用方案的编辑命令，须参考 docs/cli-api-fallback.md；仅在验证编辑输出无误后，方可替换最终幻灯片。

11. 撰写演讲者备注并组装 PPT。

    • 在编写 speech.md 或运行组装脚本前，须先阅读 docs/project-assembly-and-reporting.md。
    • 确保 outline.md 反映最终确认的大纲；speech.md 的标题须与 Slide N 一一对应。
    • 组装前，须确认 slide_jobs.json 中所有幻灯片状态为 recorded，且样例幻灯片状态为 accepted；若存在任一幻灯片状态为 pending、dispatched 或 blocked，则必须中止。

12. 汇报结果。

    • 使用 docs/project-assembly-and-reporting.md 中的最终汇报检查清单。
    • 汇报内容须包括路径、幻灯片总数、所用后端、记录结果状态，以及任何限制条件或阻塞项。

13. 保存可复用的视觉风格。

    • 若用户要求保存当前演示文稿风格，或提供的图像/PDF/PPT/PPTX 风格，须先阅读 docs/style-library.md。
    • 若最终演示文稿使用了自定义或适配风格，应主动在最终汇报中提供保存选项（依据 docs/project-assembly-and-reporting.md）；用户自定义风格存储于 ${CODEX_PPT_HOME:-~/.codex-ppt-skill}/references/（位于技能安装目录之外）。

子代理分发

样例幻灯片获批后，只要运行时环境支持启动子代理，分发幻灯片子代理即为强制要求。主代理负责准备任务与记录状态；每个子代理仅处理一个 prompts/slide_XX.json 任务，并仅返回选定图像路径、后端标识及 QA 备注。

分发逻辑、命令、结果记录、阻塞处理及后端溯源，请参考 docs/slide-generation-and-subagents.md；交接模板请参考 prompts/slide-worker.md。

子代理不得修改 outline.md、deck_spec.json、其他幻灯片任务、origin_image/、speech.md 或最终 .pptx；所有输出均由父代理记录并完成最终组装。

验收标准

• 输出为有效的 .pptx 文件。
• 每张预期的最终幻灯片图像均存在于 origin_image/slide_XX.png 路径下。
• 每张最终幻灯片图像均由已确认的后端生成，并通过 record_slide_result.py 完成记录（经审批的样例幻灯片若已在运行状态中标记为 accepted，则可豁免此条）。
• outline.md 准确反映已批准的演示文稿大纲。
• 当预期需提供演讲者备注时，speech.md 必须存在，且组装过程须将这些备注写入 PPT。
• slide_jobs.json 与 slide_run_state.json 准确反映最终状态。
• 必需的源图像须在幻灯片中清晰呈现；否则须报告阻塞项。
• 若流程受阻，最终响应须明确指出所处阶段、幻灯片 ID、证据路径及未完成原因；不得宣称演示文稿已完成。

参考映射表（Reference Map）

• docs/workflow-gates-and-progress.md：审批关卡、进度跟踪、完成依据。
• docs/backend-selection.md：后端选型规则与确认文本。
• docs/outline-style-and-sample.md：大纲、风格、样例规则及提示词示例。
• docs/user-supplied-assets.md：必需源素材的严格处理规范。
• docs/slide-generation-and-subagents.md：任务定义、分发机制、结果记录、阻塞处理与后端溯源。
• docs/cli-api-fallback.md：备用运行时、生成/编辑命令、图像限制及故障排查。
• docs/image-model-configuration.md：API 密钥、基础 URL、模型名称、.env 配置；仅在需要配置时阅读。
• docs/project-assembly-and-reporting.md：项目目录结构、备注撰写、PPT 组装、最终汇报及提示词设计原则。
• prompts/slide-worker.md：幻灯片子代理交接模板。
• references/*.md：内置视觉风格参考文档；用户自定义风格存于 ${CODEX_PPT_HOME:-~/.codex-ppt-skill}/references/，同名时优先级高于内置风格。

文档与更新

关于源代码、文档、安装、配置及示例，请参阅 ningzimu/codex-ppt-skill。