codex-ppt

Codex PPT

概述

此技能从源材料创建基于图像的PowerPoint演示文稿。每张幻灯片都是一张完整的16:9生成图像。最终图像通过scripts/assemble_ppt.py组装成.pptx。

当用户想要视觉统一的演示文稿并接受全幻灯片图像页面时使用此技能。当每个文本框、图表或形状必须保持单独可编辑时，请勿使用。

优先使用内置图像生成/编辑工具。仅当内置后端不可用、缺少所需功能或用户明确要求API/CLI模式时，才使用scripts/image_gen.py。

硬约束

• 在每个阶段之前阅读相关的Reference Map文件。此文件是编排契约；详细规则位于docs/中，工作提示位于prompts/中。
• 尊重审批关口。在docs/workflow-gates-and-progress.md中的审批完成之前，不要创建最终的deck_spec.json、speech.md、提示作业、幻灯片图像或.pptx。
• 在用户批准示例幻灯片并授权生成完整演示文稿后，只要子代理可用，每个剩余的幻灯片图像作业必须分派给幻灯片子代理。
• 主代理负责编排、提示作业、状态记录、质量保证、演讲者备注和组装。不要静默地用顺序生产替换可用的幻灯片子代理。
• 每个最终的origin_image/slide_XX.png必须由选定的图像后端生成：内置图像生成/编辑工具或scripts/image_gen.py。
• 本地绘图、Pillow、SVG、HTML/CSS/画布截图、python-pptx/PptxGenJS布局和手动叠加是失败模式，不是回退方案。
• 选定的图像后端必须在后端确认后保持不变。不要让子代理为了方便而切换后端。
• 在示例批准后，记录批准示例的生成方式，并将该确切方法传递给每个幻灯片子代理。
• 幻灯片分派和结果状态必须使用捆绑脚本记录。仅聊天消息不能使幻灯片分派或完成。
• 如果所需的子代理、图像后端或必需图像路径不可用，则停止并报告阻塞，附上幻灯片ID和证据。不要创建低质量的替代品。

可见进度

对于非平凡的演示文稿，保持一个用户可见的检查清单，其中包含一个活动步骤。规范完成证据在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个具体的样式方向，推荐一个，等待确认，然后保持一个视觉标识，同时根据页面角色变化布局。

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。
   • 在大纲、样式和后端确认后，仅生成一张代表性示例。在批准之前不要生成完整演示文稿。
   • 批准后，在deck_spec.json中记录sample_generation_method，以便作业和子代理继承相同路径。

6. 创建项目目录。

   • 在初始化文件夹或组装文件之前，阅读docs/project-assembly-and-reporting.md。
   • 如果未指定目标，使用当前工作目录或源文件目录。

7. 准备用户提供的资源。

   • 在使用论文图表、截图、标志或其他必需资源之前，阅读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. 质量检查和修复。

    • 在质量保证或组装之前，阅读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反映最终确认的演示文稿大纲。使用映射到Slide N的speech.md标题。
    • 在组装前，确保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作业，并仅返回选定的图像路径、后端和质量保证备注。

使用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、证据路径和未完成原因；不要将演示文稿称为完成。

参考映射

• 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：项目目录、备注、组装、最终报告、提示原则。
• prompts/slide-worker.md：幻灯片子代理交接模板。
• references/*.md：内置视觉样式参考。用户自定义样式位于${CODEX_PPT_HOME:-~/.codex-ppt-skill}/references/中，优先于同名的内置样式。

文档和更新

有关源材料、文档、安装、配置和示例，请参见ningzimu/codex-ppt-skill。