Codex PPT 风格体系实战指南：内置风格、参考仿制与个人风格库

本文围绕 Codex PPT（GPT-Image-2 PPT Generator Skill）的视觉风格体系展开，系统讲解随 skill 发布的 12 种内置风格、如何仿照参考材料（图片/PDF/PPT）的风格生成演示文稿，以及如何把满意的风格沉淀到本地个人风格库并长期复用。读完本文，你将掌握风格命名复用、风格参考提取、风格保存与自动发现的完整链路，并能结合仓库源码理解其底层实现。

风格从哪里来：内置风格与个人风格库

Codex PPT 的视觉风格来自两个互补的来源：

1. 内置风格（Built-in Styles）：随 skill 一起发布，存放在 skills/codex-ppt/references/ 目录下，随 skill 更新而更新；
2. 个人风格库（Personal Style Library）：存放在用户本机、skill 安装目录之外的位置，即使更新或重新安装 skill 也不会被覆盖或删除。

这种"内置 + 个人"的双层设计，让用户既能零配置快速上手，又能沉淀属于自己的长期视觉资产。底层实现上，个人风格库的根目录由运行时统一解析：脚本中通过 _runtime_home() 读取 CODEX_PPT_HOME 环境变量，未设置时回退到 ~/.codex-ppt-skill（见 codex_ppt_runtime.py），安装目录默认即 ~/.codex-ppt-skill。对应的环境变量声明位于 SKILL.md。

12 种内置风格：开箱即用，说名即用

skill 内置 12 种风格参考文件，即使完全不会写提示词，也能直接指定风格名开始制作。制作 PPT 时只需在请求中说出风格名，例如：

Please use the codex-ppt skill to turn this material into a 10-slide presentation using the built-in "Hand-Drawn Technical Explanation" style.

12 种内置风格的整页预览如下（预览图存放于 assets/style-previews/，风格定义文件存放于 skills/codex-ppt/references/）：

清爽专业风	创意杂志风
电子墨水杂志风	数据仪表盘风
复古扁平插画风	手绘技术解释风
手绘白板风	温暖手工风
科研答辩风	麦肯锡风格
党政红风格	教学课件风

这 12 个内置风格文件的完整清单也维护在 outline-style-and-sample.md 中，agent 在提供风格选择时会按该清单合并内置风格与用户自定义风格。

风格是"视觉系统"，不是"固定模板"

理解内置风格的关键在于：风格是一套视觉系统——包括配色（color palette）、字体气质（typographic character）、版式密度（layout density）与插画语言（illustration language）——而不是一个固定模板。同一套风格下，每页版式会根据该页在演示中的内容角色（封面、章节页、概念阐释、流程、对比、数据证据、总结等）动态变化，不会出现"每页长得一模一样"的机械重复。

这一点在风格定义文件中体现得非常明确。以 党政红风格.md 为例，其 JSON Brief 中明确写入 layout_usage_rule："在保持红色主导身份、字体与正式基调一致的前提下，根据页面用途变化标题位置、背景处理、意象、信息结构与留白；不要强制每页套用同一网格、模块数量、标题位置或装饰母题。" 同时提供 2~4 个语义化的 layout_blueprints（如"封面/开场""信息阐释/工作部署""成果/总结"）作为候选起点，但明确禁止把同一个 blueprint 应用到每一页。

风格定义文件的统一结构

每个内置风格文件都遵循同一结构：先是"适用场景"中文列表，再是一个可被图像模型直接消费的 GPT-Image-2 风格 Brief（JSON）。完整字段包括：

• style_name：可复用的简短风格名；
• best_for：适用场景与受众；
• visual_direction：对风格身份的凝练描述；
• canvas：画幅比例、背景、构图、密度、留白；
• color_palette：主色、次色、强调色、中性色及使用规则；
• typography：标题、正文、标签、层级、对齐与文字质量规则；
• layout_patterns / layout_usage_rule / layout_blueprints：版式模式与变化规则；
• visual_elements：允许/避免的图标、图表、卡片、纹理、装饰、照片；
• image_treatment：照片、截图、图表、插画的处理方式；
• rendering_constraints：图像模型必须遵守的渲染约束。

以党政红风格为例，其关键字段节选如下：

{
  "type": "16:9 full-slide PowerPoint image",
  "style_name": "党政红风格",
  "best_for": "党政机关、国企和事业单位的工作汇报、政策宣讲、党建学习、年度总结与重点工作部署",
  "canvas": {
    "aspect_ratio": "16:9",
    "background": "choose red, warm ivory, a restrained gradient, a relevant photograph, or a subtle abstract treatment according to the page role and subject...",
    "density": "medium information density with controlled whitespace, clear reading order..."
  },
  "color_palette": {
    "primary": "Chinese red #C41E3A for main titles, structural emphasis, and key labels",
    "secondary": "deep red #9E1530 for contrast and warm ivory #FFF9F2 for the main canvas",
    "accent": "restrained matte gold #D6A84B and warm amber #E9A11B for icons, connectors, and small title ornaments",
    "neutral": "ink black #262626, dark gray #4A4A4A, pale warm gray #F3EEE7",
    "rule": "use Chinese red to establish authority and gold as a restrained accent..."
  },
  "typography": {
    "title": "large bold Microsoft YaHei or Source Han Sans style Chinese sans-serif...",
    "body": "Microsoft YaHei or Source Han Sans style Chinese sans-serif, concise, highly readable...",
    "labels": "bold white or dark-red text on restrained red or pale-gold blocks",
    "text_quality": "all Chinese text must be exact, fully legible, non-garbled..."
  }
}

完整内容可直接查阅 党政红风格.md，其他 11 个内置风格文件结构一致。这套"场景 + JSON Brief"的结构是后续个人风格库文件的模板基准。

仿照参考材料的风格：只仿风格，不复用内容

当 12 种内置风格都不满足需求时，可以上传自己喜欢的风格参考——一张截图、多张截图，或完整 PPT/PDF——让 agent 先分析参考材料的配色、版式、字体与视觉元素，再按该风格生成新演示文稿：

Please use the codex-ppt skill to generate a presentation. Use the PDF I uploaded as the visual style reference. Review every page image in the material in detail to understand its style, then generate the presentation in a similar style.

两个必须明确的边界

• 默认只仿风格、不复用内容。除非明确要求，参考材料里的文字和数据不会被搬进新 PPT。参考材料只作为视觉风格来源，内容复用与风格复用被严格区分（见 outline-style-and-sample.md）。
• 以"看得见的页面"为唯一事实来源。对于 PDF/PPT/PPTX 参考文件，不允许仅凭文件结构、大纲文本、XML、元数据或对象层级推断风格；必须先渲染/导出代表性页面为真实页面图片，再对图片进行视觉分析。对于 PDF/PPT/PPTX 中存在的多种视觉段落，需要检查足够多的代表页面，既捕捉共享风格，也记录各段落特有的变体（见 style-library.md）。

从参考材料中提取风格系统

分析参考材料时，agent 提取的是可复用的"风格系统"而非单页构图，包括：style_name、best_for、visual_direction、canvas（画幅/背景/构图/密度/留白）、color_palette（主/次/强调/中性色 + 使用规则）、typography（标题/正文/标签/层级/对齐/文字质量）、layout_patterns（反复出现的页面类型与构图模式）、layout_blueprints（2~4 个语义化构图蓝图）、visual_elements（允许与避免的视觉元素）、image_treatment（各类素材处理方式）以及 rendering_constraints（渲染约束）。

同时严格遵守"不保存私有内容"的底线：原始文章文字、业务数据、个人信息、客户名、私有项目名、论文结果、精确引语与页面文案都不得作为风格内容保存；风格文件必须自包含，不能依赖任何外部图片或截图文件（见 style-library.md）。

个人风格库：把满意的风格永久保存、按名复用

如果生成的演示文稿风格很满意——无论是自己调出来的自定义风格，还是从参考材料复刻的风格——都可以让 agent 保存到个人风格库，之后直接复用：

I really like the visual style of this presentation. Please save it to my personal style library.

保存机制的四个要点

• 存放位置：个人风格库位于 ~/.codex-ppt-skill/references/，可通过 CODEX_PPT_HOME 环境变量改变位置。它位于 skill 安装目录之外，因此更新或重新安装 skill 时，个人风格不会被覆盖或丢失。
• 自动发现：保存后无需任何登记。下次制作 PPT 选择风格时，agent 会自动扫描个人风格库目录，把其中的 *.md 文件与内置风格列表合并后一起展示。个人自定义风格永远不会被登记进 skill 内部的文档（见 outline-style-and-sample.md）。
• 同名优先：如果个人风格与某个内置风格同名，以你的个人风格为准。可以利用这一点定制内置风格——保存一个同名的调整版即可覆盖默认效果。
• 复用方式：以后直接说风格名即可，例如"用『深色数据科技风』生成这份 PPT"。

此外，生成完成后，如果这套 deck 使用了自定义或调整过的风格，agent 会在最终报告中主动提示你可以保存；使用未修改的内置风格时则无需重复保存（该行为也记录在 SKILL.md 的保存流程中）。

风格命名规范

保存风格时，文件命名为 ${CODEX_PPT_HOME:-~/.codex-ppt-skill}/references/{style_name}.md。命名规则（见 style-library.md）：

• 优先使用简短的中文风格名，通常 2~8 个汉字或一句简洁中文短语；
• 命名的是"可复用的视觉风格"，而不是项目、客户、论文或活动；
• 避免人名、公司名、客户名、论文标题或临时任务名；
• 避免"我的风格1""好看风""新风格"这类模糊名称；
• 好示例：深色数据科技风、极简发布会风、柔和学术插画风、高密度咨询风。

如果目标文件名已存在于用户风格目录，需要询问用户是覆盖、合并还是换新名；如果文件名与内置风格重名，则需告知用户"自定义文件将优先于同名内置风格"并确认意图后再保存。

个人风格文件的标准结构

个人风格文件必须匹配内置风格文件的结构：先是"适用场景"列表，再是可直接复用于幻灯片生成的 GPT-Image-2 风格 Brief JSON。标准模板如下（完整定义见 style-library.md）：

{
  "type": "16:9 full-slide PowerPoint image",
  "style_name": "{style_name}",
  "best_for": "...",
  "visual_direction": "...",
  "canvas": {
    "aspect_ratio": "16:9",
    "background": "...",
    "composition": "...",
    "density": "..."
  },
  "color_palette": {
    "primary": "...",
    "secondary": "...",
    "accent": "...",
    "neutral": "...",
    "rule": "..."
  },
  "typography": {
    "title": "...",
    "body": "...",
    "labels": "...",
    "text_quality": "..."
  },
  "layout_patterns": ["...", "..."],
  "layout_usage_rule": "...",
  "layout_blueprints": [
    {
      "name": "...",
      "sections": [
        {"position": "...", "count": 1, "labels": ["..."]}
      ]
    }
  ],
  "visual_elements": {
    "allowed": "...",
    "avoid": "..."
  },
  "image_treatment": {
    "photos": "...",
    "screenshots": "...",
    "charts": "...",
    "illustrations": "..."
  },
  "rendering_constraints": ["...", "..."]
}

该 JSON 应足够详尽以指导未来的 agent，同时避免嵌入任何任务专属内容。保存目录不存在时需要先创建。

底层实现：扫描发现与同名优先级

个人风格库的"免登记自动发现"与"同名优先"并非魔法，而是由 skill 内部约定的运行时协议保证的：

• 发现机制：后续的风格确认步骤会扫描 ${CODEX_PPT_HOME:-~/.codex-ppt-skill}/references/ 目录，将其中的 *.md 文件与内置风格列表合并（见 outline-style-and-sample.md）。用户自定义风格通过目录扫描被发现，绝不被登记进 skill 内部的 docs/outline-style-and-sample.md 或任何其他文件。
• 同名优先级：如果用户自定义风格文件与内置风格文件同名，用户文件优先，替代内置风格（见 outline-style-and-sample.md 与 SKILL.md）。
• 写入边界：用户自定义风格禁止写入 skill 自带的 references/ 目录——该目录专用于随 skill 发布的内置风格（见 style-library.md）。
• 运行时位置解析：脚本通过 os.getenv("CODEX_PPT_HOME", DEFAULT_RUNTIME_HOME) 解析运行目录，未设置时展开为用户主目录下的 .codex-ppt-skill（见 codex_ppt_runtime.py）。因此用户完全可以通过设置 CODEX_PPT_HOME 将风格库（连同运行时虚拟环境等）迁移到任意位置。

风格相关的常见问题速查

• 后续页面风格跑偏怎么办：通常是样张风格未一致传递到后续页面，或提示词/后端/子代理执行方式在生成中途发生了变化。不要整份重做，先挑 1~2 页明显跑偏的，用已批准的样张作为风格参考重新生成，并要求"保持样张视觉风格、使用同一图像生成后端、保持同样的版式密度"。详见 FAQ。
• 是否可以保存自己的风格：可以。上传喜欢的 PPT 截图、PDF 或完整演示，让 agent 分析风格，满意后要求保存到 ~/.codex-ppt-skill/references/。同名时个人风格优先。详见 FAQ。
• 单页不满意：先只改那一页，明确指出问题（文字太小、层级不清、配色不合适、视觉过挤、概念表达不准确等）。

相关页面

• 示例提示词（英文）：指定内置风格、仿照参考风格、保存风格的完整提示词模板；
• 常见问题（英文）：风格跑偏、页面不满意、清晰度异常等问题的处理方式；
• 风格保存工作流：保存个人风格的完整执行协议（命名、冲突处理、文件结构）；
• 大纲、风格与样张流程：风格确认、内置风格清单与合并发现机制；
• 内置风格定义文件：12 种内置风格的"适用场景 + JSON Brief"完整定义。