PPT Master 快速入门：从零生成第一份原生可编辑 PowerPoint 的完整实战指南

2026-09-07 18:32:37作者：滑思眉Philip

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

项目地址：https://gitcode.com/GitHub_Trending/ppt/ppt-master

本篇指南是 PPT Master（hugohe3/ppt-master，一个把文档或主题交给 AI、在你本机生成真正的原生 .pptx 的开源工作流）的官方快速上手路线图。它覆盖从模板选用 → 三步产出第一份 deck → 快速模式 → 实时预览 → 转场动画 → 旁白视频 → 声音复刻 → 故障排查的完整使用链路，并深入到仓库源码（skills/ppt-master/ 下的工作流、脚本与参考文档），让你知道每一步背后对应的执行权威与 CLI 依据。读完本文，你既能按正确姿势跑通默认生成与快速生成，也能在出问题时按图索骥、自己定位并修复。

本文内容严格以官方中文文档 docs/zh/getting-started.md 为骨架，并在每个小节补充仓库内部对应的工作流、脚本与文档链接，方便进一步查阅。

先决条件：只需要 Python

在接触任何 deck 之前，先确认运行环境。PPT Master 是一套运行在具备 Agent 能力的 AI 工具里的工作流（Skill），它本身不需要你写代码，但本机需要满足：

依赖	说明
Python 3.10+	唯一硬性依赖，其余用一行命令装齐
一个 Agent 工具	Claude Code、Codex、Gemini CLI、VS Code Copilot、Cline 等能读写文件、执行命令的工具均可
`requirements.txt`	克隆仓库后执行 `pip install -r requirements.txt`

安装与选型细节以仓库根目录的 README_CN.md 为权威来源（含 Windows 专属安装指南 docs/zh/windows-installation.md）。值得提前记住的是：质量上限取决于模型——harness + model = agent，skills/ppt-master/SKILL.md 只负责工作流，视觉排版这类绝对坐标计算建议搭配大上下文 Claude / Kimi K3 类模型与 gpt-image-2 级别生图，效果差距明显。

用模板：Fill Native PPTX 与 Create Template 两条路

模板是可选的。默认走自由设计（不需要模板也能直接产出 deck），只有当你必须复用品牌身份、沟通与设计方法、固定版式或重复使用的 Deck 应用时才需要模板。面对"复用现成 .pptx"的诉求，先做路线判断——关键看你要什么结果：

你想要…	路径	会发生什么
用这份 deck 的原生页面壳承载新内容	Fill Native PPTX	克隆选中的源页面，并在 OOXML 中直接改写文字 / 表格 / 图表数据。来源设计保持原生；输出是受现有页面壳约束的新回填 deck。
先建立可复用设计系统，再生成新 deck	Create Template → Generate PPTX	从参考材料创建经过验证的 Brand、Style、Layout 或 Deck 工作区，再创作一份新 deck。新故事、结构与页数都可以不同于来源。

前者：把 .pptx 连同素材（或一个主题）给 AI，说「套模板」。完整执行规范见 skills/ppt-master/workflows/template-fill-pptx.md——它把来源 .pptx 当作原生页面库，通过选择、克隆、patch 源页直接写新 .pptx，与 SVG 生成管线完全独立（硬规则：此路线禁止调用 pptx_to_svg.py、svg_to_pptx.py 等 SVG 转换脚本）。其脚本层流程为：

# Step 2：创建独立项目工作区（不要直接写 projects/ 根目录）
python3 skills/ppt-master/scripts/project_manager.py init "<project_name>" --format ppt169
python3 skills/ppt-master/scripts/project_manager.py import-sources "<project_dir>" "<source.pptx>" "<material...>"

# Step 3：如需手动抽取页面库（import-sources 会自动执行 intake 并写出 *.slide_library.json）
python3 skills/ppt-master/scripts/template_fill_pptx.py analyze "<project_dir>/sources/<source.pptx>" \
  -o "<project_dir>/analysis/<stem>.slide_library.json"

# Step 4：生成 fill plan 骨架（--slides 仅是便利起点，可在 JSON 里手动重复/重排源页）
python3 skills/ppt-master/scripts/template_fill_pptx.py scaffold \
  "<project_dir>/analysis/<stem>.slide_library.json" \
  -o "<project_dir>/analysis/fill_plan.json" --slides "1,3,4"

# Step 5：数据化的文字容量检查
python3 skills/ppt-master/scripts/template_fill_pptx.py check-plan \
  "<project_dir>/analysis/<stem>.slide_library.json" "<project_dir>/analysis/fill_plan.json" \
  -o "<project_dir>/analysis/check_report.json"

# Step 6：应用 plan（默认要求 status 已置为 confirmed；-o 会自动追加时间戳）
python3 skills/ppt-master/scripts/template_fill_pptx.py apply \
  "<project_dir>/sources/<source.pptx>" "<project_dir>/analysis/fill_plan.json" \
  -o "<project_dir>/exports/<output.pptx>"

# Step 7：回读校验
python3 skills/ppt-master/scripts/template_fill_pptx.py validate "<project_dir>"

后者的明确请求方式是在对话中显式走 Create Template 路线——原生 .pptx 加新材料默认归属 Fill Native PPTX，并不是 Generate 可直接消费的模板工作区，必须显式创建工作区：

你：用 /create-template 从 projects/brand/our_deck.pptx 创建一个可复用 Deck 模板

Create Template 会分析参考材料，把结果分类为 Brand（只拥有身份系统）、Style（只拥有可移植沟通方法与视觉默认值）、Layout（品牌中立的可复用页面结构）、Deck（一类可重复演示的应用语境 + 一体化身份与结构）四种 kind 之一，然后创作或物化一个经过验证的新工作区。导入器只提供来源证据；最终工作区拥有 templates/design_spec.md，以及该 kind 真正需要的原型与素材（Brand 与 Style 不含 SVG roster；Layout 与 Deck 拥有 structured SVG 原型）。需要 PowerPoint 评审文件时再显式运行可选预览导出，生成 exports/<id>_template_preview.pptx。

复刻出的模板可放在两处：

位置	路径	说明
注册进 skill 库	`skills/ppt-master/templates/<kind>/<id>/`	可移植工作区并执行全局注册；问"有哪些模板"时会被列出来
放在 projects 下	`projects/<name>/`	相同的可移植工作区，不执行全局注册

关于目录：内置库按 kind 分目录并各自由发现索引维护，例如 skills/ppt-master/templates/layouts/layouts_index.json；四类索引是 Stage 1 模板控件与聊天发现共用的唯一已注册来源，目录永远不会被扫描。更完整的选用 / 派生 / 边界方法论见 docs/zh/templates-guide.md 与 skills/ppt-master/workflows/create-template.md。

做出第一份 deck：整个流程就三步

不装模板时的核心链路（主管线 Generate PPTX）如下，来源处理、SVG 创作到导出都由主流程权威 skills/ppt-master/workflows/generate-pptx.md 管理：

把源材料放进 projects/——PDF、DOCX、Markdown、一个网址，或直接要粘贴的文字。
在对话里告诉 AI 要把什么做成 deck。Stage 1 会让你同时确认沟通契约与自由设计 / 模板使用；只附上一个精确工作区 root 时，页面可默认进入模板模式并预选该路径：
```
你：用 projects/q3-report/sources/report.pdf 做一份 PPT
你：把这份内容做成 PPT：<粘贴你的文字>
```
拿回可编辑的 .pptx，位于 exports/<名称>_<时间戳>.pptx——真正的 DrawingML 形状、文本框、图表，在 PowerPoint / Keynote / WPS / LibreOffice 里点开就能改。

生成前，Stage 1 同时确认沟通契约、画布 / 格式与自由设计 / 模板选择。AI 随后安装所选工作区；最终 Stage 2 读取安装结果，并确认页数、视觉系统、模板应用方式与生产选项。默认主管线的典型流水线是：Initial Materials → [Fact Research] → Create Project → Template Candidate Preparation → Stage-1 Communication + Template Confirmation → [Template Installation] → Stage-2 Solution → [Image Acquisition] → Executor Live Preview → Quality Check → Post-processing → Export。之后内容分析、排版、配图、SVG 生成、导出都由 AI 完成——这就是其它能力围绕的核心环节。不想走交互确认，见下一节快速模式。

提示：没有现成资料、只有主题时也没问题。主管线会运行 topic-research 阶段补齐事实基础与来源记录，规范见 skills/ppt-master/workflows/stages/topic-research.md。

快速模式：省掉确认、不省能力

默认流程会先进行 Stage 1 的沟通 / 模板合并确认，再进入最终 Stage 2。不想经过这些交互，就显式要求快速生成：

你：用 sources/report.pdf 快速生成一份 PPT,不用跟我确认
你：这份内容直接做成 PPT,跳过确认,8 页左右,深色商务风

你明确提的照做，你没提的 AI 直接定，不再回来问你。 第二个例子里的页数和风格照样生效——快速模式省掉的是来回确认，不是你的话语权；什么都不提，才是全部交给 AI 决定。

快速模式的完整契约见 skills/ppt-master/workflows/profiles/quick-generate.md，它是 Generate-PPTX 的一个 profile 而非顶层路线。几个关键行为要点：

不开 Confirm UI 的模板选择页。每个 kind 最多给出一个精确的 Brand / Style / Layout / Deck 工作区 root，它直接校验、安装并使用；没有给出精确 root 就直接自由设计。只写模板名或风格词仍然只是设计说明。
Quick 保持无锁 flat 导出，因此 Layout / Deck 原型会指导页面创作，但不会编译成可复用的原生 Master / Layout 对象。
不跳过能力：来源转换、事实缺口研究、共享美学规范、图片 / 图标准备，以及原生形状 / 图表 / 表格创作仍按需运行。结构性公式直接写成 PowerPoint 原生 marker，不再作为图片素材准备。必需素材缺失时它会停下来跟你要，不会拿无关材料顶替。
一次性生成，不是缩短后的可续接流程。它不产生 Strategist 记录、design_spec.md、spec_lock.md 或替代性的页面计划；内容、设计和资源决策只存在于 AI 的当前上下文，交付前一旦丢失上下文就重新运行 Quick。资源 manifest、质量报告、postflight 与冷 Python 审计日志可以保留，但无法还原 AI 为什么这样设计。

脚本层面，Quick 用 --quick-generate 初始化最小工作区，并由无锁最终质量门把关后直接导出：

python3 skills/ppt-master/scripts/project_manager.py init <project_name> --format <format> --quick-generate
python3 skills/ppt-master/scripts/svg_quality_checker.py <project_path> --quick-generate --stage final --json
python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> --quick-generate --with-notes   # 或 --no-notes

实时预览与可视化修改

生成过程中会自动打开启动器报告的浏览器预览地址。它优先使用 http://localhost:5050，若 5050 已被占用则使用下一个空闲端口。

实时看着每页渲染出来。
直接改，无需 AI——选中元素后在右栏改文字、颜色、字体、字号；拖拽即可移动，或用方向键微调（Shift = 10px），Ctrl+Z 撤销。改动即时预览，点 Apply changes 写回 svg_output/。
或写注解交给 AI——点选元素写一句要改成什么，点 Submit annotations，再回对话说"应用注解"（或 "apply my annotations"），AI 会改写那块区域并重新导出 PPTX。

值得说明的是，PPT Master 最初是纯对话设计；可视化编辑是在很多用户提出后融入的（建立在社区 PR 之上）。完整的执行阶段规范见 skills/ppt-master/workflows/stages/live-preview.md。预览服务由 skills/ppt-master/scripts/confirm_ui/ 与 svg_authoring_view.py 等相关脚本支撑，端口占用时自动回退到下一空闲端口。

转场与动画

导出的 deck 用真正的 OOXML 保存页间转场和可选的页内元素对象动画，不是嵌入视频。默认行为与配套命令的完整对照见 docs/zh/animations.md，精确效果映射、完整 sidecar schema 与封包校验统一由 skills/ppt-master/references/animations.md 维护。默认值一览：

层级	默认	含义
页间转场	`fade`，0.4 秒	页面之间使用克制的视觉过渡
元素对象动画	`none`（关闭）	每页一次性完整出现；只有当动效确实有助于表达时才开启

修改动画设置不需要重新生成页面，可继续使用同一份 svg_output/。常用 CLI（脚本 skills/ppt-master/scripts/svg_to_pptx.py）：

python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push                        # 更换页间转场
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t none                        # 关闭视觉转场
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --auto-advance 5               # 每 5 秒自动翻页
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto                        # 开启自动元素入场
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation entrance_fade      # 全部使用同一种入场效果
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-trigger on-click   # 单击逐个揭示元素
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-trigger with-previous # 所有元素同时入场
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-duration 0.5 --animation-stagger 0.8  # 放慢逐步揭示

动效名称体系上有三个数值值得记牢：

页间转场共有 48 个规范标识，覆盖 PowerPoint 效果库的三个分组：细微（morph / fade / push / wipe / split / reveal / cut 等 12 个）、华丽（fall_over / curtains / page_curl / dissolve / cube 等）、动态内容（pan / ferris_wheel / conveyor / rotate / orbit / fly_through）。
对象动画注册表包含 203 个 PowerPoint 原生标识：53 个进入（entrance_*）、33 个强调（emphasis_*）、64 条动作路径（path_*）、53 个退出（exit_*）。auto / mixed / random 只选择进入效果；强调、动作路径与退出必须用显式规范标识。
旧的 29 个短名称只保留为兼容输入，写入前归一化；新选择、sidecar 与输出统一使用带前缀的规范名称。完整分类清单可运行 python3 skills/ppt-master/scripts/pptx_animations.py --list。

Start 模式按演示节奏选择：on-click（每次单击显示一个内容组，适合现场演示）、with-previous（页面出现时全部同时入场）、after-previous（默认，无需点击按顺序自动出现，适合展厅循环、录屏与旁白 deck）。注意：--recorded-narration 不支持 on-click，带旁白或用于视频导出的 deck 应使用 after-previous 或 with-previous。

验证纪律同样严格：未知效果、Start 模式、非法时序值或缺失对象引用会直接阻断导出，候选 PPTX 还会在发布前回读动画目标、效果与 timing 结构。Microsoft PowerPoint 是动效行为的主要验证目标；Keynote、WPS、LibreOffice 可能重新映射个别效果。需要逐对象精细编排（进入 → 移动 → 强调 → 退出）时，用 animation_config.py 维护稀疏的 animations.json（对稳定顶层 <g id> 内容组锚点生效）：

python3 skills/ppt-master/scripts/animation_config.py list-groups <project>
python3 skills/ppt-master/scripts/animation_config.py validate <project>

{
  "version": 1,
  "slides": {
    "03_threshold": {
      "animation": { "trigger": "after-previous" },
      "groups": {
        "risk-marker": {
          "effects": [
            { "effect": "entrance_fade", "order": 1, "duration": 0.25 },
            { "effect": "path_right", "order": 2, "delay": 0.1, "duration": 0.7 },
            { "effect": "emphasis_teeter", "order": 3, "trigger": "with-previous", "duration": 0.45 },
            { "effect": "exit_fade", "order": 4, "trigger_shape": "details-button", "duration": 0.3 }
          ]
        }
      }
    }
  }
}

旁白与视频

PPT Master 可以把演讲者备注按页生成语音旁白、把音频嵌回 PPTX，再用 PowerPoint 导出带旁白和转场的 MP4——无需第三方工具。触发方式就是在对话里直接说：

你：给这个 PPT 生成音频,并把音频嵌回重新导出
你：给这个 PPT 生成音频

旁白默认用 edge-tts（约 90 种语区，覆盖中文全部主要变体 zh-CN / zh-TW / zh-HK、英 / 日 / 韩 / 法 / 德 / 西 / 葡 / 俄 / 阿等）；需要更高质量音色可配置云端 provider（ElevenLabs / MiniMax / Qwen / CosyVoice）。AI 会按 deck 语言推荐音色，生成前只问你一次。手动跑脚本与全部 provider 参数见 docs/zh/audio-narration.md，阶段执行权威是 skills/ppt-master/workflows/stages/generate-audio.md。核心脚本 skills/ppt-master/scripts/notes_to_audio.py 的典型调用：

# 1. 确保备注已切分（按页切分演讲者备注）
python3 skills/ppt-master/scripts/total_md_split.py <project_path>

# 2A. 默认用 edge-tts 生成 MP3/SRT 对（无需 API Key，edge 模式 --voice 必填）
python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> --voice zh-CN-YunjianNeural --rate +0%

# 2B. 云端 provider 示例（ElevenLabs，需 ELEVENLABS_API_KEY）
export ELEVENLABS_API_KEY="your-elevenlabs-api-key"
python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
  --provider elevenlabs --voice-id <elevenlabs-voice-id> --elevenlabs-model eleven_multilingual_v2

# 5. 嵌回并重导出（--recorded-narration audio 写入自动推进时间）
python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \
  -o <final_narrated_pptx> --recorded-narration audio \
  --narration-start-floor 0.8 --narration-padding 0.5

两条嵌入路径的参数语义：--recorded-narration audio 准备 PowerPoint 的"录制的计时和旁白"，要求每页都有音频并写入页面自动推进时间（供旁白视频导出）；--narration-audio-dir audio 是底层音频嵌入能力，只嵌入匹配到的文件、允许部分页面有音频（用于测试或手工整理）。--narration-start-floor 0.8（页前最短秒数，默认 0.8，设 0 表示转场结束立即开始）与 --narration-padding 0.5（页尾静默停留，默认 0.5）可独立覆盖；转场结束后的实际静默时间为 max(0, narration_start_floor - transition_duration)。

视频导出仅保留一条交付路径，自动导出在 Windows PowerPoint 2016+ 上完成：

python3 skills/ppt-master/scripts/powerpoint_video.py <final_narrated_pptx> -o exports/<raw>.mp4

命令默认 1080p/30fps，并在 PowerPoint 明确成功或失败后才返回；PowerPoint for Mac 也可手动 文件 → 导出 → 创建视频。有 cue 音效时再叠加 video_sound_mix.py 混音、video_subtitles.py 对齐外挂字幕。

使用复刻音色

用 ElevenLabs / MiniMax / Qwen / CosyVoice 复刻你自己的声音（或在授权前提下复刻演讲者的声音），让整份 deck 用 你的声音 念出来。职责切分很明确：声音复刻本身在 provider 的控制台或 API 完成——你上传一段干净样本（一般 10 秒到几分钟），平台返回一个 voice_id；PPT Master 只做消费侧，拿到 voice_id 后就逐页朗读备注并嵌回 PPTX，不会把你的样本上传到任何地方。edge 不支持复刻。

你：用 MiniMax 我克隆的音色生成旁白，voice_id 是 xxxxxxx
你：用我在 ElevenLabs 复刻的 voice id abc123 生成

对应脚本（--provider 换成 elevenlabs / minimax / qwen / cosyvoice 即可切平台，--voice-id 接收复刻音色与系统音色的方式完全一样）：

python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
  --provider minimax --voice-id <你的复刻 voice id> --minimax-model speech-2.8-hd

务必注意三条边界：授权——只复刻自己拥有或取得明确授权的声音；语言覆盖——复刻音色继承说话人口音，中英混合等多语 deck 建议挑对样本语言组合处理较好的 provider（ElevenLabs eleven_multilingual_v2 与 CosyVoice 通常最宽容）；字幕能力——ElevenLabs 复刻音色与受支持的 CosyVoice 复刻音色可生成 provider 原生计时 SRT，Qwen 复刻音色在当前 API 下仍只生成音频。详细对照见 docs/zh/audio-narration.md#使用复刻音色。

遇到问题怎么办

常见问题（FAQ）是持续更新的排查真值——来自真实用户反馈。最常见情况的快速指引：

情况	先试这个
AI 跑偏或漏了步骤	让它重新读 skills/ppt-master/SKILL.md、skills/ppt-master/workflows/routing.md 和已选路线的权威文档。
视觉质量不理想	换成大上下文 Claude 模型 + `gpt-image-2`——harness 决定下限，模型决定上限。
文字溢出或元素重叠	重跑那一页，或用实时预览修；详见 FAQ。
没有生图 API key	Agent host 提供原生生图时直接使用，否则零配置网络图片搜索仍可用；见 FAQ。
动画或部分效果在别的软件里不对	Microsoft PowerPoint 是动效行为的主要验证目标。Keynote / WPS / LibreOffice 可以打开 `.pptx`，但可能重新映射或省略个别效果或 Start 语义；动效关键交付应在 PowerPoint 中验证。
担心长 deck 撑爆上下文	生成可走分段模式；详见 FAQ。

排查时先把问题定位到"创作层还是转换层"：对比 svg_output/ 中的页面与导出 PPTX——SVG 本身溢出属排版问题（模型坐标计算），SVG 正确而 PPTX 不对才可能是转换器 / 渲染器问题，应连同两份产物一起反馈。模型选择、费用结构、图表可编辑性（默认 SVG 图形转原生形状 vs --native-charts-and-tables 的 Excel 驱动对象）、自定义模板、公式 OMML、可点击超链接等更细的问题，都在 docs/zh/faq.md 中逐条解答。