pptx — 模板绑定的 PowerPoint 生成工具
pptx 是一个 CLI 工具，可将真实的 .pptx 模板转换成机器可读的 manifest 清单，然后在原始企业设计规范内生成幻灯片和整套演示文稿。它会保留母版、主题、锁定的品牌元素和占位符规则，而不是对它们进行近似模拟。
快速导览
该工作流分为三个阶段：
Setup — 安装 CLI 并从模板初始化 manifest
Discover — 探索布局、占位符和主题，了解可用内容
Build — 根据结构化规格创建幻灯片或整套演示文稿，然后校验
阶段 1：Setup
安装
uv tool install pptx-cli
或：pip install pptx-cli
使用 pptx --version 验证。
初始化 manifest
manifest 包位于项目根目录的 .pptx/ 下。始终先检查是否已存在：
ls .pptx/manifest.yaml 2>/dev/null
如果不存在 manifest，你需要用户提供一个 .pptx 模板文件。请用户提供——不要假设模板已存在。然后初始化：
pptx init <template.pptx> --out ./.pptx
这会把布局、占位符、资源、主题和规则提取到结构化 manifest 包中。
引导命令：pptx guide
运行一次即可获取完整的 CLI 契约——所有命令、模式、错误码和示例：
pptx guide --format json
这是 CLI 能力的唯一事实来源。请在会话中记住结果并随时参考。
阶段 2：Discover
在构建任何内容之前，先了解模板提供什么。以下都是只读命令，可以并行运行：
列出所有可用布局
pptx layouts list --manifest ./.pptx --format json
显示特定布局的详细信息
pptx layouts show <layout-id> --manifest ./.pptx --format json
列出某布局的占位符（告诉你可用的内容键）
pptx placeholders list <layout-id> --manifest ./.pptx --format json
显示主题元数据
pptx theme show --manifest ./.pptx --format json
列出已提取的资源
pptx assets list --manifest ./.pptx --format json
检查兼容性警告
pptx doctor --manifest ./.pptx --format json
布局 ID 是从模板派生的 slug 化名称（例如 title-only、1-title-and-content、1-breaker-with-pattern）。使用 layouts list 发现确切的 ID。
占位符键是逻辑名称，如 title、subtitle、content_1、picture。使用 placeholders list <layout-id> 发现确切的键及其对每个布局支持的内容类型。
阶段 3：Build
单张幻灯片
pptx slide create
--manifest ./.pptx
--layout <layout-id>
--set title="Your Title"
--set subtitle="Your Subtitle"
--out ./out/slide.pptx
从规格生成整套演示文稿
创建 YAML 或 JSON 规格文件，然后构建。完整规格格式见 references/deck-spec.md。
deck.yaml
manifest: ./.pptx metadata: title: My Presentation author: Author Name slides:
- layout: title-only content: title: Welcome subtitle: March 2026
- layout: 1-title-and-content content: title: Key Points content_1: | First point. Second point. Third point.
pptx deck build
--manifest ./.pptx
--spec deck.yaml
--out ./out/deck.pptx
写入前预览
对会修改文件的命令始终先使用 --dry-run 预览将要发生的情况，而不写入文件：
pptx deck build --manifest ./.pptx --spec deck.yaml --out ./out/deck.pptx --dry-run
校验输出
生成演示文稿后，根据 manifest 进行校验：
pptx validate --manifest ./.pptx --deck ./out/deck.pptx --strict --format json
支持的内容类型
text — 纯文本
image — 图片文件引用
table — 结构化表格数据
chart — 图表数据
markdown-to-text — markdown 转换为格式化文本
演讲者备注与占位符内容类型分开支持。在 deck 规格中使用幻灯片级别的 notes 字段，或对单张幻灯片生成使用 pptx slide create --notes / --notes-file。
错误处理
所有命令返回结构化 JSON 信封，包含 ok、errors 和 warnings 字段。关键退出码：
退出码 含义
0 成功
10 校验错误（输入错误、未知布局/占位符）
20 策略错误
40 冲突（输出文件已存在）
50 I/O 错误
90 内部错误
先检查 ok，若为 false 再根据 errors[0].code 分支处理。
构建演示文稿的典型工作流
检查 .pptx/manifest.yaml —— 如果缺失，请用户提供模板并运行 pptx init
运行 pptx layouts list 查看可用布局
对计划使用的每个布局，运行 pptx placeholders list <layout-id> 发现内容键
仅使用已发现的布局 ID 和占位符键起草 deck.yaml 规格
使用 pptx deck build ... --dry-run 预览
使用 pptx deck build ... --out ./out/deck.pptx 构建
使用 pptx validate ... 校验
关键规则
只使用 layouts list 中出现的布局 ID —— 未知布局会导致校验错误
只使用 placeholders list 中出现的占位符键 —— 未知键会被静默忽略或导致错误
始终使用 --manifest ./.pptx 指向 manifest 包
写入前使用 --dry-run 及早发现问题
在读取命令上使用 --format json 以获得可解析的结构化输出
详细的 deck 规格格式和高级选项，请阅读 references/deck-spec.md。