PPT Master 使用指南：在 Agent 工作流中生成原生可编辑 PowerPoint 的完整实践

PPT Master 使用指南：在 Agent 工作流中生成原生可编辑 PowerPoint 的完整实践

【免费下载链接】ppt-masterAI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations,>项目地址: https://gitcode.com/GitHub_Trending/ppt/ppt-master

PPT Master 是一套运行在任意具备 Agent 能力的 AI 工具中的 PPT 生成工作流（skill）：把 PDF、DOCX、网页或纯文字材料交给 AI，它在本机完成内容分析、视觉设计、SVG 创作与导出，产出的是带原生形状、数据驱动图表与表格、母版版式的真实.pptx文件。本文以官方中文 README 为骨架，结合仓库中的脚本目录、路由规则与配置样例，完整覆盖从安装、配置到输出管线的全流程，读完后你可以独立完成：选择 Agent 环境、配置生图/搜图后端、跑通默认与快速两种生成模式，并理解svg_output/→exports/的底层转换链。

一、产品定位：「原生深度」而不是一张能改的图

README 开篇的判断是：可编辑早已是及格线，真正拉开差距的是原生深度。PPT Master 交付的是 PowerPoint 的原生对象模型本身——带调节手柄的原生形状与连接符、按需的数据驱动图表与表格、完整的文本/图片/填充/效果；点开任意元素，它都作为原生 PowerPoint 对象继续编辑。走模板/结构化路线时，还能产出带真正母版与版式（p:sldMaster/p:sldLayout继承）的 deck。

这份深度被定义为一个前进方向而非固定清单：项目的北极星是持续向 PowerPoint 本身靠拢，逐版本补齐更多原生能力，缩小「AI 能替你生成的」与「你在 PowerPoint 里手工能做出的」之间的差距。PowerPoint ↔ SVG 映射指南 逐条、诚实地记录了当前能力的覆盖范围——其中 SmartArt 是刻意排除项，而非缺口。

工作流形态与三条承诺

从形态看，PPT Master 不是独立应用，而是运行在有 Agent 能力的 AI 工具里的一个 "skill"：在对话框里说"用这份 PDF 做一份 PPT"，它就按流程在本机生成并导出原生可编辑的.pptx，全程不写代码——只需要装 Python、装一个 AI 工具、把材料放进来。在此形态上它给出三个承诺：

• 成本透明可控：工具免费开源（MIT 协议，见 LICENSE），唯一成本是你自己的 AI 模型用量，不叠加订阅费用；
• 数据不出本地：除与 AI 模型的对话外，全流程在你的电脑上完成；
• 不锁定平台：任何具备 agent 能力的 AI IDE 均可驱动，Claude、GPT、Gemini、Kimi 等模型均可使用。

从 SKILL.md 的路由表还能看到，「从源材料生成新 deck」只是主管线，仓库同时内置了另外几条一等路线，且各自有明确的保留契约：

即：你可以从参考资料中提炼可复用的品牌/风格/版式/成品模板、把新内容填进你已有的.pptx并保留其设计，或为成品 deck 追加原生转场、动画和旁白。

这是一个工具，不是一个许愿池

harness + model = agent——PPT Master 只负责工作流，产出上限由模型决定。README 的明确建议：使用大上下文窗口（约 100 万 token）的强模型（如 Kimi K3 或 Claude）驱动流程，并搭配 AI 生图（gpt-image-2或 Googlegemini-3.1-flash-image）；其他模型能跑通流程，但存在质量差距。不要指望一把拿到完美成品——它的价值是把大部分枯燥的活儿干掉，剩下的打磨交给你；做原生可编辑的 PPT 本就是为了让你接着改，而不是甩给你一张改不动的图。模型越便宜，要补的人工就越多；效果不理想时，先升级模型，再对照快速入门与examples/中的示例工程检查用法。为什么选它、以及它不适合的场景见 为什么选 PPT Master；这些承诺背后的长期能力边界见 项目定位与能力边界。

二、快速开始

1. 前置条件

只需安装 Python 3.10+。其余依赖在第 3 步下载好项目后，用一行pip install -r requirements.txt装齐。仓库根的 requirements.txt 实际只做一件事——通过-r skills/ppt-master/requirements.txt引入 skill 内置的完整依赖列表，因此无论装完整仓库还是只装 skill 包，依赖口径一致。

• Windows：需要额外步骤（PATH 设置、执行策略等），官方提供了手把手安装指南 Windows 安装指南，从零到跑通第一份 PPT 约 10 分钟。核心要点：安装 Python 时勾选 "Add to PATH"。
• macOS / Linux：安装即用：

# macOS brew install python # Ubuntu / Debian sudo apt install python3 python3-pip

• 边缘场景备用方案（99% 的用户用不到）：Pandoc 只在需要转小众格式时才装：.doc、.odt、.rtf、.tex、.rst、.org、.typ。.docx、.html、.epub、.ipynb已由 Python 原生处理，不需要 pandoc：

# macOS brew install pandoc # Ubuntu / Debian sudo apt install pandoc

从源码结构看，这些格式转换能力对应 scripts/README.md 中的source_to_md/目录：pdf_to_md.py、doc_to_md.py、excel_to_md.py、ppt_to_md.py、web_to_md.py等后端转换器，由统一的source_to_md.py分发入口调度。

2. 选择一个 Agent

PPT Master 在任何具备 agent 能力（可读写文件、执行命令、持续多轮对话）的工具里都能跑。没用过这类工具也不用担心：它们在本项目里只扮演一个角色——一个能读写文件的 AI 聊天窗口。从下表任选一款装好即可，全程只用它的聊天面板，不需要写任何代码。

作者最推荐：Claude Code—— 本项目开发与测试最充分的环境，CLI 与 VS Code / JetBrains 扩展均可。

模型推荐：追求最佳效果，语言模型选 Kimi K3（或 Claude）驱动流程，搭配 AI 生图 ——gpt-image-2（OpenAI）或gemini-3.1-flash-image（Google）。

3. 配置项目

方式 A — Git clone（推荐，可随时拉取最新版本）：

git clone https://gitcode.com/GitHub_Trending/ppt/ppt-master.git cd ppt-master

然后安装依赖：

pip install -r requirements.txt

方式 B — 下载 ZIP（无需安装 Git，适合快速体验）：从仓库代码页选择 Download ZIP 下载，解压后同样执行pip install -r requirements.txt装依赖。注意 ZIP 没有 Git 历史，不能自动git pull。如果完整仓库下载失败或嫌体积太大，可以改到 Releases 页面下载纯技能包ppt-master-skill-*.zip（约 56 MB，功能完整，但不含内置示例 deck）。

方式 C — Skill marketplace：仓库根目录已添加 .claude-plugin/marketplace.json 元数据（当前版本 4.8.0，git-subdir方式只拉取skills/子目录），可通过 Claude Code plugin marketplace 生态一行安装：

# 跨 agent CLI（Claude Code、Cursor、Codex 等） npx skills add hugohe3/ppt-master # 或在 Claude Code 内 /plugin marketplace add hugohe3/ppt-master /plugin install ppt-master@ppt-master

上述两种 marketplace 安装方式都只会拉取 skill 文件本身（不含完整仓库），后处理脚本仍需在安装目录跑pip install -r requirements.txt。

日常更新

Git clone 安装，执行更新脚本：

python3 skills/ppt-master/scripts/update_repo.py

脚本会拉取最新版；如果requirements.txt有变化，会自动同步 Python 依赖——这与 requirements.txt 头部注释一致：update_repo.py会对该文件及其递归-r/--requirement引用树计算指纹。

ZIP 安装：重新下载最新版 ZIP，解压到新目录，把旧目录里的.env和projects/复制过去，再执行pip install -r requirements.txt。

4. 开始创作

先在 Agent 里打开项目文件夹：目标是让 AI 工作在上一步解压/克隆出来的ppt-master目录里——IDE 类工具通过菜单「文件 → 打开文件夹」打开它；CLI 类工具先cd ppt-master再启动。之后的一切都在聊天里完成。

提供原始材料（推荐）：将 PDF、DOCX、图片等文件放入projects/目录下，在 AI 聊天面板中告诉它使用哪些文件。获取路径的最快方式：在文件管理器或 IDE 侧边栏中右键文件 → 复制路径（Copy Path / Copy Relative Path），直接粘贴进聊天框：

你：请用 projects/q3-report/sources/report.pdf 这份文件生成一份 PPT

直接输入内容：也可以把文字内容直接粘贴进聊天窗口，AI 会根据这些内容生成 PPT：

你：请根据以下内容制作成 PPT：[粘贴你的文字内容...]

默认流程下（除非显式要求快速生成），AI 会先确认设计规范：

AI：好的，先确认设计规范： [模板] B) 自由设计 [格式] PPT 16:9 [页数] 8-10 页 ...

AI 全程处理——内容分析、视觉设计、SVG 生成、PPTX 导出。这个「先停下来确认」的行为有明确的源码依据：SKILL.md 的全局执行纪律规定「Blocking means stop」——在每个⛔ BLOCKING门控处等待用户显式确认，不得替用户做决定；且「串行执行」，按所选路由权威文档的步骤顺序推进。

快速生成（跳过来回确认）：显式说明即可，AI 直接进入创作与导出：

你：用 projects/q3-report/sources/report.pdf 快速生成一份 5 页 PPT，不用跟我确认

你明确提的照做，你没提的由 AI 直接定，不再回来问。它仍会转换来源、补齐事实、应用共享视觉基线，并按需使用图片/图标/原生形状/图表/表格/PowerPoint 原生行内或块级公式——省掉的是交互与持久规划，不是 PPT 能力。Quick 模式（quick-generate.md）是不可续接的一次性生成，也不会产生svg_final/预览；细节见下文「输出说明」。

输出说明（管线细节）：

• SVG 管线统一由项目转换器读取svg_output/，生成可直接编辑的原生 DrawingML.pptx，保存至exports/<name>_<timestamp>.pptx；
• 默认 Generate 流程会运行finalize_svg.py并生成自包含预览svg_final/；PowerPoint 手工「转换为形状」不在支持范围；
• Quick 模式跳过 Strategist、确认、design_spec.md、spec_lock.md与finalize_svg.py，通过无锁的 Quick 最终质量检查后导出最终 PPTX；它不写替代计划，上下文丢失后不能续接；
• 公式 marker 会把 LaTeX payload 编译为 PowerPoint 2010+ 可编辑 OMML；块级 group 与行内<tspan>run 都保留普通 SVG 预览，导出时将其替换。Keynote、WPS、LibreOffice 等非 PowerPoint 客户端的公式显示与编辑能力不在支持合同内；
• 讲稿、自定义对象动画和旁白默认关闭，Agent 可在用户要求或 deck 确有需要时启用；
• Quick 使用默认输出路径时仍会生成普通 postflight 报告，并把svg_output/镜像到backup/<timestamp>/svg_output/；显式指定输出路径时沿用普通流程不创建备份的行为；
• 图表和表格默认导出为 SVG 派生、可逐形状编辑的 DrawingML 对象，优先保证 PowerPoint / Keynote / WPS 间的视觉一致性；可加--native-charts-and-tables，把符合合同的组替换为带数据源和对象专属编辑能力的 PowerPoint 原生 Chart/Table 对象，跨软件渲染可能略有差异，保存为exports/<name>_<timestamp>_native_charts_tables.pptx。这两种导出变体都可编辑，区别在于 PowerPoint 对象模型，而不是「能否编辑」。

已有一份想复用的.pptx？把那份 deck 连同素材给 AI，说「套模板」即可——它会把新内容（文字、表格、图表数据）填进你现有的设计，只导出你挑选的页面，且保持原生可编辑。详见 常见问题 与 套模板工作流。

遇到问题？AI 迷失上下文时，让它先读 skills/ppt-master/SKILL.md；其他问题查看 常见问题——涵盖模型选择、排版问题、导出异常等，基于真实用户反馈持续更新。

5. 图片获取（可选）

非用户自带图片有两条路径，可在同一份 deck 里按图混用：

A) AI 生图— Agent host 提供原生生图工具时可直接使用；也可通过image_gen.py配置IMAGE_BACKEND和供应商*_API_KEY。host-native 生图不需要另配供应商生图 API Key，直接要求 Agent 使用自身生图工具即可。运行python3 skills/ppt-master/scripts/image_gen.py --list-backends查看供应商后端清单（该参数已在 image_gen.py 的命令行入口确认存在）。gpt-image-2目前综合质量最佳。从源码结构看，image_backends/ 目录实际内置了 13 个供应商实现：openai、gemini、qwen、zhipu、volcengine（.env.example标注的推荐核心后端），以及 minimax、stability、bfl、fal、ideogram、modelscope、openrouter、replicate、siliconflow。

B) 网络图片搜索—image_search.py，零配置可用；建议配置PEXELS_API_KEY/PIXABAY_API_KEY（都免费申请）以获得稳定的高质量结果：

• 不配置时只使用 Openverse / Wikimedia Commons，适合作为兜底，但容易出现构图随意、清晰度不稳定的图片；
• 配置后默认搜索链会追加 Pexels / Pixabay，现代商业摄影、人物、办公、生活方式和插画类图片质量明显更稳定（对应 image_sources/ 下的provider_openverse.py、provider_wikimedia.py、provider_pexels.py、provider_pixabay.py四个提供者）；
• 许可自动处理：默认把 CC0、公有领域、Pexels / Pixabay 免署名许可、CC BY、CC BY-SA 一起纳入候选；选中需署名的图片时，Executor 会在该幻灯片自动添加小字署名。只有明确不能出现署名时，才使用--strict-no-attribution限制为免署名图片（该参数在 image_search.py 的严格模式逻辑中实现）；
• 对视觉要求高的封面、产品图、人物图和品牌场景，优先级建议：用户自带高清素材 / AI 生图 > 配置 Pexels / Pixabay 的网络搜索 > 零配置网络搜索。

完整说明：image-generator.md（AI）· image-searcher.md（网络）。

API Key 的.env配置

上面提到的 API Key 统一通过.env配置，模板见仓库根的 .env.example。clone 安装可以用cp .env.example .env；skill marketplace 安装建议使用持久的用户级配置：

mkdir -p ~/.ppt-master cp /path/to/installed/ppt-master/.env.example ~/.ppt-master/.env

PPT Master 会优先读取当前进程环境变量，然后按顺序读取第一个存在的.env（多个.env之间不合并），顺序为：

1. 当前工作目录下的./.env；
2. skill 安装目录下的.env（如~/.agents/skills/ppt-master/.env）；
3. clone 仓库根目录的.env；
4. ~/.ppt-master/.env（用户级配置）。

以生图为例，.env.example 中的关键项：IMAGE_BACKEND（必需，选择供应商）、IMAGE_CONCURRENCY（--manifest批量模式下的最大并发数，默认 3，命中限流自动减半，最低 1 即串行），以及各供应商专属的*_API_KEY/*_MODEL（注意IMAGE_API_KEY/IMAGE_MODEL/IMAGE_BASE_URL这类通用变量已不再支持，请只使用各提供商自己的变量）。

三、端到端管线：脚本视角的印证

examples/下每个示例工程（如examples/ppt169_swiss_grid_systems/）都完整保留了管线各阶段的产物：notes/（每页讲稿）、svg_output/（Agent 手写 SVG）、svg_final/（finalize 后的自包含预览）、exports/（最终.pptx）、design_spec.md与spec_lock.md（设计规范与锁定）。这与 scripts/README.md 给出的典型端到端命令链一一对应：

python3 scripts/source_to_md.py <file-or-url-or-dir> [<file-or-url-or-dir> ...] # 来源 → Markdown python3 scripts/project_manager.py init <project_name> --format ppt169 # 初始化项目 python3 scripts/project_manager.py import-sources <project_path> <source_files_or_dirs...> python3 scripts/total_md_split.py <project_path> # 讲稿拆分 python3 scripts/finalize_svg.py <project_path> # 生成自包含预览 python3 scripts/animation_config.py scaffold <project_path> # 可选：对象级动画覆盖 python3 scripts/svg_to_pptx.py <project_path> # 导出原生 PPTX

几个值得注意的实现事实：

• 路由先行：SKILL.md 规定强制加载顺序——先读 SKILL.md，运行python3 scripts/attribution_guard.py完整性校验（非零退出即终止），再读 workflows/routing.md 选定唯一顶层路由，之后只加载该路由的运行时权威文档，绝不跨路由混用；
• 确定性路由：当 routing 权威已能解析请求时，不得额外添加路由选择问题；路由前置条件缺失则声明并停止该路线；
• 工作流日志：init之后，项目级 Python CLI 会自动把命令包络和有界的材料结果记录到<project_path>/validation/workflow.log，无需日志包装器；
• Windows 兼容：SKILL.md 明确，若文档中python3 ...命令在 Windows 上不可用，用python重跑同一命令。

四、文档导航

完整文档索引见 docs/zh/README.md。

五、贡献、协议与致谢

贡献流程详见 CONTRIBUTING.md；项目采用 MIT 协议（LICENSE），使用需保留署名。第三方图标（SVG Repo、Tabler Icons、Simple Icons、Phosphor Icons 等）的固定版本、许可证、署名、兼容层与商标边界，详见 第三方图标说明。

最后说明一点项目缘起：作者何雨果（Hugo He）是投融资领域从业者，工作中经常审阅和修改 PPT，因此要求 AI 生成的幻灯片仍能回到 PowerPoint 里继续编辑，而不是被压成一张张图片。作者也强调：做 PPT 只是载体，项目真正想推广的是 Python 和 agent 这套能力组合——零基础上手有一段学习曲线，但走完这段，你就接上了未来。

【免费下载链接】ppt-masterAI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations,>项目地址: https://gitcode.com/GitHub_Trending/ppt/ppt-master