企业官网建设流程全解析

• AI 技能
• 人工智能

本篇技术指南以 Codex PPT Skill（一个面向 Codex、Claude Code、OpenClaw、Hermes Agent 等支持SKILL.md的 agent 的图片式 PPT 生成 skill）的标准工作流文档为主体，完整讲解其「阶段确认、先样张后批量」的生产流程：阅读输入材料、确认大纲、确认视觉风格、确认图片后端、生成并确认样张、批量生成、质量检查与修复、演讲稿与组装、可选保存风格。读完本文，你将掌握这套 skill 从输入文章到产出.pptx的完整执行契约、每个阶段的门禁（approval gate）与产物，以及背后配套脚本（prepare_slide_prompts.py、slide_job_status.py、record_slide_result.py、assemble_ppt.py 等）的调用方式。

工作流总览：为什么强调阶段确认

Codex PPT 的核心设计理念不是"一次生成整套 PPT"，而是分阶段确认、降低返工成本。这一点在设计理念文档中表述得很直接：AI 做 PPT 最重要的不是快，而是流程可控、做出来可用。

具体到执行层面，标准流程不会一上来直接生成整套 PPT，而是依次确认大纲、风格、图片后端和样张，全部通过后才进入批量生产。流程被划分为 9 个阶段：

1. 阅读输入材料
2. 确认大纲
3. 确认视觉风格
4. 确认图片生成后端
5. 生成并确认样张
6. 批量生成
7. 质量检查与修复
8. 演讲稿与组装
9. （可选）保存风格

其中阶段 1–5 是"确认前置期"，阶段 6–8 是"生产期"，阶段 9 是收尾增值动作。

从源码契约看，这套阶段的强制性比文档叙述更严格。SKILL.md 的 Hard Constraints 明确写死了一条硬约束：在用户批准相应门禁之前，不得创建正式的deck_spec.json、speech.md、slide prompt 任务、幻灯片图片或.pptx文件。而 workflow-gates-and-progress.md 给出了完整的门禁顺序：

1. Source reading and asset extraction（输入阅读与素材提取）
2. Outline confirmation（大纲确认）
3. Visual style confirmation（视觉风格确认）
4. Image backend confirmation（图片后端确认）
5. One sample slide approval（单页样张批准）
6. Full slide generation（整套生成）
7. QA, speaker notes finalization, and PPT assembly（质检、讲稿定稿与组装）

任何阶段都不得在用户批准前一阶段前推进，除非用户明确要求跳过确认。若在批准前确实需要内部规划产物，必须用.draft.命名（如deck_spec.draft.json、speech.draft.md），并向用户明确声明"这不是最终产物"。

阶段 1：阅读输入材料

agent 的第一步是理解输入，而不是急着出图。需要搞清的信息包括：

• 主题和核心观点
• 目标受众
• 演示目标
• 页数要求
• 必须包含或排除的内容
• 是否有必需图片素材（如论文原图、实验结果图、架构图、截图、Logo）

其中"页数"在 SKILL.md 中有默认策略：如果用户没有指定页数，agent 应选择一个实际可行的页数，典型 deck 为8–12 页。

这一阶段通常不产生文件产物，但它决定了后续大纲的信息密度和素材映射，是整个流程的信息地基。

阶段 2：确认大纲

阅读完输入材料后，agent 会生成outline.md大纲文件，通常为每一页定义：

• Slide 编号
• 每页标题
• 3–5 个要点
• 页面角色，如封面、目录、概念解释、流程、对比、数据证据、总结等
• 可选视觉想法
• 必需图片素材及其用途

大纲确认前，不应生成正式 slide 图片、speech.md或.pptx。

在outline-style-and-sample.md中，大纲的具体要求被进一步细化：每个 slide 除了标题和要点，还要写清layout role and intent（版面角色与意图），例如 cover、agenda、section divider、concept explanation、process、comparison、timeline、data evidence、architecture、case study、summary、Q&A。对于使用原始图片的页面，需要写明图片路径或附件名、它在页面上的角色，以及它是"严格输入素材（strict input asset）"还是仅作"风格/版式参考"。

大纲草稿建议结构：

Slide 1: Cover Slide 2: Context / problem Slide 3-7: Main argument or sections Slide 8: Summary / recommendation / closing

涉及素材的页面可以这样写，让用户在大纲评审阶段就能直观核对素材映射：

Slide 5: Experiment Results - Key points: ... - Required images: - Main evidence figure; strict input asset; preserve data, axes, labels, legends, colors, and values Result 01 - Supporting model architecture; strict input asset; preserve labels and arrows Model Architecture

一个关键细节：大纲中用 Markdown 图片语法内嵌本地素材后，prepare_slide_prompts.py 后续可以把同样的素材转成结构化的 prompt 输入。从源码行为看，该脚本支持从deck_spec.json中的字符串形式（如strict input asset\n\nResult 01）提取图片路径，并把周边描述/alt 文本带入图片角色。

如果 deck 使用了必需的原始图片，大纲确认这一步还需要停下来，请用户逐页核对 slide-to-image 映射是否正确，之后才能进入风格选择或图片生成。

大纲被用户批准后，agent 应报告outline.md路径、slide 数量、必需素材及其页面对应关系，并说明"尚未生成任何 slide 图片或 PPTX"。

阶段 3：确认视觉风格

agent 会给出2–3 个风格方向并推荐一个。候选风格来自两个地方：

• 内置风格库：skill 随包发布的 12 种内置风格参考文件，位于 skills/codex-ppt/references/，包括清爽专业风、创意杂志风、电子墨水杂志风、数据仪表盘风、科研答辩风、复古扁平插画风、手绘技术解释风、手绘白板风、温暖手工风、麦肯锡风格、党政红风格、教学课件风；
• 个人风格库：存放在~/.codex-ppt-skill/references/（可用CODEX_PPT_HOME环境变量改变位置），位于 skill 安装目录之外，更新 skill 不会丢失。

除此之外，也可以基于用户提供的截图、PDF 或 PPT复刻风格。

风格不是固定模板，而是一套视觉系统（配色、字体气质、版式密度、插画语言）。选择风格后，整套 PPT 保持统一视觉语言，但每页版式根据内容角色变化——不会每页长得一样。

关于风格确认，outline-style-and-sample.md 有几个重要规则：

• 已有明确风格时不强制二选一：如果用户已指定风格、提供了风格图片或 PDF/PPT/PPTX 参考，不要强行走 2–3 选一流程，而是提取可用风格规则并简要复述后，直接进入后端确认和样张生成。
• PDF/PPT 风格必须看渲染图：不要仅从文档结构、大纲文本、XML、文件元数据或 slide 对象层级推断视觉系统。先渲染/导出代表页面为真实页面图片，再看渲染图推导风格；多视觉分区文件要覆盖足够多的代表页。
• 默认只仿风格、不复用内容：除非用户明确要求，参考材料里的文字和数据不会被搬进新 PPT。
• 推荐文案要具体：每个风格选项应简要说明配色、版式系统、字体方向、插画/图片处理、装饰元素、密度与留白规则，而不是空泛的"好看、专业"。文档给出了一个风格确认示例：

我建议用 A，因为它最适合这份内容的受众和表达目标。 A. 清爽专业风（推荐）：浅色背景、蓝绿强调色、结构清晰，适合汇报、答辩和技术分享。 B. 创意杂志风：大标题、强图片、留白更大胆，适合分享和传播。 C. 数据仪表盘风：指标卡、图表感布局，适合数据密集型报告。 你选哪个？也可以指定要调整的配色、布局或插画方向，或者上传一张喜欢的 PPT 风格图片让我参考。

• 同名优先：如果个人风格和某个内置风格同名，以个人风格为准——这也可以用来"定制"内置风格。个人风格库通过扫描目录自动发现，无需登记；agent 在提供风格选项前应列出个人风格目录（若存在）并与内置风格合并展示。

阶段 4：确认图片生成后端

Codex PPT 支持两种图片后端：

1. 内置图片生成工具（优先）：Codex 中通常是image_gen工具，OpenClaw 中可能是image_generate。在 SKILL.md 中明确要求：优先使用内置图片生成/编辑工具。
2. 本地 API/CLI fallback：使用 image_gen.py。只有在内置工具不可用、用户明确要求 API/CLI fallback、或当前能力无法满足时，才切换过去。

backend-selection.md 给出了决策规则与确认话术：

• 先主动探测，不靠猜：在推荐 fallback 之前，必须主动检查当前环境能否调用内置生图工具，不能仅凭 agent 名称或订阅上下文推断。
• 不要为了便利而 fallback：仅凭"能直接输出--out文件路径、本地文件管理更方便、可复用本地配置、便于批处理或自动化"这些理由，不足以切换后端。分辨率、质量、宽高比或 slide 编辑需求本身也不构成 fallback 的理由——先检查当前工具实际暴露的参数。
• 选型要确认：生成第一张图之前，要告诉用户你检查了哪些工具可用性、计划用哪个后端、为什么需要或不需要 fallback，并等待确认。

内置后端的确认话术示例：

我检查到当前环境可调用内置图片生成工具（Codex 通常是 image_gen，OpenClaw 通常是 image_generate），因此准备优先用内置工具生成样张，不切到本地 API/CLI fallback。可以开始生成 1 页样张吗？

CLI/API fallback 的确认话术示例：

我检查后没有可用的内置图片生成工具，或内置工具缺少本页必需能力，因此准备使用本地 API/CLI fallback 生成样张，读取 ~/.codex-ppt-skill/.env 中的 OPENAI_BASE_URL / CODEX_PPT_IMAGE_MODEL 配置。可以开始生成 1 页样张吗？

后端一旦确认，整套 PPT 保持一致，不应中途切换——这是 SKILL.md 的硬约束之一：不要为了让子智能体方便而临时切换后端。

CLI/API fallback 模式的运行细节（生成、编辑命令、尺寸）将在阶段 6 展开；其模型默认值是gpt-image-2.5-flare，可通过CODEX_PPT_IMAGE_MODEL环境变量覆盖。

阶段 5：生成并确认样张

大纲、风格、后端三项都确认后，agent 会只生成 1 页样张，用来检查：

• 文字是否清晰
• 风格是否符合预期
• 页面密度是否合适
• 色彩和排版是否稳定
• 是否适合批量扩展到整套 PPT

样张通过后，才批量生成整套。

样张的生成规则（见 outline-style-and-sample.md）：

• 使用已确认的风格描述；
• 条件允许时，优先选择有代表性的内容页而非封面，以展示风格在真实内容页上的适配节奏，而不是套一个通用模板；
• 直接以最终 slide 文件名保存，如{base_dir}/{deck_name}/origin_image/slide_08.png；在 CLI/API fallback 模式下用scripts/image_gen.py generate --out写入该确切路径；
• 不要在origin_image/里创建sample_slide.png，因为组装环节是围绕正式slide_XX文件名设计的；
• 将样张展示给用户，请用户确认视觉风格、字体排版、版面密度和中文字质量。

样张被批准后有一个关键动作：在deck_spec.json中记录sample_generation_method（样张生成方法），包括至少：

• backend_used：确认的后端标签，如built-in image tool或scripts/image_gen.py；
• tool_name：实际使用的工具或命令，如image_gen、image_generate或scripts/image_gen.py；
• mode：generate或edit；
• prompt_source：样张 prompt 的来源；
• size、quality及后端暴露的模型/配置细节；
• approved_sample_path：被批准的origin_image/slide_XX.png路径；
• input_context_preparation：本地源图/风格图如何提供给生图（如内置模式下用view_image）；
• handoff_rule：子智能体必须使用相同后端/工具/模式，路径不可用时返回 blocker。

这是父 agent 传给所有子智能体的"契约"——保证批量生产走与样张完全相同的生图路径，而不是退化成更便宜的本地渲染路径。

阶段 6：批量生成

样张确认后，agent 逐页生成origin_image/slide_XX.png。在支持子智能体的环境中，由一个子智能体负责一页、并行生成，加快多页产出；所有页面沿用样张确认的同一风格和同一生图后端。

在进入批量生产前，需要先补齐最终下游产物（见 slide-generation-and-subagents.md）：

• deck_spec.json
• prompts/slide_XX.json（每个 slide 一个自包含任务）
• speech.md

这些产物必须在大纲批准之后才能创建。deck_spec.json必须在运行prepare_slide_prompts.py之前包含从样张复制的sample_generation_method；该脚本会把它复制进每个prompts/slide_XX.json和slide_jobs.json。

用脚本准备每页任务

优先使用确定性辅助脚本生成结构化的每页生图任务：

~/.codex-ppt-skill/.venv/bin/python {skill_root}/scripts/prepare_slide_prompts.py \ --spec {base_dir}/{deck_name}/deck_spec.json \ --out-dir {base_dir}/{deck_name} \ --selected-backend "<confirmed backend label>" \ --force

脚本会产出：

{base_dir}/{deck_name}/ ├── prompts/ │ ├── slide_01.json │ ├── slide_02.json │ └── ... ├── slide_jobs.json └── slide_run_state.json

每个prompts/slide_XX.json是自包含的 slide 任务：包含 slide 编号、标题、输出文件名、输入图片列表、是否需要上下文图片，以及完整 prompt 文本。这些 JSON 任务文件同时服务于内置生图、CLI/API fallback 协调和子智能体交接。

给子智能体喂足上下文

父 agent 负责在派发前打包上下文。一个 slide 子智能体只看到分配给它的单页任务、显式传给他的图片和交接文本——它不知道源文章、完整大纲、其他页或只存在于父 agent 对话上下文里的概念。因此：

• 用 deck 级deck_context放多页共用的规范概念：源文摘要、核心论点、术语表、分类体系、角色、定义、时间线、必要命名；
• 用 slide 级local_context放单页专属事实："总结这六个特征""对比这两个方法""延续三步框架""使用这句原话"等；
• 像"上述六个特征""上面的框架""之前的结论""这些例子"这类隐式引用，必须展开成显式列表或定义，写进deck_context或local_context。

目标不是让子智能体去补全缺失上下文，而是让父 agent 把每个工作包打包到"直接执行该页"即可的完整程度。

每页任务的结构化视觉简报

slide-generation-and-subagents.md 给出了一份完整的结构化视觉简报 JSON 模板，把 canvas、style、deck_context、layout、text、local_context、visual_elements、constraints 分层表达，而不是只靠一长段风格文字。要点包括：

• canvas.aspect_ratio: "16:9"、use_full_canvas: true、slide_number: "do not render a slide number"（不要在图中渲染页码）；
• style中固化同一套visual_direction，保证整套配色、字体、图标语言、纹理、情绪一致；
• layout.role按页面内容角色选择（cover、agenda、section divider、concept、process、comparison、timeline、data evidence、architecture、case study、summary、Q&A），layout.intent说明为什么该页用这个版式，并遵守variation_rule：风格统一但版式随角色变化，相邻页不要重复同一 blueprint，除非是刻意设计的重复序列；
• text.text_quality明确要求 "render all Chinese text exactly, clearly, and without garbled characters"（中文精确渲染、清晰、无乱码）；
• constraints写死：最终图片本身必须包含标题和要点、所有文字可读且拼写正确、与其余页风格一致、无水印、无无关 Logo、无额外页码。

这套模板要求"一页一次生图请求"，并建议在整份 deck 中刻意混合不同页面类型（封面/分区页、问题框架、流程/时间线、对比/权衡、数据/KPI、架构/流程图、总结/下一步），避免所有页都是同一个三卡布局。

子智能体并行与状态记录

样张批准并授权整套生成后，只要当前运行时能生成子智能体，就必须使用子智能体并行：每个剩余 slide 任务一个子智能体，不允许为了省事而顺序生成。如果子智能体无法派生，应在派发步骤停下并报告 blocker，而不是降级成低质量顺序生成。

父 agent 职责要点：

• 拥有outline.md、deck_spec.json、prompts/、origin_image/、QA、speech.md和最终组装；
• 派发前运行slide_job_status.py查看可派发名额与待处理 slide id；
• 样张 slide 以"仅风格参考"输入图的形式包含进每个非样张任务；
• 立即为每个成功派发的子智能体运行record_slide_dispatch.py；
• 每个 worker 返回后，目检其选中输出，再运行record_slide_result.py把选中图片复制进origin_image/slide_XX.png并记录后端来源；
• worker 无法使用选定后端或无法访问必需输入图时，运行record_slide_blocker.py并报告 blocker。

子智能体职责要点：

• 只读分配给它的prompts/slide_XX.json；
• 只用选定后端，不得在image_gen与 CLI/API fallback 之间切换；
• 遵守任务中的sample_generation_method，使用与样张相同的工具族、生成/编辑模式、图像上下文准备和模型配置；
• 不得用本地绘图、HTML/SVG/canvas 截图、Pillow、python-pptx/PptxGenJS 排版或手动合成文本/图片叠加来制作最终 slide 图；
• 把样张当风格参考、把必需素材当严格输入资产，返回前自检文字质量、风格一致性、必需图片是否入页、版式问题；
• 只返回三样东西：选中的原始生成图片路径、所用后端、一句 QA 说明。

派发循环的脚本命令：

~/.codex-ppt-skill/.venv/bin/python {skill_root}/scripts/slide_job_status.py \ {base_dir}/{deck_name} ~/.codex-ppt-skill/.venv/bin/python {skill_root}/scripts/record_slide_dispatch.py \ {base_dir}/{deck_name} \ --slide slide_02 \ --agent-id <agent id> \ --agent-nickname "<nickname if available>" \ --prompt-file prompts/slide_02.json

结果记录：

~/.codex-ppt-skill/.venv/bin/python {skill_root}/scripts/record_slide_result.py \ {base_dir}/{deck_name} \ --slide slide_02 \ --agent-id <agent id> \ --backend-used "built-in image tool" \ --selected-source /absolute/path/to/generated/slide_02.png \ --qa-note "Text readable; style matches the approved sample."

Blocker 记录：

~/.codex-ppt-skill/.venv/bin/python {skill_root}/scripts/record_slide_blocker.py \ {base_dir}/{deck_name} \ --slide slide_02 \ --agent-id <agent id> \ --reason "selected image backend unavailable in worker"

子智能体交接模板位于 prompts/slide-worker.md，派发时必须使用该模板，而不是临时自造 worker 提示词。

CLI/API fallback 模式下的批量生图

如果后端确认环节选择了 CLI/API fallback，运行 image_gen.py 前需要先确保共享运行时存在：若~/.codex-ppt-skill/.venv/bin/python缺失或依赖导入失败，先执行：

python3 {skill_root}/scripts/codex_ppt_runtime.py bootstrap

这是 skill 的内部环境准备步骤，除非依赖安装失败需要用户介入，否则不应让用户手动执行。

单页生成命令：

~/.codex-ppt-skill/.venv/bin/python {skill_root}/scripts/image_gen.py generate \ --model gpt-image-2.5-flare \ --prompt-file {prompt_file} \ --size 2560x1440 \ --quality medium \ --out {base_dir}/{deck_name}/origin_image/slide_01.png

fallback CLI 默认gpt-image-2.5-flare，可选--model gpt-image-2.5-sunburst，也接受 provider 前缀模型名和旧版 GPT Image 模型（使用前需确认 provider 支持）。默认输出2K 16:9 横版2560x1440、medium质量；GPT Image 2.5 还支持xhigh和max（旧模型保持原有质量上限）。只有用户要求 4K、文字密集页需要更清晰输出或默认结果模糊时，才用--size 3840x2160 --quality high；人像竖版仅当用户要求时才用--size 2160x3840。注意：GPT Image 2.5 下超过2560x1440的输出属于实验性，需要检查实际尺寸与视觉质量。

从prompts/slide_XX.json生成且任务不需要输入图时，可以这样取 prompt 字段：

python3 -c 'import json, pathlib; print(json.loads(pathlib.Path("{base_dir}/{deck_name}/prompts/slide_01.json").read_text())["prompt"])' | \ ~/.codex-ppt-skill/.venv/bin/python {skill_root}/scripts/image_gen.py generate \ --prompt-file - \ --size 2560x1440 \ --quality medium \ --out {base_dir}/{deck_name}/origin_image/slide_01.png

关键限制：这条纯文本generate路径不会附加输入图片。如果prompts/slide_XX.json的input_images非空或requires_context_images为 true，就必须改用能传图的路径（内置工具让图片可见，或支持图片输入的 CLI/API edit 路径）；没有任何可用路径时，停下来问用户是否切换后端，绝不允许用纯文本生成替代严格输入素材。

最终 slide 图片命名与落盘规则

• 按 slide 顺序严格命名：slide_01.png、slide_02.png、slide_03.png……普通 deck 用两位零填充；
• 已批准的样张应已具备正确的slide_XX.png文件名并直接复用；
• 被否决的变体、草稿、参考图不要放进origin_image/，需要保留时放在项目根目录或独立drafts/目录；
• 组装前确认每个期望的slide_XX.png都存在、无缺失无多余，且slide_job_status.py显示所有非样张任务为recorded。

阶段 7：质量检查与修复

组装前，agent 会逐页检查以下问题（见 project-assembly-and-reporting.md）：

• 文字是否清晰、有无乱码
• 内容是否与大纲一致
• 标题和要点是否被截断
• 视觉风格是否跨页统一
• 是否出现多余页码（除非用户要求）
• 重要元素是否重叠

修复策略分两档：

• 严重问题（文字/版式大问题）：用更受约束的提示词重新生成该页；
• 局部小问题：优先使用选定后端的编辑能力定向修复。CLI/API fallback 模式下用：

~/.codex-ppt-skill/.venv/bin/python {skill_root}/scripts/image_gen.py edit \ --image {slide_path} \ --prompt {edit_prompt} \ --out {new_slide_path}

且只有验证编辑输出合格后，才能替换最终 slide 图片。

从 SKILL.md 的 Hard Constraints 看，本地绘图、Pillow、SVG、HTML/CSS/canvas 截图、python-pptx/PptxGenJS 排版、手工叠加等都属于"失败模式（failure modes）"而不是 fallback——绝不能用来修补或生成最终页。若必需的子智能体、生图后端或必需素材路径不可用，应停下并报告带 slide id 和证据的 blocker，而不是做一个低质量替代品。

阶段 8：演讲稿与组装

QA 通过后，生成speech.md演讲稿，然后用 assemble_ppt.py 组装成.pptx，演讲稿会自动写入每页 PPT 的备注区。

演讲稿写作规范

project-assembly-and-reporting.md 对speech.md的要求很细：

• outline.md必须反映最终确认的 deck 大纲，不要在此处从零重建；
• speech.md是能直接照着讲的演讲词，不是可见 slide 文字的摘要；中文 deck 用中文写；
• 先按 deck 内容、受众和目的选定一种交付风格（技术讲解、论文研读、产品/融资 pitch、培训工作坊、高管汇报），并让风格真正塑造讲稿——结论多直接、讲多少背景、用哪些例子、节奏多快、转场怎么措辞；
• 长度参考：标题/目录/分区页 1–2 个短段落；普通内容页通常 2–5 个短段落（中文约 150–400 字）；密集概念/架构/数据/论文解读页可更长，但过长要拆分；
• 从演讲者视角写，面向听众：先亮结论再讲细节、按观众应看的顺序讲解视觉元素、补充例子/对比/注意事项/"所以呢"，避免"本页主要介绍了……""综上所述……"这类套话，也不要提及讲稿是 AI 生成的。

speech.md的标题必须能被组装脚本映射回页码：

## Slide 1: {Title} {Presenter talk track for slide 1. For Chinese decks, write this in Chinese. Include an optional transition sentence at the end when useful.} ## Slide 2: {Title} {Presenter talk track for slide 2}

组装命令

运行组装前确保共享运行时存在（缺失时python3 {skill_root}/scripts/codex_ppt_runtime.py bootstrap）。组装命令：

~/.codex-ppt-skill/.venv/bin/python {skill_root}/scripts/assemble_ppt.py {base_dir} {deck_name}.pptx --aspect-ratio 16:9

组装脚本的关键行为（结合 assemble_ppt.py 源码）可以归纳为：

• {base_dir}是{deck_name}/的父目录，{deck_name}.pptx必须与项目文件夹同名；
• 只从{base_dir}/{deck_name}/origin_image/读取图片；
• 只读取符合slide_XX.png等正式命名模式的最终图——源码中用正则^slide_(\d+)\.(png|jpe?g|gif|bmp)$过滤，草稿和sample_slide.png会被忽略，避免误装入 PPT；
• 支持16:9和4:3两种宽高比，默认用16:9；
• 若speech.md存在且使用Slide N标题，会把备注写入对应页的 PPT speaker notes；
• 输出{base_dir}/{deck_name}/{deck_name}.pptx；
• 组装前置校验：slide_jobs.json中所有已生成 slide 应为recorded、已批准样张应为accepted；若有任何 slide 处于pending、dispatched或blocked，必须停下并报告该状态。

另外，image_gen.py会自动加载~/.codex-ppt-skill/.env中的OPENAI_API_KEY、OPENAI_BASE_URL、CODEX_PPT_IMAGE_MODEL；排查 API 访问问题可运行python3 {skill_root}/scripts/codex_ppt_runtime.py doctor --check-api。

项目目录结构

整个流程的产物统一放在如下结构中（也是组装脚本约定的输入布局）：

{base_dir}/{deck_name}/ ├── origin_image/ │ ├── slide_01.png │ ├── slide_02.png │ └── ... ├── prompts/ │ ├── slide_01.json │ └── ... ├── slide_jobs.json ├── slide_run_state.json ├── deck_spec.json ├── outline.md ├── speech.md └── {deck_name}.pptx

用户未指定输出位置时，使用当前工作目录或源文件所在目录。

最终报告

组装完成后，最终报告应包含：项目目录、PPT 文件路径、slide 图片目录、outline.md路径、speech.md路径、slide_jobs.json路径、slide 数量、确认所用图片后端且所有非样张结果已通过record_slide_result.py记录、讲稿是否已写入 PPT、被重新生成/阻塞/仍有限制的 slide，以及任何已知限制。

如果这套 deck 使用了自定义或明显调整过的风格，报告结尾还应主动提示用户保存风格（详见阶段 9）。

阶段 9（可选）：保存风格

如果这套 PPT 用的是自定义或调整过的风格，agent 会在最终报告里提示：可以把它保存到个人风格库，以后直接按名字复用。

保存机制要点（详见风格与个人风格库）：

• 存放位置：~/.codex-ppt-skill/references/（可通过CODEX_PPT_HOME环境变量改变），在 skill 安装目录之外，更新或重装 skill 不丢失；
• 自动发现：保存后无需登记，之后制作 PPT 选风格时 agent 自动扫描个人风格库，与内置风格一起列出；
• 同名优先：个人风格与内置风格同名时以个人风格为准，可借此"覆盖"内置风格；
• 复用方式：直接说风格名，如"用『深色数据科技风』生成这份 PPT"。

对用户来说，保存动作就是一句提示词：

这套 PPT 的视觉风格我很喜欢，请保存到个人风格库。

贯穿全程的可见进度与完成证据

由于整个流程门禁多、产物多，SKILL.md 要求非平凡 deck 保持一个用户可见的检查清单，每一步只有真实文件或脚本记录的状态才算完成，聊天里的口头声明不算。默认的可见步骤为：

1. Prepare source, outline, style, and backend decisions（准备源材料、大纲、风格、后端决策）
2. Generate and approve one sample slide（生成并批准一页样张）
3. Prepare slide jobs and slide state（准备 slide 任务与状态）
4. Dispatch slide subagents（派发子智能体）
5. Record generated slide results（记录生成的 slide 结果）
6. QA, repair, notes, and PPT assembly（QA、修复、讲稿与组装）

各步骤的完成证据（workflow-gates-and-progress.md）为：

• 步骤 1：outline.md已批准且图片后端已确认；
• 步骤 2：有一张最终origin_image/slide_XX.png被批准为风格基准；
• 步骤 3：prompts/slide_XX.json、slide_jobs.json、slide_run_state.json已存在；
• 步骤 4：slide_job_status.py显示有可派发任务，且每个派发的 worker 由record_slide_dispatch.py记录；
• 步骤 5：每个 worker 输出由record_slide_result.py记录（复制选中图到origin_image/slide_XX.png并记录后端来源）；
• 步骤 6：所有期望最终图存在、QA 完成、speech.md定稿、{deck_name}.pptx存在。

整套验收标准（SKILL.md 的 Acceptance Criteria）还包括：输出是有效.pptx；每个期望最终图在origin_image/slide_XX.png；除被 run state 标记为 accepted 的已批准样张外，每个最终图都由确认后端生成并经record_slide_result.py记录；slide_jobs.json与slide_run_state.json反映最终状态；必需源图在页面上可见，否则报告 blocker；若被阻塞，最终响应必须指明阶段、slide id、证据路径和未完成原因，不得宣称 deck 完成。

常见问题与进阶入口

• 快速上手：安装后直接说"请使用 codex-ppt skill，把 /path/to/article.md 做成 10 页左右的中文 PPT"，参见快速开始；
• 安装与配置：Codex、OpenClaw、Claude Code、Hermes Agent 的安装更新方式及 API/CLI fallback 配置，参见安装与配置；
• 风格预览与个人风格库：12 种内置风格预览与保存风格，参见风格与个人风格库；
• 可复用的提示词：文章转 PPT、论文答辩、管理层汇报、指定风格、修改单页等，参见示例提示词；
• 常见问题：可编辑性、API key、样张、素材插入、单页修改等，参见常见问题；
• 底层契约文档：更细的执行规则见 SKILL.md 及其 docs/ 子文档（workflow-gates-and-progress.md、outline-style-and-sample.md、backend-selection.md、slide-generation-and-subagents.md、project-assembly-and-reporting.md、cli-api-fallback.md）。

需要提醒的是，Codex PPT 生成的是图片式 PPT：视觉一致性强，但页面里的文字、图表和形状不能像传统 PPT 那样逐项编辑。如果你追求的是"先确认再量产、风格统一、产出可直接讲解"的演示生产流程，那么这套 9 阶段工作流——尤其是"大纲确认、后端确认、样张确认"三个关键把关点——就是它可控性的核心所在。

• AI 技能
• 人工智能