Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

docs: clarify update paths for ZIP and marketplace installs

hugohe34b26b4c39035
diff --git a/README.md b/README.md
index 9302fde5..c5ff8273 100644
--- a/README.md
+++ b/README.md
@@ -191,9 +191,11 @@ Never used one of these? Don't worry — in this project they play exactly one r
### 3. Set Up
-**Option A — Download ZIP** (no Git required): click **Code → Download ZIP** on the [GitHub page](https://github.com/hugohe3/ppt-master), then unzip.
+**Option A — 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.
-**Option B — Git clone** (requires [Git](https://git-scm.com/downloads) installed):
+If you plan to keep using PPT Master and update it over time, use Git clone instead.
+
+**Option B — Git clone** (recommended; requires [Git](https://git-scm.com/downloads) installed):
```bash
git clone https://github.com/hugohe3/ppt-master.git
@@ -206,7 +208,23 @@ Then install dependencies:
pip install -r requirements.txt
```
-To update later (Option A / B): `python3 skills/ppt-master/scripts/update_repo.py`
+#### Updating Later
+
+**Git clone installs:**
+
+```bash
+python3 skills/ppt-master/scripts/update_repo.py
+```
+
+The script pulls the latest version and syncs Python dependencies when `requirements.txt` changes.
+
+**Download ZIP installs:**
+
+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:
+
+```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:
>
diff --git a/README_CN.md b/README_CN.md
index ec707ade..d9999d0f 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -195,10 +195,12 @@ PPT Master 在**任何具备 agent 能力**(可读写文件、执行命令、
### 3. 配置项目
-**方式 A — 下载 ZIP**(无需安装 Git):
+**方式 A — 下载 ZIP**(无需安装 Git,适合快速体验):
[GitHub](https://github.com/hugohe3/ppt-master) → **Code → Download ZIP** · [AtomGit](https://atomgit.com/hugohe3/ppt-master) → **克隆/下载 → 下载ZIP**(国内网速更快)
-**方式 B — Git clone**(需先安装 [Git](https://git-scm.com/downloads)):
+如果你打算长期使用并持续更新,推荐使用下面的 Git clone 方式。
+
+**方式 B — Git clone**(推荐;需先安装 [Git](https://git-scm.com/downloads)):
```bash
# GitHub
@@ -214,7 +216,23 @@ cd ppt-master
pip install -r requirements.txt
```
-日常更新(方式 A / B):`python3 skills/ppt-master/scripts/update_repo.py`
+#### 日常更新
+
+**Git clone 安装:**
+
+```bash
+python3 skills/ppt-master/scripts/update_repo.py
+```
+
+脚本会拉取最新版;如果 `requirements.txt` 有变化,会自动同步 Python 依赖。
+
+**下载 ZIP 安装:**
+
+ZIP 目录没有 Git 历史,不能自动 `git pull`。更新时请重新下载最新版 ZIP,解压到新目录,然后把旧目录里的 `.env` 和 `projects/` 复制过去,再执行:
+
+```bash
+pip install -r requirements.txt
+```
> **方式 C — Skill marketplace**:仓库已添加 `.claude-plugin/marketplace.json` 元数据,可通过 [Claude Code plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces) 生态一行安装:
>
diff --git a/docs/faq.md b/docs/faq.md
index 7cbbda78..a99e350b 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -32,6 +32,26 @@ Just specify the format when starting a project (e.g., `--format xhs`). The outp
PPT Master works with any AI coding agent that can read files and run shell commands — **Claude Code** (CLI / VS Code / JetBrains / Web), **VS Code Copilot**, **Codex**, and others. See the cost comparison below for pricing differences.
+## Q: I downloaded an old version. How do I update to the latest?
+
+It depends on how you installed PPT Master:
+
+| Install method | Update method |
+|---|---|
+| Git clone | Run `python3 skills/ppt-master/scripts/update_repo.py` inside the `ppt-master` folder |
+| Download ZIP | Download the latest ZIP, unzip it into a new folder, copy your old `.env` and `projects/` folder into the new folder, then run `pip install -r requirements.txt` |
+| Skill marketplace | Reinstall or update through the matching marketplace / skills tool |
+
+For long-term use, Git clone is recommended. ZIP is fine for a quick trial, but it has no Git history and cannot run `git pull`.
+
+If you are not sure which install method you used, ask the AI to run this from the project folder:
+
+```bash
+python3 skills/ppt-master/scripts/update_repo.py
+```
+
+If the folder is not a Git clone, the script will tell you how to migrate a ZIP install.
+
## Q: Can I use AI-generated images in my presentation?
Yes. PPT Master includes a built-in image generation script that supports multiple providers (Gemini, OpenAI, FLUX, Qwen, Zhipu, etc.). During the Strategist phase, if you choose "AI generation" for the image approach, the pipeline will automatically generate images based on your content. You can also provide your own images — just place them in the project's `images/` folder.
diff --git a/docs/zh/faq.md b/docs/zh/faq.md
index f81926b3..0ee0077a 100644
--- a/docs/zh/faq.md
+++ b/docs/zh/faq.md
@@ -32,6 +32,26 @@
PPT Master 可以在任何能读取文件和执行命令的 AI 编程代理中运行——**Claude Code**(CLI / VS Code / JetBrains / Web)、**VS Code Copilot**、**Codex** 等均可使用。不同工具的使用成本可参考下方的费用对比。
+## Q: 我下载过旧版本,怎么更新到最新版?
+
+看你当时怎么安装:
+
+| 安装方式 | 更新方式 |
+|---|---|
+| Git clone | 在 `ppt-master` 目录运行 `python3 skills/ppt-master/scripts/update_repo.py` |
+| Download ZIP | 重新下载最新版 ZIP,解压到新目录;把旧目录里的 `.env` 和 `projects/` 复制过去;再运行 `pip install -r requirements.txt` |
+| Skill marketplace | 用对应的 marketplace / skills 工具重新安装或更新 |
+
+长期使用建议用 Git clone。ZIP 适合快速体验,但没有 Git 历史,不能自动 `git pull`。
+
+如果不确定自己是哪种安装方式,可以让 AI 在项目目录里运行:
+
+```bash
+python3 skills/ppt-master/scripts/update_repo.py
+```
+
+如果当前目录不是 Git clone 版本,脚本会提示你按 ZIP 方式迁移。
+
## Q: 能用 AI 生成配图吗?
可以。PPT Master 内置了图片生成脚本,支持多个供应商(Gemini、OpenAI、FLUX、通义千问、智谱等)。在策略师阶段选择"AI 生图"方案后,流程会根据内容自动生成配图。你也可以使用自己的图片——只需放到项目的 `images/` 目录下即可。
diff --git a/skills/ppt-master/scripts/update_repo.py b/skills/ppt-master/scripts/update_repo.py
index 77e2398c..00e3d423 100644
--- a/skills/ppt-master/scripts/update_repo.py
+++ b/skills/ppt-master/scripts/update_repo.py
@@ -1,9 +1,19 @@
#!/usr/bin/env python3
-"""Update the repository and sync Python dependencies when needed.
+"""PPT Master - Repository Updater
+
+Pull the latest Git checkout and sync Python dependencies when requirements
+change.
Usage:
python3 skills/ppt-master/scripts/update_repo.py
python3 skills/ppt-master/scripts/update_repo.py --skip-pip
+
+Examples:
+ python3 skills/ppt-master/scripts/update_repo.py
+ python3 skills/ppt-master/scripts/update_repo.py --skip-pip
+
+Dependencies:
+ None (standard library only)
"""
from __future__ import annotations
@@ -26,19 +36,44 @@ REPO_ROOT = SKILL_DIR.parent.parent
REQUIREMENTS_FILE = REPO_ROOT / "requirements.txt"
-def parse_args() -> argparse.Namespace:
+def non_git_checkout_message() -> str:
+ return f"""This copy of PPT Master is not a Git checkout, so it cannot be updated automatically.
+
+Repository path:
+ {REPO_ROOT}
+
+If you installed with Download ZIP:
+ 1. Download the latest ZIP from GitHub or AtomGit.
+ 2. Unzip it into a new folder.
+ 3. Copy your old .env and projects/ folder into the new folder.
+ 4. Run: pip install -r requirements.txt
+
+If you want one-command updates next time, install with Git clone:
+ git clone https://github.com/hugohe3/ppt-master.git
+
+If you installed through a skill marketplace, update or reinstall through the
+same marketplace / skills tool."""
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
parser = argparse.ArgumentParser(
description=(
"Pull the latest repository changes and sync Python dependencies "
"only when requirements.txt changes."
- )
+ ),
+ formatter_class=argparse.RawDescriptionHelpFormatter,
)
parser.add_argument(
"--skip-pip",
action="store_true",
help="Skip Python dependency sync even if requirements.txt changed.",
)
- return parser.parse_args()
+ return parser.parse_args(argv)
+
+
+def print_status(message: str = "") -> None:
+ """Print progress/status messages to stderr."""
+ print(message, file=sys.stderr)
def run_command(args: list[str], *, check: bool = True) -> subprocess.CompletedProcess[str]:
@@ -69,6 +104,11 @@ def ensure_git_available() -> None:
raise RuntimeError("Missing executable: git")
+def ensure_git_checkout() -> None:
+ if not (REPO_ROOT / ".git").exists():
+ raise RuntimeError(non_git_checkout_message())
+
+
def ensure_clean_tracked_worktree() -> None:
status = run_command(["git", "status", "--porcelain", "--untracked-files=no"], check=False)
if status.returncode != 0:
@@ -88,50 +128,54 @@ def get_head_revision() -> str:
def sync_python_dependencies() -> None:
if not REQUIREMENTS_FILE.exists():
- print("requirements.txt not found; skipping Python dependency sync.")
+ print_status("requirements.txt not found; skipping Python dependency sync.")
return
- print("requirements.txt changed. Syncing Python dependencies...")
+ print_status("requirements.txt changed. Syncing Python dependencies...")
result = run_command([sys.executable, "-m", "pip", "install", "-r", str(REQUIREMENTS_FILE)])
if result.stdout.strip():
- print(result.stdout.strip())
+ print_status(result.stdout.strip())
if result.stderr.strip():
- print(result.stderr.strip())
+ print_status(result.stderr.strip())
-def main() -> int:
- args = parse_args()
+def main(argv: list[str] | None = None) -> int:
+ args = parse_args(argv)
try:
+ ensure_git_checkout()
ensure_git_available()
ensure_clean_tracked_worktree()
before_head = get_head_revision()
before_requirements = file_digest(REQUIREMENTS_FILE)
- print(f"Repository: {REPO_ROOT}")
+ print_status(f"Repository: {REPO_ROOT}")
pull_result = run_command(["git", "pull", "--ff-only"])
if pull_result.stdout.strip():
- print(pull_result.stdout.strip())
+ print_status(pull_result.stdout.strip())
if pull_result.stderr.strip():
- print(pull_result.stderr.strip())
+ print_status(pull_result.stderr.strip())
after_head = get_head_revision()
after_requirements = file_digest(REQUIREMENTS_FILE)
if before_head == after_head:
- print("Repository is already up to date.")
+ print_status("Repository is already up to date.")
else:
- print(f"Updated from {before_head[:7]} to {after_head[:7]}.")
+ print_status(f"Updated from {before_head[:7]} to {after_head[:7]}.")
if args.skip_pip:
- print("Skipped Python dependency sync (--skip-pip).")
+ print_status("Skipped Python dependency sync (--skip-pip).")
elif before_requirements != after_requirements:
sync_python_dependencies()
else:
- print("requirements.txt unchanged. Skipping Python dependency sync.")
+ print_status("requirements.txt unchanged. Skipping Python dependency sync.")
- print("Note: system dependencies such as Node.js and Pandoc still need to be installed manually.")
+ print_status(
+ "Note: system dependencies such as Node.js and Pandoc still need "
+ "to be installed manually."
+ )
return 0
except subprocess.CalledProcessError as exc:
details = (exc.stderr or exc.stdout or "").strip()