diff --git a/README.md b/README.md index c58952f..91a7de9 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,10 @@ -# PPT Master — AI generates natively editable PPTX from any document + +> [!NOTE] +> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 +> [English](./README.en.md) · [原始项目](https://github.com/hugohe3/ppt-master) · [上游 README](https://github.com/hugohe3/ppt-master/blob/HEAD/README.md) +> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 + +# PPT Master — AI 生成原生可编辑 PPTX，支持任意文档输入 [![Version](https://img.shields.io/github/v/release/hugohe3/ppt-master?label=version&color=blue)](https://github.com/hugohe3/ppt-master/releases) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) @@ -10,159 +16,163 @@ hugohe3%2Fppt-master | Trendshift

-English | [中文](./README_CN.md) +[English](./README.md) | 中文
-This project is kept free and open source with the support of Kimi, PackyCode, APIKEY.FUN, RunAPI, YouYun ZhiSuan and other sponsors. +本项目由 Kimi、PackyCode、APIKEY.FUN、RunAPI、优云智算 等赞助方支持，得以持续免费开源。

- Kimi + Kimi

-Thanks to [Kimi](https://www.kimi.com/code/?aff=ppt-master) for sponsoring this project! [Kimi K2.7](https://platform.kimi.ai/docs/guide/kimi-k2-7-code-quickstart) is an open-source agentic model developed by Moonshot AI. With PPT Master, Kimi can understand source materials such as PDFs, DOCX files, and web pages, identify key points, structure the narrative, and generate a natively editable PPTX that you can continue refining in PowerPoint. +感谢 [Kimi](https://www.kimi.com/code/?aff=ppt-master) 赞助本项目！[Kimi K2.7](https://platform.kimi.com/docs/guide/kimi-k2-7-code-quickstart) 是 Moonshot AI 推出的开源智能体模型。搭配 PPT Master，Kimi 可以理解 PDF、DOCX、网页等原始资料，提炼重点、规划演示逻辑，并生成可在 PowerPoint 中继续修改的原生可编辑 PPTX。 -**Try [Kimi Code](https://www.kimi.com/code/?aff=ppt-master), or access the API through the Kimi Open Platform ([中文站](https://platform.kimi.com?aff=ppt-master) | [Global](https://platform.kimi.ai?aff=ppt-master)).** +**立即体验 [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。**
- + - + - + - - + +
PackyCodeThanks to PackyCode for sponsoring this project! PackyCode is a reliable and efficient API relay service provider, offering relay services for Claude Code, Codex, Gemini, and more. PackyCode provides special discounts for our project users: register using this link and enter the promo code ppt-master during recharge to get 10% off.感谢 PackyCode 赞助了本项目！PackyCode 是一家稳定、高效的 API 中转服务商，提供 Claude Code、Codex、Gemini 等多种中转服务。PackyCode 为本项目的用户提供了特别优惠，使用此链接注册并在充值时填写"ppt-master"优惠码，可以享受 9 折优惠。
APIKEY.FUNThanks to APIKEY.FUN for sponsoring this project! APIKEY.FUN is a professional enterprise-grade AI relay service committed to stable, efficient, and low-cost AI access for businesses and developers. The platform supports mainstream models including Claude, OpenAI, and Gemini, with prices as low as 7% of official rates. Register through our dedicated link for an exclusive perk: up to 5% off on top-ups, permanently.感谢 APIKEY.FUN 赞助了本项目！APIKEY.FUN 是一家专业的企业级 AI 中转站，致力于为企业和开发者提供稳定、高效、低成本的 AI 中转服务。平台支持 Claude、OpenAI、Gemini 等主流热门模型，价格低至官方原价的 7%。通过本项目专属链接注册，还可享受最高 永久充值 95 折 专属优惠。
RunAPIThanks to RunAPI for sponsoring this project! RunAPI is an efficient and stable API platform — a single API Key gives you access to 150+ leading models, including OpenAI, Claude, Gemini, DeepSeek, and Grok, at prices as low as 10% of official rates, with exceptional stability and seamless compatibility with tools like Claude Code. RunAPI offers an exclusive perk for PPT Master users: register and contact an administrator via our dedicated link to claim ¥7 in free credit.感谢 RunAPI 赞助了本项目！RunAPI 是一个高效稳定的 API 平台，一个 API Key 即可访问 OpenAI、Claude、Gemini、DeepSeek、Grok 等 150+ 主流模型，价格低至官方原价的 1 折，极其稳定，可无缝兼容 Claude Code 等工具。RunAPI 为 PPT Master 用户提供专属福利：通过本项目专属链接注册并联系管理员，即可领取 ￥7 的免费额度。
YouYun ZhiSuanThanks to YouYun ZhiSuan for sponsoring this project! YouYun ZhiSuan is UCloud's AI cloud platform, providing one-stop API services for mainstream domestic and international models, all accessible with a single key. The platform features cost-effective CodingPlan packages for domestic models (including GLM5.2, Deepseek-v4, and more), along with official channels for stable access to overseas models, meeting diverse development needs. It's compatible with mainstream AI coding tools like Claude Code and Codex, as well as general API calls. The platform supports enterprise-level high concurrency, 24/7 technical support, and self-service invoicing. Register through this link to receive up to ¥10 in free credits. This project has been built into an Agent — PPT Master — ready to use without local deployment.优云智算感谢优云智算赞助了本项目！优云智算是 UCloud 旗下 AI 云平台，一站式提供国内外主流模型的 API 服务，一个 Key 即可调用所有模型。主打高性价比国产模型 CodingPlan 套餐（GLM5.2、Deepseek-v4 等），同时提供官方转发的稳定海外模型通道，满足多场景开发需求。已兼容 Claude Code、Codex 等主流 AI 编程工具及通用 API 调用，支持企业级高并发、7×24 技术支持和自助开票。通过此链接注册，最高可获得 ¥10 免费体验金。该项目已制作成 Agent【PPT 制作大师】，无需本地部署即可使用。
-> **AI generates your deck — it doesn't fill in a template.** PPT Master is a workflow that runs inside AI IDEs (Claude Code, Cursor, VS Code + Copilot, etc.): hand the AI your PDF / DOCX / web pages, and it produces a real PowerPoint on your machine — every element editable in PowerPoint, your data stays local, no platform or model lock-in. How it works and where the limits are → [Product Positioning](#product-positioning). +> **AI 生成 PPT，不是 AI 套模板。** PPT Master 是一套在 AI IDE（Claude Code / Cursor / VS Code + Copilot 等）里运行的工作流：把 PDF / DOCX / 网页等材料交给 AI，它在你本机生成一份真正的 PowerPoint——每个元素都能在 PowerPoint 里点开修改，数据不出本地，不锁定任何平台和模型。工作原理与能力边界 → [产品定位](#产品定位)。

- Live Demo · - Examples · - FAQ · - Roadmap + 在线预览 · + 示例下载 · + 常见问题 · + 路线图

-

Download the new narrated Attention Is All You Need deck — play it in PowerPoint and every slide reads itself out loud. That's just the tip of what PPT Master can do.

+

下载这份带音频旁白的 Attention Is All You Need 论文精读 deck，在 PowerPoint 里直接放映，每一页都会自己"读"给你听 —— 这只是 PPT Master 能力的冰山一角。

- Editorial magazine — Pritzker 2026 architecture review
- Editorial Magazine — architecture photography, calm typographic grid
- Flip online · Download .pptx + 杂志风 — 普利兹克奖 2026
+ 杂志风 — 建筑摄影 + 排版网格，冷静克制的编辑感
+ 在线翻页 · 下载 .pptx 		- Data journalism — Global AI Capital 2026
- Data Journalism — Bloomberg-style dark dashboard, chart-driven
- Flip online · Download .pptx + 新闻风 — 2026 全球 AI 资本格局
+ 新闻 / 财经数据风 — 深色仪表盘，图表驱动，彭博风
+ 在线翻页 · 下载 .pptx 		- Swiss typographic grid — Grid Systems primer
- Swiss Grid — strict modular grid, restrained type, red-accent
- Flip online · Download .pptx + 瑞士风 — 网格系统入门
+ 瑞士风 — 严格栅格，克制字体，红色点缀
+ 在线翻页 · 下载 .pptx
- Glassmorphism SaaS — AI Agent engineering demo
- Glassmorphism SaaS — translucent layers, gradient depth, product UI
- Flip online · Download .pptx + 毛玻璃风 — AI Agent 工程化 Demo
+ 毛玻璃 SaaS — 半透明叠层，渐变景深，产品 UI 感
+ 在线翻页 · 下载 .pptx 		- Memphis pop — Sugar Rush festival
- Memphis Pop — bold primaries, geometric patterns, playful energy
- Flip online · Download .pptx + 孟菲斯风 — Sugar Rush 音乐节
+ 孟菲斯波普 — 高饱和原色，几何图形，俏皮活力
+ 在线翻页 · 下载 .pptx 		- Risograph zine — Indie bookstore guide
- Risograph Zine — duotone print, hand-made bookstore-culture feel
- Flip online · Download .pptx + Zine 风 — 独立书店指南
+ Risograph Zine — 双色印刷质感，手作书店文化
+ 在线翻页 · 下载 .pptx

- All examples above were generated in a single pass, with no manual polish (Claude Opus 4.7 + gpt-image-2). Downloading any .pptx and opening it in PowerPoint is the fastest way to see what it can really do.
Flip through all examples online → · examples/ directory · Why PPT Master? + 以上示例均为一次性生成、未经精修（生成模型：Claude Opus 4.7 + gpt-image-2）。下载任意一份 .pptx 在 PowerPoint 里打开，是感受真实产出水平最快的方式。
在线翻看全部示例 → · examples/ 目录 · 为什么选 PPT Master？ +

+ +

+ 更多端到端实例：合集·PPT-Master 能力展示（B 站）

--- -Drop in your source material, and the deck you get back is **more than just editable**: it has native slide transitions plus opt-in entrance animations (off by default), speaker notes that can become audio narration, charts and tables that can ship as real data-backed PowerPoint objects, and it can follow your own PPT template — a complete deck you can present as-is and keep refining. How to use each capability → [Getting Started](./docs/getting-started.md). +丢进原材料，拿回的这份 PPT **不只是能改**：它有 PPT 原生转场，也支持按需开启的入场动画（默认关闭），演讲者备注能直接合成音频旁白，图表和表格还能以带数据的 PowerPoint 原生对象形式导出，也能参考你自己的 PPT 模板来设计——一份能直接拿去讲、回头还能改的成品。每项能力怎么用 → [快速入门](./docs/zh/getting-started.md)。 -## Product Positioning +## 产品定位 -**If a file can't be opened and edited in PowerPoint, it shouldn't be called a PPT.** AI presentation tools roughly fall into four categories, and PPT Master only does the last one: +**一个文件如果在 PowerPoint 里打不开、改不动，就不该被叫做 PPT。** 市面上的 AI PPT 工具大致分四类，PPT Master 只做最后一类： -| Category | Output | Editable element-by-element in PowerPoint? | +| 类型 | 产物形态 | 能在 PowerPoint 里逐元素改吗 | |---|---|:---:| -| Template fill-in | PPTX built from a fixed template | Partially — limited by the template | -| Image-based | One large image per slide, packed into PPTX | ❌ each slide is a picture | -| HTML presentation | Web-based deck | ❌ not a PPTX | -| **Native editable (PPT Master)** | **Real DrawingML shapes, text boxes, charts** | ✅ click any element to edit | +| 模板填空 | 套模板的 PPTX | 部分可以，受模板限制 | +| 图片式 | 一页一张大图拼成 PPTX | ❌ 整页是图片 | +| HTML 演示 | 网页演示 | ❌ 不是 PPTX | +| **原生可编辑（PPT Master）** | **真 DrawingML 形状、文本框、图表** | ✅ 每个元素都能点开改 | -In form, it's not a website or an app but a workflow (a "skill") that runs inside AI IDEs like Claude Code, Cursor, VS Code + Copilot, or Codebuddy: you tell the AI in the IDE's chat — "make a deck from this PDF" — and it follows the workflow to produce a genuinely editable `.pptx` on your machine. No coding on your side; you do exactly three things — install Python, install an AI IDE, drop in your material. +形态上，它不是网站也不是 App，而是一套在 AI IDE（Claude Code / Cursor / VS Code + Copilot / Codebuddy 等）里运行的工作流（一个 "skill"）：你在 IDE 的对话框里说"用这份 PDF 做一份 PPT"，AI 按这套工作流在你本机生成真正可编辑的 `.pptx`。你不写任何代码，要做的只有三件事——装 Python、装一个 AI IDE、把资料放进来。 -This form buys three promises that other tools struggle to make at the same time: +这个形态换来三个别的工具很难同时给出的承诺： -- **Transparent, predictable cost** — the tool is free and open source; the only cost is your AI model usage. You pay exactly what you consume — no separate PPT subscription added on top -- **Data stays local** — your files shouldn't have to be uploaded to someone else's server just to make a presentation. Apart from AI model communication, the entire pipeline runs on your machine -- **No platform lock-in** — your workflow shouldn't be held hostage by any single company. Works with Claude Code, Cursor, VS Code Copilot, and more; supports Claude, GPT, Gemini, Kimi, and other models +- **成本透明可控** — 工具免费开源，唯一成本是你自己的 AI 模型用量，你用多少付多少，不在此之外增加任何订阅费用 +- **数据不出本地** — 你的文件不应该为了做一份 PPT 就被上传到别人的服务器。除与 AI 模型的对话外，全流程在你的电脑上完成 +- **不锁定平台** — 你的工作流不应该被任何一家公司绑架。Claude Code、Cursor、VS Code Copilot 等均可驱动；Claude、GPT、Gemini、Kimi 等模型均可使用 > [!IMPORTANT] -> ### This is a tool, not a wishing well -> `harness + model = agent` — PPT Master only owns the workflow; the model sets the ceiling. Recommended: **Claude with a large context window (~1M tokens) + AI image generation (`gpt-image-2`)**; other models can run the pipeline, with a quality gap. +> ### 这是一个工具，不是一个许愿池 +> `harness + model = agent`——PPT Master 只负责工作流，产出上限由模型决定。推荐 **Claude 大上下文窗口（~100 万 token）+ AI 生图（`gpt-image-2`）**；其他模型能跑通流程，但有质量差距。 > -> And don't expect a finished, perfect deck in one shot. The tool's value is taking most of the tedious work off your plate; the polishing that's left is yours — a natively editable deck exists precisely so you can keep working on it, not a flat image you can't touch. The cheaper the model, the more there is to do; if results disappoint, upgrade the model first, then check your usage against [Getting Started](./docs/getting-started.md) and the example projects. +> 也别指望一把就拿到完美成品。它的价值是帮你把大部分枯燥的活儿干掉，剩下的打磨交给你——做原生可编辑的 PPT，本就是为了让你接着改，而不是甩给你一张改不动的图。模型越便宜，要补的人工就越多；效果不理想，先升级模型，再对照[快速入门](./docs/zh/getting-started.md)和示例工程检查用法。 --- -## Built by Hugo He +## 关于作者 -I'm a finance professional (CPA · CPV · Consulting Engineer (Investment)) who regularly reviews and edits presentation decks. I wanted AI-generated slides to remain editable in PowerPoint, not flattened into images — so I built this. +我是何雨果（Hugo He），投融资领域从业者（注册会计师 · 资产评估师 · 咨询工程师（投资）），工作中经常审阅和修改 PPT。我希望 AI 生成的幻灯片仍然能在 PowerPoint 里继续编辑，而不是被压成一张张图片——所以做了这个。 -Knowing how to use Python and AI agents will matter more and more, and this project is also meant to show how far you can go with just those two things. There's a learning curve if you're starting cold, but it's the curve worth climbing — making a deck is just the excuse; what I'm really pushing is Python and agents. +未来，使用 Python 和 AI agent 的能力会越来越重要，这个项目也想展示：仅凭这两样，你能走多远。零基础上手有一段学习曲线，但走完这段，你就接上了未来——做 PPT 只是个借口，我真正想推广的是 Python 和 agent。 --- -## You Might Also Like +## 你可能也感兴趣 ### ResearchStudio-Reel -> A Microsoft open-source project I recently joined — from **paper** to **talk video**, **poster**, and **blog**, automating the **last mile** of research dissemination. +> 微软开源项目，我最近也参与其中——从**论文**到**演讲视频**、**海报**与**博客**，自动化科研传播的**最后一公里**。 > -> 📦 **Repo:** [microsoft/ResearchStudio](https://github.com/microsoft/ResearchStudio) · 📄 **Paper:** [arXiv:2607.04438](https://arxiv.org/abs/2607.04438) +> 📦 **仓库：**[microsoft/ResearchStudio](https://github.com/microsoft/ResearchStudio) · 📄 **论文：**[arXiv:2607.04438](https://arxiv.org/abs/2607.04438)
ResearchStudio-Reel demo + alt="ResearchStudio-Reel 演示" /> - ResearchStudio-Reel generated poster + ResearchStudio-Reel 生成的海报
-BibTeX — if you use ResearchStudio-Reel in your research +BibTeX —— 如果你在研究中使用了 ResearchStudio-Reel ```bibtex @article{xiao2026researchstudioreel, @@ -178,24 +188,24 @@ Knowing how to use Python and AI agents will matter more and more, and this proj --- -## Quick Start +## 快速开始 -### 1. Prerequisites +### 1. 前置条件 -**All you need to install is [Python](https://www.python.org/downloads/) 3.10+.** Everything else comes with one line — `pip install -r requirements.txt` — after you download the project in Step 3. +**只需安装 [Python](https://www.python.org/downloads/) 3.10+。** 其余依赖在第 3 步下载好项目后，用一行 `pip install -r requirements.txt` 装齐。
-Windows — see the dedicated step-by-step guide ⚠️ +Windows — 请看专门的手把手安装指南 ⚠️ -Windows requires a few extra steps (PATH setup, execution policy, etc.). We wrote a **step-by-step guide** specifically for Windows users: +Windows 需要一些额外步骤（PATH 设置、执行策略等）。我们为 Windows 用户写了一份**手把手安装指南**： -**📖 [Windows Installation Guide](./docs/windows-installation.md)** — from zero to a working presentation in 10 minutes. +**📖 [Windows 安装指南](./docs/zh/windows-installation.md)** — 从零到跑通第一份 PPT，10 分钟搞定。 -Quick version: download Python from [python.org](https://www.python.org/downloads/) → **check "Add to PATH"** during install → done; dependencies are installed in Step 3. +简要流程：从 [python.org](https://www.python.org/downloads/) 下载 Python → **安装时勾选 "Add to PATH"** → 完成，依赖安装见第 3 步。
-macOS / Linux — install and go +macOS / Linux — 安装即用 ```bash # macOS @@ -207,9 +217,9 @@ sudo apt install python3 python3-pip
-Edge-case fallback — 99% of users don't need this +边缘场景备用方案 — 99% 的用户用不到 -**Pandoc** — only needed for legacy document formats: `.doc`, `.odt`, `.rtf`, `.tex`, `.rst`, `.org`, or `.typ`. `.docx`, `.html`, `.epub`, `.ipynb` are handled natively by Python — no pandoc required. +**Pandoc** — 只在需要转小众格式时才装：`.doc`、`.odt`、`.rtf`、`.tex`、`.rst`、`.org`、`.typ`。`.docx`、`.html`、`.epub`、`.ipynb` 已由 Python 原生处理，不需要 pandoc。 ```bash # macOS @@ -220,172 +230,178 @@ sudo apt install pandoc ```
-### 2. Pick an Agent +### 2. 选择一个 Agent -PPT Master runs in **any tool with agent capability** — read/write files, execute commands, and sustain multi-turn conversation. +PPT Master 在**任何具备 agent 能力**（可读写文件、执行命令、持续多轮对话）的工具里都能跑。 -Never used one of these? Don't worry — in this project they play exactly one role: an AI chat window that can read and write files. Pick any tool from the table, install it, and you'll only ever use its chat panel. No coding involved. +没用过这类工具也不用担心：它们在本项目里只扮演一个角色——一个能读写文件的 AI 聊天窗口。从下表任选一款装好即可，全程只用它的聊天面板，不需要写任何代码。 -> **Author's pick: [Claude Code](https://claude.ai/code)** — the environment this project is developed and tested on most thoroughly, as the CLI or the VS Code / JetBrains extension. +> **作者最推荐：[Claude Code](https://claude.ai/code)** ——本项目开发与测试最充分的环境，CLI 与 VS Code / JetBrains 扩展均可。 -| Type | Examples | Notes | +| 类型 | 代表工具 | 说明 | |---|---|---| -| **IDE-native agent** | • VS Code architecture ([VS Code](https://code.visualstudio.com/) itself, plus forks & derivatives): [Cursor](https://cursor.sh/), Trae, Codebuddy IDE, [Windsurf](https://codeium.com/windsurf), etc.
• Other architectures: [Zed](https://zed.dev/), etc. | Editor with a built-in agent | -| **IDE plugin / extension** | [Claude Code](https://claude.ai/code) (VS Code / JetBrains extension), [GitHub Copilot](https://github.com/features/copilot), [Cline](https://cline.bot/), etc. | Installed inside hosts like VS Code or JetBrains | -| **CLI agent** | [Claude Code](https://claude.ai/code) CLI, [Codex CLI](https://github.com/openai/codex), Gemini CLI, etc. | Runs in the terminal; suits scripting, remote, or server use | +| **IDE 内置 agent** | • VS Code 架构（含 [VS Code](https://code.visualstudio.com/) 本体及分支与衍生）：[Cursor](https://cursor.sh/)、Trae、Codebuddy IDE、[Windsurf](https://codeium.com/windsurf) 等
• 其他架构：[Zed](https://zed.dev/) 等 | 编辑器原生集成 agent | +| **IDE 插件 / 扩展** | [Claude Code](https://claude.ai/code)（VS Code / JetBrains 扩展）、[GitHub Copilot](https://github.com/features/copilot)、[Cline](https://cline.bot/)、通义灵码 等 | 装在 VS Code / JetBrains 等宿主里使用 | +| **CLI agent** | [Claude Code](https://claude.ai/code) CLI、[Codex CLI](https://github.com/openai/codex)、Gemini CLI 等 | 终端里运行，适合脚本化 / 远程 / 服务器场景 | -> **Model recommendation**: for the best results, use **Claude Opus** with `gpt-image-2`; **Gemini 3.5 Flash** currently offers great overall value for money — notably fast and well worth a try. +> **模型推荐**：追求最佳效果选 **Claude Opus**，搭配 `gpt-image-2` 生图；**Gemini 3.5 Flash** 目前综合性价比很高，尤其速度很快，值得一试。 -**🔑 Want to use Claude / GPT / Gemini but don't have access yet?** Project sponsors **[PackyCode](https://www.packyapi.com/register?aff=ppt-master)**, **[APIKEY.FUN](https://apikey.fun/register?aff=PPT-MASTER)** and **[RunAPI](https://runapi.co/register?aff=WMLJ)** offer pay-as-you-go access to Claude, GPT, Gemini and more — no subscription required, with exclusive discounts for our users (details at the top of this page). +**🔑 想用 Claude / GPT / Gemini 但还没有渠道？** 本项目赞助商 **[PackyCode](https://www.packyapi.com/register?aff=ppt-master)**、**[APIKEY.FUN](https://apikey.fun/register?aff=PPT-MASTER)** 与 **[RunAPI](https://runapi.co/register?aff=WMLJ)** 均支持按量调用 Claude、GPT、Gemini 等主流模型，无需订阅、支持国内支付，并为本项目用户提供专属优惠（详情见页首）。 -**🔀 Juggling several providers?** Once you hold keys from more than one of them, [cc-switch](https://github.com/farion1231/cc-switch) — a cross-platform desktop app — lets you one-click switch API providers for Claude Code, Codex, Gemini CLI and more, no manual config editing. +**🔀 手上有多个渠道？** 拿到多家的 API Key 后，[cc-switch](https://github.com/farion1231/cc-switch)（跨平台桌面应用）可以一键切换 Claude Code、Codex、Gemini CLI 等工具的 API 供应商，免去手动改配置。 -### 3. Set Up +### 3. 配置项目 -**Option A — Git clone** (recommended; requires [Git](https://git-scm.com/downloads) installed): the preferred path, since a clone can pull the latest version at any time. +**方式 A — Git clone**（推荐；需先安装 [Git](https://git-scm.com/downloads)）：首选这种方式，因为 clone 可以随时拉取最新版本。 ```bash +# GitHub git clone https://github.com/hugohe3/ppt-master.git +# AtomGit（中国大陆地区网速更快） +git clone https://atomgit.com/hugohe3/ppt-master.git cd ppt-master ``` -Then install dependencies: +然后安装依赖： ```bash pip install -r requirements.txt ``` -**Option B — Download ZIP** (no Git required; best for a quick trial): click **Code → Download ZIP** on the [GitHub page](https://github.com/hugohe3/ppt-master), then unzip, and install dependencies with `pip install -r requirements.txt`. A ZIP has no Git history, so it can't `git pull` — see Updating Later. If that download is too large or fails, grab the skill-only package `ppt-master-skill-*.zip` (~50 MB, fully functional but without the bundled example decks) from the [Releases](https://github.com/hugohe3/ppt-master/releases) page instead. +**方式 B — 下载 ZIP**（无需安装 Git，适合快速体验）： +[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`（更新见下）。 -#### Updating Later +如果完整仓库下载失败、或嫌体积太大，可以改到 [Releases](https://github.com/hugohe3/ppt-master/releases) 页面下载纯技能包 `ppt-master-skill-*.zip`（约 50 MB，功能完整，但不含内置示例 deck）。 -**Git clone installs:** +#### 日常更新 + +**Git clone 安装：** ```bash python3 skills/ppt-master/scripts/update_repo.py ``` -The script pulls the latest version and syncs Python dependencies when `requirements.txt` changes. +脚本会拉取最新版；如果 `requirements.txt` 有变化，会自动同步 Python 依赖。 -**Download ZIP installs:** +**下载 ZIP 安装：** -ZIP folders do not include Git history, so they cannot run `git pull`. To update, download the latest ZIP, unzip it into a new folder, copy your old `.env` and `projects/` folder into the new folder, then run: +ZIP 目录没有 Git 历史，不能自动 `git pull`。更新时请重新下载最新版 ZIP，解压到新目录，然后把旧目录里的 `.env` 和 `projects/` 复制过去，再执行： ```bash pip install -r requirements.txt ``` -> **Option C — Skill marketplace**: the repo ships `.claude-plugin/marketplace.json`, so it can be installed through the [Claude Code plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces) ecosystem: +> **方式 C — Skill marketplace**：仓库已添加 `.claude-plugin/marketplace.json` 元数据，可通过 [Claude Code plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces) 生态一行安装： > > ```bash -> # Cross-agent CLI (Claude Code, Cursor, Codex, etc.) +> # 跨 agent CLI（Claude Code、Cursor、Codex 等） > npx skills add hugohe3/ppt-master > -> # Or inside Claude Code +> # 或在 Claude Code 内 > /plugin marketplace add hugohe3/ppt-master > /plugin install ppt-master@ppt-master > ``` > -> Both install paths above only fetch the skill files (not the full repo); you still need to `pip install -r requirements.txt` from the installed location for the post-processing scripts to run. +> 上述两种安装方式都只会拉取 skill 文件本身（不含完整仓库），后处理脚本仍需在安装目录跑 `pip install -r requirements.txt`。 -### 4. Create +### 4. 开始创作 -**First, open the project folder in your agent:** the goal is to point the AI at the `ppt-master` directory you unzipped / cloned in the previous step. In an IDE-type tool, use **File → Open Folder** — the AI chat panel is usually in the sidebar; in a CLI agent, `cd ppt-master` first, then launch it. Everything from here on happens in the chat. +**先在 Agent 里打开项目文件夹：** 目标是让 AI 工作在上一步解压 / 克隆出来的 `ppt-master` 目录里——IDE 类工具通过菜单 **文件 → 打开文件夹**（File → Open Folder）打开它，AI 聊天面板通常在侧边栏；CLI 类工具先 `cd ppt-master` 再启动。之后的一切都在聊天里完成。 -**Provide source materials (recommended):** Place your PDF, DOCX, images, or other files in the `projects/` directory, then tell the AI chat panel which files to use. The quickest way to get the path: right-click the file in your file manager or IDE sidebar → **Copy Path** (or **Copy Relative Path**) and paste it directly into the chat. +**提供原始材料（推荐）：** 将 PDF、DOCX、图片等文件放入 `projects/` 目录下，在 AI 聊天面板中告诉它使用哪些文件。获取路径的最快方式：在文件管理器或 IDE 侧边栏中右键文件 → **复制路径**（Copy Path / Copy Relative Path），直接粘贴进聊天框。 ``` -You: Please create a PPT from projects/q3-report/sources/report.pdf +你：请用 projects/q3-report/sources/report.pdf 这份文件生成一份 PPT ``` -**Paste content directly:** You can also paste text content straight into the chat window and the AI will generate a PPT from it. +**直接输入内容：** 也可以把文字内容直接粘贴进聊天窗口，AI 会根据这些内容生成 PPT。 ``` -You: Please turn the following into a PPT: [paste your content here...] +你：请根据以下内容制作成 PPT：[粘贴你的文字内容...] ``` -Either way, the AI will first confirm the design spec: +两种方式下 AI 都会先确认设计规范： ``` -AI: Sure. Let's confirm the design spec: - [Template] B) Free design - [Format] PPT 16:9 - [Pages] 8-10 pages - ... +AI：好的，先确认设计规范： + [模板] B) 自由设计 + [格式] PPT 16:9 + [页数] 8-10 页 + ... ``` -The AI handles everything — content analysis, visual design, SVG generation, and PPTX export. +AI 全程处理——内容分析、视觉设计、SVG 生成、PPTX 导出。 -> **Output:** The SVG pipeline has one PPTX export route: PPT Master's converter reads `svg_output/` and writes a directly editable native DrawingML deck to `exports/_.pptx`. Step 7 still always runs `finalize_svg.py`, producing self-contained files in `svg_final/` for visual inspection or manual insertion as SVG pictures; PowerPoint's manual **Convert to Shape** command is outside the supported contract. A copy of `svg_output/` is always snapshotted to `backup//svg_output/` for re-export / archival. By default charts and tables export as SVG-derived shapes (pixel-consistent across PowerPoint / Keynote / WPS); pass `--native-objects` to instead emit them as **real editable PowerPoint chart / table objects backed by data** (rendering may vary across apps), saved as `exports/__native_charts.pptx`. +> **输出说明：** 标准导出从 `svg_output/` 经项目转换器生成原生 DrawingML `.pptx`，保存至 `exports/_.pptx`；这是唯一的 PPTX 产物路线，文字和图形可直接编辑。`svg_output/` 始终镜像到 `backup//svg_output/`，便于归档或后续重跑。流程仍会强制生成 `svg_final/`：它是一组自包含的视觉预览 SVG，可直接打开，也可作为 SVG 图片手动插入 PowerPoint；PowerPoint 手工“转换为形状”不在支持范围。图表和表格默认导出为 SVG 派生的 DrawingML 形状（在 PowerPoint / Keynote / WPS 间像素一致）；加 `--native-objects` 则在同一原生导出路线中改为**带数据、可直接编辑的 PowerPoint 原生图表 / 表格对象**（跨软件渲染可能略有差异），保存为 `exports/__native_charts.pptx`。 -> **Already have a `.pptx` you want to reuse?** Hand the AI that deck plus your material and ask it to "fill this deck with the new content" — it fills text, table, and chart data into your existing design and exports only the pages you pick, staying natively editable. See the [FAQ](./docs/faq.md) and [template-fill workflow](./skills/ppt-master/workflows/template-fill-pptx.md). +> **已有一份想复用的 `.pptx`？** 把那份 deck 连同素材给 AI，说「套模板」即可——它会把新内容（文字、表格、图表数据）填进你现有的设计，只导出你挑选的页面，且保持原生可编辑。详见 [常见问题](./docs/zh/faq.md) 与 [套模板工作流](./skills/ppt-master/workflows/template-fill-pptx.md)。 -> **Something went wrong?** If the AI loses context, ask it to read `skills/ppt-master/SKILL.md`; for everything else, check the **[FAQ](./docs/faq.md)** — it covers model selection, layout issues, export problems, and more. Continuously updated from real user reports. +> **遇到问题？** AI 迷失上下文时，让它先读 `skills/ppt-master/SKILL.md`；其他问题查看 **[常见问题](./docs/zh/faq.md)** — 涵盖模型选择、排版问题、导出异常等，基于真实用户反馈持续更新。 -### 5. Image Acquisition (Optional) +### 5. 图片获取（可选） -Two paths for non-user images, mixable per image in the same deck: +非用户自带图片有两条路径，可在同一份 deck 里按图混用： -**A) AI generation** — `image_gen.py`. Set `IMAGE_BACKEND` plus the provider's `*_API_KEY` (`OPENAI_API_KEY`, `GEMINI_API_KEY`, etc.), and the pipeline calls it automatically. Run `python3 skills/ppt-master/scripts/image_gen.py --list-backends` for the full backend list. `gpt-image-2` is currently the best default. +**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` 目前综合质量最佳。 -**B) Web image search** — `image_search.py`. **Zero-config works**; configure `PEXELS_API_KEY` / `PIXABAY_API_KEY` (both free) for consistently higher-quality results: +**B) 网络图片搜索** — `image_search.py`。**零配置**可用；建议配置 `PEXELS_API_KEY` / `PIXABAY_API_KEY`（都免费申请）以获得稳定的高质量结果： -- Without keys, search uses Openverse / Wikimedia Commons only — useful as a fallback, but image quality can be uneven because many results are ordinary user uploads -- With keys, the default provider chain also appends Pexels / Pixabay, which materially improves modern stock photography, people, workplace, lifestyle, and illustration coverage -- Licensing is handled automatically: CC0, Public Domain, Pexels / Pixabay no-attribution licenses, CC BY, and CC BY-SA are all considered together, and Executor adds a small inline credit whenever the selected image requires attribution. Use `--strict-no-attribution` only when a slide cannot tolerate any credit line -- For high-impact covers, product shots, portraits, and branded scenes, prefer this order: user-provided high-resolution assets / AI generation > web search with Pexels / Pixabay keys > zero-config web search +- 不配置时只使用 Openverse / Wikimedia Commons，适合作为兜底，但容易出现构图随意、清晰度不稳定的图片 +- 配置后默认搜索链会追加 Pexels / Pixabay，现代商业摄影、人物、办公、生活方式和插画类图片质量明显更稳定 +- 许可自动处理：默认把 CC0、公有领域、Pexels / Pixabay 免署名许可、CC BY、CC BY-SA 一起纳入候选；选中需署名的图片时，Executor 会在该幻灯片自动添加小字署名。只有明确不能出现署名时，才使用 `--strict-no-attribution` 限制为免署名图片 +- 对视觉要求高的封面、产品图、人物图和品牌场景，优先级建议：用户自带高清素材 / AI 生图 > 配置 Pexels / Pixabay 的网络搜索 > 零配置网络搜索 -The API keys above all live in `.env`. Clone installs can use `cp .env.example .env`; skill marketplace installs should use a persistent user config: +上面提到的 API Key 统一通过 `.env` 配置。clone 安装可以用 `cp .env.example .env`；skill marketplace 安装建议使用持久的用户级配置： ```bash mkdir -p ~/.ppt-master cp /path/to/installed/ppt-master/.env.example ~/.ppt-master/.env ``` -PPT Master reads the current process environment first, then the first `.env` found in this order: current working directory, skill directory (e.g. `~/.agents/skills/ppt-master/.env`), clone repo root, `~/.ppt-master/.env`. +PPT Master 会优先读取当前进程环境变量，然后按顺序读取第一个存在的 `.env`：当前工作目录、skill 安装目录（如 `~/.agents/skills/ppt-master/.env`）、clone 仓库根目录、`~/.ppt-master/.env`。 -> Full reference: [`image-generator.md`](./skills/ppt-master/references/image-generator.md) (AI) · [`image-searcher.md`](./skills/ppt-master/references/image-searcher.md) (web). +> 完整说明：[`image-generator.md`](./skills/ppt-master/references/image-generator.md)（AI）·[`image-searcher.md`](./skills/ppt-master/references/image-searcher.md)（网络）。 --- -## Documentation +## 文档导航 -| | Document | Description | -|---|----------|-------------| -| 📘 | [Getting Started](./docs/getting-started.md) | First deck in 3 steps, plus how to use templates, live preview, animations, narration, voice cloning (**new users start here**) | -| 🆚 | [Why PPT Master](./docs/why-ppt-master.md) | How it compares to Gamma, Copilot, and other AI tools | -| 🪟 | [Windows Installation](./docs/windows-installation.md) | Step-by-step setup guide for Windows users | -| 📖 | [SKILL.md](./skills/ppt-master/SKILL.md) | Core workflow and rules | -| 📐 | [Canvas Formats](./skills/ppt-master/references/canvas-formats.md) | PPT 16:9, Xiaohongshu, WeChat, and 10+ formats | -| 🛠️ | [Scripts & Tools](./skills/ppt-master/scripts/README.md) | All scripts and commands | -| 💼 | [Examples](./examples/README.md) | All example projects | -| 🏗️ | [Technical Design](./docs/technical-design.md) | Architecture, design philosophy, why SVG | -| ❓ | [FAQ](./docs/faq.md) | Model selection, cost, layout troubleshooting, custom templates | +| | 文档 | 说明 | +|---|------|------| +| 📘 | [快速入门](./docs/zh/getting-started.md) | 三步做出第一份 deck，外加模板、实时预览、动画、旁白、声音复刻的用法（**新用户从这里开始**） | +| 🆚 | [为什么选 PPT Master](./docs/zh/why-ppt-master.md) | 与 Gamma、Copilot 等工具的对比 | +| 🪟 | [Windows 安装指南](./docs/zh/windows-installation.md) | Windows 用户手把手安装教程 | +| 📖 | [SKILL.md](./skills/ppt-master/SKILL.md) | 核心流程与规则 | +| 📐 | [画布格式](./skills/ppt-master/references/canvas-formats.md) | PPT 16:9、小红书、朋友圈等 10+ 种格式 | +| 🛠️ | [脚本与工具](./skills/ppt-master/scripts/README.md) | 所有脚本和命令 | +| 💼 | [示例](./examples/README.md) | 所有示例项目 | +| 🏗️ | [技术路线](./docs/zh/technical-design.md) | 架构、设计哲学、为什么选 SVG | +| ❓ | [常见问题](./docs/zh/faq.md) | 模型选择、费用、排版问题排查、自定义模板 | --- -## Contributing +## 贡献 -See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to get involved. +详见 [CONTRIBUTING.md](./CONTRIBUTING.md)。 -## License +## 开源协议 [MIT](LICENSE) -## Acknowledgments +## 致谢 -[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 principles) +[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 设计原则） -## Related Tools +## 相关工具 -[cc-switch](https://github.com/farion1231/cc-switch) — one-click switching of API providers across Claude Code / Codex / Gemini CLI and more. +[cc-switch](https://github.com/farion1231/cc-switch) —— 一键切换 Claude Code / Codex / Gemini CLI 等工具的 API 供应商。 -## Contact & Collaboration +## 联系与合作 -Looking to collaborate, integrate PPT Master into your workflow, or just have questions? +欢迎合作交流、将 PPT Master 集成到你的工作流，或者单纯提问： -- 💬 **Questions & sharing** — [GitHub Discussions](https://github.com/hugohe3/ppt-master/discussions) -- 🐛 **Bug reports & feature requests** — [GitHub Issues](https://github.com/hugohe3/ppt-master/issues) +- 💬 **提问与分享** — [GitHub Discussions](https://github.com/hugohe3/ppt-master/discussions) +- 🐛 **Bug 反馈与功能建议** — [GitHub Issues](https://github.com/hugohe3/ppt-master/issues) --- @@ -401,11 +417,11 @@ Looking to collaborate, integrate PPT Master into your workflow, or just have qu --- -## Sponsors & Support +## 赞助与支持 -PPT Master is currently built and maintained primarily by me. Every new template, bug fix, and documentation update takes ongoing resources — currently shared by the sponsors and individual supporters below. +PPT Master 目前主要由我开发维护。每个新模板、Bug 修复、文档更新都需要持续的资源投入，目前由以下赞助方和个人支持者共同分担。 -**Corporate sponsors** +**企业赞助方** Kimi   @@ -415,22 +431,22 @@ PPT Master is currently built and maintained primarily by me. Every new template   RunAPI   -YouYun ZhiSuan +优云智算   Powered by DigitalOcean -**Individual support** +**个人赞助** -If PPT Master has been helpful to you, individual support of any amount helps keep the project moving and free. +如果 PPT Master 帮到了你，任何金额的个人赞助都能帮助项目持续更新、保持免费开源。 -Sponsor via PayPal +通过 PayPal 赞助 -Alipay QR Code +支付宝收款码 --- -Made with ❤️ by [Hugo He](https://www.hehugo.com/) — if this project helps you, please give it a ⭐ and consider [sponsoring](#sponsors--support). +Made with ❤️ by [何雨果 Hugo He](https://www.hehugo.com/) — 如果这个项目对你有帮助，请给一个 ⭐，也欢迎[赞助支持](#赞助与支持)。 -Official distribution: GitHub (primary) · AtomGit (mirror). Redistributions on other platforms are unofficial. MIT licensed — attribution required. +官方发布渠道：GitHub（主仓库）· AtomGit（镜像）。其他平台转发版本均为非官方版本。MIT 协议，使用需保留署名。 -[⬆ Back to Top](#ppt-master--ai-generates-natively-editable-pptx-from-any-document) +[⬆ 回到顶部](#ppt-master--ai-生成原生可编辑-pptx支持任意文档输入)