README_CN.md - ppt-master

README_CN.md

1	# PPT Master — AI 生成原生 PowerPoint，支持任意文档输入
2
3	[![Version](https://img.shields.io/github/v/release/hugohe3/ppt-master?label=version&color=blue)](https://github.com/hugohe3/ppt-master/releases)
4	[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5	[![GitHub stars](https://img.shields.io/github/stars/hugohe3/ppt-master.svg)](https://github.com/hugohe3/ppt-master/stargazers)
6	[![AtomGit stars](https://atomgit.com/hugohe3/ppt-master/star/badge.svg)](https://atomgit.com/hugohe3/ppt-master)
7	[![The Agentic Leaderboard](https://www.theagenticleaderboard.com/badges/ppt-master.svg)](https://www.theagenticleaderboard.com/agent/?q=ppt-master)
8
9	<p align="center">
10	<a href="https://trendshift.io/repositories/25760?utm_source=repository-badge&utm_medium=badge&utm_campaign=badge-repository-25760" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/25760" alt="hugohe3%2Fppt-master \| Trendshift" width="250" height="55"/></a>
11	</p>
12
13	[English](./README.md) \| 中文
14
15	<details open>
16	<summary>本项目由 <a href="https://www.kimi.com/code/?aff=ppt-master">Kimi</a>、<a href="https://www.packyapi.ai/register?aff=ppt-master">PackyCode</a>、<a href="https://apikey.fun/register?aff=PPT-MASTER">APIKEY.FUN</a>、<a href="https://runapi.co/register?aff=WMLJ">RunAPI</a>、<a href="https://www.compshare.cn/coding-plan?ytag=GPU_YY-git_pptmaster0624">优云智算</a> 等赞助方支持，得以持续免费开源。</summary>
17
18	<p align="center">
19	<a href="https://www.kimi.com/code/?aff=ppt-master"><img src="https://gcdn.moonshot.cn/growth-cdn/sponsor/kimi-zh.png" alt="Kimi" width="100%"></a>
20	</p>
21
22	感谢 [Kimi](https://www.kimi.com/code/?aff=ppt-master) 赞助本项目！[Kimi K3](https://platform.kimi.com/docs/guide/kimi-k3-quickstart) 是全球首个开源 3T 级模型，拥有原生视觉能力与 100 万 Token 上下文。搭配 PPT Master，K3 可以理解 PDF、DOCX、网页等原始资料，提炼重点、规划演示逻辑，并生成可在 PowerPoint 中继续修改的原生可编辑 PPTX。
23
24	立即体验 [Kimi Code](https://www.kimi.com/code/?aff=ppt-master)，或通过 Kimi 开放平台（[中文站](https://platform.kimi.com?aff=ppt-master)｜[Global](https://platform.kimi.ai?aff=ppt-master)）使用 API。
25
26	<hr>
27
28	<table>
29	<tr>
30	<td width="180"><a href="https://www.packyapi.ai/register?aff=ppt-master"><img src="docs/assets/sponsors/packycode.png" alt="PackyCode" width="150"></a></td>
31	<td>感谢 PackyCode 赞助了本项目！PackyCode 是一家稳定、高效的 API 中转服务商，提供 Claude Code、Codex、Gemini 等多种中转服务。PackyCode 为本项目的用户提供了特别优惠，使用<a href="https://www.packyapi.ai/register?aff=ppt-master">此链接</a>注册并在充值时填写"ppt-master"优惠码，可以享受 9 折优惠。</td>
32	</tr>
33	<tr>
34	<td width="180"><a href="https://apikey.fun/register?aff=PPT-MASTER"><img src="docs/assets/sponsors/apikey-fun.png" alt="APIKEY.FUN" width="150"></a></td>
35	<td>感谢 APIKEY.FUN 赞助了本项目！APIKEY.FUN 是一家专业的企业级 AI 中转站，致力于为企业和开发者提供稳定、高效、低成本的 AI 中转服务。平台支持 Claude、OpenAI、Gemini 等主流热门模型，价格低至官方原价的 <strong>7%</strong>。通过<a href="https://apikey.fun/register?aff=PPT-MASTER">本项目专属链接</a>注册，还可享受最高 <strong>永久充值 95 折</strong> 专属优惠。</td>
36	</tr>
37	<tr>
38	<td width="180"><a href="https://runapi.co/register?aff=WMLJ"><img src="docs/assets/sponsors/runapi.png" alt="RunAPI" width="150"></a></td>
39	<td>感谢 RunAPI 赞助了本项目！RunAPI 是一个高效稳定的 API 平台，一个 API Key 即可访问 OpenAI、Claude、Gemini、DeepSeek、Grok 等 150+ 主流模型，价格低至官方原价的 <strong>1 折</strong>，极其稳定，可无缝兼容 Claude Code 等工具。RunAPI 为 PPT Master 用户提供专属福利：通过<a href="https://runapi.co/register?aff=WMLJ">本项目专属链接</a>注册并联系管理员，即可领取 <strong>￥7 的免费额度</strong>。</td>
40	</tr>
41	<tr>
42	<td width="180"><a href="https://www.compshare.cn/coding-plan?ytag=GPU_YY-git_pptmaster0624"><img src="docs/assets/sponsors/youyun.png" alt="优云智算" width="150"></a></td>
43	<td>感谢优云智算赞助了本项目！优云智算是 UCloud 旗下 AI 云平台，一站式提供国内外主流模型的 API 服务，一个 Key 即可调用所有模型。主打高性价比国产模型 CodingPlan 套餐（GLM5.2、Deepseek-v4 等），同时提供官方转发的稳定海外模型通道，满足多场景开发需求。已兼容 Claude Code、Codex 等主流 AI 编程工具及通用 API 调用，支持企业级高并发、7×24 技术支持和自助开票。通过<a href="https://www.compshare.cn/coding-plan?ytag=GPU_YY-git_pptmaster0624">此链接</a>注册，最高可获得 <strong>¥10 免费体验金</strong>。该项目已制作成 Agent【PPT 制作大师】，无需本地部署即可使用。</td>
44	</tr>
45	</table>
46
47	</details>
48
49	> 可编辑早已是及格线——真正拉开差距的是原生深度。 PPT Master 交给你的是一份真正的 PowerPoint：母版、原生形状、数据驱动的图表与表格，而不是一堆扁平文本框，也不是套模板填空的结果。它还不止把幻灯片排得好看——先替你把逻辑理顺，再谈视觉；而这份原生深度在持续向 PowerPoint 本身靠拢，逐版本补齐更多原生能力。形态上，它是一套在有 Agent 能力的 AI 工具里运行的工作流：把你的主题或材料交给 AI，就在你本机生成，数据不出本地，不锁定任何平台和模型。工作原理与能力边界 → [产品定位](#产品定位)。
50
51	<p align="center">
52	<a href="https://hugohe3.github.io/ppt-master/"><strong>在线预览</strong></a> ·
53	<a href="./examples/"><strong>示例下载</strong></a> ·
54	<a href="./docs/zh/faq.md"><strong>常见问题</strong></a> ·
55	<a href="./docs/zh/roadmap.md"><strong>路线图</strong></a>
56	</p>
57
58	<h3 align="center">下载这份<a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_attention_is_all_you_need/exports/attention_is_all_you_need_narrated.pptx">带音频旁白的 <em>Attention Is All You Need</em> 论文精读 deck</a>，在 PowerPoint 里直接放映，每一页都会自己"读"给你听 —— 这只是 PPT Master 能力的冰山一角。</h3>
59
60	<table>
61	<tr>
62	<td align="center" width="33%">
63	<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_pritzker_2026"><img src="docs/assets/screenshots/preview_pritzker_2026.png" alt="杂志风 — 普利兹克奖 2026" /></a><br/>
64	<sub><b>杂志风</b> — 建筑摄影 + 排版网格，冷静克制的编辑感<br/>
65	<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_pritzker_2026">在线翻页</a> · <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_pritzker_2026/exports/pritzker_2026.pptx">下载 .pptx</a></sub>
66	</td>
67	<td align="center" width="33%">
68	<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_global_ai_capital_2026"><img src="docs/assets/screenshots/preview_global_ai_capital.png" alt="新闻风 — 2026 全球 AI 资本格局" /></a><br/>
69	<sub><b>新闻 / 财经数据风</b> — 深色仪表盘，图表驱动，彭博风<br/>
70	<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_global_ai_capital_2026">在线翻页</a> · <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_global_ai_capital_2026/exports/global_ai_capital_2026.pptx">下载 .pptx</a></sub>
71	</td>
72	<td align="center" width="33%">
73	<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_swiss_grid_systems"><img src="docs/assets/screenshots/preview_swiss_grid.png" alt="瑞士风 — 网格系统入门" /></a><br/>
74	<sub><b>瑞士风</b> — 严格栅格，克制字体，红色点缀<br/>
75	<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_swiss_grid_systems">在线翻页</a> · <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_swiss_grid_systems/exports/swiss_grid_systems.pptx">下载 .pptx</a></sub>
76	</td>
77	</tr>
78	<tr>
79	<td align="center" width="33%">
80	<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_glassmorphism_demo"><img src="docs/assets/screenshots/preview_glassmorphism_demo.png" alt="毛玻璃风 — AI Agent 工程化 Demo" /></a><br/>
81	<sub><b>毛玻璃 SaaS</b> — 半透明叠层，渐变景深，产品 UI 感<br/>
82	<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_glassmorphism_demo">在线翻页</a> · <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_glassmorphism_demo/exports/glassmorphism_demo.pptx">下载 .pptx</a></sub>
83	</td>
84	<td align="center" width="33%">
85	<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_sugar_rush_memphis"><img src="docs/assets/screenshots/preview_sugar_rush_memphis.png" alt="孟菲斯风 — Sugar Rush 音乐节" /></a><br/>
86	<sub><b>孟菲斯波普</b> — 高饱和原色，几何图形，俏皮活力<br/>
87	<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_sugar_rush_memphis">在线翻页</a> · <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_sugar_rush_memphis/exports/sugar_rush_memphis.pptx">下载 .pptx</a></sub>
88	</td>
89	<td align="center" width="33%">
90	<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_indie_bookstore_zine_guide"><img src="docs/assets/screenshots/preview_indie_bookstore_zine.png" alt="Zine 风 — 独立书店指南" /></a><br/>
91	<sub><b>Risograph Zine</b> — 双色印刷质感，手作书店文化<br/>
92	<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_indie_bookstore_zine_guide">在线翻页</a> · <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_indie_bookstore_zine_guide/exports/indie_bookstore_zine_guide.pptx">下载 .pptx</a></sub>
93	</td>
94	</tr>
95	</table>
96
97	<p align="center">
98	<sub>以上示例均为一次性生成、未经精修（生成模型：Claude Opus 4.7 + <code>gpt-image-2</code>）。下载任意一份 .pptx 在 PowerPoint 里打开，是感受真实产出水平最快的方式。<br/><a href="https://hugohe3.github.io/ppt-master/">在线翻看全部示例 →</a> · <a href="./examples/"><code>examples/</code> 目录</a> · <a href="./docs/zh/why-ppt-master.md">为什么选 PPT Master？</a></sub>
99	</p>
100
101	<p align="center">
102	更多端到端实例：<a href="https://space.bilibili.com/111258938/lists/8144072"><strong>合集·PPT-Master 能力展示</strong></a>（B 站）
103	</p>
104
105	---
106
107	丢进原材料，拿回的不是一张能改的静态版面，而是一份带完整 PowerPoint 行为的成品：原生页间转场、可按需开启的入场动画（默认关闭）、演讲者备注一键合成音频旁白乃至视频、图表和表格可作为带数据的原生对象导出，也能沿用你自己的 PPT 模板来设计——直接拿去讲，回头还能接着改。每项能力怎么用 → [快速入门](./docs/zh/getting-started.md)。
108
109	## 产品定位
110
111	可编辑如今只是及格线——真正要紧的是你能拿到多少 PowerPoint。 PPT Master 交付的是 PowerPoint 的原生对象模型本身，而且有深度：带调节手柄的原生形状与连接符、按需的数据驱动图表与表格、完整的文本 / 图片 / 填充 / 效果，点开任意元素都作为原生 PowerPoint 对象继续编辑；走模板 / 结构化路线时，它还能为你产出带真正母版与版式（`p:sldMaster` / `p:sldLayout` 继承）的 deck。
112
113	而且这份深度是一个前进方向，不是一张固定清单。 PPT Master 的北极星是持续向 PowerPoint 本身靠拢：不断开发、集成更多 PowerPoint 原生能力，一个版本接一个版本，缩小「AI 能替你生成的」和「你在 PowerPoint 里手工能做出的」之间的差距。[PowerPoint ↔ SVG 映射指南](./docs/zh/powerpoint-svg-mapping.md) 逐条、诚实地记录了这份能力今天覆盖到哪——SmartArt 是刻意的排除，不是缺口。
114
115	形态上，它是一套在有 Agent 能力的 AI 工具里运行的工作流（一个 "skill"）：你在对话框里说"用这份 PDF 做一份 PPT"，它就按流程在你本机生成、导出原生可编辑的 `.pptx`。你不写任何代码，只做三件事——装 Python、装一个 AI 工具、把材料放进来。
116
117	从源材料生成新 deck 是主管线，但不是唯一路线：PPT Master 还能从你的参考资料中提炼可复用的品牌 / 风格 / 版式 / 成品模板，把新内容填进你已有的 `.pptx` 并保留其设计，或为成品 deck 追加原生转场、动画和旁白——每条路线都有明确的保留契约。
118
119	在这份原生深度之上，这个形态还带来三个承诺：
120
121	- 成本透明可控 — 工具免费开源，唯一成本是你自己的 AI 模型用量，不在此之外增加任何订阅费用
122	- 数据不出本地 — 除与 AI 模型的对话外，全流程在你的电脑上完成
123	- 不锁定平台 — 任何具备 agent 能力的 AI IDE 均可驱动；Claude、GPT、Gemini、Kimi 等模型均可使用
124
125	为什么选它、以及它不适合的场景 → [为什么选 PPT Master](./docs/zh/why-ppt-master.md)；这些承诺背后的长期能力边界 → [项目定位与能力边界](./docs/zh/project-positioning.md)。
126
127	> [!IMPORTANT]
128	> ### 这是一个工具，不是一个许愿池
129	> `harness + model = agent`——PPT Master 只负责工作流，产出上限由模型决定。推荐 Kimi K3（或 Claude）大上下文窗口（~100 万 token）+ AI 生图（`gpt-image-2` 或 Google `gemini-3.1-flash-image`）；其他模型能跑通流程，但有质量差距。
130	>
131	> 也别指望一把就拿到完美成品。它的价值是帮你把大部分枯燥的活儿干掉，剩下的打磨交给你——做原生可编辑的 PPT，本就是为了让你接着改，而不是甩给你一张改不动的图。模型越便宜，要补的人工就越多；效果不理想，先升级模型，再对照[快速入门](./docs/zh/getting-started.md)和示例工程检查用法。
132
133	---
134
135	## 关于作者
136
137	我是何雨果（Hugo He），投融资领域从业者（注册会计师 · 资产评估师 · 咨询工程师（投资）），工作中经常审阅和修改 PPT。我希望 AI 生成的幻灯片仍然能在 PowerPoint 里继续编辑，而不是被压成一张张图片——所以做了这个。
138
139	未来，使用 Python 和 AI agent 的能力会越来越重要，这个项目也想展示：仅凭这两样，你能走多远。零基础上手有一段学习曲线，但走完这段，你就接上了未来——做 PPT 只是个借口，我真正想推广的是 Python 和 agent。
140
141	---
142
143	## 你可能也感兴趣
144
145	### <a href="https://github.com/microsoft/ResearchStudio">ResearchStudio-<img src="https://raw.githubusercontent.com/ai-nuts/Storage/main/ResearchStudio/ResearchStudio-Reel/docs/figures/reel-wordmark.png" alt="Reel" height="16"></a>
146
147	> 微软开源项目，我最近也参与其中——从论文到演讲视频、海报与博客，自动化科研传播的最后一公里。
148	>
149	> 📦 仓库：[microsoft/ResearchStudio](https://github.com/microsoft/ResearchStudio) · 📄 论文：[arXiv:2607.04438](https://arxiv.org/abs/2607.04438)
150
151	<table align="center">
152	<tr>
153	<td align="center" valign="middle" width="53%">
154	<a href="https://aka.ms/ResearchStudio">
155	<img src="https://raw.githubusercontent.com/ai-nuts/Storage/main/ResearchStudio/ResearchStudio-Reel/docs/figures/reel_demo.gif" width="100%"
156	alt="ResearchStudio-Reel 演示" />
157	</a>
158	</td>
159	<td align="center" valign="middle" width="47%">
160	<a href="https://aka.ms/ResearchStudio">
161	<img src="https://raw.githubusercontent.com/ai-nuts/Storage/main/ResearchStudio/ResearchStudio-Reel/docs/examples/latent_diffusion_landscape/poster.png" width="100%" alt="ResearchStudio-Reel 生成的海报" />
162	</a>
163	</td>
164	</tr>
165	</table>
166
167	<details>
168	<summary><strong>BibTeX</strong> —— 如果你在研究中使用了 ResearchStudio-Reel</summary>
169
170	```bibtex
171	@article{xiao2026researchstudioreel,
172	title = {ResearchStudio-Reel: Automate the Last Mile of Research from Paper to Poster, Video, and Blog},
173	author = {Lingao Xiao and Yalun Dai and Yangyu Huang and Qihao Zhao and Wenshan Wu and Hugo He and Ruishuo Chen and Jin Jiang and Qianli Ma and Jiahuan Zhang and Xin Zhang and Ying Xin and Yang Ou and Yan Xia and Scarlett Li and Longbo Huang and Zhipeng Zhang and Yang He and Yap Kim Hui and Yan Lu},
174	journal = {arXiv preprint arXiv:2607.04438},
175	year = {2026},
176	url = {https://arxiv.org/abs/2607.04438}
177	}
178	```
179
180	</details>
181
182	---
183
184	## 快速开始
185
186	### 1. 前置条件
187
188	只需安装 [Python](https://www.python.org/downloads/) 3.10+。其余依赖在第 3 步下载好项目后，用一行 `pip install -r requirements.txt` 装齐。
189
190	<details>
191	<summary><strong>Windows</strong> — 请看专门的<a href="./docs/zh/windows-installation.md">手把手安装指南</a> ⚠️</summary>
192
193	Windows 需要一些额外步骤（PATH 设置、执行策略等）。我们为 Windows 用户写了一份手把手安装指南：
194
195	📖 [Windows 安装指南](./docs/zh/windows-installation.md) — 从零到跑通第一份 PPT，10 分钟搞定。
196
197	简要流程：从 [python.org](https://www.python.org/downloads/) 下载 Python → 安装时勾选 "Add to PATH" → 完成，依赖安装见第 3 步。
198	</details>
199
200	<details>
201	<summary><strong>macOS / Linux</strong> — 安装即用</summary>
202
203	```bash
204	# macOS
205	brew install python
206
207	# Ubuntu / Debian
208	sudo apt install python3 python3-pip
209	```
210	</details>
211
212	<details>
213	<summary><strong>边缘场景备用方案</strong> — 99% 的用户用不到</summary>
214
215	Pandoc — 只在需要转小众格式时才装：`.doc`、`.odt`、`.rtf`、`.tex`、`.rst`、`.org`、`.typ`。`.docx`、`.html`、`.epub`、`.ipynb` 已由 Python 原生处理，不需要 pandoc。
216
217	```bash
218	# macOS
219	brew install pandoc
220
221	# Ubuntu / Debian
222	sudo apt install pandoc
223	```
224	</details>
225
226	### 2. 选择一个 Agent
227
228	PPT Master 在任何具备 agent 能力（可读写文件、执行命令、持续多轮对话）的工具里都能跑。
229
230	没用过这类工具也不用担心：它们在本项目里只扮演一个角色——一个能读写文件的 AI 聊天窗口。从下表任选一款装好即可，全程只用它的聊天面板，不需要写任何代码。
231
232	> 作者最推荐：[Claude Code](https://claude.ai/code) ——本项目开发与测试最充分的环境，CLI 与 VS Code / JetBrains 扩展均可。
233
234	\| 类型 \| 代表工具 \| 说明 \|
235	\|---\|---\|---\|
236	\| IDE 内置 agent \| • VS Code 架构（含 [VS Code](https://code.visualstudio.com/) 本体及分支与衍生）：[Cursor](https://cursor.sh/)、Trae、Codebuddy IDE、[Windsurf](https://codeium.com/windsurf) 等<br>• 其他架构：[Zed](https://zed.dev/) 等 \| 编辑器原生集成 agent \|
237	\| IDE 插件 / 扩展 \| [Claude Code](https://claude.ai/code)（VS Code / JetBrains 扩展）、[GitHub Copilot](https://github.com/features/copilot)、[Cline](https://cline.bot/)、通义灵码等 \| 装在 VS Code / JetBrains 等宿主里使用 \|
238	\| CLI agent \| [Claude Code](https://claude.ai/code) CLI、[Codex CLI](https://github.com/openai/codex)、Gemini CLI 等 \| 终端里运行，适合脚本化 / 远程 / 服务器场景 \|
239
240	> 模型推荐：追求最佳效果，语言模型选 [Kimi K3](https://www.kimi.com/code/?aff=ppt-master)（或 Claude）驱动流程，搭配 AI 生图 —— `gpt-image-2`（OpenAI）或 `gemini-3.1-flash-image`（Google）。本项目赞助商 Kimi Code 支持按量调用，很适合上手。
241
242	🔑 想用 Claude / GPT / Gemini 但还没有渠道？本项目赞助商 [PackyCode](https://www.packyapi.ai/register?aff=ppt-master)、[APIKEY.FUN](https://apikey.fun/register?aff=PPT-MASTER) 与 [RunAPI](https://runapi.co/register?aff=WMLJ) 均支持按量调用 Claude、GPT、Gemini 等主流模型，无需订阅、支持国内支付，并为本项目用户提供专属优惠（详情见页首）。
243
244	🔀 手上有多个渠道？拿到多家的 API Key 后，[cc-switch](https://github.com/farion1231/cc-switch)（跨平台桌面应用）可以一键切换 Claude Code、Codex、Gemini CLI 等工具的 API 供应商，免去手动改配置。
245
246	### 3. 配置项目
247
248	方式 A — Git clone（推荐；需先安装 [Git](https://git-scm.com/downloads)）：首选这种方式，因为 clone 可以随时拉取最新版本。
249
250	```bash
251	# GitHub
252	git clone https://github.com/hugohe3/ppt-master.git
253	# AtomGit（中国大陆地区网速更快）
254	git clone https://atomgit.com/hugohe3/ppt-master.git
255	cd ppt-master
256	```
257
258	然后安装依赖：
259
260	```bash
261	pip install -r requirements.txt
262	```
263
264	方式 B — 下载 ZIP（无需安装 Git，适合快速体验）：
265	[GitHub](https://github.com/hugohe3/ppt-master) → Code → Download ZIP · [AtomGit](https://atomgit.com/hugohe3/ppt-master) → 克隆/下载 → 下载ZIP（中国大陆地区访问 GitHub 下载不便时用这个，网速更快）；解压后同样用 `pip install -r requirements.txt` 装依赖。ZIP 没有 Git 历史，不能自动 `git pull`（更新见下）。
266
267	如果完整仓库下载失败、或嫌体积太大，可以改到 [Releases](https://github.com/hugohe3/ppt-master/releases) 页面下载纯技能包 `ppt-master-skill-*.zip`（约 50 MB，功能完整，但不含内置示例 deck）。
268
269	#### 日常更新
270
271	Git clone 安装：
272
273	```bash
274	python3 skills/ppt-master/scripts/update_repo.py
275	```
276
277	脚本会拉取最新版；如果 `requirements.txt` 有变化，会自动同步 Python 依赖。
278
279	下载 ZIP 安装：
280
281	ZIP 目录没有 Git 历史，不能自动 `git pull`。更新时请重新下载最新版 ZIP，解压到新目录，然后把旧目录里的 `.env` 和 `projects/` 复制过去，再执行：
282
283	```bash
284	pip install -r requirements.txt
285	```
286
287	> 方式 C — Skill marketplace：仓库已添加 `.claude-plugin/marketplace.json` 元数据，可通过 [Claude Code plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces) 生态一行安装：
288	>
289	> ```bash
290	> # 跨 agent CLI（Claude Code、Cursor、Codex 等）
291	> npx skills add hugohe3/ppt-master
292	>
293	> # 或在 Claude Code 内
294	> /plugin marketplace add hugohe3/ppt-master
295	> /plugin install ppt-master@ppt-master
296	> ```
297	>
298	> 上述两种安装方式都只会拉取 skill 文件本身（不含完整仓库），后处理脚本仍需在安装目录跑 `pip install -r requirements.txt`。
299
300	### 4. 开始创作
301
302	先在 Agent 里打开项目文件夹：目标是让 AI 工作在上一步解压 / 克隆出来的 `ppt-master` 目录里——IDE 类工具通过菜单文件 → 打开文件夹（File → Open Folder）打开它，AI 聊天面板通常在侧边栏；CLI 类工具先 `cd ppt-master` 再启动。之后的一切都在聊天里完成。
303
304	提供原始材料（推荐）：将 PDF、DOCX、图片等文件放入 `projects/` 目录下，在 AI 聊天面板中告诉它使用哪些文件。获取路径的最快方式：在文件管理器或 IDE 侧边栏中右键文件 → 复制路径（Copy Path / Copy Relative Path），直接粘贴进聊天框。
305
306	```
307	你：请用 projects/q3-report/sources/report.pdf 这份文件生成一份 PPT
308	```
309
310	直接输入内容：也可以把文字内容直接粘贴进聊天窗口，AI 会根据这些内容生成 PPT。
311
312	```
313	你：请根据以下内容制作成 PPT：[粘贴你的文字内容...]
314	```
315
316	默认流程下（除非显式要求快速生成），AI 会先确认设计规范：
317
318	```
319	AI：好的，先确认设计规范：
320	[模板] B) 自由设计
321	[格式] PPT 16:9
322	[页数] 8-10 页
323	...
324	```
325
326	AI 全程处理——内容分析、视觉设计、SVG 生成、PPTX 导出。
327
328	快速生成（跳过来回确认）：显式说明即可，AI 直接进入创作与导出。
329
330	```
331	你：用 projects/q3-report/sources/report.pdf 快速生成一份 5 页 PPT，不用跟我确认
332	```
333
334	你明确提的照做，你没提的由 AI 直接定，不再回来问你。它仍会转换来源、补齐事实、应用共享视觉基线，并按需使用图片 / 图标 / 原生形状 / 图表 / 表格 / 公式——省掉的是交互与持久规划，不是 PPT 能力。它是不可续接的一次性生成，也不会产生 `svg_final/` 预览。完整说明 → [快速模式](./docs/zh/getting-started.md#快速模式)。
335
336	> 输出说明： SVG 管线统一由项目转换器读取 `svg_output/`，生成可直接编辑的原生 DrawingML `.pptx`，保存至 `exports/<name>_<timestamp>.pptx`。默认 Generate 流程会运行 `finalize_svg.py` 并生成自包含预览 `svg_final/`；PowerPoint 手工“转换为形状”不在支持范围。用户可显式启用[快速生成](./skills/ppt-master/workflows/profiles/quick-generate.md)：它跳过 Strategist、确认、`design_spec.md`、`spec_lock.md` 与 `finalize_svg.py`——你明确提出的要求照做，你没提的由 Agent 在一次有效上下文中直接决定；仍按需转换来源、研究事实缺口、应用共享 mode / visual style / 美学规范、准备图片 / 图标 / 公式，并考虑原生形状与数据可视化，随后按规范手写 SVG，通过无锁的 Quick 最终质量检查，再导出最终 PPTX。它不写替代计划，上下文丢失后不能续接。原生图表 / 表格替换、讲稿、动效、旁白和诊断等普通导出能力仍可按需使用；讲稿、自定义对象动画和旁白默认关闭，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 对象模型，而不是“能否编辑”。
337
338	> 已有一份想复用的 `.pptx`？把那份 deck 连同素材给 AI，说「套模板」即可——它会把新内容（文字、表格、图表数据）填进你现有的设计，只导出你挑选的页面，且保持原生可编辑。详见 [常见问题](./docs/zh/faq.md) 与 [套模板工作流](./skills/ppt-master/workflows/template-fill-pptx.md)。
339
340	> 遇到问题？ AI 迷失上下文时，让它先读 `skills/ppt-master/SKILL.md`；其他问题查看 [常见问题](./docs/zh/faq.md) — 涵盖模型选择、排版问题、导出异常等，基于真实用户反馈持续更新。
341
342	### 5. 图片获取（可选）
343
344	非用户自带图片有两条路径，可在同一份 deck 里按图混用：
345
346	A) AI 生图 — `image_gen.py`。设置 `IMAGE_BACKEND` 和对应 `*_API_KEY`（`OPENAI_API_KEY`、`GEMINI_API_KEY` 等），流程会自动调用。`python3 skills/ppt-master/scripts/image_gen.py --list-backends` 查看完整后端清单。`gpt-image-2` 目前综合质量最佳。
347
348	B) 网络图片搜索 — `image_search.py`。零配置可用；建议配置 `PEXELS_API_KEY` / `PIXABAY_API_KEY`（都免费申请）以获得稳定的高质量结果：
349
350	- 不配置时只使用 Openverse / Wikimedia Commons，适合作为兜底，但容易出现构图随意、清晰度不稳定的图片
351	- 配置后默认搜索链会追加 Pexels / Pixabay，现代商业摄影、人物、办公、生活方式和插画类图片质量明显更稳定
352	- 许可自动处理：默认把 CC0、公有领域、Pexels / Pixabay 免署名许可、CC BY、CC BY-SA 一起纳入候选；选中需署名的图片时，Executor 会在该幻灯片自动添加小字署名。只有明确不能出现署名时，才使用 `--strict-no-attribution` 限制为免署名图片
353	- 对视觉要求高的封面、产品图、人物图和品牌场景，优先级建议：用户自带高清素材 / AI 生图 > 配置 Pexels / Pixabay 的网络搜索 > 零配置网络搜索
354
355	上面提到的 API Key 统一通过 `.env` 配置。clone 安装可以用 `cp .env.example .env`；skill marketplace 安装建议使用持久的用户级配置：
356
357	```bash
358	mkdir -p ~/.ppt-master
359	cp /path/to/installed/ppt-master/.env.example ~/.ppt-master/.env
360	```
361
362	PPT Master 会优先读取当前进程环境变量，然后按顺序读取第一个存在的 `.env`：当前工作目录、skill 安装目录（如 `~/.agents/skills/ppt-master/.env`）、clone 仓库根目录、`~/.ppt-master/.env`。
363
364	> 完整说明：[`image-generator.md`](./skills/ppt-master/references/image-generator.md)（AI）·[`image-searcher.md`](./skills/ppt-master/references/image-searcher.md)（网络）。
365
366	---
367
368	## 文档导航
369
370	\| \| 文档 \| 说明 \|
371	\|---\|------\|------\|
372	\| 📘 \| [快速入门](./docs/zh/getting-started.md) \| 三步做出第一份 deck，外加模板、实时预览、动画、旁白、声音复刻的用法（新用户从这里开始） \|
373	\| 🆚 \| [为什么选 PPT Master](./docs/zh/why-ppt-master.md) \| 为什么选它、以及它不适合的场景 \|
374	\| 🧭 \| [项目定位与能力边界](./docs/zh/project-positioning.md) \| 长期定位、产品承诺与能力边界 \|
375	\| 🪟 \| [Windows 安装指南](./docs/zh/windows-installation.md) \| Windows 用户手把手安装教程 \|
376	\| 📖 \| [SKILL.md](./skills/ppt-master/SKILL.md) \| 核心流程与规则 \|
377	\| 📐 \| [画布格式](./skills/ppt-master/references/canvas-formats.md) \| PPT 16:9、小红书、朋友圈等 10+ 种格式 \|
378	\| 🛠️ \| [脚本与工具](./skills/ppt-master/scripts/README.md) \| 所有脚本和命令 \|
379	\| 💼 \| [示例](./examples/README.md) \| 所有示例项目 \|
380	\| 🏗️ \| [技术路线](./docs/zh/technical-design.md) \| 架构、设计哲学、为什么选 SVG \|
381	\| ❓ \| [常见问题](./docs/zh/faq.md) \| 模型选择、费用、排版问题排查、自定义模板 \|
382
383	<sub>完整文档索引 → [`docs/zh/`](./docs/zh/README.md)</sub>
384
385	---
386
387	## 贡献
388
389	详见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
390
391	## 开源协议
392
393	[MIT](LICENSE)
394
395	## 致谢
396
397	[SVG Repo](https://www.svgrepo.com/) · [Tabler Icons](https://github.com/tabler/tabler-icons) · [Simple Icons](https://github.com/simple-icons/simple-icons) · [Phosphor Icons](https://github.com/phosphor-icons/core) · [Robin Williams](https://en.wikipedia.org/wiki/Robin_Williams_(author))（CRAP 设计原则）
398
399	## 相关工具
400
401	[cc-switch](https://github.com/farion1231/cc-switch) —— 一键切换 Claude Code / Codex / Gemini CLI 等工具的 API 供应商。
402
403	## 联系与合作
404
405	欢迎合作交流、将 PPT Master 集成到你的工作流，或者单纯提问：
406
407	- 💬 提问与分享 — [GitHub Discussions](https://github.com/hugohe3/ppt-master/discussions)
408	- 🐛 Bug 反馈与功能建议 — [GitHub Issues](https://github.com/hugohe3/ppt-master/issues)
409
410	---
411
412	## 赞助与支持
413
414	PPT Master 目前主要由我开发维护。每个新模板、Bug 修复、文档更新都需要持续的资源投入，目前由以下赞助方和个人支持者共同分担。
415
416	企业赞助方
417
418	<a href="https://www.kimi.com/code/?aff=ppt-master"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/sponsors/kimi-dark.svg"><img src="docs/assets/sponsors/kimi-light.svg" alt="Kimi" height="40" /></picture></a>
419
420	<a href="https://www.packyapi.ai/register?aff=ppt-master"><img src="docs/assets/sponsors/packycode.png" alt="PackyCode" height="40" /></a>
421
422	<a href="https://apikey.fun/register?aff=PPT-MASTER"><img src="docs/assets/sponsors/apikey-fun.png" alt="APIKEY.FUN" height="40" /></a>
423
424	<a href="https://runapi.co/register?aff=WMLJ"><img src="docs/assets/sponsors/runapi.png" alt="RunAPI" height="40" /></a>
425
426	<a href="https://www.compshare.cn/coding-plan?ytag=GPU_YY-git_pptmaster0624"><img src="docs/assets/sponsors/youyun.png" alt="优云智算" height="40" /></a>
427
428	<a href="https://m.do.co/c/547f129aabe1"><img src="https://opensource.nyc3.cdn.digitaloceanspaces.com/attribution/assets/PoweredByDO/DO_Powered_by_Badge_blue.svg" alt="Powered by DigitalOcean" height="40" /></a>
429
430	个人赞助
431
432	如果 PPT Master 帮到了你，任何金额的个人赞助都能帮助项目持续更新、保持免费开源。
433
434	<a href="https://paypal.me/hugohe3"><img src="https://img.shields.io/badge/PayPal-赞助-00457C?style=for-the-badge&logo=paypal&logoColor=white" alt="通过 PayPal 赞助" /></a>
435
436	<img src="docs/assets/alipay-qr.jpg" alt="支付宝收款码" width="220" />
437
438	---
439
440	Made with ❤️ by [何雨果 Hugo He](https://www.hehugo.com/) — 如果这个项目对你有帮助，请给一个 ⭐，也欢迎[赞助支持](#赞助与支持)。
441
442	<sub>官方发布渠道：<a href="https://github.com/hugohe3/ppt-master">GitHub</a>（主仓库）· <a href="https://atomgit.com/hugohe3/ppt-master">AtomGit</a>（镜像）。其他平台转发版本均为非官方版本。MIT 协议，使用需保留署名。</sub>
443
444	[⬆ 回到顶部](#ppt-master--ai-生成原生-powerpoint支持任意文档输入)
445

445 lines MARKDOWN