企业官网建设流程全解析

• AI 技能
• 人工智能

导读

本文基于 docs/en/workflow.md 系统讲解 codex-ppt-skill 的标准工作流（Standard Workflow）：它以"分阶段确认"为核心，将 PPT 生成拆解为资料审阅、大纲确认、视觉风格确认、图像后端确认、样张确认、批量生成、质检修复、讲稿与装配、风格存档九个阶段，避免一次性生成整份演示文稿带来的返工成本。读完本文，你将掌握 codex-ppt 每一步的产出物、审批门禁（approval gate）、关键脚本调用链，以及如何与源码中的 SKILL.md、workflow-gates-and-progress.md、slide-generation-and-subagents.md 等文档配合，完成一套可控、可追踪、可复用的"图像式 PPT"生产流程。

一、工作流设计理念：为什么必须"分阶段确认"

workflow.md 开篇即点明核心原则：强调分阶段确认（staged confirmation）。与"一键生成 20 页 PPT"的体验相反，codex-ppt 要求在正式产出前依次确认大纲、风格、图像后端与样张，从而大幅降低返工成本。

这一理念在 docs/en/design.md 中得到了更完整的阐释：AI 生成 PPT 最重要的不是速度，而是一个可控、能产出可用结果的过程。因此设计者刻意将流程拆成若干步骤——读资料、出大纲、定风格、出样张、确认后批量生成、装配 PPTX——并且主张"图像式 PPT"与"可编辑 PPT"解耦为两个独立 Skill：先生成高质量的整页图像式演示，待内容和视觉方向都确认无误后，再按需决定是否做可编辑转换。

从 SKILL.md 的 Hard Constraints 可以看到这套理念如何被强制化为纪律：

• 尊重审批门禁：在 workflow-gates-and-progress.md 规定的审批通过之前，不得创建最终的deck_spec.json、speech.md、prompt 任务、幻灯片图像或.pptx文件；
• 样张是唯一的"风格契约"：样张获批后，必须记录sample_generation_method并传给每个 slide 子代理，禁止子代理擅自切换后端；
• 本地绘制不是回退方案：Pillow、SVG、HTML/CSS/canvas 截图、python-pptx/PptxGenJS 排版、手动叠加等，全部属于失败模式（failure modes），不能当作图片生成的备胎。

可见，"分阶段确认"不是简单的流程建议，而是由 Skill 文档与状态脚本共同执行的硬约束。

二、九阶段全景：每个阶段做什么、产出什么

2.1 阶段总览

标准工作流共九步，其中阶段 1–5 是"确认期"（只出文档与单张样张），阶段 6–8 是"生产期"（批量出图、质检、装配），阶段 9 是可选的"沉淀期"（存档风格）：

其中阶段 2–5 的审批顺序与"不得提前生成最终产物"的红线，在 workflow-gates-and-progress.md 中被固化为 Mandatory Phase Gates：在前一阶段被用户批准之前，不得进入下一阶段，除非用户明确要求跳过确认。

2.2 阶段 1：审阅源材料

代理首先要对输入材料（文章、报告、论文、笔记或大纲）做信息抽取，明确五类信息：

• 主题与中心论点（topic and central argument）；
• 目标受众（target audience）；
• 演示目标（presentation objective）；
• 所需页数（required slide count）；
• 必须包含/必须排除的内容，以及是否需要图像资产。

对应源码侧，SKILL.md 给出了同样的清单，并补充了一个务实细节：若用户未指定页数，代理应自行选择实用页数，典型演讲为 8–12 页。这一阶段不产出任何文件，只形成决策上下文，供后续大纲撰写使用。

2.3 阶段 2：确认大纲（outline.md）

代理生成outline.md，通常包含：

• 幻灯片编号与标题；
• 每页 3–5 个关键点；
• 每页的角色（role）：封面、目录、概念解释、流程、对比、数据佐证或总结；
• 可选的视觉创意；
• 必需的图像资产及其用法。

大纲获批前，不得生成任何最终幻灯片图像、speech.md或.pptx文件——这是全流程第一条硬门禁。

关于大纲的写法，outline-style-and-sample.md 提供了更细的规范：每页需要定义"布局角色与意图"（如 cover、agenda、section divider、concept、process、comparison、timeline、data evidence、architecture、case study、summary、Q&A），并且当幻灯片依赖本地源图时，直接在Required images列表中使用 Markdown 图片语法内嵌资产，让用户在大纲评审阶段就能可视化核对"哪张图配哪一页"。推荐的大纲骨架是：

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

大纲写完后代理应停在原地，向用户汇报outline.md路径、页数、必需图像及映射关系，并说明"尚未生成任何图片或 PPTX"，等待用户批准。

2.4 阶段 3：确认视觉风格

代理提出2–3 个风格方向并推荐其一。候选风格来自：

• 12 种内置风格（见 docs/en/styles.md）：清爽专业风、科研答辩风、手绘技术解释风、麦肯锡风格、党政红风格、教学课件风等；
• 用户的个人风格库（~/.codex-ppt-skill/references/，可用CODEX_PPT_HOME环境变量重定向，位于 Skill 安装目录之外，升级/重装 Skill 不会丢失）；
• 从用户提供的截图、PDF 或演示文稿中复刻风格。

完整风格预览见 样式与个人风格库。源码侧，outline-style-and-sample.md 补充了风格确认的三条实操规则：

1. 用户已指定风格或提供了参考物时，不要强行走 2–3 选 1，直接抽取风格规则并复述确认即可；
2. PDF/PPT/PPTX 风格参考必须"先渲染成真实页面图像再观察"，不能仅从文档结构、XML、元数据或对象层级推断视觉系统；
3. 默认只复刻风格、不复刻内容，除非用户明确要求沿用参考材料中的文字与数据。

风格一旦选定，整份演示应保持一致的视觉语言，但各页布局可随内容角色变化——即"同一套视觉系统，每页不同构图"，而不是复制同一模板。

2.5 阶段 4：确认图像生成后端

图像后端只有两类，规则由 backend-selection.md 明确：

1. 内置图像工具（首选）：例如 Codex 的image_gen、OpenClaw 的image_generate；
2. 本地 API/CLI fallback：scripts/image_gen.py，仅在内置工具不可用、用户明确要求 API/CLI 模式、或当前能力无法满足请求时启用。

选择后端有两条红线：

• 不要仅凭环境名或订阅上下文推断内置工具可用，必须先实际探测工具是否可调用；
• 后端确认后全篇必须固定使用同一后端，中途不得切换。

后端确定后，代理需要用确认话术向用户汇报检查结果并征求同意，内置模式与 fallback 模式各有标准话术模板（见 backend-selection.md）。若走 fallback 模式，image_gen.py会自动加载~/.codex-ppt-skill/.env中的OPENAI_API_KEY、OPENAI_BASE_URL、CODEX_PPT_IMAGE_MODEL配置；从 image_gen.py 源码可见其默认模型为gpt-image-2.5-flare、默认尺寸为2560x1440、默认质量为medium、默认输出格式为png，并内置了对gpt-image-*系列的像素总量、边缘长度、宽高比上限的校验逻辑。

2.6 阶段 5：生成并确认一张样张

样张是控制质量的核心手段。代理只先生成一张代表性样张（优先选内容页而非封面），然后检查五项指标：

• 文字是否清晰（文本清晰度）；
• 风格是否符合预期；
• 信息密度是否合适；
• 颜色与布局是否稳定；
• 该设计能否扩展到整份演示。

样张必须直接保存为最终页文件名（如origin_image/slide_08.png），获批后即作为该页的最终图，不得另建sample_slide.png，因为装配脚本只识别slide_XX.png命名（见 outline-style-and-sample.md）。样张获批后，代理要把sample_generation_method写入deck_spec.json，至少记录backend_used、tool_name、mode（generate/edit）、prompt_source、size/quality/模型配置、approved_sample_path、input_context_preparation、handoff_rule——这是传给子代理的"同路径生产契约"。

只有样张获批后，才允许进入整篇生产。

2.7 阶段 6：批量生成（支持子代理并行）

样张获批后，代理逐页生成origin_image/slide_XX.png。在支持子代理的环境中，每页由一个子代理并行生成，加速多页生产；每一页都遵循样张确认的风格与图像后端。

从 slide-generation-and-subagents.md 看，批量阶段有一套严格的状态机协议：

1. 先用prepare_slide_prompts.py生成每页的 JSON 任务（prompts/slide_XX.json）与状态文件slide_jobs.json、slide_run_state.json；
2. 用slide_job_status.py查看可派发的槽位（dispatch_slots_available）与待处理页；
3. 每个子代理只领取一个slide_XX.json任务，随后主代理立即用record_slide_dispatch.py --slide slide_XX --agent-id <id>记录派发；
4. 子代理返回后，主代理视觉检查输出，再用record_slide_result.py --backend-used "built-in image tool" --selected-source <path>将选中图复制进origin_image/slide_XX.png并记录后端溯源；
5. 子代理无法使用所选后端或无法访问必需输入图时，用record_slide_blocker.py记录阻塞，而不是生产低质量替代品。

关键命令示例：

# 查看可派发槽位与待处理页 ~/.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> \ --prompt-file prompts/slide_02.json # 记录结果并复制进 origin_image/ ~/.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/slide_02.png \ --qa-note "Text readable; style matches the approved sample."

派发阶段的核心原则是："是否已派发/是否已完成"只能以脚本记录为准，聊天消息不算数（"Chat messages alone do not make a slide dispatched or complete"）。若运行环境无法生成子代理，代理应在派发步骤停下并上报 blocker，而不是退化成串行低质生产。

为了让子代理任务自包含，slide-generation-and-subagents.md 要求主代理在派发前把跨页语义写进deck_spec.json：

• deck 级deck_context：多页共用的规范概念，如源文摘要、核心论点、术语表、人物、定义、时间线、必需命名；
• 页级local_context：该页工人必须看到的页面专属事实，如"总结这六条特征""对比这两种方法"；
• 把"上述框架""前文结论""这些示例"这类隐式指代展开成显式清单，避免子代理去猜上下文。

每页任务使用结构化视觉简报（structured visual brief），将画布、风格、布局、文本、视觉元素、约束分层描述，而不是依赖一段冗长的风格段落。一个典型的slide_XX.json结构包含type（16:9 全页 PPT 图像）、canvas（纵横比、禁用页码）、style（风格名、视觉方向、配色、字体、质感、deck 一致性）、deck_context、layout（role/intent/composition/content_zones/variation_rule）、text（标题、关键点、中文渲染质量要求）、local_context、visual_elements、constraints（无水印、无无关 logo、无额外页码）。完整的 JSON 模板可直接在 slide-generation-and-subagents.md 中取用。

2.8 阶段 7：质量审查与修复

装配之前，代理必须逐页检查：

• 文字清晰度（无乱码）；
• 与大纲的一致性；
• 内容是否被截断（标题、要点是否完整）；
• 跨页视觉一致性；
• 是否出现多余页码（除非用户要求）；
• 元素是否重叠。

修复策略分两档（详见 project-assembly-and-reporting.md）：

• 严重问题：用更严格、更约束化的 prompt 整页重新生成；
• 局部小问题：优先用所选后端的图像编辑能力定点修复；fallback 模式下用scripts/image_gen.py edit --image {slide_path} --prompt ... --out {new_slide_path}，且验证编辑结果后才允许替换最终页。

2.9 阶段 8：讲稿与装配

代理先生成speech.md，再用assemble_ppt.py装配为.pptx，讲稿会自动写入每页的备注区（notes section）。

speech.md的写作规范（见 project-assembly-and-reporting.md）值得特别注意：

• 写的是可朗读的演讲逐字稿，而不是对页面文字的简要概括；
• 按演讲语言书写（中文 deck 用中文讲稿）；
• 每页用## Slide N: {Title}标题，装配脚本据此把讲稿映射进对应 PPT 备注；
• 全篇保持一个交付风格（技术讲解型 / 论文研读型 / 产品 Pitch 型 / 培训工作坊型 / 高管汇报型），再按页面角色微调语气；
• 长度参考：封面/目录/章节分隔页 1–2 段；普通内容页 2–5 段（中文约 150–400 字）；密集的概念/架构/数据页可更长；
• 从演讲者视角写作（如"这里我想强调的是…""我们先看左边这个结构…"），避免 AI 腔与"综上所述"式空话，且不要提及讲稿由 AI 生成。

装配命令如下，{base_dir}是{deck_name}/的父目录，{deck_name}.pptx必须与项目文件夹同名：

# 若共享运行环境缺失，先执行 bootstrap（内部步骤，通常由代理代为完成） 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

装配前必须核验状态：slide_jobs.json中所有已生成页为recorded、样张页为accepted；只要存在pending、dispatched或blocked状态，就应停止并上报，不能装配。assemble_ppt.py支持16:9与4:3两种纵横比（默认 16:9），只读取slide_01.png、slide_02.png这类最终命名图，草稿与样张变体会被忽略。

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

如果本次演示使用了自定义风格或经过调整的风格，代理应在最终报告中提示：可将该风格存入个人风格库，今后按名字直接复用。存储位置为${CODEX_PPT_HOME:-~/.codex-ppt-skill}/references/，位于 Skill 安装目录之外，升级不会丢失；个人风格与内置风格同名时，个人风格优先，因此也可以利用同名覆盖来"定制"某个内置风格（详见 docs/en/styles.md）。若用户同意保存，代理再读取 style-library.md 执行存档。

三、审批门禁与可见进度：状态即证据

3.1 七阶段强制门禁

workflow-gates-and-progress.md 将九个阶段压缩为七道强制门禁，明确顺序为：源材料阅读与资产抽取 → 大纲确认 → 视觉风格确认 → 图像后端确认 → 单张样张批准 → 整篇生成 → 质检/讲稿定稿/PPT 装配。

硬性规则包括：

• 大纲获批前，不得创建最终的deck_spec.json、speech.md、prompt 任务文件、幻灯片图像或.pptx；
• 确需内部规划文件时，使用.draft.前缀命名（如deck_spec.draft.json、speech.draft.md）并明确标注"非最终"；
• 若 deck 依赖必需源图，在大纲确认时停下，请用户核对"页 ↔ 图"映射后再进入风格与图像阶段。

3.2 用户可见的进度清单

对于非平凡 deck，代理应维护一个用户可见的检查清单，且同一时刻只亮一个活动步骤：

1. 准备源材料、大纲、风格与后端决策；
2. 生成并批准一张样张；
3. 准备幻灯片任务与状态；
4. 派发幻灯片子代理；
5. 记录生成的幻灯片结果；
6. 质检、修复、讲稿与 PPT 装配。

每一步都有对应的完成证据（completion evidence），例如"派发子代理"的完成证据是slide_job_status.py显示存在可派发页、且每个已派发的工人都被record_slide_dispatch.py记录；"记录结果"的完成证据是record_slide_result.py已将选中图复制进origin_image/slide_XX.png并写入后端溯源。核心纪律是：不能仅凭聊天对话标记步骤完成，必须依据真实文件或脚本记录的状态。

四、标准项目结构与最终交付物

一个完整的项目目录结构如下（见 project-assembly-and-reporting.md）：

{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

对应 docs/en/quickstart.md 中的用户可见交付物，用户通常收到：outline.md（大纲）、origin_image/slide_XX.png（每页最终图）、speech.md（每页讲稿）以及{presentation-name}.pptx（最终 PowerPoint 文件）。

最终报告应包含：项目目录、PPT 文件路径、图像目录、outline.md/speech.md/slide_jobs.json路径、页数、所用后端及每页结果的记录确认、讲稿是否写入 PPT、以及任何被重新生成/阻塞/存在已知限制的页面（见 project-assembly-and-reporting.md）。若使用自定义或明显调整过的风格，报告末尾应附一句"可保存到个人风格库"的提示。

五、工作流的验收标准与常见误区

SKILL.md 给出了成文的 Acceptance Criteria，可作为一次完整流程是否真正闭环的检验清单：

• 输出为合法的.pptx；
• 每张预期最终图都存在于origin_image/slide_XX.png；
• 每张最终图都由确认过的后端生成，并经record_slide_result.py记录（样张页由运行状态标记为 accepted 除外）；
• outline.md反映已批准的大纲；
• 需要讲稿时speech.md存在，且装配时写入 PPT 备注；
• slide_jobs.json与slide_run_state.json反映最终状态；
• 必需源图在页面上可见呈现，否则上报 blocker；
• 若被阻塞，最终回复须指明阶段、slide id、证据路径与未完成原因，不得宣称 deck 已完成。

实践中容易踩的误区包括：凭聊天消息标记派发/完成、让子代理切换后端、在样张获批前就生成全篇、用本地绘制替代真实图像后端、把草稿文件留在origin_image/导致装配读到多余图、以及跳过讲稿写作直接装配。这些都与工作流文档和状态脚本的设计意图相悖，规避它们即可稳定复现"大纲 → 风格 → 样张 → 批量 → 质检 → 装配"的完整闭环。

六、与其他文档的衔接

标准工作流是 codex-ppt 的"主流程说明书"，与 Skill 内其他文档构成完整的操作手册体系，可按需查阅：

• 工作流门禁与进度：审批门禁、进度清单与完成证据；
• 大纲、风格与样张规范：outline 写法、风格确认话术、样张要求与sample_generation_method记录；
• 后端选择：内置工具与 API/CLI fallback 的决策规则与确认话术；
• 幻灯片生成与子代理：任务 JSON、派发循环、结果/阻塞记录与溯源；
• 项目装配与报告：目录结构、讲稿规范、装配命令与最终报告；
• 样式与个人风格库 与 style-library.md：12 种内置风格与个人风格存档；
• 安装与配置、快速开始、示例提示词 与 FAQ 覆盖从安装到疑难排查的完整旅程。

一句话总结这套工作流的设计价值：它不是追求"最快的 PPT"，而是追求"每一步都可确认、每个产物都有记录、每次失败都可追踪"的确定性流程——大纲、风格、后端、样张四道关卡把关在前，状态脚本全程留痕，最终装配前逐页质检，从而让 AI 生成演示文稿从"开盲盒"变成"可控的工业化生产"。

• AI 技能
• 人工智能