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。
• 用户批准示例幻灯片并授权生成完整演示文稿后，只要子 Agent 可用，其余每张幻灯片的图像任务都必须派发给幻灯片子 Agent。
• 主 Agent 负责编排、提示词任务、状态记录、QA、演讲者备注和组装。不得悄悄改用顺序制作来取代可用的幻灯片子 Agent。
• 每张最终的 origin_image/slide_XX.png 都必须由选定的图像后端生成：内置图像生成/编辑工具或 scripts/image_gen.py。
• 本地绘图、Pillow、SVG、HTML/CSS/canvas 截图、python-pptx/PptxGenJS 布局和手动叠加都属于失败方式，不是备用方案。
• 后端确认后，必须始终使用同一个图像后端。不得让子 Agent 为图方便而切换后端。
• 示例获批后，记录获批示例的生成方式，并将完全相同的方法交给每个幻灯片子 Agent。
• 幻灯片派发和结果状态必须通过随附脚本记录。仅靠聊天消息不能将幻灯片标记为已派发或已完成。
• 如果所需的子 Agent、图像后端或必需的图像路径不可用，请停止并报告阻碍事项，同时提供幻灯片 ID 和证据。不要创建质量较低的替代品。

可见进度

对于非简单的演示文稿，请维护一份用户可见的清单，并保持只有一个步骤处于进行中。完成情况的权威证据见 docs/workflow-gates-and-progress.md。

默认可见步骤：

1. 准备源材料、提纲、风格和后端决策。
2. 生成并批准一张示例幻灯片。
3. 准备幻灯片任务和幻灯片状态。
4. 派发幻灯片子 Agent。
5. 记录生成的幻灯片结果。
6. QA、修复、备注和 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. 质量检查和修复。

    • 执行 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 反映最终确认的演示文稿大纲。使用与 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/ 中。

子 Agent 分派

样例获批后，只要运行时可以启动子 Agent，就必须使用子 Agent。主 Agent 准备任务并记录状态；每个工作 Agent 只处理一个 prompts/slide_XX.json 任务，并且只返回所选图片路径、后端和 QA 备注。

分派、命令、结果记录、阻塞项和后端来源信息请参阅 docs/slide-generation-and-subagents.md。请使用 prompts/slide-worker.md 作为交接模板。

子 Agent 不得编辑 outline.md、deck_spec.json、其他幻灯片任务、origin_image/、speech.md 或最终的 .pptx。父 Agent 负责记录输出并组装。

验收标准

• 输出是有效的 .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：幻灯片子 Agent 交接模板。
• references/*.md：内置视觉风格参考。用户自定义风格位于 ${CODEX_PPT_HOME:-~/.codex-ppt-skill}/references/，其优先级高于同名内置风格。

文档与更新

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