使用Claude Code基于ppt-master生成PPT

一、引言

在日常工作和学习中，PPT制作往往不是简单地把文字复制到幻灯片里。真正耗时的部分通常在于：梳理材料结构、确定每页主题、设计版式、选择图表、控制信息密度、反复调整视觉效果，以及最终导出一个可以继续编辑的pptx文件。

传统AI PPT工具大多偏向网页端一键生成，优点是上手快，缺点也很明显：生成结果常常不够可控，很多页面只是图片化输出，后续想在PowerPoint里精细修改文字框、图形、图表、动画时并不方便。

ppt-master的思路更适合开发者。它不是一个单纯的网页应用，而是一个面向AI Agent的演示文稿生成工作流。开发者可以在Claude Code、Codex CLI、Gemini CLI、Cursor、Cline等具备文件读写和命令执行能力的工具中，让Agent基于ppt-master读取资料、规划页面、生成SVG页面，再导出为原生可编辑的PowerPoint文件。

也就是说，使用ppt-master的关键不是“打开一个网站点生成”，而是把它当作一个本地项目，让Code CLI Agent在项目中按流程完成整套制稿工作。

本文以Claude Code为主要示例，同时也说明如何迁移到其他Code CLI Agent中使用。

二、ppt-master适合解决什么问题

ppt-master的核心目标是：把PDF、DOCX、网页链接、Markdown或直接粘贴的文字内容，转换成一个真正可编辑的PPTX文件。

它和普通AI PPT工具最大的区别在于输出形式：

类型	常见输出	后续编辑体验
图片式生成	每页是一张大图	只能整体移动或裁剪，无法精细编辑元素
网页式生成	HTML或在线演示页面	展示方便，但不是传统PPT文件
模板填充式生成	固定模板中的文字替换	结构稳定，但自由度有限
ppt-master	原生PPT形状、文本框、图表	可在PowerPoint中逐个元素编辑

因此，ppt-master更适合以下场景：

• 根据论文、报告、产品文档或会议纪要生成汇报PPT；
• 根据Markdown大纲生成课程讲义、技术分享或项目复盘；
• 根据网页文章生成可二次编辑的演示文稿；
• 需要保留本地文件，不希望把完整资料上传到第三方PPT平台；
• 对页面质量、版式风格、可编辑性有较高要求。

需要注意的是，ppt-master并不是完全脱离模型能力的魔法工具。它更像一个“工作流框架”，负责规范生成步骤、脚本处理、格式转换和导出；最终页面质量仍然取决于你使用的模型、提示词质量和输入材料质量。

三、整体工作流

使用Code CLI Agent基于ppt-master生成PPT时，可以把过程理解为下面这条链路：

准备资料 -> 启动Agent -> 读取ppt-master工作流 -> 创建项目 -> 导入资料
-> 确认页面方案 -> 生成SVG页面 -> 预览和修改 -> 后处理 -> 导出PPTX

其中开发者真正需要做的事情并不多，主要包括：

1. 准备本地环境和ppt-master项目；
2. 把原始资料放到项目目录中；
3. 用Claude Code或其他Agent打开该项目；
4. 用自然语言描述要生成什么类型的PPT；
5. 在关键节点确认页数、比例、风格、受众和内容重点；
6. 检查导出的pptx文件并做最后人工微调。

Agent负责阅读ppt-master的SKILL.md或AGENTS.md，然后按项目内置脚本执行转换、拆分、生成、检查和导出。

四、环境准备

1.基础软件

建议先准备以下环境：

环境	用途
Git	拉取ppt-master项目
Python 3.10+	运行ppt-master脚本
pip	安装Python依赖
Node.js/npm	安装部分Agent、Skill或插件时会用到
PowerPoint或WPS	打开和检查导出的pptx
Claude Code或其他Code CLI Agent	驱动整个生成流程

检查本机环境：

git --version
python --version
pip --version
node -v
npm -v

如果在Linux或macOS中使用，也可以把python替换为python3：

python3 --version
pip3 --version

2.准备一个可用的Agent

本文以Claude Code为例。进入工作目录后，启动方式通常如下：

claude

如果你使用的是Codex CLI，则可以在项目目录中运行：

codex

如果使用Gemini CLI、Cursor Agent、Cline、Roo Code等工具，核心要求也是一样的：它必须能够读取项目文件、写入生成结果，并能执行本地命令。

如果你的工具只能聊天，不能读写本地文件和执行脚本，那就不适合直接驱动ppt-master完整流程。

五、安装ppt-master

1.拉取项目源码

推荐先使用完整源码方式，这样目录结构清晰，脚本和示例都在本地，便于排查问题。

git clone https://github.com/hugohe3/ppt-master.git
cd ppt-master

2.安装Python依赖

进入项目根目录后安装依赖：

pip install -r requirements.txt

如果系统中同时存在多个Python版本，可以使用：

python -m pip install -r requirements.txt

或在Linux/macOS中使用：

python3 -m pip install -r requirements.txt

安装完成后，建议不要急着让Agent生成正式PPT，可以先让它阅读项目说明，确认当前环境是否具备运行条件。

3.通过Skill方式安装

如果你使用的Agent支持安装Skill，也可以使用ppt-master提供的Skill方式。

官方文档中给出的通用安装方式类似如下：

npx skills add hugohe3/ppt-master

在Claude Code中，也可以通过插件市场方式安装：

/plugin marketplace add hugohe3/ppt-master
/plugin install ppt-master@ppt-master

不过要注意，Skill安装通常只是安装工作流文件，不一定等同于完整拉取项目源码。后处理和导出仍然依赖项目中的Python脚本，因此初次使用时仍建议先采用完整源码方式，等流程跑通后再考虑Skill方式。

六、准备生成材料

ppt-master支持多种输入材料，常见类型包括：

• PDF文档；
• DOCX文档；
• 网页链接；
• Markdown文件；
• 已有PPTX文件；
• 直接粘贴的一段文字或大纲。

为了让目录更清晰，建议在projects目录下为每次生成任务建立独立文件夹，例如：

ppt-master/
└── projects/
    └── ai-report-demo/
        └── sources/
            ├── report.pdf
            ├── outline.md
            └── images/

如果只是根据一份Markdown大纲生成PPT，可以新建：

projects/ai-report-demo/sources/outline.md

outline.md中可以写清楚主题、受众、页数和内容结构，例如：

# 企业内部知识库建设方案

## 目标受众

技术负责人、产品经理、运维负责人

## 期望页数

10页左右

## 内容重点

- 当前知识沉淀的问题
- 知识库系统的目标
- 整体架构
- 权限设计
- 检索与问答能力
- 落地计划
- 风险与成本

材料越清晰，Agent越容易规划出稳定的页面结构。不要只给一句“帮我生成一个关于某某主题的PPT”，除非你愿意让模型自行补全大量内容。

七、使用Claude Code生成PPT

1.进入ppt-master目录

cd /path/to/ppt-master
claude

在Windows PowerShell中示例：

cd D:\Code\ppt-master
claude

进入Claude Code后，建议先让它阅读项目规则：

请先阅读当前项目的 AGENTS.md 和 skills/ppt-master/SKILL.md，
理解 ppt-master 的完整工作流。
暂时不要生成PPT，先告诉我本项目生成PPT的大致步骤和需要我确认的信息。

这一步很重要。ppt-master不是普通代码库，它的核心流程写在SKILL.md中。如果Agent没有先读工作流，可能会误以为只需要随手写一个python-pptx脚本，最终生成质量会明显下降。

2.给出生成任务

确认Agent理解流程后，可以给出正式任务：

请基于 projects/ai-report-demo/sources/outline.md 生成一份 10 页左右的中文PPT。

要求：
1. 受众是企业技术负责人和产品经理；
2. 风格偏专业、简洁、适合内部汇报；
3. 输出比例为 16:9；
4. 每页保留适量演讲提示；
5. 最终导出为可编辑的 pptx 文件；
6. 在开始生成页面前，先向我确认页面结构、风格和页数。

这段提示词的重点不是告诉模型“马上生成”，而是要求它先确认结构。因为PPT生成的成本通常高于普通文本，先确认大纲可以避免后面大量返工。

3.确认页面方案

正常情况下，Agent会先给出类似下面的信息：

主题：企业内部知识库建设方案
比例：16:9
页数：10页
风格：专业、简洁、内部汇报
页面结构：
1. 封面
2. 背景与问题
3. 建设目标
4. 总体架构
5. 内容沉淀流程
6. 权限与治理
7. 检索与问答能力
8. 落地计划
9. 风险与成本
10. 总结

如果结构不合适，不要继续执行，可以直接让它调整：

把“风险与成本”提前到第7页，
并新增一页“试点范围与验收指标”，总页数保持10页。

确认无误后，再让它继续生成：

页面结构确认，可以继续按 ppt-master 工作流生成 SVG 页面并导出 pptx。

4.预览与修改

ppt-master支持在生成过程中通过本地预览检查页面效果。根据项目文档，预览服务通常会运行在：

http://localhost:5050

如果Agent启动了预览服务，可以在浏览器中打开该地址检查每一页。发现问题后，不建议只说“优化一下”，而是要指出具体页面和具体元素：

第3页左侧文字过密，请减少两条次要 bullet，
并把右侧架构图的层级关系改成从上到下。

或者：

第6页的配色太花，改成深蓝、白色、绿色强调色，
整体更像技术架构汇报。

越具体的反馈，越容易让Agent稳定修改。

5.导出PPTX

生成完成后，ppt-master通常会把文件输出到exports目录中。你可以让Agent明确告诉你导出路径：

请告诉我最终导出的 pptx 文件路径，
并确认是否完成了后处理和质量检查。

常见输出类似：

exports/ai-report-demo_20260521_102633.pptx

拿到文件后，用PowerPoint或WPS打开检查：

• 文字是否可以选中和编辑；
• 图形是否是可编辑元素；
• 页面比例是否正确；
• 字体是否缺失；
• 图片是否正常显示；
• 动画和切换是否符合预期；
• 是否存在文字溢出、遮挡或错位。

AI生成的PPT不建议直接用于正式汇报，至少要人工检查一遍。尤其是涉及数据、引用、金额、时间节点和结论判断的页面，必须自己核对。

八、使用Codex或其他CLI Agent

如果不用Claude Code，也可以用Codex CLI或其他Code CLI Agent执行类似流程。关键仍然是让Agent先读项目工作流，而不是直接凭经验生成脚本。

以Codex CLI为例：

cd /path/to/ppt-master
codex

进入交互后，可以输入：

请先阅读 AGENTS.md 和 skills/ppt-master/SKILL.md，
然后基于 projects/ai-report-demo/sources/outline.md 生成一份中文PPT。
在真正生成前，先确认页面结构、风格、页数、比例和输出文件名。

如果是Gemini CLI、Cline或Roo Code，提示词也可以保持类似：

你现在位于 ppt-master 项目根目录。
请严格按照项目内 AGENTS.md 和 skills/ppt-master/SKILL.md 的流程工作。
不要另写一个简化版PPT脚本。
请使用项目已有脚本完成资料导入、页面规划、SVG生成、后处理和PPTX导出。

这类提示的意义在于约束Agent使用项目内置能力，而不是自行发明流程。

九、常用提示词模板

1.从Markdown生成技术分享PPT

请基于 projects/java-cache-demo/sources/outline.md 生成一份中文技术分享PPT。

要求：
1. 主题是“Spring Boot缓存设计实践”；
2. 受众是后端开发工程师；
3. 页数控制在12页左右；
4. 风格专业、清晰、偏技术培训；
5. 需要包含架构图、流程图和关键代码摘要页；
6. 每页不要堆太多文字；
7. 最终导出为可编辑PPTX。

开始前请先给我确认页面目录。

2.从PDF报告生成汇报PPT

请基于 projects/q2-report/sources/report.pdf 生成一份中文汇报PPT。

要求：
1. 面向管理层；
2. 页数控制在8到10页；
3. 重点突出结论、趋势、风险和下一步计划；
4. 数据图表要尽量转成可读性强的页面；
5. 风格简洁、正式；
6. 导出为16:9可编辑PPTX。

请先提炼报告核心结论，再给出页面结构供我确认。

3.从网页文章生成演示文稿

请基于这个网页内容生成一份中文PPT：
https://example.com/article

要求：
1. 适合15分钟分享；
2. 总页数不超过10页；
3. 用通俗语言解释核心概念；
4. 保留关键术语；
5. 每页添加简短演讲提示；
6. 最终导出为可编辑PPTX。

如果需要先抓取网页内容，请使用 ppt-master 内置的 source_to_md 工具。

4.让Agent做生成后自检

请检查刚生成的PPT项目：
1. 是否所有页面都有对应SVG；
2. 是否完成了后处理；
3. 是否已经导出PPTX；
4. 是否存在明显文字溢出、空白页、图片缺失或脚本报错；
5. 请给出最终文件路径和需要人工复查的页面。

十、常见问题

1.Agent没有按ppt-master流程执行

如果发现Agent开始手写一个简单的python-pptx脚本，或者绕过项目目录直接生成文件，通常说明它没有读懂项目工作流。

可以中断并重新提示：

请停止当前简化实现。
重新阅读 skills/ppt-master/SKILL.md，并严格按照该文件定义的流程执行。
不要自行改写为普通 python-pptx 脚本。

2.生成到一半上下文不够

PPT生成属于长流程任务，页数越多、资料越长，对上下文要求越高。可以采用以下方式降低风险：

• 每次先生成8-12页，不要一上来要求几十页；
• 输入材料先整理成结构清晰的Markdown；
• 让Agent先确认大纲，再进入页面生成；
• 长报告可以先让Agent提炼摘要，再用摘要生成PPT；
• 如果中途断开，让Agent从项目目录和已有输出中恢复进度。

可以这样提示：

请根据当前 projects/ai-report-demo 目录中的已有文件恢复任务，
不要重新开始。先检查已经完成到哪一步，再继续后处理和导出。

3.图片质量不稳定

如果PPT中需要大量配图，建议配置可用的图片生成或图片搜索能力。ppt-master支持通过环境变量或.env文件配置相关服务。

如果暂时没有图片模型，也可以先要求生成纯图形、图标和结构图为主的版本：

本次不要依赖外部图片生成。
请优先使用形状、图标、流程图、结构图和文本排版完成页面。

这样虽然视觉冲击力弱一些，但稳定性更高，也更适合技术汇报。

4.导出的PPTX打开后字体不一致

这通常和本机字体环境有关。可以在生成前指定常见字体：

请使用 Windows 和 macOS 都较常见的中文字体方案，
中文优先使用微软雅黑或思源黑体风格，英文使用 Arial 或 Aptos。

如果要用于公司正式模板，最好提供已有PPTX模板，让Agent基于模板提取或复刻风格。

5.正式汇报前还需要人工编辑吗

需要。ppt-master能明显提高初稿效率，但最终交付前仍建议人工处理：

• 删除不必要的页面；
• 校对事实、数据和引用；
• 调整标题语气；
• 统一字体和间距；
• 检查图表含义；
• 替换公司模板和品牌元素；
• 根据演讲节奏调整动画。

把AI生成结果当作高质量初稿，而不是最终成品，会更加稳妥。

十一、实践建议

使用ppt-master时，建议形成一套固定工作习惯：

1. 先把原始材料整理为结构清晰的Markdown或文档；
2. 每次生成都新建独立项目目录；
3. 明确告诉Agent受众、页数、比例、风格和输出要求；
4. 开始生成前必须确认页面目录；
5. 中途预览时给出具体页码和具体修改意见；
6. 导出后人工检查可编辑性和事实准确性；
7. 对常用场景沉淀自己的提示词模板。

如果只是临时做一个简单演示，在线AI PPT工具可能更快；但如果你希望结果可控、可追踪、可复用，并且最终得到真正可编辑的pptx文件，那么Code CLI Agent + ppt-master会更适合开发者工作流。

十二、总结

ppt-master把PPT生成这件事拆成了一个适合AI Agent执行的工程化流程：资料转换、项目创建、页面规划、SVG生成、预览修改、质量检查和PPTX导出。Claude Code、Codex CLI、Gemini CLI这类工具则负责理解需求、调用脚本、修改文件和推进流程。

这类方案的价值不在于完全替代人工设计，而在于把最耗时的初稿阶段自动化。你只需要准备材料、确认结构、给出反馈，剩下的重复性操作交给Agent完成。最终拿到的不是一组截图，而是可以继续在PowerPoint中编辑的演示文稿，这也是它区别于很多一键式AI PPT工具的核心优势。