ningzimu/codex-ppt-skill 本地安装：先认清图片式 PPT 边界

安装 ningzimu/codex-ppt-skill 前，先要分清一个边界：它生成的是“整页图片式”PPT。每一页先由生图后端生成一张完整 16:9 幻灯片图片，再用本地脚本组装成 .pptx。所以它适合追求统一视觉表达，不适合要求文字框、图表、形状都能逐项编辑的场景。

这个 skill 的价值在于把文章、报告、论文、课程笔记或大纲变成视觉统一的演示稿，并配套生成 outline.md、逐页图片、speech.md 和最终 PowerPoint 文件。第一个限制也很明确：如果后期要像传统 PPT 那样逐个改对象，需要另走图片转可编辑方案，不能把它当成对象式 PPTX 生成器。

适合谁使用

codex-ppt 更适合做技术分享、论文答辩、产品汇报、课程课件、调研报告和强视觉统一的图片式演示文稿。输入可以是文章、Markdown、大纲、PDF、Word、课程笔记，也可以带论文原图、实验结果图、截图或架构图。

如果你的核心诉求是“快速得到一套观感统一、可直接演示的 PPT”，它很合适；如果核心诉求是“把每个文本框都保留为 PowerPoint 对象”，要提前换工具或在生成后再尝试 image-to-editable-ppt-skill 这类转换流程。

本地安装路径

Codex 里推荐用 skills CLI 安装到全局 skills 目录。安装完成后重启 Codex，让新 skill 生效。

npx -y skills@latest add ningzimu/codex-ppt-skill \
  --skill codex-ppt \
  --agent codex \
  --global

如果从 GitHub Releases 下载 codex-ppt-skill-v*.zip，解压后把其中的 codex-ppt 文件夹放到 ~/.codex/skills/codex-ppt。本地开发这个仓库时，也可以把 skills/codex-ppt 软链接到 Codex skills 目录：

mkdir -p ~/.codex/skills
ln -s /path/to/codex-ppt-skill/skills/codex-ppt ~/.codex/skills/codex-ppt

依赖和生图配置

skill 内部要求 python3，并带有 requirements.txt：python-pptx>=1.0.2、Pillow>=10.0.0、openai>=2.0.0、filelock>=3.16.0。组装 PPTX 时会使用 scripts/assemble_ppt.py，生成图片时优先使用当前环境可调用的内置图片生成工具。

在 Codex 环境中，如果内置图片生成工具可用，一般不需要自己填 API key。只有选择 API/CLI fallback，或内置工具不可用时，才需要关注 OPENAI_API_KEY、OPENAI_BASE_URL、CODEX_PPT_IMAGE_MODEL 和 CODEX_PPT_HOME。后端一旦确认，整套 PPT 应保持同一个生图路径，避免样张和后续页面风格跑偏。

第一次试跑

安装并重启后，在 Codex 中直接点名使用 codex-ppt。第一次不要从二十页、复杂品牌稿开始，先用一份短文章或大纲跑 8 到 10 页，重点看大纲确认、风格确认、样张确认和最终输出是否完整。

请使用 codex-ppt skill，把 /path/to/article.md 做成 10 页左右的中文 PPT。

如果已经知道用途，可以把页数、风格和必用图片写清楚，例如内部技术分享、清爽专业风、第 5 页必须使用架构图、第 8 页必须保留实验结果图。不要跳过样张确认；确认一页效果后，再授权整套生成，返工成本会低很多。

输出检查

一套 PPT 通常会生成独立项目目录，结构类似 {基础目录}/{PPT名称}/。重点检查 outline.md 是否和你确认过的大纲一致，origin_image/slide_XX.png 是否按页码保存最终幻灯片图片，speech.md 是否包含每页演讲备注，最后再看 {PPT名称}.pptx 是否能正常打开。

{基础目录}/{PPT名称}/
├── origin_image/
│   ├── slide_01.png
│   ├── slide_02.png
│   └── ...
├── outline.md
├── speech.md
└── {PPT名称}.pptx

如果某一页文字太小、配色不稳、版式太挤或概念表达不准，优先只改这一页。整套重跑容易消耗时间，也可能让原本满意的页面发生变化。仓库示例里也强调了单页局部修改的思路：定位页码和问题，再让 agent 针对该页重生成或编辑。

使用边界

ningzimu/codex-ppt-skill 的流程偏完整：确认大纲、确认风格、确认生图后端、生成样张、逐页生成、检查质量、写演讲稿、组装 PPTX。它不是一条“输入一句话立刻吐出最终文件”的捷径，而是把视觉统一、样张把关和输出检查都纳入流程。

本地跑通的判断标准也很具体：安装后能被 agent 识别，首轮能产出 outline.md，样张能正常生成，最终目录里有 origin_image/、speech.md 和 .pptx。只要记住“图片式页面 + 样张确认 + 输出目录检查”这三点，就能少踩把它误当可编辑 PPT 生成器的坑。