【免费下载链接】ppt-master
AI 把任意文档生成真正可编辑的 PowerPoint —— 原生形状与动画、演讲者备注可合成音频旁白、还能参考你自己的 .pptx 模板,而不是一张张图片 · 何雨果出品
导读:本文以 PPT Master 官方 快速入门 为主线,系统讲解从环境搭建到交付可编辑 .pptx 的完整闭环:三目录安装模型、模板复用(Create Template / Edit Native PPTX)、Default 与 Quick 两代生成流程、实时预览、OOXML 动画、旁白与复刻音色,以及常见故障排查。读完你既能在自己的 Agent 环境中跑通第一份 deck,也能理解每一步背后的工作流文件与脚本调用链,具备独立排错与深度定制的能力。
一、安装:先分清三个目录,再装依赖
启动 Agent 之前,PPT Master 要求你先建立清晰的"目录心智模型"。它把环境拆成三个职责完全不同的目录,混用是新手最常见的错误来源:
| 目录 | 它是什么 | 怎样产生 |
|---|---|---|
| Skill 安装目录 | 包含 SKILL.md、requirements.txt、工作流与脚本的 PPT Master 包 | 完整仓库 clone 或仓库 ZIP 中是 skills/ppt-master/;marketplace/plugin 安装或 skill-only release ZIP 则使用自己的安装或解压位置 |
| 工作目录 | 你在 Agent 中打开的、可持久保存且可写的目录 | 完整仓库 clone 或仓库 ZIP 通常使用仓库根目录;skill-only 安装则自行选择,不必是 skill 安装目录 |
| 活动项目 | 一次生成任务的来源、SVG、报告、备份与导出物所在目录 | Agent 会在 <工作目录>/projects/<生成的项目名>/ 下初始化,并报告精确路径 |
1.1 环境前置条件
所有安装方式都有两个硬性前提:
- Python 3.10+。官方快速开始仅此一条依赖即可起步,其余依赖一行
pip install -r requirements.txt解决。 - 一个已安装且已鉴权的 Agent host——它必须能读写工作目录、执行 shell 命令、维持多轮对话(Claude Code、VS Code Copilot、Codex 等皆可)。
1.2 两种安装路径的依赖安装命令
完整仓库 clone 或仓库 ZIP:从仓库根目录安装:
python3 -m pip install -r requirements.txt
Skill-only 安装:先定位同时包含 skill 的 SKILL.md 与 requirements.txt 的安装/解压目录,再从该路径安装:
python3 -m pip install -r "<installed-skill-dir>/requirements.txt"
使用 npx skills add hugohe3/ppt-master 还要求本机有可用的 npx 命令(通常由 Node.js/npm 提供,仓库未规定 Node/npm 最低版本);Agent host 自带的 /plugin install 则不走这条 npx 路径。
1.3 依赖清单背后的脚本分工
requirements.txt 中的可选依赖并非全部必装,大多数工具只依赖 Python 标准库。从 skills/ppt-master/requirements.txt 的注释可以精确对应到脚本:
- SVG 转 PPTX(
svg_to_pptx.py):python-pptx>=0.6.21、XlsxWriter>=3.0.0(原生图表)、skia-pathops>=0.9.2(Merge Shapes 合并形状物化)、uharfbuzz>=0.50.0(OpenType 排版与字形轮廓); - PDF 转 Markdown(
pdf_to_md.py):PyMuPDF>=1.23.0,注意其 AGPL-3.0 许可,不转换 PDF 源可跳过此行; - 文档转 Markdown(
doc_to_md.py):.docx → mammoth、.html → markdownify、.epub → ebooklib、.ipynb → nbconvert;.doc/.odt/.rtf/.tex/.rst/.org/.typ等小众格式才需要额外安装 pandoc; - Excel 转 Markdown(
excel_to_md.py):openpyxl>=3.1.0; - 图片处理:
Pillow>=9.0.0、numpy>=1.20.0; - 网页转 Markdown(
web_to_md.py):requests、beautifulsoup4;可选curl_cffi用于绕过微信等站点的 TLS 指纹屏蔽; - AI 生图(
image_gen.py):Gemini 后端需要google-genai; - 旁白(
notes_to_audio.py):edge-tts>=7.2.8; - SVG 实时编辑器(
svg_editor/server.py):flask>=3.0.0。
1.4 启动 Agent 的正确位置
安装完成后,从工作目录启动 Agent,而不是从 host 管理的 skill 缓存目录启动。执行入口会单独解析已安装的 skill。安装方式的选择见仓库根目录 README.md 的 Quick Start;运行时纪律则由 SKILL.md 定义——它是全局执行纪律与路由选择的唯一入口,加载顺序为:先读 SKILL.md,再运行 attribution_guard.py 完整性门禁,然后读取 routing.md,最后只加载被选中的一条顶层路由及其运行时权威文档。
二、用模板:两条路径,先分清楚你要什么
模板是可选的。 默认走自由设计(free design)——不需要模板,可以直接跳到下一节。只有 deck 必须复用品牌身份、沟通与设计方法、固定版式或重复使用的应用场景时,才需要模板。
2.1 复用现成 .pptx 的两条路
| 你想要… | 路径 | 会发生什么 |
|---|---|---|
| 用这份 deck 的原生页面壳承载新内容 | Edit Native PPTX | 导入 round-trip 工作区;未改页面逐字节恢复,page_plan.json 可选页、重排、重复或省略,且只编辑计划中的页面 |
| 先建立可复用设计系统,再生成新 deck | Create Template → Generate PPTX | 从参考材料创建经过验证的 Brand、Style、Layout 或 Deck 工作区,再创作一份新 deck;新故事、结构与页数都可以不同于来源 |
第一条路的用法:把 .pptx 连同素材(或一个主题)给 AI,说"填进这套模板",见 Edit Native PPTX 工作流。
第二条路(本节重点)必须显式请求 Create Template 路线。原生 .pptx 加新材料默认属于 Edit Native PPTX,并不是 Generate 可以直接消费的模板工作区。先创建工作区:
你:用 /create-template 从 projects/brand/our_deck.pptx 创建一个可复用 Deck 模板
2.2 四种模板 kind 与各自职责
Create Template 会分析参考材料,确认结果属于 Brand、Style、Layout 还是 Deck,再创作或物化一个经过验证的新工作区。四者的分工(见 模板指南):
| Kind | 复用什么 | 原生 PowerPoint 结果 |
|---|---|---|
| Brand | 色彩、字体、Logo、语态、图标风格 | 仅身份约束;生成页保持 Slide-local,归入一个干净的 Master + Blank Layout |
| Style | 沟通方法、开放页面角色词汇、证据/数据规则、视觉默认值、图像/图标方向 | 扁平 Slide-local 页面;Style 值作为最终 Stage 2 的种子,不变成品牌身份或可复用 Layout |
| Layout | 品牌无关的页面语法、Master/Layout 身份、语义文本角色、槽位、版式名册 | 带可复用原生 Masters、命名 Layouts 与占位符的结构化 deck |
| Deck | 重复出现的演示应用家族:应用上下文、身份、页面结构与实际原型 | 由 AI 依据模板与当前内容推导页面/原型应用方案 |
Theme、Slide Master、Slide Layout、Placeholder 是 PowerPoint 原生对象,不是额外的工作区 kind。Brand 和 Style 不含 SVG roster;Layout 与 Deck 拥有结构化 SVG 原型。
2.3 工作区落点:library 还是 project
在 create-template 简报中选择 library(沿用原默认)或 project。两种范围都要求 templates/,并使用可选的 images/、icons/ 和按需生成的 exports/;空的可选目录直接省略。项目范围要求给出已初始化的目标项目;只有全局库范围会执行注册。
复刻出的模板可以放在两个位置之一:
| 位置 | 路径 | 说明 |
|---|---|---|
| 注册进 skill 库 | skills/ppt-master/templates/<kind>/<id>/ | 可移植工作区并执行全局注册;问"有哪些模板"时会被列出来 |
| 放在 projects 下 | projects/<name>/ | 不执行全局注册的共享限定名 spec root;四种 kind 均可共存,结构由 Layout 优先于 Deck |
library 工作区拥有 templates/design_spec.md,共享 project root 则拥有 templates/design_spec.<kind>.<id>.md,以及该 kind 真正需要的原型和素材。如果需要 Layout 或 Deck 的 PowerPoint 评审文件,再显式运行可选预览导出;它会按需创建 exports/<id>_template_preview.pptx。生成时引用的是工作区根目录。
2.4 Default Generate 的模板选择机制
Default Generate 把模板选择放在 Stage 1,与沟通契约同屏确认;沟通推荐在此时不会读取任何模板。关键规则(与 routing.md §7 一致):
- 普通请求默认自由设计;用户明确要求模板或提供任意精确 root 时,默认进入模板模式,但界面始终允许切换;
- 未注册 root 进入"指定地址"下拉框;与注册 canonical root 完全相同的路径归回对应 kind 下拉框;
- 只提供一个 root 时可预选它;提供多个 root 时都只作为候选、不预选;
- 完整选择中每个 kind 最多一份;Layout 与 Deck 可以共存,结构由 Layout 提供;多 kind project root 必须原子选择;
- 一次确认同时闭合沟通与模板选择,随后才校验、安装所选 root;最终 Stage 2 才读取安装结果;
- 裸模板名(bare template name)永远不会被解析为工作区;"极简风 / McKinsey 风格"这类描述只是设计说明(style brief),不是模板查找令牌。
带模板生成的示例:
你:用 sources/report.pdf 做 deck,模板用 skills/ppt-master/templates/layouts/presentation_core/
完整说明见 模板指南。
三、做出第一份 deck:默认流程的三步闭环
环境与工作目录就绪后,整个默认流程就是三步:
第一步:给 Agent 可读取的源材料。 PDF、DOCX、Markdown、网址,或直接粘贴的文字都可以。放在 <工作目录>/inputs/ 之类的目录即可,不需要先手工创建最终的 projects/<name>/。底层由 source_to_md.py 的调度器把各类源统一转为标准 Markdown(-t <type> 仅在检测歧义时使用,-o 仅在需要指定输出位置时使用),支持的转换类型包括 pdf / doc / excel / pptx / web / markdown / text。
第二步:在对话里告诉 AI 要做什么。 Default Generate Step 2 或 Quick 初始化 会在工作目录的 projects/ 下创建活动项目并报告精确路径。存在文件型材料时才导入;直接粘贴的文字保留在对话上下文,不需要导入:
你:用 <报告文件路径.pdf> 做一份 PPT
你:把这份内容做成 PPT:<粘贴你的文字>
从源码看,初始化实际执行的是 project_manager.py 的 init 与 import-sources 两个子命令,同时创建 validation/workflow.log 冷审计日志:
python3 ${SKILL_DIR}/scripts/project_manager.py init <project_name>
python3 ${SKILL_DIR}/scripts/project_manager.py import-sources <project_path> <source_files_or_dirs...>
第三步:拿回可编辑的 .pptx。 除非显式指定其他输出路径,文件位于 <活动项目>/exports/<项目名>_<时间戳>.pptx。完整仓库 clone 或仓库 ZIP 通常对应 <仓库根目录>/projects/<生成的项目名>/exports/...;skill-only 安装则对应 <工作目录>/projects/<生成的项目名>/exports/...。以 Agent 报告的活动项目精确路径为准,不要到仓库根目录查找一个没有项目上下文的 exports/。
3.1 两个关键术语:Stage 与工作区根目录
这些术语不是需要你另建的目录:
- Stage 1:确认沟通契约——用途、受众、阅读场景、画布/格式——以及自由设计/模板选择;
- 工作区根目录(workspace root):可选的 Brand、Style、Layout 或 Deck 可复用包的根目录,不是活动项目;
- Stage 2:确认页数、视觉系统、模板应用方式与生产选项。之后内容分析、排版、配图、SVG 生成与导出都由 AI 完成。
从 generate-pptx.md 的管线定义看,Default 完整执行路径是:
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
其中 Stage 2 之后的生产步骤都有对应脚本:svg_quality_checker.py(质量门禁,要求 final 报告 0 错误)、total_md_split.py(演讲者备注按页拆分)、finalize_svg.py(自包含 SVG 预览)、svg_to_pptx.py(导出原生 PPTX,并回读候选包校验动画/时序)。
四、快速模式:跳过确认,但不缩水能力
默认流程会先进行 Stage 1 的沟通/模板合并确认,再进入最终 Stage 2。不想经过这些交互,就显式要求快速生成:
你:用 sources/report.pdf 快速生成一份 PPT,不用跟我确认
你:这份内容直接做成 PPT,跳过确认,8 页左右,深色商务风
你明确提的照做,你没提的 AI 直接定,不再回来问你。 第二个例子里"8 页左右、深色商务风"照样生效——快速模式省掉的是来回确认,不是你的话语权。Quick 不会真正生成 Default 的三套方向,而是直接执行 Default 会推荐的方向:自由设计时选整体适配度最高者,已安装模板时选最充分表达模板上下文的可行方向。什么都不提,才是全部交给 AI 决定。
4.1 模板能力在 Quick 中的保留方式
快速模式不会打开 Confirm UI 的模板选择页。每个 kind 最多给出一个精确的 Brand / Style / Layout / Deck 工作区 root,它会直接校验、安装并使用;没有给出精确 root,就直接自由设计。只写模板名或风格词仍然只是设计说明。
Quick 保持无锁流程,但不丢失模板能力:
- 自由设计及仅 Brand / Style 的输出保持 flat;
- 一旦提供 Layout / Deck 工作区,创作 SVG 中的显式 Master / Layout / slot 元数据会保留,并编译成可复用原生结构;
- P01 前,agent 会读取全部已安装模板 SVG,并在当前上下文冻结一段自然语言应用方案(Template Application 段落);不创建确认页或 spec 工件。
4.2 Quick 不跳过能力,也不产生持久规划
从 quick-generate.md 的 Profile Boundary 看:来源转换、事实缺口研究、共享美学规范、图片/图标准备,以及原生形状/图表/表格创作仍按需运行。显式选择的 manual 素材或不可替代的文件依赖缺失时,Quick 会阻塞并索取文件;自动 AI 生成或必需切片路径耗尽时,Quick 会移除失败任务与过期 manifest 条目,改用原生可编辑文字 / SVG 或已备好的非 AI 素材继续本次运行,并在最终交接中披露替代结果。
注意:快速模式是一次性生成,不是缩短后的可续接流程。它不产生 Strategist 记录、design_spec.md、spec_lock.md 或替代性的页面计划——内容、设计和资源决策只存在于 AI 的当前上下文。交付前一旦丢失该上下文,就重新运行 Quick。完整说明见 快速模式 profile。
五、实时预览与可视化修改
生成过程中会自动打开启动器报告的浏览器预览地址。按入门文档的说明,它优先使用 http://localhost:5050,若 5050 已被占用则使用下一个空闲端口。
端口精确定位:仓库源码中 confirm_ui/server.py 的
DEFAULT_PORT = 5050(Stage 1/2 确认页默认绑定127.0.0.1:5050);而 SVG 编辑器的实时预览服务默认从6060起扫描第一个空闲端口(见 svg_editor.md)。无论哪种服务,都以启动器输出或<项目路径>/live_preview/lock.json中的实际 URL 为准,不要臆测端口。
预览编辑器提供两种交互模式:
- 直接改,无需 AI:选中元素后在右栏改文字、颜色、字体、字号;拖拽即可移动,或用方向键微调(
Shift= 10px),Ctrl+Z撤销。改动即时预览,点 Apply changes 写回svg_output/; - 写注解交给 AI:点选元素写一句要改成什么,点 Add annotation 暂存,再点 Apply changes 把注解标记写入
svg_output/;回到对话说"应用注解"(apply my annotations),AI 会改写那块区域并重新导出 PPTX。
从 svg_editor.md 的实现细节看:每个元素在运行时会获得临时 _edit_N id,只有被注解的元素在保存后保留 id;预览时服务端会内联 <use data-icon> 占位符并托管 images/*,磁盘上的 SVG 不被预览过程改动。重新导出始终是对话驱动的——应用修改只更新 svg_output/,刷新 PPTX(finalize_svg.py + svg_to_pptx.py)是对话步骤,编辑器本身绝不运行导出管线。注解应用阶段由 live-preview.md 定义:先用 check_annotations.py 列出待办注解,逐条修改后移除 data-edit-target / data-edit-annotation 标记,并追加 annotation_applied 记录到 live_preview/annotations.jsonl,再重跑 Step 7.2/7.3 导出。
PPT Master 最初是纯对话设计;可视化编辑是在很多用户提出后融入的(建立在社区贡献的 PR #85 之上)。完整说明见 实时预览阶段。
六、转场与动画:真实的 OOXML,不是视频
导出的 deck 用真正的 OOXML 保存页间转场和可选的页内元素对象动画,不是嵌入视频。默认行为:
| 层级 | 默认值 | 含义 |
|---|---|---|
| 页间转场 | fade,0.4 秒 | 克制的视觉过渡 |
| 页内对象动画 | none(关) | 每页整体呈现;仅在动效有助于表达时开启 |
6.1 动画预设体系与兼容输入
对象动画默认不启用;只有显式使用 -a auto、203 个原生 entrance_* / emphasis_* / path_* / exit_* 预设之一,或 animations.json 侧车文件,才会启用。从 animations.md 可知这 203 个键的构成:53 个 entrance(进入)、33 个 emphasis(强调)、64 个 motion path(路径)、53 个 exit(退出)预设。29 个旧短名称只保留为兼容输入;新的动画选择统一使用带前缀的规范名称。auto / mixed / random 只从进入效果中选择;强调、路径、退出行为必须使用显式规范键。
页间转场则有 48 个规范键,覆盖当前 PowerPoint 画廊的三个分组:
- Subtle(细微):
morph、fade、push、wipe、split、reveal、cut、random_bars、shape、uncover、cover、flash; - Exciting(醒目):
fall_over、drape、curtains、wind、prestige、fracture、crush、peel_off、page_curl、airplane、origami、dissolve、checkerboard、blinds、clock、ripple、honeycomb、glitter、vortex、shred、switch、flip、gallery、cube、doors、box、comb、zoom、random; - Dynamic Content(动态内容):
pan、ferris_wheel、conveyor、rotate、window、orbit、fly_through。
旧名 strips、circle、diamond、newsflash、plus、pull、wedge、wheel 仅作兼容输入,会被解糖为原生效果加 Effect Options(例如 diamond → shape + shape: diamond)。
6.2 常用命令行配方
改变动画设置不需要重新生成页面。复用同一个 svg_output/ 即可(默认发布导出仍要求当前匹配的 final SVG 质量报告通过):
| 目标 | 命令 |
|---|---|
| 保持默认 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project> |
| 改变页间转场 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push |
| 移除视觉转场 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t none |
| 每 5 秒自动推进 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --auto-advance 5 |
| 开启自动元素呈现 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto |
| 全 deck 使用一种进入效果 | 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 |
6.3 Start 模式与逐对象定制
三种 Start 模式:on-click(一次点击出现一组,适合现场控场)、with-previous(与页面一起出现,适合统一入场)、after-previous(默认,无点击顺序出现,适合 kiosk 与旁白 deck)。注意 --recorded-narration 不支持 on-click。
只靠 deck 级设置不够时(例如一个对象先进入、再移动、再强调、最后退场),使用 animations.json 侧车。它瞄准稳定的顶层 <g id="..."> 内容组——组 ID 是 PowerPoint 形状目标锚点,不是动画窗格行。一个组可以挂多行 effects[] 生成多条顺序行:
{
"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 }
]
}
}
}
}
}
配套工具链:animation_config.py list-groups 列出真实组、animation_config.py validate 校验侧车、pptx_animations.py --describe <effect> 查看某效果接受的选项、pptx_animations.py --list 查看完整分类清单。
6.4 严格校验与兼容边界
动画设置是严格模式:未知效果、未知 Start 模式、非法时序值、缺失对象引用都会直接阻断导出,而不是悄悄变成别的效果。候选 PPTX 还会在发布前被回读,检查 timing 放置、ID、形状目标、效果、时长与 Start 模式。Microsoft PowerPoint 是动效行为的主要验证目标;Keynote、WPS、LibreOffice 可以打开 .pptx,但可能重新映射或省略个别效果或 Start 语义——动效关键交付应在 PowerPoint 中验证。完整说明见 转场与动画。
七、旁白与视频:备注 → 语音 → 嵌入 → MP4
把演讲者备注按页生成语音旁白,把音频嵌回 PPTX,再用 PowerPoint 导出带旁白和转场的 MP4——无需第三方工具:
你:给这个 PPT 生成音频,并把音频嵌回重新导出
你:给这个 PPT 生成音频
旁白默认用 edge-tts(约 90 种语区,覆盖全部主要中文变体 zh-CN / zh-TW / zh-HK 粤语,以及英语、日语、韩语、法语、德语等);需要更高质量音色可配置云端 provider(ElevenLabs / MiniMax / Qwen / CosyVoice)。AI 会按 deck 语言推荐音色,生成前只问你一次。
7.1 工作产物与嵌入路径
一次完整旁白生成会在 <project_path>/audio/ 下产出:每页一个与 SVG 同名的音频文件(01_cover.mp3…)、带 provider 时间戳时的逐页 SRT(01_cover.srt…,页内时间轴以 00:00:00,000 为零点)、以及一个紧凑的 manifest.json(仅记录 provider/model、音频/字幕格式、相关音色设置与 SHA-256 指纹,不含逐页清单与 API key)。原演讲者备注保持不变。
两条嵌入路径由 svg_to_pptx.py 的参数区分:
| 命令 | 用途 |
|---|---|
--recorded-narration audio | 写入 PowerPoint 录制计时与旁白,要求每页音频完整,用于旁白/视频导出,重导出为 exports/<name>_<timestamp>_narrated.pptx |
--narration-audio-dir audio | 底层音频嵌入,允许部分覆盖,适合测试或手动收尾 |
--narration-start-floor 0.8 | 可选:从目标页转场开始到旁白的最小秒数(默认 0.8;0 表示转场一结束立即开始) |
--narration-padding 0.5 | 可选:旁白结束后、页面前进前的静默保持(默认 0.5) |
7.2 手动调用脚本(进阶)
跳过 AI 流程、直接调用脚本的完整链路(详见 音频旁白与视频导出):
# 1. 确保备注已按页拆分(后处理 Step 7.1)
python3 skills/ppt-master/scripts/total_md_split.py <project_path>
# 2A. edge-tts 生成 MP3/SRT(默认,无需 API key)
python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
--voice zh-CN-YunjianNeural --rate +0%
# 2B. 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
# 2C. MiniMax(支持系统音色与复刻 voice_id;海外需设 MINIMAX_TTS_BASE_URL)
export MINIMAX_API_KEY="your-minimax-api-key"
python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
--provider minimax --voice-id <minimax-voice-id> \
--minimax-model speech-2.8-hd
# 2D. Qwen TTS(仅音频,当前 API 不返回时间戳)
export DASHSCOPE_API_KEY="your-dashscope-api-key"
python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
--provider qwen --voice-id <qwen-voice> \
--qwen-model qwen3-tts-flash --qwen-language-type Chinese
# 2E. 支持时间戳的 CosyVoice 音色
export COSYVOICE_API_KEY="your-dashscope-api-key"
python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
--provider cosyvoice --voice-id <cosyvoice-voice> \
--cosyvoice-model cosyvoice-v3-flash
# 3. 导出带嵌入音频的旁白版 PPTX
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 \
--inherit-motion-from "<base_postflight_report>"
发送 TTS 请求前,notes_to_audio.py 会校验每一页都有可读、非空的逐页备注;缺失或为空返回退出码 2,需先补备注再重跑。edge 默认最多 3 路并发生成,可用 --concurrency <N> 调节。列出某语区可用音色:
python3 skills/ppt-master/scripts/notes_to_audio.py --list-voices --locale ja-JP
7.3 导出为视频
一旦旁白版 PPTX 位于 exports/,Windows PowerPoint 2016+ 可自动导出 MP4:
python3 skills/ppt-master/scripts/powerpoint_video.py \
<final_narrated_pptx> -o <raw_powerpoint_video.mp4>
该命令使用录制计时与旁白,默认 1080p/30fps,仅在 PowerPoint 报告成功或失败后才返回。嵌入 PPTX 的音频必须是 PowerPoint 可靠格式:m4a(AAC)、mp3 或 wav;内置生成默认 mp3。自动 MP4 导出不新增 Python 包,但要求 Windows PowerPoint 2016+ 与 Windows PowerShell。依赖方面,edge-tts 已列入 skills/ppt-master/requirements.txt(生成时需联网调用微软在线 TTS;生成的 MP3 是本地文件,之后播放与导出不再依赖网络)。
八、使用复刻音色:把 deck 变成"你的声音"
用 ElevenLabs / MiniMax / Qwen / CosyVoice 复刻你自己的声音(或在授权前提下复刻演讲者的声音),让整份 deck 用你的声音念出来。
职责划分是关键:声音复刻本身发生在 provider 的控制台或 API——你上传一段样本(典型 10 秒到几分钟的干净音频),provider 返回一个 voice_id;PPT Master 处于消费侧,它拿这个 voice_id 逐页朗读备注并嵌回 PPTX,永远不会把你的样本上传到任何地方。
| Provider | 在哪里复刻 | 样本时长 |
|---|---|---|
| ElevenLabs | 其控制台 → Voices → Add Voice(Instant / Professional Voice Cloning) | 约 1 分钟(Instant)/ 30 分钟以上(Professional) |
| MiniMax | 其平台控制台 → Voice Clone | 约 10 秒 – 5 分钟 |
| Qwen TTS | DashScope 控制台 → 语音合成 → 声音复刻 | 约 10 秒 – 5 分钟 |
| CosyVoice | DashScope 控制台 → 语音合成 → 声音复刻 | 约 10 秒 – 5 分钟 |
复刻之后在对话里直接说即可,AI 会跳过音色推荐步骤直接使用你的 voice_id:
你:用我复刻的 MiniMax 音色生成旁白,voice_id 是 xxxxxxx
你:用我的 ElevenLabs 复刻音色 abc123 生成旁白
或直接调脚本:
python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
--provider minimax --voice-id <your-cloned-voice-id> \
--minimax-model speech-2.8-hd
几点须知:
- 授权——只复刻你拥有或有明确许可的声音,各 provider 条款均禁止冒名;
- 语言覆盖——复刻音色继承说话人的口音;多语 deck(如中文夹杂英文术语)建议选能较好处理语言混合的模型(ElevenLabs
eleven_multilingual_v2与 CosyVoice 通常最宽容); - 字幕能力——复刻的 ElevenLabs 与受支持的 CosyVoice 音色可产生带 provider 时间戳的 SRT;Qwen 复刻音色在当前 API 下仅音频;
- 有效期——复用
voice_id期间该音色须在你的 provider 账户中保持可用,保留/删除/过期策略由 provider 决定。
完整说明见 使用复刻音色。
九、遇到问题怎么办:先查 FAQ,再回读权威文档
常见问题(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 撑爆上下文 | 生成可走分段模式(generation_mode: split),规划会话结束后在新对话输入 继续生成 projects/<project_name> 进入执行会话;详见 FAQ |
9.1 排查机制背后的设计逻辑
"重新读 SKILL.md 和 routing.md"并非敷衍——PPT Master 的运行时纪律就是单一权威:路由只允许选择恰好一条顶层路线(Generate PPTX / Create Template / Edit Native PPTX),选择后只读取该路线的运行时权威文档,加载路线之间互斥、从不竞争(见 routing.md)。因此当 Agent 偏离时,让它回到权威入口重新对齐,是最高效的修复方式。
模型选择、费用、图表可编辑性、自定义模板等更多话题,都收录在 FAQ 中;动画精确效果映射、侧车完整 schema 与包校验规则见 动画执行参考。
十、结语:从三目录模型到交付闭环
回顾这条完整链路:三个目录各司其职(安装目录、工作目录、活动项目)→ 依赖一行安装(视安装方式选择仓库根目录或 skill 安装目录)→ 源材料三步走(喂给 Agent → Stage 1 确认沟通契约与模板 → Stage 2 确认方案与生产选项)→ 导出可编辑 .pptx(exports/<项目名>_<时间戳>.pptx)→ 视需要叠加实时预览微调、OOXML 动画、旁白与复刻音色。默认流程为首次体验者提供了完整的确认护栏;快速模式为熟练用户提供了不缩水能力的一次性通道;而模板系统用 Brand / Style / Layout / Deck 四种工作区把"可复用的设计资产"与"一次性的源文件"彻底分离。出现任何偏差,回读 SKILL.md、routing.md 与 FAQ 即可恢复方向。
【免费下载链接】ppt-master
AI 把任意文档生成真正可编辑的 PowerPoint —— 原生形状与动画、演讲者备注可合成音频旁白、还能参考你自己的 .pptx 模板,而不是一张张图片 · 何雨果出品
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考



