codex-ppt-skill 风格体系全解：12 种内置风格、参考材料仿制与个人风格库持久化复用
codex-ppt-skill 风格体系全解：12 种内置风格、参考材料仿制与个人风格库持久化复用
本文深入剖析 codex-ppt-skill 的视觉风格机制：它如何从「内置风格」与「个人风格库」两个来源取色，如何仿照用户上传的截图/PDF/PPT 提炼风格，以及如何把一套满意的风格保存到 skill 安装目录之外、实现跨版本复用。读完你不仅能熟练调用 12 种内置风格，还能读懂风格参考文件的结构、个人风格库的发现与优先级规则，以及样张确认后风格如何沿用到整套 PPT 的每一页。
风格从哪里来：两个来源、一条主线
Codex PPT 的视觉风格来自两个地方：
- 内置风格：随 skill 发布，开箱即用，跟随 skill 版本更新；
- 个人风格库：存放在你本机
~/.codex-ppt-skill/references/目录，更新或重装 skill 也不会丢失。
两者的实现位置在仓库中清晰可查：内置风格文件位于 skills/codex-ppt/references/，共 12 个 Markdown 文件；个人风格库的读写逻辑定义在 skills/codex-ppt/docs/style-library.md，并在 SKILL.md 的工作流最后一步「Save reusable styles」中被调用。
这里要先厘清一个关键认知：风格是一套视觉系统（配色、字体气质、版式密度、插画语言），不是固定模板。同一套风格下，每页版式会根据内容角色变化——封面、目录、概念解释、流程、对比、数据页各有各的版式，不会每页长得一样。这一原则在 outline-style-and-sample.md 中被明确为工程约束：「a deck should have one coherent visual identity, not one repeated composition」，即整套 deck 只有一套视觉身份，但页面布局随内容角色变化。
12 种内置风格：不会写提示词也能直接用
skill 内置 12 种风格参考，制作 PPT 时直接说风格名即可：
请使用 codex-ppt skill，把这份材料做成 10 页 PPT，使用内置的「手绘技术解释风」。
12 种内置风格及其仓库位置一览：
| 风格名 | 参考文件 | 风格预览图 |
|---|---|---|
| 清爽专业风 | 清爽专业风.md | clean-professional.png |
| 创意杂志风 | 创意杂志风.md | creative-magazine.png |
| 电子墨水杂志风 | 电子墨水杂志风.md | e-ink-magazine.png |
| 数据仪表盘风 | 数据仪表盘风.md | data-dashboard.png |
| 复古扁平插画风 | 复古扁平插画风.md | retro-flat-illustration.png |
| 手绘技术解释风 | 手绘技术解释风.md | handdrawn-technical.png |
| 手绘白板风 | 手绘白板风.md | handdrawn-whiteboard.png |
| 温暖手工风 | 温暖手工风.md | warm-handmade.png |
| 科研答辩风 | 科研答辩风.md | scientific-defense.png |
| 麦肯锡风格 | 麦肯锡风格.md | mckinsey-style.png |
| 党政红风格 | 党政红风格.md | party-government-red.png |
| 教学课件风 | 教学课件风.md | teaching-courseware.png |
例如「手绘技术解释风」适合中文技术文章配图、技术概念解释、课程课件、知识卡片、AI/软件工程主题分享等需要降低理解门槛的场景；「数据仪表盘风」则适合指标卡、图表感布局的数据密集型报告。以下是两张代表性预览：
风格参考文件内部结构：一份可直接复用的 JSON Brief
每个内置风格文件（如 手绘技术解释风.md）都包含「适用场景」清单和一段名为「GPT-Image-2 风格 Brief」的 JSON。这段 JSON 不是给人看的装饰，而是可以原样作为幻灯片生成风格提示词使用的结构化描述。以手绘技术解释风为例，其核心字段包括：
type：16:9 full-slide PowerPoint image，即整页幻灯片图片；style_name/best_for：风格可复用名称与适用场景；visual_direction：一句浓缩的风格身份描述（如 "clean Chinese handdrawn technical explainer, near-white paper background..."）；canvas：画布属性——宽高比16:9、背景色（如#FCFBF7近白纸色）、构图、密度与留白规则；color_palette：色板——线条色（软石墨#2F3437）、强调色（淡蓝#BFD7F1、鼠尾草绿#CFE2D1、浅桃#F4C7B8、淡紫#D8C7EF）及使用规则（pastel 只用于强调，保持页面安静通透）；typography：标题、正文、强调的手写中文排版气质与文字质量要求；layout_patterns：高频复用的页面类型（中心概念图、前后对比、三步流程图、心智模型页、矩阵/决策页、总结页）；layout_usage_rule：布局蓝图只作为候选起点，须按每页语义角色选取并适配，相邻页不得重复同一蓝图；layout_blueprints：2-4 个语义化描述的版式蓝图（如 "small central concept map" 的 top-left 标题 + center 概念图 + 四周 4 个标签 + bottom-right 一句话结论）；visual_elements：允许/避免的视觉元素清单（如允许细手绘箭头、铅笔排线、pastel 标记块；避免乱涂白板框、马克笔托盘、大型卡通角色、发黄纸张）；rendering_constraints：渲染约束（保持"平静手绘技术插画"而非头脑风暴白板、中文文字精准且稀疏、无水印无无关 logo）。
这套结构在 style-library.md 中被完整复述为「提取风格系统」的标准字段清单，并额外补充了 image_treatment（照片/截图/图表/插画的处理方式）。也就是说，无论内置风格还是个人风格，都遵循同一份 JSON 契约，这保证了风格文件可以被生成管线直接消费。
仿照参考材料的风格：先分析、再仿照、不复用内容
如果 12 种内置风格都不满足需求，可以把喜欢的风格参考直接交给 agent：一张截图、多张截图，或完整 PPT/PDF。建议让 agent 先分析参考材料的配色、版式、字体和视觉元素，再按该风格生成新 PPT：
请使用 codex-ppt skill 生成 PPT。视觉风格参考我上传的这份 PDF。请详细阅读我提供材料中的每一页图片，确保了解其风格，然后仿照其风格进行生成。
这里有两个重要边界：
- 默认只仿风格、不复用内容。除非你明确要求，参考材料里的文字和数据不会被搬进新 PPT。这一点在 outline-style-and-sample.md 中被表述为「separate content reuse from style reuse」：未经明确要求，提供的图片/PDF/PPT 只作为风格参考。
- 从真实可见页面提取风格。对 PDF/PPT/PPTX 类参考，不能从文档结构、大纲文本、XML、元数据或对象层级推断视觉系统，必须先渲染/导出代表性页面为真实图片，再基于可见内容提取风格（见 outline-style-and-sample.md）。若文件存在多个视觉分区，需检查足够多的代表页以捕捉共享风格与分区差异。
个人风格库：保存、自动发现与同名优先
无论调出来的自定义风格，还是从参考材料复刻的风格，只要满意，都可以让 agent 保存，以后直接复用：
这套 PPT 的视觉风格我很喜欢，请保存到个人风格库。
存放位置：skill 安装目录之外
个人风格库位于 ~/.codex-ppt-skill/references/，在 skill 安装目录之外。更新或重新安装 skill 时，个人风格不会被覆盖或丢失。目录位置可通过 CODEX_PPT_HOME 环境变量改变，其默认值在 SKILL.md 中声明为运行时目录覆盖项，并在多个脚本中实际生效，例如 assemble_ppt.py、image_gen.py、remove_chroma_key.py 都通过 os.getenv("CODEX_PPT_HOME", "~/.codex-ppt-skill") 解析运行时根目录。
保存的完整文件路径为：
${CODEX_PPT_HOME:-~/.codex-ppt-skill}/references/{style_name}.md
style-library.md 对命名规则有明确要求：优先使用 2-8 个汉字的简短中文风格名；命名的是「可复用的视觉风格」而非项目、客户、论文或活动名；避免个人名、公司名、论文标题和临时任务名，也避免「我的风格1」「好看风」这类含糊名字；推荐示例如「深色数据科技风」「极简发布会风」「柔和学术插画风」「高密度咨询风」。
自动发现：零登记、零配置
保存后无需任何登记。之后制作 PPT 选择风格时，agent 会自动扫描个人风格库目录（如果存在），把其中的 *.md 与内置风格列表合并展示。这个机制在 outline-style-and-sample.md 中被写为硬性步骤：「Before offering or using reusable styles, list the user custom style directory (if it exists) and merge its *.md files with the built-in list below」；style-library.md 同样强调：「No registration step is needed ... discovered by directory scan, so they need no registration」。个人风格永远不会被登记进内置风格清单。
同名优先：用个人风格定制内置风格
如果个人风格与某个内置风格同名，以你的个人风格为准。你可以利用这一点定制内置风格：保存一个同名的调整版即可覆盖默认效果。保存时若目标文件名与内置风格重名，agent 会明确告知「个人文件将优先于同名内置风格」并确认你的意图后再保存（见 style-library.md）。若目标文件在个人风格库已存在，则会询问是覆盖、合并还是换新名。
复用方式：直接说风格名
保存后，以后直接说风格名即可：
用「深色数据科技风」生成这份 PPT。
保存什么、不保存什么
style-library.md 对保存边界有严格规定：
- 保存：可复用的视觉规则——
style_name、best_for、visual_direction、canvas、color_palette、typography、layout_patterns、layout_usage_rule、layout_blueprints、visual_elements、image_treatment、rendering_constraints； - 不保存：用户原文、业务数据、个人信息、客户名、私有项目名、论文结果、精确引用、页面文案等一次性内容；不把源图片/截图作为风格文件的依赖；未经明确要求不保留可识别 logo 或品牌名；风格文件必须自包含，不得依赖外部文件。
保存后的最终报告需给出：新风格名、保存文件路径、风格存储在 skill 安装目录之外因此更新/重装不丢失，以及一句复用提示，例如「以后可以说：用『深色数据科技风』生成这份 PPT」。
主动提示保存
生成完成后，如果这套 deck 用的是自定义或调整过的风格，agent 也会在最终报告里主动提示你可以保存；使用未修改的内置风格时无需重复保存。这条规则同样写入 SKILL.md：「If the final deck used a custom or adapted style, proactively offer to save it in the final report」。
风格如何在整套 PPT 中传承：样张 + 全局风格参考
从工程实现看，风格的「稳定传承」依赖一条明确链路。大纲、风格、生图后端确认后，先生成一张样张作为整套 PPT 的视觉基准；用户确认样张后，样张路径被记录为 deck 级风格参考（approved_style_reference），之后每一页的提示词都会带上它。
这一机制在 prepare_slide_prompts.py 中可见：deck_spec.json 中的 approved_style_reference 被解析为全局风格参考，逐页组装提示词时，如果该页 use_approved_style_reference 为真，就把样张图片作为输入图片之一（Image 1）传给生成后端。对应的「Style Reference Rule」在 prepare_slide_prompts.py 中明确要求：
Use Image 1 as the approved sample-slide style reference. Match its palette, typography mood, density, texture, and overall visual identity. Do not copy its exact layout unless this slide's layout explicitly asks for it.
即：每一页继承样张的配色、字体气质、密度、纹理与整体视觉身份，但不复制样张的具体版式——这正是「风格是视觉系统而非模板」这一理念的代码级落地。同时，outline-style-and-sample.md 要求样张批准后在 deck_spec.json 中记录 backend_used、tool_name、mode、prompt_source、size、quality、approved_sample_path、input_context_preparation、handoff_rule 等字段，作为父进程传给子 agent 的契约，确保整条流水线使用与样张相同的生图路径。
风格相关的提示词速查与常见问题
在 docs/prompts.md 中可以直接取用以下风格相关提示词：
- 指定内置风格：在指令中加入「使用内置的『手绘技术解释风』，用手绘线条、结构化示意图、轻量标注和清晰的概念拆解来呈现内容」，也可替换为「清爽专业风」「科研答辩风」「数据仪表盘风」「电子墨水杂志风」「创意杂志风」等；
- 仿照参考风格：上传 PDF 并说明「大标题、强留白、黑白灰主色、少量红色强调，整体像商业杂志专题页。请详细阅读我提供材料中的每一页图片，确保了解其风格，然后仿照其风格进行生成」；
- 保存风格：直接说「请把它保存到 codex-ppt 的个人风格库里，方便以后复用。说明里包含配色、字体气质、版式规则、插画/图表风格和适用场景」。
关于风格的常见疑问，docs/faq.md 中有两条直接答案：
- 可以保存自己的风格吗？ 可以。把喜欢的 PPT 截图、PDF 或完整 PPT 交给 agent 分析，生成满意后让 agent 保存到个人风格库；风格库存放在 skill 安装目录之外，更新或重装 skill 都不会丢失，与内置风格同名时个人风格优先；
- 如何更新 skill 到最新版本？ 重新执行安装命令覆盖即可，API key 配置和个人风格库都存放在 skill 安装目录之外，更新不会丢失。
此外，FAQ 还解释了「为什么第一张样张不错、后面的页面又变差或风格不一样」：这通常说明样张风格未被稳定传递，或后续页面换了提示词/后端/子 agent 执行方式。正确处理不是整套重来，而是挑 1-2 页明显跑偏的页面，让 AI 对照已确认样张重新生成，并明确要求「保持样张的视觉风格、同一图片生成后端和同一版式密度」。